Twelve layers, one verdict
How BonkLM's twelve guardrail layers compose: the GuardrailResult contract, the eight inbound validators, the outbound guards, and the rules that bind them.
BonkLM ships twelve named layers. They’re not coupled — each is a small module with a single public function. The interesting part is how they compose. This post walks the architecture.
The contract
Every layer returns a GuardrailResult. Same shape, regardless of whether the layer is a validator (inbound text) or a guard (outbound text or tool args):
enum Severity { INFO, WARNING, BLOCKED, CRITICAL }
enum RiskLevel { LOW, MEDIUM, HIGH }
interface GuardrailResult {
allowed: boolean
blocked: boolean
severity: Severity // 4 levels
risk_level: RiskLevel // 3 levels — derived from cumulative risk_score
risk_score: number // cumulative — sum of finding weights (0–100+)
reason?: string
findings: Finding[] // raw matches with offsets
timestamp: number
}That uniformity is the whole trick. The engine doesn’t care which layer ran — it accumulates findings and decides the action.
The twelve
Eight validators inspect inbound text, tool-call arguments, and retrieved context:
- Prompt Injection — instruction-override, system-prompt extraction, persona pivots. 35+ patterns across 6 categories, plus 52 multilingual patterns across 16 language codes.
- Jailbreak — DAN-class roleplay, hypothetical framings, social-engineering ladders. 44 patterns across 10 categories.
- Reformulation — catches paraphrase and wording tricks that slip past naive keyword filters.
- Encoded Rescan — decodes base64, hex, ROT, leetspeak, zero-width characters, and multi-layer chains, then scans the decoded text again.
- Harm Intent — deterministic harm-goal detection with no LLM judge in the path.
- Social Engineering — credential-phishing and pretext-coercion patterns.
- Boundary — delimiter abuse, fake-section markers, context-overflow patterns.
- Indirect Injection — provenance-gated scanning of retrieved docs, tool results, and memory writes; never fires on raw user text.
The remaining layers guard outbound text, tool args, and streams:
- Secret — 37 credential types (38 patterns, 27 critical / 9 high / 2 medium): API keys, AWS keys, GitHub tokens, JWT, OpenAI sk-proj-* (post-2024), Anthropic sk-ant-*, Stripe live/test/restricted, Slack, Twilio, SendGrid, Mailgun, private SSH/PGP.
- PII — 30 patterns spanning US, EU, and international identifiers (7 US · 18 EU · 5 common); Luhn-validated card numbers; IBAN/NIF/PESEL/DNI/NIE/personnummer.
- Bash + XSS — command-injection in shell-execution tool calls, and reflected / DOM-based markup injection in output. A separate Production guard blocks commands aimed at production environments (force-push, deploy, kubectl).
- Streaming — chunk-level inspection of LLM token streams at the edge that cuts the stream mid-flight if any layer trips.
Composition rules
The GuardrailEngine takes an array of layers and two top-level dials:
shortCircuit— stop at first blocking verdict. Default true. Set false to collect all findings before deciding.parallel— run all layers concurrently. Default false. Worth it when shortCircuit is false and you want to bound latency.
The engine merges findings, picks the highest risk_level across layers, and applies the configured action (block / sanitize / log / allow).
Why twelve and not three
Some libraries ship a monolithic “guardrail” that does everything. We split because the layers have different lifecycles. The pattern catalogues evolve at different cadences (secrets churns monthly with new key formats; XSS is much more stable). The layers have different failure modes (a secret false-positive is annoying; a PII false-positive is a compliance incident). And the layers belong to different reviewers — the security team owns Prompt Injection, the privacy team owns PII, platform engineering owns Bash safety.
Splitting them lets each team move at its own pace without breaking the others. The engine’s job is just to compose them.
Where to go next
Each layer has its own reference in the Validators and Guards docs pages. The playground runs the prompt-testable layers against your own prompts.