api-recon

Files (10)

• SKILL.md
• reference.md
• build_perm_tree.py · scripts/
• extract_route_map.py · scripts/
• harvest_static.py · scripts/
• package-lock.json · scripts/
• package.json · scripts/
• preload.js · scripts/
• runtime_harvest.js · scripts/
• spider_mpa.py · scripts/

SKILL.md (first lines)

# API Recon (Frontend Endpoint Reconnaissance)

Under **authorized** conditions, discover as completely as possible: **backend APIs** (paths, methods, parameters, response bodies), **frontend routes**, and **UI feature trigger points** (tabs, modals, table actions, etc.).

---

## Boundaries & Prohibitions (Agent Must-Read · Violating = Out of Scope)

This skill **only performs API / parameter-surface reconnaissance**, not vulnerability hunting or exploitation.

### Task Boundaries

| Scope | Allowed | Prohibited |
|---|---|---|
| **Target** | Enumerate path, method, parameters, routes, UI trigger points | SQLi/XSS/IDOR/brute-force/fuzz vulnerabilities, modified-packet attacks, destructive operations |
| **Auth** | Hook + stub/mock to bypass **client-side** login gates | Asking user for or guessing account passwords; attempting real login form submission |
| **Runtime** | Hook endpoints without credentials, use mock responses to let SPA enter the post-login shell | Flows that depend on a real backend session to continue |

### Credential-Free Dynamic Analysis (Phase 3 Default)

1. **Intercept and stub** login, permission, menu, and other bootstrap endpoints via `preload.js` / `runtime_harvest.js`;
2. Return **structurally correct, success business-code, data-may-be-empty** mock bodies for business query endpoints;
3. Enable the frontend to render post-login pages even without a backend or under 401 conditions, thereby triggering more XHR/fetch/WebSocket calls;
4. **Empty data, blank tables, placeholder UI blocks are expected** — do not pivot to real login or vulnerability testing for this.

**In one sentence**: Use mocks to expand frontend routes and component mounting, **only record outbound requests**; what the backend returns doesn't matter — what matters is **what other endpoints the frontend still sends**.

### Hard Process Prohibitions

| Prohibited | Alternative |
|---|---|
| grep/curl/Read main entry `index-*.js` to extract API paths before Phase 1 completes | Run `OUTDIR/harvest_static.py` |
| Hand-writing `extract_apis.py` or similar scripts to replace harvest | Modify `OUTDIR/harvest_static.py` and re-run |
| Repeating the same grep/command after ≥2 failures | Switch strategy: read tool_logs, modify harvest, consult reference |
| Skipping gates A/B, directly running originals from `scripts/` | Copy to OUTDIR and adapt for the target |
| Real username/password, OTP, OAuth, etc. authentication | stub/mock (see above) |
| Skipping stub under the pretext of "getting real data", doing IDOR/injection testing | Only record outbound; that's recon scope |
| Delete, export sensitive data, batch write, and other irreversible operations | Coverage clicks are the same |
| Claiming all pages and endpoints obtained without completing runtime + dynamic enumeration | See "Completion Definition" or note limitations |
| Claiming all parameters mastered without completing parameter trigger matrix + diff | Phase 3b matrix + Phase 5 diff |
| Inferring required/optional from a single runtime sample | Multi-sample diff or reverse-engineer from validation rules/errors |

---

## Two-Layer Model + Run Modes

| Layer | Output | Limitations |
|---|---|---|
| **Static** (JS bundle) | Full endpoint paths, draft routes, call-site field candidates | No HTTP methods; parameters need Phase 1b; misses runtime-assembled URLs |
| **Runtime** (live session) | Method + body + response + dynamic URL + WS/SSE; multi-sample diff completes parameters | Pages must actually render to send requests; single sample insufficient for required/optional |

| Run Mode | Engine | Use Case |
|---|---|---|
| **depth** | `runtime_harvest.js` (Puppeteer) | API list, METHOD/params/response body, WS/SSE, reproducible batch runs |
| **coverage** | browser + `preload.js` | Click tabs/modals/tables, deeper feature-point coverage |
| **both** | depth then coverage | Most complete, most time-consuming |

