http-attack 0.0.0-stage → 1.0.1-rc.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.0.0
+
+Adversarial probes against an HTTP API running on the local machine, as a Claude Code plugin and a standalone CLI.
+
+- Probe groups: malformed input, paths and query, raw parser errors, search (LIKE wildcards, injection), concurrent
+  duplicate creates, oversized and never-ending bodies, database faults, authentication, ownership (IDOR), CSRF, durability.
+- Stable finding ids (`<rule>:<probe>:<target>`), a rule registry with severities, and `--format json` with `schemaVersion: 1`
+  and a summary of probes run, not run, skipped and suppressed.
+- `http-attack.config.json`: per-route expectations (`public`, `bodyLimit`, `maxHeaderBytes`, `invalidUtf8`,
+  `idempotentCreate`, `vary`, `contentType`) and suppressions with a mandatory reason.
+- Exit codes: 0 no findings, 1 findings, 2 the run could not complete (crash, invalid argument, app down, no probe run, probe not run).
+- Fault injection with `--fault-sqlite`, or with any shell command set as `faultCmd`/`faultRestore` in the config file (never on the command line).
+- Bodies from files (`@body.json`) for Windows PowerShell 5.1, nested bodies (`--vary` JSON pointer), custom media types and
+  custom authentication headers.
+- Loopback hosts only. Zero runtime dependencies; Node 22.13 or newer.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nahuel Mosse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# http-attack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Adversarial probes against an HTTP API running on your machine, as an npm package with a CLI, and as a Claude Code skill that runs the same CLI.
+Unit tests prove the handler does what you thought of; http-attack sends what you did not think of, against the real
+server: malformed bodies, hostile paths, raw parser errors, concurrent duplicate creates, bodies that never end, LIKE and
+SQL injection in search, database faults, missing authentication, IDOR and CSRF. Each failure is reported with a severity,
+the response that would have been correct, and a stable id you can suppress with a reason.
+
+Zero runtime dependencies. Node 22.13 or newer. Loopback hosts only.
+
+> The probes create and delete rows, lock the database and send 50 MB bodies. Run them against a throwaway database, and
+> remember that a tunnel (`kubectl port-forward`, `ssh -L`, a cloud SQL proxy) answers on `127.0.0.1` too.
+
+## Install
+
+```bash
+npm i -D http-attack
+```
+
+## Usage
+
+```bash
+npx http-attack http://127.0.0.1:3000 \
+  --header "Authorization: Bearer $TOKEN_A" --other-header "Authorization: Bearer $TOKEN_B" \
+  --write 'POST /items {"name":"Ana","email":"ana@example.com"}' \
+  --read "/items?limit=10" --search "/items q" \
+  --unique 'POST /items {"name":"Uno","email":"uno@example.com"}' \
+  --item-path "/items/{id}" --common-headers "X-Request-Id, Cache-Control" --body-limit 65536
+```
+
+`--help` lists every option. In Windows PowerShell 5.1 put JSON bodies in a file (`--write "POST /items @body.json"`),
+because PowerShell strips the quotes of inline JSON; a body that does not parse exits 2 and shows what arrived.
+
+Exit codes: `0` no findings (after suppressions), `1` findings, `2` the run could not complete (crash, invalid argument,
+app down, no probe run, or a probe that could not run).
+
+`--format json` prints `{ schemaVersion: 1, summary, findings, rows }`. A finding id is `<rule>:<probe>:<target>`, for
+example `server-error:path-param-letters:GET /items/{id}`; it never contains generated values.
+
+## Config reference
+
+`http-attack.config.json` in the project (or `--config <path>`):
+
+```json
+{
+  "bodyLimit": 65536,
+  "commonHeaders": ["x-request-id", "cache-control"],
+  "authHeaderNames": ["x-auth-token"],
+  "itemPath": "/items/{id}",
+  "routes": {
+    "/catalog": { "public": true, "reason": "public read-only catalogue" },
+    "POST /imports": { "bodyLimit": 10485760, "invalidUtf8": "replace" },
+    "POST /things": { "idempotentCreate": true, "reason": "ON CONFLICT DO NOTHING answers 200 with the same item" }
+  },
+  "ignore": [{ "id": "parser-accepted:big-header:raw", "reason": "the load balancer caps headers at 1 MB" }]
+}
+```
+
+| Key | Meaning |
+|---|---|
+| `public` | for one route: reads and writes without credentials are expected to succeed. Needs a `reason` |
+| `bodyLimit` | the documented body limit in bytes |
+| `maxHeaderBytes` | the app's header limit; the oversized-header probe sends limit + 1 KB |
+| `invalidUtf8` | `reject` (default) or `replace` (the parser substitutes U+FFFD by design) |
+| `idempotentCreate` | for one route: several 2xx for one key are expected. Needs a `reason` |
+| `vary`, `contentType` | the body field that keeps requests apart (JSON pointer), the media type of write bodies |
+| `routes` | the settings above per path (`"/items"`), per request (`"POST /items"`) or per template (`"/items/{id}"`); `public` and `idempotentCreate` exist only here. `bodyLimit`, `maxHeaderBytes`, `invalidUtf8`, `vary`, `contentType` may also be top-level defaults |
+| `commonHeaders`, `rawExempt`, `authHeaderNames`, `itemPath`, `persistIgnore` | as the flags of the same name |
+| `faultCmd`, `faultRestore` | shell commands that break and heal the database (`docker pause db`). Config only, never a flag, because they run a shell |
+| `persistDir` | a directory outside the working and temp directories where `--persist-save` may write |
+| `writes`, `reads`, `searches`, `uniques` | the routes to attack; bodies as objects or `"@file"` |
+| `ignore` | `{ id, reason }`: a finding id, a rule name, or `<rule>:<prefix>*`; it must start with a known rule. The reason is mandatory |
+
+## CI
+
+Depend on the package and run it in the pipeline, with the app started against a scratch database:
+
+```yaml
+- run: npm ci
+- run: node app.mjs & # start the app on a scratch database
+- run: npx http-attack http://127.0.0.1:3000 --config http-attack.config.json --format json > attack.json
+```
+
+The step fails on exit 1 (findings) and exit 2 (could not run). The lockfile pins the version, so CI and the Claude Code
+skill (which prefers the project's own copy) run the same probes.
+
+## Claude Code skill
+
+The repository is also a Claude Code plugin whose skill drives the CLI: it reads the router, builds the command, triages the rows and fixes the findings.
+
+```bash
+claude plugin marketplace add NahuelMosse/http-attack
+claude plugin install http-attack@http-attack
+```
+
+Pin a release by adding the tag to the marketplace source:
+
+```bash
+claude plugin marketplace add NahuelMosse/http-attack#v1.0.0
+```
+
+Update with `claude plugin marketplace update http-attack`, then `claude plugin update http-attack@http-attack`.
+Then ask Claude to break-test your local API ("my Express API is running on localhost:3000, try to break it before I ship").
+When the project has `http-attack` in its `devDependencies`, the skill runs that copy; otherwise the one bundled in the skill (`skills/http-attack/scripts/`).
+
+The skill directory is self-contained: `npx skills add NahuelMosse/http-attack` copies only `skills/http-attack/`, and it carries its own CLI, so a vendored copy runs without the npm package.
+
+## Development
+
+```bash
+npm test                         # unit and integration tests
+node tests/e2e-fixtures.mjs 3     # attack both fixtures three times: identical results, the fixed one clean
+```
+
+`tests/fixtures/` holds a deliberately broken API and its fixed twin; the vulnerable one must keep reporting
+the ids pinned in `tests/expected-vulnerable.json`.
+
+MIT licensed. See `NOTICES.md` for the ideas this builds on.

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "http-attack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1-rc.0",
+  "description": "Adversarial probes against an HTTP API running on this machine: malformed input, parser errors, races, injection, database faults, missing auth, IDOR and CSRF.",
+  "keywords": ["http", "api", "security", "testing", "fuzzing", "idor", "csrf", "sql-injection", "hardening", "cli"],
+  "license": "MIT",
+  "author": "Nahuel Mosse",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NahuelMosse/http-attack.git"
+  },
+  "homepage": "https://github.com/NahuelMosse/http-attack#readme",
+  "bugs": {
+    "url": "https://github.com/NahuelMosse/http-attack/issues"
+  },
+  "type": "module",
+  "bin": {
+    "http-attack": "skills/http-attack/scripts/http-attack.mjs"
+  },
+  "files": [
+    "skills/http-attack",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=4 \"tests/*.test.mjs\""
+  }
+}

