Hunt: API Security (golden-image rework)
Turn an API surface inventory into ranked, evidence-carrying CANDIDATES for BOLA/IDOR, BFLA, mass assignment, excessive data exposure, auth/JWT flaws, and rate-limit abuse. This skill produces candidates, never verdicts - findings leave ONLY through the G1 proof gate (triage).
Current emphasis (update on wiki harvest): mass assignment on PUT/PATCH update paths and API version downgrade (/v1/ under /v2/ middleware) over GET-param BOLA swaps - models over-index on over-represented old methods; the newest harvested technique leads until superseded.
Assumes hunt-core for the scope gate, two-account rule,
confirmation gate, enumeration limits, stop conditions, wiki protocol,
FIND output, and Deadends. Do not re-derive any of that here.
Wiki
Hub: [[web-moc]] - Primary page: [[api-security]] - Payload arsenal:
wiki/payloads/api.md
Anchors: [[api-testing]], [[graphql-attacks]], [[grpc-web-attacks]],
[[rsql-injection]], [[rsql]], [[rate-limit-bypass]], [[redos]],
[[jwt-attacks]]
REFS: [[api-security]], wiki/payloads/api.md
mcp__wiki-search__query (lex) "API REST GraphQL gRPC BOLA BFLA mass assignment excessive data exposure OWASP API Top 10" via wiki-search MCP - ONLY on a concrete hint the map above does not cover (a specific sink/version/CVE, an observed escape); not a blanket first step.
Shared bypass arsenal (blocked implies research, but walk this first): skills/exploit/hunt/hunt-api/references/bypass-arsenal.md - GET-copy-PUT mass-assignment discovery, async worker authz gap, GraphQL hidden-mutation/introspection-bypass ladder, cross-tenant config write.
For object-level authorization outside a formal API see hunt-idor.
Paths (binding - define once at the top of the run notes)
# seat side (wsl) - engagement tree is DOUBLE-NESTED in VMshare:
ENG_DIR=/mnt/c/Users/Lenovo/Desktop/VMshare/<eng>/<eng>
RUN=$ENG_DIR/hunt/api/<host>
# VM side (WHERE ffuf/jq/python3 run, same tree through the VMware share):
ENG_DIR=/mnt/VMshare/<eng>/<eng>
RUN=$ENG_DIR/hunt/api/<host>
Corpus and probes live in the VMshare tree; the VM runs tools against the /mnt/VMshare spelling as user tz; the seat reads the same bytes at the /mnt/c/Users/Lenovo/Desktop/VMshare spelling. The repo tree targets/ is admin/ingest only - probe artifacts NEVER land there.
Transport
Every VM-native command block ships through ONE documented transport:
cd /mnt/c/Users/Lenovo/Documents/ObisidianVaults/ZTorch/ZTorch && bash scripts/vm-ssh.sh '<command>'
- vm-ssh lands as user tz (NOT root): no root-only paths, no sudo.
- vm-ssh.sh takes the command as ONE argument. Commands containing
quotes ship as base64: write the script, then run
echo <b64> | base64 -d | bashinside the vm-ssh argument. - Non-login shells do NOT source profile.d: the PATH scope-shim is NOT active. Target-facing fetches MUST use the shim binaries by absolute path /opt/scope-shim/bin/{curl,httpx}.
- Shim verdict semantics (verified live): explicit out-of-scope host dies rc 126 (never work around it); in-scope passes; UNKNOWN hosts get an ADVISORY and the fetch proceeds - an advisory is NOT approval; verify against scope.md and self-deny anything not clearly in scope.
Entry gate
All four must pass before Step 1; each is falsifiable:
Active engagement exists (repo tree targets//active.md) and is on the targets//scope.md in-scope list. Scope-guard is the deny. (targets/ is the repo admin tree; $ENG_DIR holds corpus and run artifacts only - see Paths.)
hunt-core loaded (skills/exploit/hunt/hunt-core/SKILL.md - it owns scope gate, two-account rule, confirmation gate, enum limits; never restated here).
Producer verified - at least ONE of: (a) $ENG_DIR/js//findings/endpoints.jsonl parses AND its manifest.sha256 sidecar passes
sha256sum -crun FROM that findings/ dir on the VM (manifest paths are findings/-relative);
(b) $ENG_DIR/state.md asset table has >= 1 endpoint row for ;
(c) the kickoff seeded $RUN/raw/spec/. None = dispatch the surface lane first; never probe blind.Toolchain preflight (fails LOUD; fatal only on tools the chosen branch needs - grpcurl is probed, fatal only for the gRPC branch):
for t in /usr/bin/ffuf /usr/bin/jq /usr/bin/python3 \ /opt/scope-shim/bin/curl /opt/scope-shim/bin/httpx \ /home/tz/go/bin/httpx /home/tz/go/bin/grpcurl; do [ -x "$t" ] || { echo "MISSING TOOL: $t"; exit 1; } done
Checklist (mandatory)
Copy checklist.md (this skill's dir) to
$ENG_DIR/hunt/api/<host>/api-checklist.md at run start. Tick boxes as
steps finish; unchecked at stop = UNCHECKED lane, re-run from the first
unchecked step. The SKILL.md text and the checklist header agree
byte-for-byte on that copy target.
Nudge
Review-skill re-injection text (pinned for vocabulary match; NOTE: the completion-gate script itself emits a different generic nudge - see scripts/completion-gate.py NUDGE - both strings mean the same thing: resume at the first unchecked box):
Your work was just reviewed by the review skill and it was found
that you either missed a step of analysis, or didn't generate an
artifact of sufficient proof. Look at the markdown based checklist
and the output for each step, find what you missed, and complete
that step.
On this nudge: resume at the FIRST unchecked box of $ENG_DIR/hunt/api//api-checklist.md - never restart the run from zero. REVIEW may only be ticked after every earlier box is ticked.
Methodology
Setup: two accounts per hunt-core (A owns, B attacks, separate
profiles; internal IDs + tokens recorded as identities.md profiles
api-A/api-B). Drive load-bearing requests through Burp/Caido for
operator visibility (Skill(hunt-burp)); brute/fuzz belongs in
Intruder, not a hand-rolled loop. A throwaway shim-curl per account for
the writeup PoC is fine.
Rank before testing. Undocumented spec endpoints (classic BFLA - nobody tested the route the client does not exercise); GraphQL introspection fields the client never invokes; batching/alias endpoints (per-item authz applied per request, not per operation); bulk/export routes (higher severity per finding); non-GET verbs on read-looking routes; newest features (authz middleware lags new code).
Step 1 - Spec acquisition (terminal state per source)
Probe the standard spec locations; each source gets a terminal state (fetched | BLOCKED/ | 404-archived), one row per source URL:
mkdir -p "$RUN"/raw/spec
for p in openapi.json swagger.json api-docs swagger/v1/swagger.json \
v2/api-docs graphql; do
code=$(/opt/scope-shim/bin/curl -s -o "$RUN/raw/spec/${p//\//_}" \
-w '%{http_code}' "https://<host>/$p")
echo "https://<host>/$p -> $code" >> "$RUN/raw/spec/spec-sources.md"
done
GraphQL introspection probe (record the status code; 400 with no
introspection is a terminal row, not an error). One row per probe, all
rows same schema url -> code, bodies go to their own files:
code=$(/opt/scope-shim/bin/curl -s -o "$RUN/raw/spec/graphql-introspect.json" \
-w '%{http_code}' -X POST "https://<host>/graphql" \
-H 'Content-Type: application/json' \
-d '{"query":"{ __schema { queryType { name } } }"}')
echo "https://<host>/graphql (POST introspection) -> $code" \
>> "$RUN/raw/spec/spec-sources.md"
Every probe path 404s -> tick "N/A: no spec - discovery branch" and run Step 1b. On an SPA host the bundle IS the spec: consume the js-parser endpoints.jsonl instead of fuzzing (grep it for API_URL/route constants; prove a disputed route absent with the catch-all oracle - unregistered paths 405 non-GET and 404 GET, byte-identical to a nonsense-path probe - never via OPTIONS Allow headers, frequently a uniform lie; dead client code can call endpoints the server never mounted [[api-testing]]).
Step 1b - No-spec discovery branch (ffuf, rate-capped)
Compensating control (ffuf uses its own HTTP client, the PATH shim cannot see it): PRE-FLIGHT verify against scope.md and record the check in spec-sources.md BEFORE the run; POST-DIFF nothing needed (single fixed host; multi-host fuzzing inherits the jxscout-style host-diff control - list every host in the wordlist output and verify each against scope.md).
# wordlist lives in the REPO (ship once per engagement like jsluice-patterns.json):
# seat: cp scripts/wordlists/harness-paths.txt /mnt/c/Users/Lenovo/Desktop/VMshare/<eng>/<eng>/wordlists/api-paths.txt
# VM reads it at: $ENG_DIR/wordlists/api-paths.txt
/usr/bin/ffuf -w "$ENG_DIR"/wordlists/api-paths.txt \
-u "https://<host>/FUZZ" -rate 15 -t 1 \
-o "$RUN/raw/spec/ffuf-endpoints.json" -of json \
-fc 404
Rate cap honors no_dos. This is service discovery, bounded by RoE, NOT object enumeration - the 5-to-20 object cap does not apply and the wordlist is not clamped to 20.
Step 2 - Parse and rank
Reducer (env-passing heredoc: quoted heredoc keeps python verbatim, env expands RUN; TRUNCATE not append so re-runs are idempotent). Inputs: any fetched openapi json, the ffuf json, or the js-parser endpoints - copied into $RUN as endpoints-seed.jsonl by this one-liner when (a) is the producer path (the rename IS the declaration; gate 3(a) verified the producer's original):
cp "$ENG_DIR"/js/<domain>/findings/endpoints.jsonl \
"$RUN"/endpoints-seed.jsonl
cat > /tmp/rank.py <<'PY'
import json, os, re, glob
run = os.environ["RUN"]
out = open(run + "/endpoints.jsonl", "w")
seen, n = set(), 0
def rank(ep, method):
if "batch" in ep or "alias" in ep: return "batch"
if re.search(r"bulk|export", ep): return "bulk"
if method != "GET": return "non-get"
if re.search(r"/v[01]/", ep): return "old-version"
return "unranked"
rows = []
for f in glob.glob(run + "/raw/spec/*.json"):
try:
blob = json.load(open(f))
if isinstance(blob, dict) and "paths" in blob:
rows.append(("openapi", blob))
except Exception:
pass
seed = run + "/endpoints-seed.jsonl"
if os.path.exists(seed):
for line in open(seed):
if line.strip().startswith("{"):
rows.append(("js-parser", json.loads(line)))
for src, blob in rows:
if src == "openapi":
for ep, methods in blob["paths"].items():
for m, spec in methods.items():
if m.lower() not in ("get","post","put","patch","delete"):
continue
params = [p.get("name") for p in (spec or {}).get("parameters", [])]
rec = (ep, m.upper(), params, "openapi", rank(ep, m.upper()))
else:
rec = (blob.get("url",""), blob.get("method","GET") or "GET",
blob.get("params",[]), "js-parser",
rank(blob.get("url",""), blob.get("method","GET") or "GET"))
k = (rec[0], rec[1])
if k in seen: continue
seen.add(k)
out.write(json.dumps({"endpoint": rec[0], "method": rec[1],
"params": rec[2], "spec_source": rec[3],
"rank_reason": rec[4]}) + "
"); n += 1 out.close(); print(n) PY RUN="$RUN" python3 /tmp/rank.py
Generate ranked-targets.md (endpoint | verb | rank_reason | probe_plan)
from endpoints.jsonl - the markdown table is a GENERATED view, never
the primary store. python3 scripts/lint-md-tables.py on it before
ticking.
Step 3 - Accounts
Two accounts per hunt-core; record profiles api-A/api-B in $ENG_DIR/identities.md (create if absent; cite existing rows from a prior lane, do not duplicate).
Steps 4-11 - Class probes
Each probe: drive the load-bearing request through the proxy seat, save the full request/response pair under $RUN/probes/raw/ (filename = sha256 of method+path+body), append one JSONL row per attempt, append every (host, method, path) to $ENG_DIR/_requests.md with auth-profile-ref = api-A | api-B | -.
- Step 4 BOLA - swap object IDs cross-account (numeric, UUID, body/path/header). This IS object enumeration: <= 5 identifiers default, 20 ceiling with operator approval, 0 under no_bruteforce. Plant A's canary first (marker discipline, hunt-core); cite total/pagination counts for scale, never sweep. Full bounded-sample loop: hunt-idor. NOT: 200 echoing your own request; a shared/public/org-visible object. IS: B's session returns A's actual data matching A's baseline, clean session.
- Step 5 BFLA - call admin/privileged methods as B; swap verb (GET -> PUT/DELETE); hit the undocumented spec endpoints. IS confirmation: the privileged action EXECUTED, not a bare 200.
- Step 6 Mass assignment - add role/isAdmin/verified/balance to PUT/PATCH bodies. Create filtering says nothing about UPDATE handlers (written separately) - re-submit the same field there with the id in the BODY as well as the query (id/_id/_number aliases; query-only is often rejected). IS confirmation: fresh authenticated read shows the field took effect.
- Step 7 Excessive data exposure - diff raw responses vs what the UI renders (full objects, other users' fields, internal flags). 200 with redacted/null fields = server-side filtering WORKING.
- Step 8 Auth/JWT - alg:none, weak secret, kid injection ([[jwt-attacks]]), API-key reuse, missing-auth routes, OAuth scope creep.
- Step 9 GraphQL (N/A: no GraphQL surface) - batching/aliases
(rate-limit bypass), nested-query depth, field suggestions.
Payloads: [[graphql-attacks]].
On an APQ-only gateway (ad-hoc queries rejected) the replay rules:
- Hash source order: MAIN-bundle embedded registry first (some builds ship the full op->composite table as a webpack data module - grep op names for adjacent <64hex>_<128hex> pairs), THEN live-traffic capture for ops the registry lacks. Lazy chunks never carry hashes.
- Treat a captured keyring as valid for ONE deploy only, but do NOT discard it on rotation: the composite splits _ - on a new deploy ALL prefixes rotate while tails stay near-invariant, so DIFF old vs new registry and re-stamp the prefix from the live bundle; yesterday's entry then executes again. Compare the live bundle name against the corpus bundle to detect rotation first. Full model: references/apq-replay.md Gate 3.
- Hash binding: the APQ retry path verifies sha256(text)==hash before execution (one alias insertion -> PERSISTED_QUERY_HASH_MISMATCH; ad-hoc queries without persistedQuery -> masked ISE) - field-level probing (over-fetch, introspection) is dead at the gate on a hash-binding gateway; test VARIABLES on registered ops, never fields. The alias-probe doubles as a per-deploy canary for binding regressions.
- Canonical executing body = {"variables":{...},"extensions": {"persistedQuery":{...}}} - operationName is OPTIONAL but, if present, must exactly match the registry entry for that hash; a mismatched operationName alongside a valid hash silently masks to the uniform error (ISE or PQNF). Verify with a KNOWN-executing op first.
- Read uniform ISE/PQNF as "unregistered/mismatch", not as a crash:
gateways use one masked error for every resolution failure; probe
a KNOWN-executing op first to prove the transport, then diff.
Full capture-to-curl pipeline (composite hash format, framing,
rotation detection, error-oracle table, retry discipline,
hash-capture recipe):
references/apq-replay.md.
- Step 10 gRPC (N/A: no gRPC surface; also "N/A: grpcurl absent on VM (install failed)") - reflection, grpcurl calls, protobuf field tamper, same authz tests as REST.
- Step 11 Rate/resource - bounded burst proving the throttle absent on a sensitive action; NEVER volume against a live auth endpoint; honor no_bruteforce/no_dos. [[rate-limit-bypass]].
Every probe JSONL row: {class, host, endpoint, method, evidence (absolute probes/raw/ path), observed, confidence}.
Step 12 - Bypass ladder (every 403 / stripped field / dead end from 4-6)
Not closed until tried: parameter pollution (?id=A&id=B - check and fetch may read different occurrences), array/nested wrapping ({"user":{"role":"admin"}}), casing/separator variants (isAdmin/is_admin/admin), alternate content-type (form vs JSON vs XML), verb-override headers (X-HTTP-Method-Override), version downgrade (/v1/ predates /v2/ middleware - the most reliable), and batching to skip per-item authz. One row per tried bypass with outcome in probes/bypass.md; the artifact is non-empty even when all fail.
Chain: mass assignment taking effect -> privilege escalation -> re-run Step 5 (BFLA) as the escalated principal. Quota/price/limit abuse hands off to hunt-bizlogic.
Step 13 - Exit artifact (candidates)
Merge probe JSONLs (union, truncate+dedupe on endpoint+method+class; keys class|host|endpoint|method|evidence|confidence|next). candidates.md carries the human table + probe counts with EVERY class section present ("no hits" where true - a missing class section = failed lane; an explicit empty note = clean target).
Step 14 - Pointer + ledgers
$ENG_DIR/hunt-api-.md is a thin pointer carrying:
API-HUNT-DONE endpoints=<n> probes=<n> candidates=<n>
(bola=<n> bfla=<n> massassign=<n> exposure=<n> auth=<n>
graphql=<n> grpc=<n> ratelimit=<n>)
Plus: _requests.md rows complete, state.md asset rows (access=exploit-candidate, source=hunt-api, dedupe url+endpoint), Deadends rows with the WHY.
Confirmation gate
NOT confirmation: a 200 echoing your own request back; an empty or shell response; B seeing an object that is shared, public, or org-visible; a body you have not compared against A's baseline; a BFLA endpoint returning 200 without the privileged action actually performed; a mass-assignment write returning 200 with the extra field accepted but the privileged field never verified in effect; any result not re-verified in a clean session.
IS confirmation:
- BOLA - B's low-priv session returns A's actual data, matching A's own baseline response, legitimate/shared access ruled out, reproduced in a clean session.
- BFLA - a low-priv token reaching AND executing an admin function (perform the action, do not just get a 200).
- Mass assignment - the privileged field verified in effect from a fresh authenticated read.
Candidates carry proof inputs; the FIND verdict belongs to triage/G1.
Validation
- Proof = content belonging to ANOTHER account/tenant in the response, with a unique canary written by A and read via B (two-account rule).
- Negative control: a randomized/nonexistent object id returns 404 or empty; that makes the 200-on-B a real object read, not a stub.
- Counterevidence: 200 with redacted/null fields is server-side filtering WORKING.
False Positives
- 200 with fields stripped = authorization working, not BOLA.
- Soft-deleted object shadowing (own data, deleted, still readable).
- Own-account data mistaken for another's: plant the marker first.
- Public-by-design endpoints (docs, catalogs) read as broken authz.
- 429 read as authz failure; it is rate limiting, not access control.
Cross-routing
- hunt-idor for object-level flaws outside a formal API (UI routes, direct object links).
- hunt-auth when the failure is token scope/audience, not object id.
- hunt-bizlogic for quota/price/limit abuse on API endpoints.
- GraphQL traversal/introspection depth: hunt-injection.
Severity
- CRITICAL - unauthenticated admin action, or cross-tenant data access.
- HIGH - BOLA/BFLA reaching other users' data or functions; mass-assignment privilege escalation.
- MEDIUM - excessive data exposure; missing or weak rate limiting.
Deadends
Append: - [ ] API on <host> <endpoint> -- BOLA/BFLA/mass-assign all
enforced; extra fields ignored; JWT validated; introspection off
Record what you tried (pollution/array/verb/version-downgrade/batch), not just that it failed.
N/A escapes
- "N/A: no spec - discovery branch" (every spec probe 404'd)
- "N/A: spec found" (Step 1b skipped)
- "N/A: no GraphQL surface"
- "N/A: no gRPC surface" / "N/A: grpcurl absent on VM (install failed)" An N/A tick is a claim with a reason, never a silent pass. Identical strings in SKILL.md and checklist.md.
Bitter-pill variant
When the kickoff designates this run freehand: skip the checklist copy and numbered steps, one freehand pass over the surface inventory, output lands ONLY in $RUN/analysis/bitter-pill.md (tried / found / dismissed, every claim carries file:line). Never edits structured outputs. Proof gates still apply - freehand never skips proof. Declare with one _requests.md row (lane = hunt-api-bitterpill) so completion-gate routes to this artifact contract instead of the checklist ledger.
Depth walk (mandatory)
Walk EVERY applicable row of the payload arsenal page cited above.
Record each row in $RUN/coverage-depth.md as a table
| row | state | evidence | where state is probed, blocked, or
N/A, and evidence is a probe-pair path or a Deadends.md line. A bare
probed with no evidence reference fails the completion gate
(NEEDS-REVIEW). N/A rows cite why (surface shape forbids it).
Blocked implies research: before any Deadend is claimable on a blocked
row, (a) walk the arsenal page's bypass-ladder rows for that control
class, and (b) run one wiki query AND one mcp__wigolo__search for the
specific tech-plus-control bypass. Results, or a genuine null, land in
coverage-depth.md. "No research tried" is not a claimable state.
Exit artifact + handoff
ONE exit artifact set: $RUN/candidates.jsonl (machine) +
candidates.md (human) + $ENG_DIR/hunt-api-.md (pointer with
API-HUNT-DONE + counts). The consumer (triage) finds at $RUN:
ranked-targets.md, endpoints.jsonl, probes/.jsonl, probes/raw/,
candidates.{jsonl,md}. Findings leave ONLY through G1 (triage).
Distill confirmed GENERIC patterns: python3 scripts/wiki-stage.py --kind technique --slug <slug> --target-page techniques/web/api-security.md.
After writing $RUN/surfaces.jsonl, import the surfaced spec paths
and endpoints into the hunt feed: one JSON row per surface
{"surface": "<endpoint>", "host": "<host>", "class_hint": "api"},
then python3 scripts/surface_backlog.py <eng> import-jsonl $RUN/surfaces.jsonl --source hunt-api.
Stop conditions
Terminal states complete (probed | N/A with reason | deadend row written), nothing written into skill dirs (skills/exploit/hunt/ hunt-api/ stays untouched), no unchecked boxes above REVIEW. hunt-core stop conditions fire unchanged (a confirmed auth-bypass or data exposure = report at the primitive, do not keep enumerating past proof).
Attack surface
APPROACH: Get the spec (Swagger/introspection/.proto), then rank undocumented/undialed endpoints, batching/alias ops, bulk/export routes and non-GET verbs; run BOLA (cross-account ID swap), BFLA (privileged call as low-priv), and mass assignment (role/isAdmin), driving load-bearing requests through Burp.
AVOID: A 200 echoing your own request, an object that is shared/public/org-visible, a BFLA 200 without the action performed, or a mass-assign field merely accepted is NOT confirmation - verify B pulls A's data / the privileged action executes / the field takes effect on a fresh read.