# Hunt API

> Turn an API surface inventory into ranked, evidence-carrying CANDIDATES

- Skill: `encod3d-sec/hunt-api-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add encod3d-sec/hunt-api-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/encod3d-sec/hunt-api-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: Encod3d-Sec (https://skillmd.com/u/encod3d-sec)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/encod3d-sec/hunt-api-2

---


# 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/
<eng> 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 | bash` inside 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:

1. Active engagement exists (repo tree targets/<eng>/active.md) and
   <host> is on the targets/<eng>/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.)
2. hunt-core loaded (skills/exploit/hunt/hunt-core/SKILL.md - it owns
   scope gate, two-account rule, confirmation gate, enum limits; never
   restated here).
3. Producer verified - at least ONE of:
   (a) $ENG_DIR/js/<domain>/findings/endpoints.jsonl parses AND its
   manifest.sha256 sidecar passes `sha256sum -c` run FROM that
   findings/ dir on the VM (manifest paths are findings/-relative); \
   (b) $ENG_DIR/state.md asset table has >= 1 endpoint row for <host>; \
   (c) the kickoff seeded $RUN/raw/spec/.
   None = dispatch the surface lane first; never probe blind.
4. 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/<host>/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/<code> | 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 <host> 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/<object>_id/<object>_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 <deploy-scoped prefix>_
    <stable per-op tail> - 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-<host>.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-<host>.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.