package/skills/http-attack/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: http-attack
+description: Break-test an HTTP API the user runs locally before shipping it. Sends malformed bodies, hostile paths, raw parser errors, concurrent duplicate creates, never-ending bodies, LIKE/SQL injection in search, database faults, missing auth, IDOR and CSRF, and reports each failure with its severity and the correct response. Use when asked to attack, harden, fuzz or break-test a local API, or to check it never answers 500. Not for code review, load tests, OpenAPI conformance, or hosts the user does not own.
+---
+
+# http-attack
+
+Unit tests prove the handler does what the developer thought of. This skill sends what the developer did not think of,
+against the real server, and reports each failure with its severity and the response that would have been correct.
+
+## Scope and safety
+
+- Only an app the user owns, running on this machine (`localhost`, `127.0.0.1`, `::1`). The script refuses other hosts.
+- **Loopback is not proof the app is local.** `kubectl port-forward`, `ssh -L`, a cloud SQL proxy or a dev tunnel all answer on
+  `127.0.0.1` while the data lives elsewhere. Confirm with the user that the app behind the port is a local process.
+- The probes create about 20-40 rows per write route, delete rows, lock the database and send 50 MB bodies. **Use a
+  throwaway database** (a scratch SQLite file, or a Postgres/MySQL database created for this run), never one with data
+  that matters. If you cannot confirm it is throwaway, stop and ask.
+
+## Method
+
+1. **Discover the surface.** Read the router (or the OpenAPI file) and list every route as one of: *create* (POST that
+   stores), *update/delete*, *read one* (`/items/{id}`), *list*, *search* (list with a free-text parameter). Note per route: the
+   auth scheme (bearer, cookie, API key, custom header), the unique keys of the stored entity, the body limit, the
+   database, the maximum header size, whether the route is public by design, and the headers every response must carry
+   (request id, `Cache-Control`, security headers).
+2. **Start the app** on a free port with the scratch database and get credentials for two users (see below).
+3. **Run the script** (below) with one `--write` per create/update route, `--read` per list, `--search` per search route,
+   `--unique` per create guarded by a unique key.
+4. **Triage every row.** `FAIL` is a finding; `NOT RUN` is a probe that could not reach a verdict (the legitimate body was
+   refused, no item route is known, no rows to search): fix the input and run again, it is never a pass. A finding that is
+   correct behaviour for this app is not a bug: say so and suppress it in the config with the reason (next section), do not
+   change the app to satisfy the probe.
+5. **Fix** real findings at the right layer (`references/fixes.md` has the fix per finding and stack), not by special-casing
+   the probe. Add a regression test per fixed finding to the app's own suite.
+6. **Re-run the same command** until it reports **0 findings, or every remaining one is suppressed in the config with its
+   reason**, and no row is `NOT RUN` (or each is suppressed with a reason). Exit code 0 means exactly that.
+7. **Clean up**: the run left rows in the scratch database; drop the database (or the file), do not reuse it.
+
+## Running it
+
+If the project lists `http-attack` in its `devDependencies`, run `npx --no-install http-attack` instead of
+`node "${CLAUDE_SKILL_DIR}/scripts/http-attack.mjs"` in every command below: it is the version CI runs. Without that
+dependency, use the copy bundled with this skill, as written.
+
+Git Bash / macOS / Linux:
+
+```bash
+MSYS_NO_PATHCONV=1 node "${CLAUDE_SKILL_DIR}/scripts/http-attack.mjs" http://127.0.0.1:3000 \
+  --header "Authorization: Bearer $TOKEN_A" --other-header "Authorization: Bearer $TOKEN_B" \
+  --write 'POST /items {"name":"Ana","email":"ana@example.com"}' \
+  --read "/items?limit=10" --search "/items q" \
+  --unique 'POST /items {"name":"Uno","email":"uno@example.com"}' \
+  --item-path "/items/{id}" --common-headers "X-Request-Id, Cache-Control" --body-limit 65536 \
+  --fault-sqlite ./data/app.db
+```
+
+Windows PowerShell (5.1 strips the quotes inside inline JSON, so put bodies in files):
+
+```powershell
+Set-Content -Encoding ascii body.json '{"name":"Ana","email":"ana@example.com"}'
+node "${CLAUDE_SKILL_DIR}/scripts/http-attack.mjs" http://127.0.0.1:3000 `
+  --header "Authorization: Bearer $env:TOKEN_A" --write "POST /items @body.json" --read "/items?limit=10"
+```
+
+An inline JSON body that does not parse exits 2 and shows what arrived. `node "${CLAUDE_SKILL_DIR}/scripts/http-attack.mjs" --help` lists every option.
+Notes:
+
+- Zero dependencies; Node 22.13 or newer.
+- Every write body gets a per-run suffix on one string field (the first containing `@`, else the first string; `--vary /item/email`
+  picks another, also nested) so a uniqueness rule never answers in place of the defense under test.
+- `--content-type application/vnd.api+json` for non-default media types; `--auth-header-name X-Auth-Token` when credentials
+  travel in a custom header; `--auth-env VAR` / `--other-auth-env VAR` keep tokens off the command line.
+- Cookie authentication: add `--csrf` and pass the cookie with `--header "Cookie: ..."`.
+- Persistence is a two-step run around a restart: `--persist-save state.json`, restart the app, `--persist-verify state.json` (the file must be inside the working or temp
+  directory, or the config must name its directory in `persistDir`).
+- Other databases: `faultCmd` (`"docker pause db"`) and `faultRestore` (`"docker unpause db"`) in the config file: any shell
+  command that breaks the database and the one that heals it (the restore always runs). They are read only from the config
+  file, never from the command line, because they run a shell: have the user review them before the run.
+- On Git Bash for Windows set `MSYS_NO_PATHCONV=1` so `/items` is not rewritten into a Windows path, and give the app and
+  `--fault-sqlite` the same absolute Windows path (`D:/app/data/app.db`).
+
+**Two users' tokens.** Use the app's own seed or signup: create two users (alice, bob) against the scratch database, log in
+as each, and export the tokens (`TOKEN_A`, `TOKEN_B`) or the session cookies. If the app has no login, a test helper that
+signs a token for two different user ids works. The ownership rows need both; without user B they are skipped.
+
+## Config file
+
+`http-attack.config.json` in the project (or `--config <path>`) holds what the command line cannot say. Per-route settings
+go under `routes` (key `"/items"`, `"POST /items"` or a template such as `"/items/{id}"`); `bodyLimit`, `maxHeaderBytes`,
+`invalidUtf8`, `vary` and `contentType` may also be given at the top level for every route. `public` and `idempotentCreate` relax
+a check, so they are accepted only inside one route and only with a `reason`:
+
+```json
+{
+  "bodyLimit": 65536,
+  "commonHeaders": ["x-request-id", "cache-control"],
+  "routes": {
+    "/catalog": { "public": true, "reason": "public read-only catalogue" },
+    "/imports": { "bodyLimit": 10485760, "invalidUtf8": "replace" },
+    "POST /things": { "idempotentCreate": true, "reason": "ON CONFLICT DO NOTHING answers 200 with the same item" }
+  },
+  "ignore": [
+    { "id": "parser-accepted:big-header:raw", "reason": "the load balancer in front caps headers at 1 MB" }
+  ]
+}
+```
+
+| Setting | Meaning |
+|---|---|
+| `public` + `reason` | reads and writes of this route without credentials are expected to succeed (the reason is mandatory) |
+| `bodyLimit` | the documented limit in bytes: the never-ending body sends limit+1 bytes, the multibyte probe is built from it |
+| `maxHeaderBytes` | the app's header limit: the oversized-header probe sends limit+1 KB |
+| `invalidUtf8` | `reject` (default) or `replace` (the parser substitutes U+FFFD by design) |
+| `idempotentCreate` + `reason` | several 2xx for one key are expected (`ON CONFLICT DO NOTHING`); the reason is mandatory |
+| `vary`, `contentType` | as the flags |
+| `ignore` | `{id, reason}`: `id` is a finding id (shown in every report row), a rule name (`stack-leak`), `<rule>:<probe>` (every target of that probe), or `<rule>:<prefix>*`. It must start with a known rule and a reason is mandatory. `not-run` is never accepted alone: name the probe (`not-run:<probe>`) so one gap cannot hide the others |
+
+The config can also hold `faultCmd`, `faultRestore`, `persistDir`, and list `writes`, `reads`, `searches`, `uniques` (bodies as objects or `"@file"`) and `persistIgnore`
+(fields skipped when comparing the persisted item).
+
+## Reading the report
+
+Each row is `pass`, `FAIL <severity>`, `NOT RUN`, `suppressed` or `skipped` (the config says it does not apply). Failures show
+`expected:`, `evidence:` and an `id:` that is stable between runs. `--format json` prints `{schemaVersion: 1, summary, findings,
+rows}`; the summary counts `run`, `passed`, `failed`, `suppressed`, `notRun`, `skipped` and findings by severity.
+Exit codes: `0` no findings, `1` findings, `2` the run could not complete (bad argument, app down, crash, zero probes run, or
+some probe not run).
+
+## Severity
+
+Every rule the script can emit; the finding id is `<rule>:<probe>:<target>`.
+
+| Rule | Severity | Meaning |
+|---|---|---|
+| `process-died` | critical | the app stopped answering during a probe |
+| `unauthenticated-access` | critical | a write or read is granted (2xx) without credentials |
+| `idor` | critical | another user's credentials reach this user's object (2xx) |
+| `sql-injection` | critical | an injected OR returns rows that a no-match control does not |
+| `duplicates-stored` | critical | concurrent identical creates stored more than one distinct item |
+| `file-served` | critical | a repo, secret or OS file came back over HTTP |
+| `csrf` | critical | a cookie-authenticated write from a foreign Origin was accepted |
+| `not-durable` | critical | a saved item is gone or different after a restart |
+| `connection-dropped` | high | the connection was closed without a response while the app stayed up |
+| `server-error` | high | a 5xx on client input (including path params, quotes and unique violations) |
+| `accepted-invalid` | high | input that must be refused got a 2xx/3xx (bad JSON, invalid UTF-8, wrong type, other methods) |
+| `no-body-limit` | high | a body over the limit is accepted, or a body that never ends is read forever |
+| `double-slash-mismatch` | high | `//x` answers 2xx with something other than `/x` |
+| `wildcard-unescaped` | high | `%` or `_` in a search reach LIKE as wildcards |
+| `parser-accepted` | high | the HTTP parser let a malformed raw request through |
+| `fault-not-reported` | high | a write during a database fault was not answered with a 5xx |
+| `limit-counts-characters` | medium | the body limit counts characters, not bytes |
+| `read-before-reject` | medium | a 50 MB body was read in full before the 415 |
+| `media-type-strict` | medium | a case or parameter variant of the media type is refused (RFC 9110 8.3.1) |
+| `stack-leak` | medium | a 5xx body leaks a stack trace, driver error or SQLSTATE |
+| `parser-no-common-headers` | medium | a parser-level error lacks the app's common headers |
+| `headers-missing` | medium | a response lacks a header every response must carry |
+| `missing-allow` | low | 405 without an `Allow` header |
+| `head-unsupported` | low | HEAD on a readable route answers 405 (RFC 9110 9.1) |
+| `not-run` | - | a probe could not reach a verdict; never a pass |
+
+A 5xx whose body leaks internals is reported twice on purpose: `server-error` (the app failed on client input) and `stack-leak`
+(what the body disclosed) have different fixes and different owners, so each keeps its own id and can be suppressed on its own.
+
+## What the script probes
+
+| Group | Probes | Correct response |
+|---|---|---|
+| input | truncated JSON, invalid UTF-8 inside a string, no `Content-Type`, `Application/JSON; charset=utf-8`, a string field sent as number/null/array/object, 1 MB body, limit+1 bytes of multibyte characters, PUT/DELETE/PATCH on the route | 4xx, never 5xx, nothing coerced or stored |
+| paths | `//x` vs `/x`, `/%`, `?x=%FF%`, 30-digit numbers in query and path parameters (`/items/999...`, `/items/abc`, invalid UUID), HEAD/OPTIONS, `/.git/config`, `/.env`, `../../etc/passwd`, win.ini | 4xx or the same resource, never 5xx; files 404 |
+| search | `%`, `_`, quotes, `\`, `' OR 1=1 --`, compared as parsed rows against a search that matches nothing | only rows containing the literal text |
+| parser (raw socket) | `GARBAGE` request line, non-ASCII bytes in the path, an oversized header, `Content-Length` with `Transfer-Encoding` | 400/431 with the common headers, connection closed |
+| resources | 50 MB `text/plain` to a JSON route, a chunked body that never ends (sends limit+1 bytes) | 415 at the first bytes; 413 at the limit or 408/close |
+| concurrency | N identical creates released together (last-byte sync) | exactly one 201, the rest 409 |
+| faults | a legitimate write while the database is locked or broken (`--fault-sqlite`, or `faultCmd` in the config) | 503/500 with a generic body, the process keeps answering |
+| auth | each write and read without credentials; user B reads and deletes A's item (after checking B can use its own) | 401 (or a redirect to login); 404/403 for B |
+| csrf | write with a foreign `Origin`, another port of the same host, `Origin: null` | 4xx |
+| durability | create, restart, read back | same status and body |
+
+Also check by hand what the script cannot: mass assignment (`"role":"admin"` on create/update), excessive data exposure, function-level
+authorization (a regular user calling admin routes), rate limits on login, business-logic abuse (double-spend of a one-time token,
+two updates with the same version, a counter below zero). Map findings to OWASP API Security Top 10 (API1, API2, API4, API5) and ASVS
+level 1 for the security floor of a whole application.
+
+## What this skill does not do
+
+- Contract conformance against an OpenAPI schema and property-based input generation: Schemathesis.
+- Stateful sequence fuzzing over a whole API: RESTler.
+- Known-CVE and misconfiguration scanning of the stack: OWASP ZAP API scan or Nuclei templates.
+- Content discovery of unlinked routes: ffuf with a wordlist.
+- Load and latency limits: a load tool.

