x-security CLI

Most teams run their API gateway and WAF on defaults. The security is already in the box (authentication, rate limits, request validation, ownership/BOLA checks), but turning it on means learning each vendor's config DSL, and the rules you write lock you into that vendor and drift out of sync with your code.

x-security is one security policy per route, written as an extension of the OpenAPI spec you already have. It versions in git, diffs like code, and a deterministic CLI compiles it to whichever gateway you run.

• No new DSL. Policy lives in your OpenAPI file, next to the route it protects.
• No vendor lock-in. One spec compiles to Kong, Coraza, BunkerWeb, OpenAppSec, Envoy, or a firewall bundle. Switch gateways without rewriting a line of policy.
• No config drift. The spec is the source of truth; validate fails CI when the running gateway drifts from it.
• Deterministic. No LLM calls, no API keys. It compiles exactly what your spec says, and nothing it can't verify.

Install

npm i -g @chain305/x-security     # installs the `xsecurity` command
xsecurity --help

Or run it without installing:

npx @chain305/x-security --help

Requires Node 20+. Docker is needed only for xsecurity test.

How it works

   your OpenAPI spec                          your gateway
  ┌──────────────────┐   xsecurity generate  ┌──────────────┐
  │  paths:          │  ───────────────────► │ Kong / Coraza│
  │    /users/{id}:  │                       │ Envoy / WAF  │
  │      x-security: │  ◄─────────────────── │  …enforced   │
  │        …         │   xsecurity validate  └──────────────┘
  └──────────────────┘     (drift gate)

1. Annotate — attach an x-security block to each route. Write it by hand, with the visual builder, or with the free AI plugin that reads your code and drafts the policy for you.
2. Compile — xsecurity generate turns the annotated spec into native config for your gateway. One spec, any supported target.
3. Test — xsecurity test spins the gateway up in Docker, sends real traffic, and asserts the policy actually blocks what it should.
4. Enforce & catch drift — deploy the config, then run xsecurity validate in CI so the pipeline fails the moment the gateway and the spec disagree.

Quickstart

npm i -g @chain305/x-security

# 1. scaffold empty x-security blocks on every route that lacks one
xsecurity init api.yaml

# 2. fill them in — by hand, the visual builder, or the plugin —
#    then check your OWASP API Top 10 coverage
xsecurity report api.yaml

# 3. compile to the gateway you run
xsecurity generate api.yaml --target kong > kong.yaml

# 4. prove it blocks the exploit and allows legit traffic (needs Docker)
xsecurity test api.yaml --target kong

# 5. gate CI on drift between the spec and the deployed gateway
xsecurity validate api.yaml --target kong --gateway http://localhost:8001

Commands

| Command | What it does | | --- | --- | | xsecurity init <spec> | Add empty x-security blocks to operations missing them | | xsecurity report <spec> | OWASP API Top 10 coverage and annotation reports | | xsecurity generate <spec> --target <t> | Compile an annotated OpenAPI spec into gateway config (kong, coraza, bunkerweb, openappsec, firewall, envoy) | | xsecurity test <spec> --target <t> | Closed-loop test: generate config, spin up Docker, send traffic, assert | | xsecurity validate <spec> --target kong --gateway <url\|file> | Detect drift between the spec and a running/exported gateway config | | xsecurity verify <spec> --target <t> --gateway <addr> | Read-only post-deploy check that the gateway loaded the emitted artifacts | | xsecurity diff <old> <new> --target <t> | Diff the generated config for two spec versions | | xsecurity migrate <spec> --from 0.4 --to 0.5 | Rewrite a spec between schema versions |

Run xsecurity <command> --help for full flags.

Support matrix

Compile & deploy targets

xsecurity generate --target <name> compiles one annotated spec to any of these. Two are hosted deploys; the rest are self-hosted bundles you drop into your gateway.

| Target (--target) | What it is | Delivery | Status | | --- | --- | --- | --- | | cloudflare | Cloudflare Ruleset Engine + WAF | hosted deploy | GA | | aws-apigw | AWS API Gateway + WAFv2 | hosted deploy | beta | | kong | Kong Gateway (decK plugin config) | self-hosted bundle | beta | | coraza | Coraza / ModSecurity WAF (SecLang) | self-hosted bundle | beta | | coraza (nginx preset) | NGINX + libcoraza | self-hosted bundle | beta | | bunkerweb | BunkerWeb (OpenResty WAF) | self-hosted bundle | beta | | openappsec | Check Point Open AppSec WAF | self-hosted bundle | beta | | envoy | Envoy (ext_proc / Lua filter) | self-hosted bundle | alpha | | firewall | Host firewall (iptables) | self-hosted bundle | SSRF egress only¹ |

¹ firewall is L3/L4: it enforces only API7 SSRF egress via domainAllowlist; it can't introspect HTTP, so it's not on the coverage matrix below.

OWASP API Top 10 coverage per target

How much of each class a target can enforce natively. 🟢 full · 🟡 partial · 🔴 gap · ⚪ not yet measured. Authorization cells show stateless → with a JWT identity wired.

| OWASP API class | Cloudflare | AWS API GW | BunkerWeb | | --- | :--: | :--: | :--: | | API1 · Broken Object Level Auth (BOLA) | 🔴→🟡 | 🔴→🟢 | 🔴 | | API2 · Broken Authentication | 🟡 | 🟡 | 🟡 | | API3 · Broken Object Property Auth (BOPLA) | 🟡 | 🟡 | 🟡 | | API4 · Unrestricted Resource Consumption | 🟢 | 🟡 | 🟡 | | API5 · Broken Function Level Auth (BFLA) | 🟡 | 🟡→🟢 | 🟡 | | API6 · Unrestricted Access to Business Flows | 🟡 | 🟡 | 🟡 | | API7 · Server-Side Request Forgery (SSRF) | 🔴 | 🔴 | 🟢 | | API8 · Security Misconfiguration | 🟡 | 🟡 | 🟡 | | API9 · Improper Inventory Management | 🔴 | 🔴 | 🟡 | | API10 · Unsafe Consumption of APIs | 🟡 | 🟡 | 🟡 |

Only these three targets are independently measured today; Kong, Coraza, NGINX, Envoy and OpenAppSec compile the same policy but aren't yet published with a per-class measurement (⚪). Cells like 🔴→🟢 are the same control stateless vs. with a JWT identity wired. Ownership checks (BOLA/BFLA) need to know who the caller is, so a stateless WAF can't enforce them. A 🟡 means the target enforces most of the class natively, though not all of it. Full per-field matrix (incl. the x-security-native injection / prompt-injection / audit classes): usewaf.com/coverage.

License

Apache-2.0