Pentests, assets & phases

The anatomy of a pentest — its type and mode, its lifecycle states, the assets that inventory its targets, the Rules of Engagement that authorize them, and the three phases agents work through.

Pentest

A pentest is a single engagement against a defined target. Two attributes are set when you create it and never change:

Type — what kind of target is being assessed:
- web — a web application
- api — an HTTP API
- server — a host or network service
Mode — how the engagement is driven:
- guided — you select the agents for each phase and advance one phase at a time
- automatic — default agents are assigned to every phase and run end to end without intervention

Creating the pentest is not enough to start it. You also need an active Rules of Engagement that covers every asset. Without one, the orchestrator refuses to start (no_active_roe). See Engagement, RoE & kill switch.

Lifecycle states

A pentest moves through a well-defined set of states. Only valid transitions are allowed.

State	Meaning
`draft`	Just created, not yet configured
`configured`	Has a type, methodology and at least one asset; ready to run
`running`	A phase is actively executing
`phase_completed`	The current phase finished; awaiting the next one
`processing`	Final results are being processed
`completed`	Finished successfully (terminal)
`paused`	Paused by the user
`cancelled`	Cancelled by the user (terminal)
`archived`	Archived after inactivity (terminal)
`failed`	An error occurred during execution

Kill is not a lifecycle state. It is a control flag: POST /pentests/{id}/kill forces a terminal stop and preserves evidence. The pentest still lands in a terminal state (completed, cancelled or failed). That is distinct from cancelled, which is the result of asking the Go streaming backend to stop the current stream. See cancel vs kill.

A pentest that sits idle while configured or running is archived automatically after a period of inactivity, and the owner is notified by email.

Assets

Assets are the inventory — the concrete targets attached to the pentest. They are not the legal or operational authorization to touch those targets; that is the Rules of Engagement. Both are required. A pentest needs at least one asset, and exactly one should be marked primary (is_primary: true), which the agents attack first.

Each asset has an asset_type:

`asset_type`	Example value
`url`	`https://example.com/app`
`domain`	`example.com`
`ip`	`192.168.1.100`
`api`	`api.example.com/v1/`

A single pentest can mix asset types — for example a primary domain plus a couple of supporting url and ip assets.

{
  "assets": [
    {"asset_type": "domain", "asset_value": "example.com", "is_primary": true},
    {"asset_type": "ip", "asset_value": "192.168.1.100"},
    {"asset_type": "url", "asset_value": "https://example.com/api"}
  ]
}

Activation of a RoE fails if any asset falls outside allowed_cidrs / allowed_domains (or is covered by a deny list). Keep the inventory and the RoE in sync before you launch.

Phases

Every pentest works through three ordered phases. Agents are assigned per phase, and the platform requires a minimum of 3 and a maximum of 4 agents per phase.

#	Phase	What happens
1	Reconnaissance	Gather information about the target, passively and actively
2	Enumeration	Identify and map services, endpoints and resources
3	Analysis	Analyse the surface and confirm vulnerabilities

Phases run in order: you cannot start a later phase before the previous one has its agents assigned and has run.

How modes map onto phases

The phases are the same in both modes — what differs is who drives the transitions between them.

Guided

For each phase you pick the agents, run it, review the output, then decide whether to continue. You trigger the findings processing yourself — it runs as a background job — and finish the pentest when you’re done. You don’t have to run all three phases.

Automatic

Default agents are assigned to all phases at once and executed back to back. Vulnerabilities are processed in-stream and the pentest is marked completed with no manual step.

In both modes, progress streams in real time while a phase runs. Automatic mode still processes findings inside that stream; you do not call a separate processing step. To authorize the run, see Engagement, RoE & kill switch. To see the findings that come out of Analysis, see Vulnerabilities. To understand the agents that do the work, see Agents, tools & MCP.