AI-driven PTES framework. Behaviour under .agents/, orchestrated from root AGENTS.md.
Target:
The in-scope subject of an assessment (logical asset: an IP, domain, or URL and its agreed boundary). Identity does not change when the technical address or workspace path changes.
Avoid: Host, endpoint, asset (too generic); equating Target with directory or scan IP
Engagement workspace:
One run of an assessment on disk, identified by target_id. Exactly one Target per workspace; the same Target may have multiple workspaces over time. Multi-asset contracts become multiple workspaces, not one shared Target.
Avoid: Calling the workspace itself “the Target”; multi-Target trees under one target_id
scan_host:
The technical address tools connect to for a given workspace (may differ from how the Target is named — DNS, hosts file, pivot).
Avoid: Treating scan_host as the Target’s identity
Scope:
What this Engagement workspace may and may not touch or do (in/out of scope, time box, banned techniques). Narrows allowed action on the Target for this run. Machine-checkable in scope.md (allow_hosts / deny_hosts / window / banned): the Scope gate (scope-check.js) refuses a deny_hosts host before scanning, and the validator flags a scan_host that its own scope forbids. deny_hosts is the hard boundary; allow_hosts is soft (scan_host may legitimately differ from the Target name).
Avoid: Equating Scope with Target identity; treating Scope as optional colour text; enforcing allow_hosts as hard (it isn't — deny is)
Authorization:
The recorded permission to test. Machine dialect: handoff authorization: confirmed and/or authorization.md - status: confirmed. Without confirmed Authorization, phase ≥1 must not start (validator gate).
Avoid: Inferring consent from Scope text alone; leaving pending while advancing the Chain
PTES phase:
A numbered stage of the engagement chain with its own procedure, session packet, and manifest handoff: 0 Pre-engagement, 1 Intelligence Gathering, 1b Web pre-test, 2 Threat Modeling, 3 Vulnerability Analysis, 4 Exploitation, 5 Post Exploitation, 6 Reporting. 1b is a full phase (not a sub-step of 1); it is skippable when its trigger is absent, not a second-class stage.
Avoid: Treating 1b outputs as Phase-1 attachments without a 1b manifest; calling skippable phases “not real phases”
Phase procedure:
Execution authority for one PTES phase (steps and goals). Does not by itself define what the session may read or write.
Avoid: Treating cheatsheets or skills as procedure
Session packet:
Context-boundary contract for one phase session: allowed reads, forbidden actions, allowed writes, and knowledge bag. Machine-shaped on each phase in schema.json (session_packet); paired with the Phase procedure; isolation, not steps.
Avoid: Collapsing packet into “just the procedure”; ignoring packet as soft guidance
Chain:
Ordered PTES phases plus handoff via Manifests; progress in chain-status.md (parsed/asserted by the Schema module).
Avoid: Product-specific runner files as the chain definition; next_phase that lies about completed manifests
Manifest:
Per-phase handoff record: produced-file list plus handoff summary (schema summary keys). The next phase’s primary input surface.
Avoid: Using the Manifest as the Report; skipping summary keys
Schema:
Machine-checkable contract and module of record for Engagement workspace layout, Chain phase map, required products, handoff summary fields, forbidden paths, and Verified Vulnerability artifact patterns (schema.json).
Avoid: Using Schema as the Phase procedure; parallel phase tables in AGENTS/PTES; inventing paths outside the Schema
Environment contract:
How tools run for this workspace (container vs host, mounts, browser host). Rendered via the env adapter (env-render.js), not by re-copying docker strings into every Phase procedure.
Avoid: Each Skill inventing its own run environment; ${IP} as workspace id
Reference corpus:
Command cheatsheets as optional hints only — never execution authority and never a Knowledge tier.
Avoid: Running the engagement from sections alone; treating sections as Tier-1
Knowledge entry:
A reusable method or judgment note in the knowledge base — not engagement-specific Evidence or a Verified Vulnerability write-up.
Avoid: Promoting Target-specific findings into the knowledge base as general methods without generalization
Tier-1 knowledge:
Curated, phase-indexed knowledge the agent may load by default via LOOKUP or the session knowledge bag.
Avoid: Putting archive/import dumps in knowledge bags or the phase index
Tier-2 knowledge:
Archive or bulk-imported material consulted only after a Tier-1 miss.
Avoid: Preloading Tier-2 into every phase session
LOOKUP:
The only knowledge interface for phases: keywords → ordered Tier-1 paths (hard bag per PTES phase section), then Tier-2 on miss.
Avoid: Ad-hoc tree browsing as the primary path; treating PTES-INDEX section headers as decoration only
Signal alias:
A shared keyword vocabulary that expands handoff terms for both LOOKUP and src-hunter playbook resolve (knowledge/signal-aliases.json). Not a third corpus and not a Phase procedure.
Avoid: Duplicating incompatible keyword lists in phases; merging LOOKUP and playbook into one resolve CLI
Skill:
Reusable adapter or tool wrapper that helps a Phase procedure land files, drive tools, or look up knowledge. A Skill has no phase number and must not invent a second path or stage vocabulary. Prefer executable resolve CLIs (LOOKUP, src-hunter playbook.js) over free-association tables.
Avoid: Moving phase semantics into a Skill so the procedure only says “run the skill”; dual path names; second PTES chains inside skills
Role:
Operator identity for the agent: intake questions, compliance, and danger boundaries. Not the phase step list.
Avoid: Putting orchestration or cookbooks in Role
AGENTS.md:
Thin orchestration entry: chain order, pointers to procedures/schema/skills. Not execution authority for steps.
Avoid: Expanding AGENTS.md into full cookbooks
Threat model:
Structured judgment of this run’s attack surface and priority threats (including assumptions). Steers verification and exploitation order; it is not itself a vulnerability list.
Avoid: Treating the Threat model as Verified Vulnerabilities; ignoring it to exhaust every Raw scan result equally
Threat coverage:
Each Threat model priority_threat’s Phase-3 disposition — verified (→ VULN-NNN), refuted (with reason), or untested (with reason) — so the Threat model is a checkable gate on verification, not just advice (threat-coverage.md, handoff threat_coverage). Distinct from the Triage ledger: coverage of prioritized threats, not of every Raw scan result.
Avoid: Leaving prioritized threats with no recorded disposition; conflating threat coverage with the Triage ledger
Raw scan result:
Unverified tool output against a Target that has not been manually confirmed.
Avoid: Vulnerability, finding, hit (when treated as confirmed)
Verified Vulnerability:
A vulnerability manually confirmed against the Target. Stable identifier VULN-NNN.
Avoid: Finding, hit, alert, Raw scan result
Triage ledger:
The record of every Raw scan result’s disposition — dismissed (with reason), verifying, or promoted to a VULN-NNN — so review coverage is auditable and nothing is dropped silently. One per Phase-3 workspace (vulns/triage.md); the Report consumes it for a coverage statement. Handoff field triaged_count.
Avoid: Treating the Triage ledger as the Verified Vulnerability list or as Evidence; leaving Raw scan results untriaged
Evidence:
Artifacts (screenshots, request/response, logs) that demonstrate a security-relevant claim on the Target. When a Verified Vulnerability exists, its Evidence is bound to that item.
Avoid: Treating entire scanner dumps as Evidence; “proof” as a separate entity
Exploit log:
The record of exploitation attempts against a Verified Vulnerability.
Avoid: Report; Evidence (log is narrative of attempts, Evidence is supporting artifacts)
Access:
A foothold on the Target obtained through successful exploitation of a Verified Vulnerability.
Avoid: Calling Phase-3 confirmation “access”; shell/session as domain synonyms
Report:
The client-facing engagement deliverable, structured around Verified Vulnerabilities (scope through remediation).
Avoid: Manifest, Exploit log, or verified-vulns summary alone as the Report
Retest:
A later run against the same Target after remediation, diffed against a baseline run to show what is fixed / still open / new. Findings match across runs by vulnerability identity (normalized title), since VULN-NNN is per-run (retest.js; optional retest.md).
Avoid: Treating a retest as a fresh engagement with no baseline; matching findings across runs by per-run VULN-NNN id
- One PTES phase → one Phase procedure + one Session packet.
- Phase procedure owns phase semantics; Skills only adapt (tools/paths/knowledge), never redefine stages.
- Schema binds workspace layout, Chain map, and handoff summary keys; Environment contract + env adapter bind how tools execute.
- Manifest (files + handoff summary) is the phase-to-phase handoff surface.
- LOOKUP (executable + policy) is the only knowledge interface for phases (Tier-1 first, Tier-2 on miss only).
- Playwright executor ≠ Evidence landing; Evidence lands under Schema artifact_patterns.
- Reference corpus ≠ knowledge; Knowledge entry ≠ Evidence.
- ROLE ≠ orchestration; AGENTS ≠ cookbooks.
- Target is logical; Engagement workspace (target_id) is one run on exactly one Target; scan_host is how tools reach it.
- Scope bounds the run; Authorization is the gate before offensive work.
- Threat model prioritizes what to verify; Raw scan result → (manual confirm) → Verified Vulnerability; Evidence binds to the claim / VULN.
- Every Raw scan result gets a Triage ledger disposition; the ledger makes review coverage auditable and feeds the Report’s coverage statement.
- Exploitation produces Exploit log + Evidence; success yields Access.
- Report consumes Verified Vulnerabilities (and Access where relevant), not Raw scan results as confirmed.
- Retest diffs a later run against a baseline run of the same Target (fixed / still-open / new); it is a Reporting-adjacent step (
retest.js), not a PTES phase.