bouncer

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), and Nigeria (NDPC, FCCPC, FIRS) — 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": "auto",
    "repo": "./my-app",
    "roots": ["."]
  },
  "packs": ["uk-osa", "uk-aadc"],
  "packDirs": [],
  "ignore": [],
  "exclude": [],
  "failOn": ["fail"]
}

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

bouncer is language-agnostic. The default auto adapter scans TS/JS, Go, Java, Kotlin, Scala, C#, C/C++, Rust, Swift, Dart, PHP, Python, Ruby, Elixir, SQL and HTML templates. Surfaces are found by directory/file names in any naming convention (signup/, sign_up.py, SignUpController.java). Comments and test/fixture files are never counted as evidence. next and react-native remain as TS/JS-only aliases. Narrow with target.languages.

• exclude — extra globs to skip (added to built-in test/fixture/mock excludes; set "defaultExcludes": false to disable those).
• packs — which rule packs to run. Built-ins: uk-osa, uk-aadc, ng-ndpc, ng-fccpc, ng-firs.
• 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": "(share[_-]?location|location[_-]?sharing)[\"']?\\s*[:=]\\s*(false|off)\\b",
    "in": ["profile", "privacy", "location"],
    "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

any, signup, auth, profile, privacy, location, chat, livestream, ugc, moderation, consent, legal, dsr, security, retention, breach, processors, payments, invoice, governance. Unknown surface names are pack-validation errors.

Nigeria packs

For a platform operating in Nigeria, three packs ship built-in:

• ng-ndpc — Nigeria Data Protection Act 2023 (NDPC): privacy notice, opt-in & granular consent, data-subject rights, encryption, retention/erasure, NDPA localization, DPO designation, 72-hour breach plan, cross-border safeguards.
• ng-fccpc — consumer protection (FCCPC): blanket "no refund / all sales final" clauses flagged as void — and high-precision, so a tiered or conditional refund policy doesn't trip it — plus refund-policy present, no drip pricing, explicit terms acceptance, terms of service present.
• ng-firs — tax (FIRS): 7.5% VAT rate, VAT on commission, WHT on payouts, VAT tax invoice.

Some obligations are process, not code — NDPC registration, signed cross-border DPAs, the WHT remittance itself. Those rules surface as gaps to track (add them to ignore with a note), not things a static scan can prove.

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, 22, and 24.

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.