coordination

Files (22)

• SKILL.md
• ATTACK_INDEX.md · reference/
• GIT_CONVENTIONS.md · reference/
• OUTPUT_STRUCTURE.md · reference/
• PATT_STANDARD.md · reference/
• VALIDATION.md · reference/
• bookkeeping.md · reference/
• context-injection.md · reference/
• coordinator.md · reference/
• coverage-matrix.md · reference/
• creative-research.md · reference/
• credential-loading.md · reference/
• executor-role.md · reference/
• intelligence-gateway.md · reference/
• orchestrator.md · reference/
• output-discipline.md · reference/
• preflight-checklist.md · reference/
• principles.md · reference/
• role-matrix.md · reference/
• skeptic-role.md · reference/
• spawning-recipes.md · reference/
• validator-role.md · reference/

SKILL.md (first lines)

# Coordination

Runs as a spawned subagent (one per target). Within its own context, the coordinator holds engagement state inline — it does not delegate its thinking to further sub-subagents. Thinks before every action.

The parent orchestrator (main session) **must not** execute this workflow inline. If you find yourself doing P1-P5 in the main session, you skipped the spawn step in `skills/hackthebox/SKILL.md` (or the relevant platform skill) and the bookkeeping discipline is silently disabled.

## Principle (Rule 0)

**Source code first.** Read all accessible source — application code, config, scripts, share contents — before any executor batch. Every answer is in the data you already have. Guessing without reading is the most common failure mode.

## Workflow

```
P0: Ingest scope
 ↓
P0.5: Profiling & AI Reasoning (MANDATORY) — Fingerprint services/tech stack. Apply AI reasoning to plan pentesting workflow. See `reference/intelligence-gateway.md` for gateway checks (Human Approval required). Do not execute skills until complete.
 ↓
P1: Recon + read source code → write attack-chain.md → run preflight-checklist
 ↓
┌→ P2: Think — read chain + experiments.md, write 3 hypotheses (≥1 [wildcard]), pick 1-2 to test
│  P2b: Research (conditional) — see reference/creative-research.md
│  P3: Execute — spawn 1-2 executors with CHAIN_CONTEXT [+ RESEARCH_BRIEF]
│  P4: Integrate — read results, update chain, revise theory
│      No progress 1 batch → consider P2b
│      goal_attempts ≥ 3 on any conceptual goal → P4b
│      Goal → P5
└─ loop (max 30 experiments; mandatory skeptic at experiments 5, 15, 25)

P4b: Reset — re-read all recon + source + chain. Creative Research (mandatory). Fresh theory.
P5: Validate + Report
```

### Steps

1. **Tech Stack Profiling & AI Reasoning (MANDATORY)** — Before any active skills execute, read and fingerprint the target to identify services and the technology stack. Apply AI-based reasoning to formulate a customized penetration testing workflow and plan following the Enterprise AI Intelligence Gateway (`reference/intelligence-gateway.md`). Wait for Human Approval before dispatching executor skills.
2. **Recon + Source Code** — read all accessible code (see `formats/reconnaissance.md`). Run pre-flight checklist (`reference/preflight-checklist.md`).
3. **Think** — write 3 hypotheses to `attack-chain.md`, ≥1 tagged `[wildcard]`. Pick 1-2 to spawn.
4. **Test** — 1-2 executors per batch, integrate before next.
5. **Validate** — finding-validator per finding + engagement-thoroughness validator at P5 (see `reference/validator-role.md`).
6. **Report** — validated findings in `{OUTPUT_DIR}/artifacts/validated/` → Transilience PDF via `formats/transilience-report-style/SKILL.md`.

## attack-chain.md

`{OUTPUT_DIR}/attack-chain.md`. Updated every batch. Sections: services, surface, theory (3 hypotheses + chosen), tested, next. Bullets, max 50 lines, prune old items to one-liners.

## Bookkeeping

experiments.md ledger, tools/ logs, EXPERIMENT_ID injection, conceptual-goal counting — see `reference/bookkeeping.md`.

## Creative Research (P2b)

Triggers: P4b reset (mandatory), goal_attempts ≥ 3 on any goal, novel error class, source code unreadable, every executor returned negative, no hypothesis at P2, no progress for 1 batch. See `reference/creative-research.md`. Most batches skip P2b.

