@chain305/x-security 0.2.3 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +97 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,15 +1,19 @@
|
|
|
1
1
|
# x-security CLI
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
the
|
|
3
|
+
**Most teams run their API gateway and WAF on defaults.** The security is
|
|
4
|
+
already in the box — authentication, rate limits, request validation,
|
|
5
|
+
ownership/BOLA checks — but turning it on means learning each vendor's config
|
|
6
|
+
DSL, and the rules you write lock you into that vendor and drift out of sync
|
|
7
|
+
with your code.
|
|
8
|
+
|
|
9
|
+
**`x-security` is one security policy per route, written as an extension of the
|
|
10
|
+
OpenAPI spec you already have.** It versions in git, diffs like code, and a
|
|
11
|
+
deterministic CLI compiles it to whichever gateway you run.
|
|
7
12
|
|
|
8
13
|
- **No new DSL** — policy lives in your OpenAPI file, next to the route it protects.
|
|
9
14
|
- **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.
|
|
10
|
-
- **No config drift** — the spec is the source of truth;
|
|
11
|
-
|
|
12
|
-
Deterministic. No LLM calls, no API keys.
|
|
15
|
+
- **No config drift** — the spec is the source of truth; `validate` fails CI when the running gateway drifts from it.
|
|
16
|
+
- **Deterministic** — no LLM calls, no API keys. It compiles exactly what your spec says, and nothing it can't verify.
|
|
13
17
|
|
|
14
18
|
## Install
|
|
15
19
|
|
|
@@ -24,25 +28,105 @@ Or run it without installing:
|
|
|
24
28
|
npx @chain305/x-security --help
|
|
25
29
|
```
|
|
26
30
|
|
|
31
|
+
Requires Node 20+. Docker is needed only for `xsecurity test`.
|
|
32
|
+
|
|
33
|
+
## How it works
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
your OpenAPI spec your gateway
|
|
37
|
+
┌──────────────────┐ xsecurity generate ┌──────────────┐
|
|
38
|
+
│ paths: │ ───────────────────► │ Kong / Coraza│
|
|
39
|
+
│ /users/{id}: │ │ Envoy / WAF │
|
|
40
|
+
│ x-security: │ ◄─────────────────── │ …enforced │
|
|
41
|
+
│ … │ xsecurity validate └──────────────┘
|
|
42
|
+
└──────────────────┘ (drift gate)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
1. **Annotate** — attach an `x-security` block to each route. Write it by hand,
|
|
46
|
+
with the [visual builder](https://usewaf.com/policy-builder.html), or with
|
|
47
|
+
the free AI plugin that reads your code and drafts the policy for you.
|
|
48
|
+
2. **Compile** — `xsecurity generate` turns the annotated spec into native
|
|
49
|
+
config for your gateway. One spec, any supported target.
|
|
50
|
+
3. **Test** — `xsecurity test` spins the gateway up in Docker, sends real
|
|
51
|
+
traffic, and asserts the policy actually blocks what it should.
|
|
52
|
+
4. **Enforce & catch drift** — deploy the config, then run `xsecurity validate`
|
|
53
|
+
in CI so the pipeline fails the moment the gateway and the spec disagree.
|
|
54
|
+
|
|
55
|
+
## Quickstart
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm i -g @chain305/x-security
|
|
59
|
+
|
|
60
|
+
# 1. scaffold empty x-security blocks on every route that lacks one
|
|
61
|
+
xsecurity init api.yaml
|
|
62
|
+
|
|
63
|
+
# 2. fill them in — by hand, the visual builder, or the plugin —
|
|
64
|
+
# then check your OWASP API Top 10 coverage
|
|
65
|
+
xsecurity report api.yaml
|
|
66
|
+
|
|
67
|
+
# 3. compile to the gateway you run
|
|
68
|
+
xsecurity generate api.yaml --target kong > kong.yaml
|
|
69
|
+
|
|
70
|
+
# 4. prove it blocks the exploit and allows legit traffic (needs Docker)
|
|
71
|
+
xsecurity test api.yaml --target kong
|
|
72
|
+
|
|
73
|
+
# 5. gate CI on drift between the spec and the deployed gateway
|
|
74
|
+
xsecurity validate api.yaml --target kong --gateway http://localhost:8001
|
|
75
|
+
```
|
|
76
|
+
|
|
27
77
|
## Commands
|
|
28
78
|
|
|
29
79
|
| Command | What it does |
|
|
30
80
|
| --- | --- |
|
|
81
|
+
| `xsecurity init <spec>` | Add empty `x-security` blocks to operations missing them |
|
|
82
|
+
| `xsecurity report <spec>` | OWASP API Top 10 coverage and annotation reports |
|
|
31
83
|
| `xsecurity generate <spec> --target <t>` | Compile an annotated OpenAPI spec into gateway config (`kong`, `coraza`, `bunkerweb`, `openappsec`, `firewall`, `envoy`) |
|
|
32
|
-
| `xsecurity validate <spec> --target kong --gateway <url\|file>` | Detect drift between the spec and a running/exported gateway config |
|
|
33
84
|
| `xsecurity test <spec> --target <t>` | Closed-loop test: generate config, spin up Docker, send traffic, assert |
|
|
85
|
+
| `xsecurity validate <spec> --target kong --gateway <url\|file>` | Detect drift between the spec and a running/exported gateway config |
|
|
34
86
|
| `xsecurity verify <spec> --target <t> --gateway <addr>` | Read-only post-deploy check that the gateway loaded the emitted artifacts |
|
|
35
|
-
| `xsecurity report <spec>` | OWASP API Top 10 coverage and annotation reports |
|
|
36
87
|
| `xsecurity diff <old> <new> --target <t>` | Diff the generated config for two spec versions |
|
|
37
|
-
| `xsecurity init <spec>` | Add empty `x-security` blocks to operations missing them |
|
|
38
88
|
| `xsecurity migrate <spec> --from 0.4 --to 0.5` | Rewrite a spec between schema versions |
|
|
39
89
|
|
|
40
90
|
Run `xsecurity <command> --help` for full flags.
|
|
41
91
|
|
|
42
|
-
##
|
|
92
|
+
## Support matrix
|
|
93
|
+
|
|
94
|
+
### Compile & deploy targets
|
|
95
|
+
|
|
96
|
+
`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.
|
|
97
|
+
|
|
98
|
+
| Target (`--target`) | What it is | Delivery | Status |
|
|
99
|
+
| --- | --- | --- | --- |
|
|
100
|
+
| `cloudflare` | Cloudflare Ruleset Engine + WAF | hosted deploy | GA |
|
|
101
|
+
| `aws-apigw` | AWS API Gateway + WAFv2 | hosted deploy | beta |
|
|
102
|
+
| `kong` | Kong Gateway (decK plugin config) | self-hosted bundle | beta |
|
|
103
|
+
| `coraza` | Coraza / ModSecurity WAF (SecLang) | self-hosted bundle | beta |
|
|
104
|
+
| `coraza` *(nginx preset)* | NGINX + libcoraza | self-hosted bundle | beta |
|
|
105
|
+
| `bunkerweb` | BunkerWeb (OpenResty WAF) | self-hosted bundle | beta |
|
|
106
|
+
| `openappsec` | Check Point Open AppSec WAF | self-hosted bundle | beta |
|
|
107
|
+
| `envoy` | Envoy (ext_proc / Lua filter) | self-hosted bundle | alpha |
|
|
108
|
+
| `firewall` | Host firewall (iptables) | self-hosted bundle | SSRF egress only¹ |
|
|
109
|
+
|
|
110
|
+
¹ `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.
|
|
111
|
+
|
|
112
|
+
### OWASP API Top 10 coverage per target
|
|
113
|
+
|
|
114
|
+
How much of each class a target can **enforce natively**. 🟢 full · 🟡 partial · 🔴 gap · ⚪ not yet measured.
|
|
115
|
+
|
|
116
|
+
| OWASP API class | Cloudflare | AWS API GW | BunkerWeb |
|
|
117
|
+
| --- | :--: | :--: | :--: |
|
|
118
|
+
| API1 · Broken Object Level Auth (BOLA) | 🔴 | 🔴 | 🔴 |
|
|
119
|
+
| API2 · Broken Authentication | 🟡 | 🟡 | 🟡 |
|
|
120
|
+
| API3 · Broken Object Property Auth (BOPLA) | 🟡 | 🟡 | 🟡 |
|
|
121
|
+
| API4 · Unrestricted Resource Consumption | 🟢 | 🟡 | 🟡 |
|
|
122
|
+
| API5 · Broken Function Level Auth (BFLA) | 🟡 | 🟡 | 🟡 |
|
|
123
|
+
| API6 · Unrestricted Access to Business Flows | 🟡 | 🟡 | 🟡 |
|
|
124
|
+
| API7 · Server-Side Request Forgery (SSRF) | 🔴 | 🔴 | 🟢 |
|
|
125
|
+
| API8 · Security Misconfiguration | 🟡 | 🟡 | 🟡 |
|
|
126
|
+
| API9 · Improper Inventory Management | 🔴 | 🔴 | 🟡 |
|
|
127
|
+
| API10 · Unsafe Consumption of APIs | 🟡 | 🟡 | 🟡 |
|
|
43
128
|
|
|
44
|
-
-
|
|
45
|
-
- Docker (only for `xsecurity test`)
|
|
129
|
+
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 (⚪). Authorization classes (**API1**, **API5**) rise when JWT **identity** is wired — with identity context API1 reaches 🟡 on Cloudflare and 🟢 on AWS, and API5 reaches 🟢 on AWS. Full per-field matrix (incl. the Writ-native injection / prompt-injection / audit classes): **[usewaf.com/coverage](https://usewaf.com/coverage)**.
|
|
46
130
|
|
|
47
131
|
## License
|
|
48
132
|
|
package/package.json
CHANGED