Skip to content

AGENTS.md

Latest commit

 

History

History
261 lines (186 loc) · 11.5 KB

AGENTS.md

File metadata and controls

261 lines (186 loc) · 11.5 KB
Raw

Pentester Agent Framework

Orchestration entry. Behaviour/compliance: .agents/ROLE.md.
Execution authority: .agents/phases/. Contract: .agents/schema/schema.json.

Skills (Layer 2 adapters): .agents/skills/pentester-*/SKILL.md
Third-party depth packs: .agents/skills/third-party/<name>/SKILL.md (nested OK; see third-party/PHASE_MAP.md)

Language

  1. Detect the user's language from their messages (e.g. Chinese → 中文, English → English).
  2. All agent-facing prose uses that language: chat, intake questions, progress notes, handoff commentary, Report body (report.md), engagement diary (target/${ID}/solutions.md).
  3. Keep technical identifiers in English: VULN-NNN, paths, schema keys, CVE, CVSS, PTES, CLI flags.
  4. Phase procedures / skill docs are English technical SSOT; manifest machine dialect is bilingual (交接摘要 | Summary — see schema.json). Do not mix random languages in one Report.

Before you begin

  1. .agents/ROLE.md — identity, intake, compliance
  2. .agents/schema/ — schema.json + env.md + target-schema.md
  3. .agents/phases/ — execute phases (session packet)

Map

Path Role
.agents/ROLE.md Identity, intake, compliance, danger ops
.agents/schema/schema.json Module of record: Chain map, paths, session_packet, handoff keys
.agents/schema/env.md Environment contract · env-render.js · materialize.js
.agents/schema/evidence-land.md Playwright → Evidence landing
.agents/REPORT-SKELETON.md Report fill interface · check-report.js
.agents/knowledge/reporting/report-wording-depth.md Optional wording depth only (not second authority)
.agents/phases/ Phase procedure + session packet
.agents/PTES.md Pointer routing only
.agents/knowledge/LOOKUP.md Knowledge interface · bin/lookup.js
.agents/skills/ Adapters (sole skill authority; no host mirror trees in git)
.agents/mcp/ Optional MCP — skip if INDEX empty
target/${ID}/ Engagement workspace
examples/schema-mini/ Golden Schema fixture
docs/agents/ issue-tracker, domain, host-skills, archive-locality

Chain

0 → 1 → 1b? → 2 → 3 → 4 → 5 → 6

Phase map SSOT:

node .agents/schema/validate-target-schema.js --print-phase-map

Handoff: Manifest (files + handoff summary) →
node .agents/schema/validate-target-schema.js ${ID} --strict-summary --stamp-chain

Authorization: handoff authorization: confirmed (or authorization.md - status: confirmed) required before phase ≥1 / full fixture.

URL Target: Phase 0 still bootstraps; only RoE Q&A may simplify (phases/00).

Phase order is inviolable. Parallelism applies only inside a single phase — never run Phase N+1 work before Phase N handoff + validate pass.

Phase-internal parallelism & Subagent strategy

Hard boundary

Layer Rule
Cross-phase Serial only: 0 → 1 → 1b? → 2 → 3 → 4 → 5 → 6. Schema validate + resolve-skills + authorization gates unchanged.
Inside one phase Maximize parallelism via subagents for independent / long / dictionary-heavy work.

When a task must go to a subagent

Inside the current phase, must delegate if any of:

  1. Independent — no hard dependency on another in-flight task's result
  2. Long-running — port scans, dirbust, Playwright deep crawl, heavy fuzz, hydra, sqlmap, nuclei deep, source hunting, large report assembly
  3. Large dictionaries / bulk data — PentesterSpecialDict / raft / multi-wordlist fuzz or parse

Main agent must not monopolize the session running those jobs inline when subagents are available.

Main agent responsibilities (orchestrator only)

  1. Decompose phase work + dependency graph
  2. Maintain & re-print the Phase Task List (mandatory — see below)
  3. Skill gate: resolve-skills.js + Read MUST skills (main or short subagent OK)
  4. Spawn subagents with clear scope, output paths, no/short timeout policy
  5. Merge subagent outputs into Schema product paths only
  6. Phase close: manifest + validate-target-schema.js ${ID} --strict-summary [--stamp-chain]

Main agent does: threat-model synthesis, triage disposition decisions needing judgment, user-facing intake/questions, dangerous-op approval, final handoff keys.
Main agent does not: sit on a single long nmap/ffuf/sqlmap/playwright job when it can be a subagent.

Subagent contract

Each subagent prompt must include:

  • ${ID}, ${SCAN_HOST}, scan_env, phase id
  • Exact commands (prefer env-render / guard.js pre-flight for active scans)
  • Write paths under target/${ID}/ (Schema artifact_patterns / phase paths only)
  • Scope / authorization constraints; no expanding RoE
  • Return format: files written + short summary (stdout)

Subagents must not: advance the phase chain, rewrite authorization, invent alternate product trees, or skip guard.js for offensive commands.

Parallel waves

Wave 1: all tasks with deps = ∅  → spawn in parallel
Wave 2: deps all completed       → spawn in parallel
…
Main: merge → write remaining schema products → Task List final → validate

Independent scans (e.g. TCP full + UDP top + passive OSINT) → same wave.
Dirbust that needs open web ports → after port/service wave.

Task List display (mandatory)

At phase start, after skill gate, and every time a task starts/completes/fails, re-print the full table in the user language. Do not omit.

### Current Phase Task List (Phase X)