**Parameter methodology** (no universal script): paths via harvest/regex; parameters via **anchor window-expansion + UI binding chain + multi-sample diff + error reverse-inference** (grep recipes see [reference.md](reference.md) section J).

---

## Completion Definition

All must be satisfied before claiming recon complete:

- [ ] **Static**: Phase 1 harvest produces `api_static.txt`, `routes.txt`, `js/`
- [ ] **Runtime**: At least depth or coverage; coverage/both requires **Hook active + dynamic enumeration loop**
- [ ] **Shell entry**: Accessing business paths is not `/login` (note hash routing)
- [ ] **Parameters**: coverage/both completes parameter trigger matrix + `param_samples.json`; Phase 5 merges `params_merged.json`
- [ ] **Depth** (if module pages are blank): Phase 4 permission tree restored and re-run until **module-level APIs** appear (not just locale/bootstrap)
- [ ] **Delivery**: Phase 5 outputs complete (see Phase 5 output table); `insert_assets` writes service and endpoint assets

---

## Scripts & Gates

`scripts/` are reference templates only — **prohibited** to run originals directly and treat as final results.

**Rules**: Read first → adapt for target → write to `OUTDIR` (e.g. `recon/`) → record `CHANGES.md`; if not matching, rewrite per methodology, only borrow structure.

| Gate | When | Reference Script → OUTDIR Copy | Common Must-Change Items |
|---|---|---|---|
| **A (Static)** | After Phase 0, **first** harvest/spider run | `harvest_static.py` / `spider_mpa.py` | **Most sites' default regex runs directly**; only change endpoint regex, webpack/Vite `publicPath`, MPA exclude/cookie when manifest/dialect doesn't match |
| **B (Runtime)** | After Phase 2, before depth/coverage run | `runtime_harvest.js` / `preload.js` + `config.json` | Cookie/localStorage keys, neutralize success values, stubs, login regex, api prefix, hash/history |

**SPA mandatory order** (non-exchangeable; Phase numbering takes precedence over "explore first, then script"):

| Step | Required | Prohibited |
|---|---|---|
| After Phase 0 | Next Bash = `python3 OUTDIR/harvest_static.py <URL> OUTDIR` | curl/grep/Read main entry `index-*.js` (usually >500KB) |
| Gate A | Copy script → minor changes as needed → **run immediately** | Manually extract APIs first then decide whether to harvest |
| Before Phase 1 completes | `wc -l` verify outputs; 404 → fix harvest and retry | Hand-write extract scripts; repeatedly grep un-downloaded URLs |
| From Phase 1b | grep only `OUTDIR/js/*.js` | Use main bundle instead of harvest |

- ✅ Copy `harvest_static.py` → (optional) change regex → **run immediately**
- ❌ curl main bundle → grep multiple times → write temp extract → harvest only at the end
- **MPA**: After Phase 0, next Bash = `python3 OUTDIR/spider_mpa.py ...`

---

## Tool & Output Constraints

| Constraint | Description |
|---|---|
| Large files | `index-*.js` >100KB **prohibited** from Read/grep into context; use OUTDIR scripts for batch processing |
| grep output | Must `\| head -20` or `-m 5`; keep only path summaries in conversation, don't paste bundle fragments |
| Validation | Use `wc -l`, `ls \| wc -l`; don't Read entire directories |
| Regex probing | Optional, ≤1 time, only on ≤50KB small chunks or HTML; authoritative static results come from harvest |
| reference | Recipes/templates/troubleshooting see [reference.md](reference.md), don't repeat full content inline |

---

## Execution Roadmap

```
Phase 0 Classify + OUTDIR
  → Gate A → Phase 1 harvest (★ run immediately ★)
  → Phase 1b parameter reverse-engineering
  → Phase 2 auth three gates → config.json

From ijlalhaider313/ARTEX, AGPL-3.0.

More from ijlalhaider313/ARTEX