## Spawning

See `reference/spawning-recipes.md` for copy-paste-ready spawn patterns per role. Context contracts in `reference/context-injection.md`. Role boundaries in `reference/role-matrix.md`.

## Roles

| Role | File | Context | When |
|------|------|---------|------|
| Executor (explore) | `reference/executor-role.md` | Full chain + skills | Recon / breadth |
| Executor (exploit) | `reference/executor-role.md` | Full chain + skills + scenarios | Confirmed theory |
| Skeptic | `reference/skeptic-role.md` | experiments.md + recon (no chain) | Mandatory at experiments 5, 15, 25 |
| Validator (finding) | `reference/validator-role.md` | Evidence only (blind) | One per finding |
| Validator (engagement) | `reference/validator-role.md` | OUTPUT_DIR only (blind) | At P5 |

## Rules

1. **Autonomous.** Coordinator MUST NOT call `AskUserQuestion`. If a credential is missing, run `python3 tools/env-reader.py`; if it returns NOT_SET, terminate with `status=BLOCKED` and emit a clear blocker. Asking is the parent orchestrator's job (except for the Human Approval gate in Phase 0.5).
2. **Mandatory Profiling & Reasoning (Intelligence Gateway).** Before executing any active skills against the target, you MUST profile the technology stack (services used, frameworks, architecture) and apply AI-based reasoning to determine the optimal penetration testing workflow. See `reference/intelligence-gateway.md`. Any attempt to execute a Skill directly must be rejected.
3. **Think before acting.** Write 3 hypotheses (≥1 wildcard) to attack-chain.md before every batch. Record rejected ones — they are the search tree.
4. **Max 1-2 executors per batch.** Recon can use more.
5. **Pass chain context + specific PATT_URL** to executors. Not the full PATT map.
6. **30-experiment cap.**
7. **goal_attempts ≥ 3 on a conceptual goal** → P4b reset. Count by *goal*, not literal technique string. Five PKINIT cert variants chasing "use this cert to authenticate" = five strikes against one goal. See `reference/bookkeeping.md` for the goal column.
8. **Mandatory skeptic** at experiments 5, 15, 25 (see `reference/skeptic-role.md`).
9. **All output to OUTPUT_DIR.**
10. **Sequential flag progression** in multi-flag engagements. User-foothold first; root path usually flows from there.
11. **No partial completion as a success state.** A multi-flag engagement is incomplete until every flag submits. `status=FAILED_partial` is a temporary marker, never a final outcome.
12. **Phase 3 (skill-update + Slack + queue) is parent-orchestrator only.** Coordinator emits PHASE3_SUMMARY and exits.
13. **Source for library internals.** Before writing Python against any library API (Impacket, ldap3, pyasn1), read the source. Prefer CLI tools (secretsdump.py, ticketer.py, getST.py).
14. **Background command discipline.** State the specific result a tunnel/relay/listener will produce before spawning.
15. **Report gate.** Validated findings exist → Transilience PDF report required. Read `formats/transilience-report-style/pentest-report.md`.
16. **Validation completeness.** After validators run, every validated finding has `evidence/validation/validation-summary.md`. Flag any without proof.

## Token Discipline

- Internal output (chain, logs, reports): bullets, not prose.
- Executor prompts: 1-2 relevant skill files + the specific PATT_URL.
- attack-chain.md max 50 lines; bookkeeping max 10% of mission tokens.
- User-facing output (reports, summaries): detailed.

## References

`reference/intelligence-gateway.md` · `reference/principles.md` · `reference/preflight-checklist.md` · `reference/role-matrix.md` · `reference/bookkeeping.md` · `reference/spawning-recipes.md` · `reference/context-injection.md` · `reference/creative-research.md` · `reference/executor-role.md` · `reference/skeptic-role.md` · `reference/validator-role.md` · `reference/VALIDATION.md` · `reference/ATTACK_INDEX.md` · `reference/OUTPUT_STRUCTURE.md` · `reference/GIT_CONVENTIONS.md` · `formats/INDEX.md`

From gohilrajbha0312/Pentest-tool, MIT.