| ID | 任务描述 | 执行方式 | 状态 | 依赖 | 备注 |
|----|----------|----------|------|------|------|
| T1 | … | subagent | running | - | 无 timeout |
| T2 | … | subagent | pending | T1 | 无 timeout |
| T3 | … | 主 Agent | pending | T1,T2 | - |
Column Values
执行方式 subagent | 主 Agent
状态 pending | running | completed | failed
依赖 - or T1,T2
备注 long jobs: always mark 无 timeout when applicable

Optional: also write target/${ID}/task-list-phase-${N}.md for audit (does not replace chat re-print).

Subagent timeout policy (long scans & large dicts)

Aligned with ROLE § Long-running operations.

Forbidden: short default timeouts on long / dictionary jobs.

Class Examples Timeout
Deep / full scan nmap -p- / deep scripts, masscan none or ≥ 3600s / 0 = infinite
Dirbust / fuzz gobuster, ffuf, feroxbuster, dirsearch + large wordlists none or ≥ 3600s / 0
Brute hydra, medusa, patator none or ≥ 3600s / 0
App abuse sqlmap, nuclei deep templates none or ≥ 3600s / 0
Browser Playwright long recon / multi-role crawl none or ≥ 3600s / 0
Any large-dict path under .agents/wordlists/PentesterSpecialDict/ none or ≥ 3600s / 0

If the host requires a timeout parameter, pass an explicit very large value and set Task List 备注 = 无 timeout (meaning: not using a short operational timeout).
If no output >10 minutes, ask the user (do not kill silently). Prefer wordlists via ensure.js + docker /wordlists.

Quick / judgment tasks (handoff parse, short curl, STRIDE table edit) may stay on main agent with normal tool timeouts.

Skills

Hard rule — resolve + load skills at phase entry

Auto-matching on user keywords is not enough. At the start of every phase:

node .agents/skills/resolve-skills.js --id ${ID} --phase <N> --write --strict
  1. Read .agents/phases/<NN>-….md
  2. Run resolve-skills (content-driven plan from handoffs / threat-model / Signals)
  3. Read every path under MUST Read in order and follow those skills
  4. Optional: --signals "sqli,xss" to force extra depth packs

Map SSOT: .agents/skills/skill-map.json · human notes: third-party/PHASE_MAP.md

Skipping resolve-skills / Skill gate is a process defect (same class as skipping validate).

Framework adapters (pentester-*)

Skill Phase Role
pentester-init-target 0 materialize
pentester-enum-services 1 Schema plan / product paths
pentester-recon 1 recon methodology + attack-surface map
pentester-playwright 1b / 3 / 4 Browser + Evidence landing
pentester-src-hunter 1b / 3 / 4 playbook.js --signal
pentester-threat-model 2 STRIDE + Signal mapping
pentester-scan-ingest 1 / 3 raw scanner → Triage ledger
pentester-exploit 4 PoC / exploit-db / msf path
pentester-waf-bypass 4 filter / WAF bypass when blocked
pentester-post-exploit 5 situational / lateral, scope-gated
pentester-gen-report 6 SKELETON + check-report
pentester-knowledge-base any LOOKUP runtime
pentester-knowledge-import maint Offline archive · import.js
pentester-toolkit any DotSlash tools (.agents/tools/)
pentester-mcp-manager any MCP if INDEX non-empty
pentester-update-solution any Target-local notes only
pentester-setup-tools setup Deps

Third-party (third-party/, nested)

Vendor packs (VulnClaw specialized). Technique depth only — never replace Schema products or phase order. Index: .agents/skills/third-party/README.md.

Knowledge

node .agents/bin/lookup.js --phase ${N} --keywords "…"

Tier-1 first; miss → tier-2. Prefer external KNOWLEDGE_ARCHIVE_ROOT for bulk packs (docs/agents/archive-locality.md).

MCP

If .agents/mcp/INDEX.md has no tools → skip entirely.

Phase transition

□ Skill gate: `resolve-skills.js --phase N --write --strict` + all MUST Read paths Read
□ Task List published (phase start) and kept current until phase end
□ Long / independent / dict tasks delegated to subagents (no short timeout)
□ Schema path products written (main merges subagent outputs)
□ Manifest + handoff summary keys
□ Authorization confirmed if phase ≥1
□ validate --strict-summary [--stamp-chain] pass
□ Task List final (all terminal states: completed|failed)
□ reusable method → pentester-knowledge-base
□ temp files cleaned
□ user progress sync (user language) — `node .agents/schema/status.js ${ID}` for the one-screen view

Env (pointer)

.agents/schema/env.md — ${ID} / ${SCAN_HOST} / docker mount / Playwright host.
node .agents/schema/env-render.js --scan-env … --id … --host …
Wordlists submodule: node .agents/wordlists/ensure.js (or npm run setup:dicts) before fuzz.

Report

Phase 6 fills REPORT-SKELETON in the user's language, then check-report.js / validate … --check-report [--stamp-chain].
Assemble data sections: schema/assemble-report.js ${ID}. Deliver: schema/deliver.js ${ID}.
Remediation retest (re-run vs a baseline): schema/retest.js --baseline <old> --current ${ID} --write.
Optional wording depth: knowledge/reporting/report-wording-depth.md (not second authority).

Agent skills

Issue tracker

Issues live in this repo's GitHub Issues via the gh CLI. See docs/agents/issue-tracker.md.

Triage labels

Default five-role vocabulary: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. See docs/agents/triage-labels.md.

Domain docs

Single-context: root CONTEXT.md + docs/adr/. See docs/agents/domain.md.