An orchestrator that never tests, six specialist agents that do, one evidence gate between them and the report, and a directory of plain files that holds the state. This is the design-level map; the repository is authoritative.
GRIMNIR is the always-resident brief. It classifies the target, confirms scope, builds the plan, delegates, tracks state and compiles the report. It never tests anything itself.
HUGINN runs Phase 0 for every target: subdomains, ports, fingerprints, crawling and JavaScript analysis. It writes the asset map and appends routing-tagged items to the shared intel feed.
Specter (API and web), ARTEMIS (GenAI, LLM, MCP), Hunter (network and AD), Nimbus (cloud) and Nomad (mobile). Each is a full methodology definition with its own scripts, reading the same shared hunting rules at startup.
Findings are born theoretical. A confirmation primitive produces a verdict and a single script promotes the finding from it. High and Critical claims need the class-appropriate artifact or they are blocked.
Merges confirmed findings from every agent into one report, deduplicates across domains, surfaces cross-domain chains and maps them to the relevant frameworks.
Agents (personas), skills (interactive procedures), commands (slash entry points) and scripts (one mechanical job each). Shared capability lives at the repo root; specialist capability lives under that specialist.
Everything about one target lives under $GRIMNIR_WORKSPACE/project/, outside the repository. Because the contract is files, a later session resumes by reading them, and a coverage claim can be reconciled against them instead of asserted.
| File | Holds |
|---|---|
scope.md, test-plan.md | Authorization, target type, the plan |
roe.json | The program's rules of engagement |
state.json | Per-agent phase, status, checkpoints |
asset-map.json | The attack surface HUGINN found |
intel.jsonl | Append-only cross-agent feed |
decisions.jsonl | Why a lane was engaged, skipped or not filed |
activity.jsonl | Every lane, finding and validation |
agent/findings/ | Structured findings, one id per agent prefix |
Non-interactive primitives each emit the same verdict record. One script reads it and is the only thing allowed to promote a finding, so a promotion cannot claim more than its evidence does.
Differential authorization, authentication and tier oracles; an out-of-band listener for blind SSRF and injection; headless rendering for XSS; SSTI, SQL injection, JWT and race oracles; and an MCP-native primitive.
A finding lists a base claim plus escalations. Each is settled on its own, promotion needs the base to survive, and the filed severity is the highest one whose claims all survived.
A linter checks outbound reports for internal identifiers, codenames and punctuation, and warns when a draft claims more than the surviving floor.
A playbook is one declarative attack chain that joins recon signals, the reachability taxonomy, a confirmation primitive and the never-submit list into a single decision unit.
The matcher ranks playbooks REACHABLE, BLOCKED or UNKNOWN against the fresh asset map, so the test plan leads with lanes that can actually fire.
A matched chain renders as runnable commands: the confirm primitive, then finding creation, then promotion from the evidence, with target-specific values left as explicit placeholders.
At /engage, reachability labels each lane and a brief sets a spend, skip or gated prior. A coverage gate at the end refuses to close on only the assets that got attention.
One confirmed roe.json per engagement holds every limit the program imposes. Scripts check it before live requests, and a missing file means conservative defaults, never unlimited.
Requests per second per host, a daily request budget and quiet hours, counted across every process in the engagement.
Required headers such as a research user agent, a scanning ban and an opt-in ban on AI tools, honored where the program asks for them.
When a proxy is set, all target traffic is routed through it and the tooling fails closed instead of connecting directly.
Read ARCHITECTURE.md in the repository → Back to the home page