bouncer

Static compliance-controls checker — the controls a regulation requires, verified in your code.

nugehs.github.io/bouncer-web (site)

bouncer verifies that the controls a regulation requires actually exist in your code — UK Online Safety Act, ICO Children's Code (AADC) — expressed as deterministic rule packs. It runs in CI, exits non-zero when a required control is missing, and needs no LLM.

It checks IDs at the door so non-compliant code doesn't get in.

bouncer is an engineering aid, not legal advice. A green report means the coded controls a rule looks for were found — it is not a substitute for a compliance / DPO review.

Why

Regulators now expect demonstrable controls: age assurance, high-privacy defaults for children, report/block affordances on user-generated content, a DPIA, a risk assessment. Those are concrete things that either exist in a codebase or don't. bouncer turns a regulation into a set of static checks over your repo, the same way tieline turns an API contract into drift checks — the engine knows nothing about the law; the rule packs do.

bouncer vs semgrep / policy-as-code

Scanners like semgrep, CodeQL, or Snyk answer "is there bad code here?" — they hunt for vulnerabilities and dangerous patterns that shouldn't exist. bouncer answers the opposite question: "does the code the regulation requires actually exist?" — age assurance on sign-up, report/block on UGC surfaces, high-privacy defaults for children. A repo can be vulnerability-free and still fail every one of those obligations. Policy-as-code tools (OPA/Rego, Conftest) gate configs and infrastructure against policy; bouncer gates application source against regulatory rule packs, with file:line evidence for every control and an honest unknown when a surface can't be located. In short: semgrep finds vulnerabilities; bouncer proves required controls exist. They complement each other — run both.

Install

npx @nugehs/bouncer init
npx @nugehs/bouncer check

Or clone and run with plain Node (zero runtime dependencies, Node ≥ 18).

Usage

bouncer init [path]                 # write a starter bouncer.config.json
bouncer check                       # run packs, print report, exit 1 on a missing control
bouncer check --pack uk-aadc        # restrict to one pack
bouncer check --status fail         # show only the failures
bouncer report --out report.html    # self-contained HTML audit report
bouncer list                        # every rule the configured packs apply
bouncer explain <ruleId>            # what a rule requires + how it is checked
bouncer packs                       # rule packs shipped with bouncer
bouncer doctor                      # sanity-check config, adapter, packs
bouncer mcp                         # start the MCP server (stdio)

Verdicts

unknown is deliberate: bouncer never reports a green pass for a surface it could not find. Missing surface → honest "can't determine".

Configuration

bouncer.config.json:

{
  "target": {
    "adapter": "next",
    "repo": "./my-app",
    "roots": ["app", "src", "components"]
  },
  "packs": ["uk-osa", "uk-aadc"],
  "packDirs": [],
  "ignore": [],
  "failOn": ["fail"]
}

• adapter — how regulation surfaces (sign-up, profile, chat, livestream…) map onto files for your stack.

Adapters shipped today: next (App Router) and react-native. That's it — if your stack isn't covered, an adapter is a single small file mapping surface aliases to file globs (see src/lib/adapters/next.js). Adapter PRs are very welcome — nuxt, sveltekit, remix, flutter, django are all natural candidates.

• packs — which rule packs to run. Built-ins: uk-osa, uk-aadc.
• packDirs — extra directories of your own *.json packs.
• ignore — rule ids to skip.
• failOn — which buckets make check exit non-zero (default ["fail"]).

Rule packs

A pack is JSON. Each rule maps a legal standard to a static assertion over a surface:

{
  "id": "aadc.geolocation-default-off",
  "standard": "Standard 10 — Geolocation",
  "severity": "high",
  "surface": "profile",
  "intent": "Geolocation must default to off for children.",
  "fix": "Default any location-sharing setting to off.",
  "assert": {
    "find": "(geo|location)[^\\n;,]{0,30}(default|initial)[^\\n;,]{0,15}(false|off)",
    "in": ["profile", "any"],
    "expect": "present"
  }
}

Assertion nodes:

• { "find": "<regex>", "in": "<surface|glob>", "expect": "present|absent" }
• { "allOf": [ … ] } · { "anyOf": [ … ] } · { "not": … }

in accepts a surface alias (resolved by the adapter), an array of aliases/globs, or a raw glob. expect: "absent" flips the meaning — a match is a violation (used for nudge patterns, self-declared age checkboxes, etc.).

Surfaces (next adapter)

any, signup, auth, profile, chat, livestream, ugc, governance.

MCP

bouncer is also an MCP server (stdio), so an agent can pull the same deterministic results:

// .mcp.json
{ "mcpServers": { "bouncer": { "command": "npx", "args": ["-y", "@nugehs/bouncer", "mcp"] } } }

CI

- run: npx @nugehs/bouncer check

Fails the build when a required control goes missing — e.g. someone removes an age-gate or a report button from a UGC surface.

Tests

npm test    # node --test — zero dependencies, nothing to install

The suite runs on Node's built-in test runner against throwaway fixture repos: glob/brace expansion, every assertion probe (find, allOf/anyOf/not, allInFile + within windows, expect: "absent"), the pass/fail/unknown verdict semantics, and pack loading. CI runs it on Node 18, 20, and 22.

License

MIT

Part of the toolchain

bouncer is one of four tools that form a deterministic trust layer for AI-assisted development. Each answers a question people keep handing to an LLM — with static analysis instead.

• repoctx — context: what does this change actually touch?
• tieline — contracts: did the front end and back end quietly stop agreeing?
• bouncer (this tool) — compliance: could you defend this to Ofcom?
• aiglare — governance: where can the model do something you can't undo?

More at segunolumbe.com. static analysis, never the model.