package/skills/http-attack/references/fixes.md

@@ -0,0 +1,111 @@
+# Fixes by finding and stack
+
+Fix the cause in the app; do not special-case the probe. If a finding is correct behaviour for the route, suppress it in
+`http-attack.config.json` with the reason (see SKILL.md). Rule names are the ones in the severity table.
+
+## input: `accepted-invalid`, `server-error`, `media-type-strict`, `no-body-limit`, `limit-counts-characters`
+
+| Probe | Correct | Fix |
+|---|---|---|
+| Truncated JSON | 400 with the app's error body | catch the parse error in the body middleware |
+| Invalid UTF-8 inside a string | 400, nothing stored with U+FFFD | strict decoding (below), or accept the replacement on purpose and set `invalidUtf8: "replace"` for the route |
+| No `Content-Type` | 415, never 5xx | read the header defensively: `(h ?? '').split(';')[0].trim().toLowerCase()` |
+| `Application/JSON; charset=utf-8` | accepted | compare the media type lowercased, without parameters (RFC 9110 8.3.1) |
+| String field sent as number, null, array, object | 400/422, never coerced | validate types with a schema; never `String(x)` user input |
+| 1 MB body, limit+1 bytes of multibyte characters | 413 | count **bytes** while reading, not characters after decoding |
+| PUT/DELETE/PATCH on a route that does not take them | 405 with `Allow` | let the router answer 405 and set `Allow` |
+
+Strict UTF-8 and body limits per stack:
+
+- **Express**: `express.json({ limit: '64kb', verify: (req, res, buf) => { new TextDecoder('utf-8', { fatal: true }).decode(buf); } })`
+  and an error handler that maps `err.type === 'entity.too.large'` to 413 and `entity.parse.failed` or a `TypeError` from
+  `verify` to 400. Without `verify`, body-parser replaces invalid bytes with U+FFFD.
+- **Fastify**: `Fastify({ bodyLimit: 65536 })`; add a content-type parser with `parseAs: 'buffer'` that decodes with
+  `new TextDecoder('utf-8', { fatal: true })` and calls `done(err)` on failure. The default JSON parser replaces invalid bytes.
+- **FastAPI / Starlette**: a pydantic model rejects wrong types with 422 (`strict=True` for no coercion). Limit the body in
+  middleware that counts `await request.stream()` bytes and answers 413, or at the proxy (`--limit-max-requests` is not a body
+  limit). Invalid UTF-8 in `request.json()` raises `UnicodeDecodeError`: catch it and answer 400.
+- **Django / DRF**: `DATA_UPLOAD_MAX_MEMORY_SIZE` (default 2.5 MB) answers 400 `RequestDataTooBig`; set it to the documented limit.
+  DRF's JSON parser rejects invalid UTF-8 with a `ParseError` (400).
+- **Go net/http**: `r.Body = http.MaxBytesReader(w, r.Body, 64<<10)` answers `*http.MaxBytesError`: map it to 413. `encoding/json`
+  replaces invalid UTF-8 with U+FFFD: check `utf8.Valid(raw)` on the bytes read before `json.Unmarshal`. Use
+  `dec.DisallowUnknownFields()` and typed structs so a number sent for a string is an error.
+- **Rails**: wrap params in strong parameters and check types; the JSON parser raises `ActionDispatch::Http::Parameters::ParseError`
+  (400). Limit the body at the proxy or with Rack middleware; Rails has no default limit.
+
+## paths: `server-error` on path parameters, `double-slash-mismatch`, `file-served`
+
+- Never feed `req.url` to `new URL(path, base)`: `//x` parses as a host. Use `req.url.split('?')` or the framework's router.
+- Wrap `decodeURIComponent` and answer 400 on `URIError`.
+- Validate path parameters before the database: `^[0-9]{1,15}$` for integer ids (a 30-digit id overflows `integer` in Postgres: 22003),
+  a UUID parser for UUID ids (`not-a-uuid` is Postgres 22P02). Both are client errors: 400 or 404, not 500.
+- Serve static files from a dedicated directory, never the repository root; deny dotfiles.
+
+## search: `wildcard-unescaped`, `sql-injection`, `server-error` on quotes
+
+Bind the term as a parameter and escape the LIKE wildcards in it. The escape character must be declared where the dialect
+does not default to it:
+
+| Database | Query | Escape the term with |
+|---|---|---|
+| PostgreSQL | `name ILIKE $1` | `term.replace(/[\\%_]/g, '\\$&')`; `\` is the default LIKE escape, `ESCAPE '\'` is also valid |
+| MySQL / MariaDB | `name LIKE ?` | same; `\` is already the default escape. Do **not** write `ESCAPE '\'` in a MySQL string literal: the backslash escapes the closing quote. Write `ESCAPE '\\'` (or choose another character with `ESCAPE '!'`) |
+| SQLite | `name LIKE ? ESCAPE '\'` | same escape; SQLite has no default escape character, so `ESCAPE` is required |
+| SQL Server | `name LIKE @p ESCAPE '\'` | escape `[` too |
+
+A quote answered with 5xx is either string-built SQL (fix: parameters) or a driver rejecting the literal (`to_tsquery` with
+a bare quote: use `plainto_tsquery` or `websearch_to_tsquery`). Confirm which before calling it an injection.
+
+## parser: `parser-accepted`, `parser-no-common-headers`
+
+These answers come from the HTTP parser, before any middleware.
+
+- **Node `http`**: handle `server.on('clientError', (err, socket) => ...)` and write the status line plus the common headers
+  yourself (`HPE_HEADER_OVERFLOW` is 431). Do not raise `maxHeaderSize` to make the probe pass; if the limit is higher by design,
+  set `maxHeaderBytes` in the config.
+- **Express / Fastify**: Fastify has `clientErrorHandler`; Express uses the Node hook on the `http.Server` it wraps.
+- **uvicorn / gunicorn (FastAPI, Django)**: the server answers parser errors itself. Put the headers in the proxy in front
+  (nginx `error_page` with `add_header ... always`), then pass `--raw-exempt "nginx answers parser errors"`.
+- **Go net/http**: there is no parser-error hook; the standard server answers `400 Bad Request` with no custom headers. Set
+  the headers in the proxy that fronts it, or wrap the listener, and use `--raw-exempt`.
+- **Rails (Puma)**: Puma answers parser errors itself; add the headers at the proxy.
+- `Content-Length` together with `Transfer-Encoding` must be refused (request smuggling): keep the server's strict parsing on.
+
+## resources: `no-body-limit`, `read-before-reject`
+
+- Check `Content-Type` before reading the body (415 at the first bytes).
+- A byte limit in the body reader: answer 413 at the limit, then close with a lingering close: keep reading and discard the rest of
+  the body up to a cap. An immediate destroy resets the socket and the client loses the 413, notably with large bodies. In Node
+  (all versions) a response to a request sent with `Connection: close` (any `agent: false` client, curl `-H 'Connection: close'`,
+  HTTP/1.0) destroys the socket as soon as the response finishes, whatever the handler still reads, so consuming the body is not
+  enough: write the 413 with its `Content-Length`, keep draining, and call `res.end()` on the request's `close`. Express and
+  Fastify answering 413 from their body parser do not do this: against such a client the 413 can be lost to a reset (EPIPE
+  / ECONNRESET), which is a limitation of the client's view, not a missing limit. Plus server timeouts: Node `server.requestTimeout`,
+  `server.headersTimeout`; Go `ReadHeaderTimeout`, `ReadTimeout`; uvicorn `--timeout-keep-alive` and a proxy `client_body_timeout`;
+  Puma `first_data_timeout`.
+
+## concurrency: `duplicates-stored`, `server-error` on the race
+
+A `UNIQUE` constraint in the database, and map its violation to 409: Postgres `23505`, MySQL `1062`, SQLite
+`SQLITE_CONSTRAINT_UNIQUE`; check-then-insert in the app is not enough. For a create that is idempotent by design
+(`ON CONFLICT DO NOTHING` answering 200 with the same item) set `idempotentCreate: true` for the route.
+
+## faults: `process-died`, `fault-not-reported`, `stack-leak`, `server-error`
+
+- Await every database call inside the handler's error boundary; no fire-and-forget writes. A global `unhandledRejection` logger
+  is a backstop, not the fix.
+- Answer a fixed body (`{"error":"internal"}`) and log the error server-side: no stack, no driver message, no SQLSTATE.
+- Map "database unavailable" (pool timeout, lock, connection refused) to 503 with `Retry-After`.
+
+## auth and csrf: `unauthenticated-access`, `idor`, `csrf`
+
+- Deny by default: authentication middleware on the router, then opt routes out (and declare them `public` in the config).
+- Scope every query by owner: `WHERE id = ? AND owner = ?`, and answer 404 (not 403) for objects of another user.
+- CSRF with cookie authentication: check `Origin` (and `Sec-Fetch-Site`) against the app's own origin; `SameSite` alone does not
+  cover same-site pages on another port. Django `CsrfViewMiddleware`, Rails `protect_from_forgery` (answers 422 or 403: both
+  count as a refusal), Express `csurf` replacements or a custom Origin check, Go `http.CrossOriginProtection` (1.25+).
+- A 302 to the login page for an unauthenticated request is a refusal.
+
+## durability: `not-durable`
+
+Commit before answering; no in-memory store; migrations run on start.

package/skills/http-attack/scripts/http-attack.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// http-attack: adversarial probes against an HTTP API running on this machine. Run with --help for the options.
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { main } from './lib/cli.mjs';
+
+// Runs when this file is the entry point, also when it is reached through a symlink or a junction.
+// If the paths cannot be resolved the file still runs: a silent exit 0 would read as a clean result.
+const isEntry = () => {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return true; }
+};
+
+if (isEntry()) process.exitCode = await main(process.argv.slice(2));