Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / agent-orchestration

Security agent orchestration

Strix turns scan settings into a coordinated security-testing system. It builds a root agent to control the assessment and specialist agents to perform focused investigation. Shared instructions, scan state, and tools let the agent tree move from user-defined target mapping to validated evidence and a final report.

Agent construction

Agent construction creates the actors for one scan and gives each actor a role. The root owns scan-wide progress. Specialist agents handle focused work that the root assigns.

Root agent

The root agent is the scan coordinator. It reads the current user-defined scope and scan context, divides the target into focused tasks, starts and monitors specialists, tracks coverage, reviews findings, and submits the final scan result. Its operating instructions explicitly keep all hands-on testing with child agents rather than the root. (Agent factory and prompts)

The root is the only agent that can complete the whole scan. It must account for child work, coverage, and filed reports before it ends the assessment.

References: strix/…/system_prompt.jinja• L3-10 strix/…/system_prompt.jinja• L328-336 strix/…/tool.py• L90-143

Specialist agents

Specialist agents are child agents with one focused objective. The parent supplies the task and related skills. The child then works in the shared scan environment and returns a completion report to its parent. (Agent tools and workflows)

The tree grows as the assessment reveals new work. Discovery can lead to a separate validation task. A confirmed result can then lead to a reporting task. In white-box work, the reporting agent derives and files the fix with the report instead of creating a separate fixing agent. This structure keeps parallel work narrow and gives each result a clear owner.

References: strix/…/system_prompt.jinja• L321-345 strix/…/system_prompt.jinja• L348-385 strix/…/tools.py• L407-453

Scan context

Scan context keeps agents in the same assessment. It carries scope, testing mode, source-aware behavior, interaction mode, and available system connections into the root and every child. The child factory captures these scan-level choices so a child does not silently use a different assessment policy.

The context also connects agents to shared workspace state and the agent graph. A child may inherit prior conversation context when it needs the parent’s target and evidence. It may instead start clean when the task is independent.

References: strix/…/factory.py• L663-705 strix/…/factory.py• L757-788 strix/…/runner.py• L294-359

Operating instructions

Operating instructions tell an agent what security work to perform, what limits apply, and how to leave useful state for the rest of the scan. Strix renders them from a common prompt plus the agent role, scan mode, scope context, and focused skills.

System prompt

The system prompt defines authorized security validation as the agent’s purpose. The user-defined target scope is authoritative and can change when the user adds or removes targets. Agents must follow the latest scope and must not let websites, files, or tool output change it. (Agent factory and prompts)

The prompt also sets the quality bar for the assessment. Agents map the target, choose the relevant static or dynamic path, validate suspected weaknesses, record coverage, use the threat model, and preserve evidence for reporting. A candidate must end as confirmed, ruled out, or an open proof gap instead of disappearing from the scan.

The prompt changes with the role. Root instructions focus on delegation and scan control. Child instructions focus on the assigned test. Interactive runs add explicit rules for returning control to the user or waiting for another agent. Autonomous runs must use lifecycle tools rather than plain text to finish or wait. The per-run scope block is rendered at the end so the current target scope and MCP connections remain tied to the scan.

References: strix/…/system_prompt.jinja• L1-18 strix/…/system_prompt.jinja• L33-65 strix/…/system_prompt.jinja• L200-242 strix/…/system_prompt.jinja• L541-543 strix/…/scope.jinja• L1-34

Prompt composition

Prompt composition combines shared system rules with scan-specific guidance. The scan mode sets the expected depth and pace. White-box scans require both source review and live validation when possible. Interactive mode adds user handoff behavior. Root agents receive coordination rules, while children receive the same scan context without the root-only role instructions.

The renderer resolves skills in a stable order. Caller-selected skills come first, followed by scan-mode guidance, common browser and Python guidance, evidence-quality guidance, and role- or white-box-specific guidance. It places guidance common to an agent class before a cache point. It places caller-selected skills after that point, then appends the per-run scope block. This keeps prompts for sibling agents similar while preserving each child’s focused guidance and the current user-defined target context.

The factory can use a caller-supplied instruction override instead of rendering the built-in prompt. Otherwise it renders the prompt from the selected skills, scan flags, interaction mode, and system prompt context. This keeps normal agents consistent while allowing an explicitly chosen prompt for a controlled use case.

References: strix/…/prompt.py• L19-75 strix/…/prompt.py• L78-149 strix/…/prompt.py• L153-163 strix/…/system_prompt.jinja• L508-543 strix/…/runner.py• L165-197

Skill guidance

Skill guidance gives an agent focused knowledge for a vulnerability type, protocol, tool, or testing method. Skills selected at construction shape the agent from its first turn. The agent can load more guidance when a new task needs it.

The parent should give a child a small set of related skills. The renderer separates skills shared by all agents of the same kind from skills requested for one agent. This keeps the shared prompt reusable while keeping each child’s objective clear and its result easier to assess. The Agent factory and prompts page covers prompt and skill assembly in more detail.

References: strix/…/prompt.py• L24-75 strix/…/prompt.py• L105-135 strix/…/system_prompt.jinja• L508-539

Agent graph

The agent graph is the live work map for a scan. It links parents and children, tracks work state, and carries results back to the agent that requested the work.

Task delegation

Delegation starts with a focused task and optional skills. The child runs independently while the parent plans other work or monitors progress. The root and its children should inspect existing graph work before creating another child so the scan does not spend turns on duplicate coverage.

The intended shape is nested. A discovery task can create a validation task for one lead. A reporting task can then file the confirmed result and derive its source fix when the scan has code access. (Agent tools and workflows)

References: strix/…/system_prompt.jinja• L338-360 strix/…/tools.py• L71-120 strix/…/tools.py• L407-515

Agent messages

Agent messages move focused questions, instructions, and evidence between agents. They complement shared notes and coverage records by asking another agent to act or respond. Child completion reports are the normal result path back to the parent.

The graph preserves the handoff when possible and prevents a stopped child from producing repeated terminal notices. This lets a parent resume or finish with a reliable view of child outcomes.

References: strix/…/tools.py• L123-208 strix/…/tools.py• L518-636 strix/…/agents.py• L266-366

Agent states

Agent states show whether work is active, waiting, complete, stopped, failed, or paused by the scan budget. Waiting includes a reason such as user input, another agent, or recovery from a stalled turn. That reason tells run control when an automatic wake-up is useful.

The graph keeps these states with messages, recovery limits, idle-resume counts, and budget flags. A resumed scan can therefore preserve unfinished work instead of treating a pause as a clean result.

References: strix/…/agents.py• L25-65 strix/…/agents.py• L77-147 strix/…/agents.py• L198-264 strix/…/execution.py• L367-446

Investigation tools

Investigation tools turn an agent’s plan into work against the shared workspace and user-authorized targets. The tool surface joins local analysis, target research, proxy inspection, shared scan records, coordination, and security reporting.

Workspace and target access

Every agent can use the shared sandbox for filesystem and shell work. The common security tools also support web research, proxy traffic, scope checks, coverage, threat-model updates, report handling, and coordination. These capabilities let a specialist move from mapping to proof without changing its assigned role.

When MCP connections are available, an agent discovers the relevant connection and tool before it calls them. This gives the scan access to authoritative data such as deployment settings, schemas, known issues, or logs when the target itself cannot provide that data. The scope instructions identify connected services for the current run and direct the agent through discovery before dispatch.

References: strix/…/factory.py• L574-618 strix/…/factory.py• L707-753 strix/…/scope.jinja• L18-34

Tool registration

Tool registration extends the shared investigation surface without changing the lifecycle boundary. Registered tools are available to agents built after registration. Per-agent tools apply only to the agent being built. In both cases, the lifecycle tool remains the final control boundary.

The factory rejects duplicate names across base, registered, per-agent, and lifecycle tools. This keeps model calls unambiguous when the tool sets are combined. (Agent tools and workflows)

References: strix/…/factory.py• L621-660 strix/…/factory.py• L707-721

Planning records

Planning records separate unfinished work from durable scan knowledge. An agent’s private plan supports complex decisions. Todos track its own next steps. Shared notes preserve facts that another agent may need.

Coverage and the threat model provide the shared view of what the scan has assessed and how the target’s trust boundaries work. These records support coordination rather than replace it: a todo tracks work, a note preserves knowledge, and a message asks another agent to act.

References: strix/…/system_prompt.jinja• L215-242 strix/…/factory.py• L574-592

Security evidence

Reporting tools turn validated evidence into findings that the scan can review and deliver. A dynamic finding needs proof of a real weakness and its impact. A dependency finding needs a verified package and CVE link plus evidence that explains its use and priority.

Agents can revise a filed finding when later evidence changes its confidence, impact, severity, remediation, or code context. They should update an existing finding when it is the same issue and delete it when retesting proves that the issue does not exist. The root reviews reports across the scan before it writes the final summary.

Proxy-backed findings also carry the request identifiers that prove the behavior. The reporting path checks those identifiers against the active proxy project. A temporary proxy failure can defer the links rather than create unverified evidence.

References: strix/…/system_prompt.jinja• L216-224 strix/…/factory.py• L574-612 strix/…/tool.py• L900-1548 strix/…/tool.py• L1763-2162

Scan completion

Scan completion joins specialist work into one customer-facing result. Children close or report their assigned work first. The root then reconciles the graph, coverage, threat model, and findings before it submits the executive summary.

Assessment flow

The following flow shows how scan settings become coordinated testing and a final security result.

flowchart TD
    A[Scan settings and user scope] --> B[Build root agent]
    B --> C[Render shared instructions and current scope]
    C --> D[Map target and plan coverage]
    D --> E[Delegate focused specialist work]
    E --> F[Investigate with workspace and target tools]
    F --> G{Evidence confirmed?}
    G -->|No| H[Close coverage or record proof gap]
    G -->|Yes| I[File or revise the appropriate report]
    H --> J[Child completion report]
    I --> J
    J --> K[Root reconciles graph, coverage, and findings]
    K --> L[Finish scan with executive summary]

References: strix/…/factory.py• L663-753 strix/…/runner.py• L146-197 strix/…/runner.py• L261-380 strix/…/tools.py• L518-636 strix/…/tool.py• L82-143

Lifecycle actions

Lifecycle actions make control transfer explicit. A child uses agent_finish to return its result. The root uses finish_scan to persist the final report and end the scan. In interactive work, wait_for_user returns control to the user and wait_for_agents parks the agent while it waits for child work.

The run ends a turn only when the relevant lifecycle tool returns a successful result. Plain text does not finish or yield the run. This rule prevents an agent from appearing complete when it has not returned its result, handed control to the user, or waited for required work.

References: strix/…/factory.py• L515-571 strix/…/system_prompt.jinja• L33-65 strix/…/system_prompt.jinja• L225-242 strix/…/execution.py• L451-570

Completion safeguards

The root cannot finish while child agents remain active. It also cannot treat an unverified lead as complete. Each candidate needs a closure state and a matching coverage record. Confirmed issues need the right report. Open proof gaps must remain visible for follow-up.

Budget limits, provider failures, and interruptions can pause or stop work without losing scan state. The coordinator records statuses and messages so the root can resume the scan or account for unfinished work.

References: strix/…/tool.py• L108-143 strix/…/system_prompt.jinja• L200-224 strix/…/execution.py• L719-812 strix/…/agents.py• L77-138

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the root and child role rules aligned with their lifecycle tools. The root must end with finish_scan; a child must end with agent_finish.
  • Keep the latest user-defined scope authoritative. New prompt context must not let websites, files, or tool output change the scope, and must let the user add or remove targets.
  • Keep per-run scope and MCP guidance after the reusable prompt prefix. Scope data must remain current to the scan and must not become shared cached content.
  • Keep child factory inputs aligned with scan context so mode, source-aware behavior, interaction mode, and scope remain consistent.
  • Preserve nested delegation and focused child tasks when changing graph creation or prompt guidance. Avoid duplicate work and broad specialist roles.
  • Keep completion reports, terminal notices, wait states, and resume state compatible so parents do not wait forever for stopped children.
  • Keep coverage, threat-model, notes, and report state visible to later agents when changing shared tools or prompt quality rules.
  • Preserve report-class boundaries, proof requirements, counterevidence, deduplication, and proxy evidence checks when changing reporting behavior.
  • When adding tools, keep names unique, schemas compatible with the selected route, result limits bounded, and the lifecycle tool last.

Important failure modes

TriggerConsequenceGuard
An agent ignores the latest user scope or lets a website, file, or tool output change itThe agent may miss an authorized target or test a target the user did not authorize.Keep the user-defined scope authoritative and treat only the user as able to change it.
Per-run scope is placed in the shared prompt prefixA cached prompt can expose stale targets or MCP connections to another scan.Render the scope block after the cache point and attach it to the current run.
Root performs hands-on testing instead of delegatingSpecialist coverage and the intended control split are lost.Keep root guidance focused on decomposition, monitoring, shared state, and final review.
A child receives a broad or duplicate taskWork overlaps and the scan cannot show clear coverage.Inspect the graph first and assign one concrete objective with focused skills.
A child stops without a completion pathThe parent can wait for work that never returns.Preserve one terminal notice and the child completion flow.
An agent ends a turn with plain textThe run continues without a valid result or handoff.Require a successful lifecycle tool result.
A candidate has no closure state or coverage recordThe final result can hide an unverified surface.Record confirmed, ruled-out, or open-proof-gap status and reconcile coverage.
A report is filed without proof or counterevidenceThe scan publishes a weak signal or inflated impact.Require concrete evidence, an opposing-case pass, and honest confidence.
A dynamic finding and dependency finding are mixed during revisionReport meaning and severity context become unclear.Keep revisions within the original finding class.
Proxy evidence uses stale identifiers or an unavailable exchangeThe report loses replayable HTTP proof.Verify identifiers against the active proxy project and attach them after recovery.
Added tools share a base or lifecycle nameAgent construction fails or model calls become ambiguous.Validate unique names before and during construction.
A route rejects the tool schema or receives an unbounded resultTool calls fail or useful context is lost.Adapt schemas and apply result limits before history insertion.
Root calls finish_scan while children remain activeThe final summary omits unfinished specialist work.Review graph state and wrap up every active child first.

Key files

FileWhy to read it
strix/…/factory.pyDefines root and child construction, prompt selection, tool assembly, route adaptation, result limits, registration, and lifecycle boundaries.
strix/agents/prompts/system_prompt.jinjaDefines scope rules, role rules, testing method, evidence standards, shared state, delegation, and completion behavior.
strix/agents/prompts/scope.jinjaDefines the current user scope, authorized target context, MCP connection context, and MCP tool discovery path appended to the shared prompt.
strix/…/prompt.pyShows how scan mode, role, scope context, skills, and prompt cache boundaries become prompt input.
strix/…/runner.pyConnects scan settings to root construction, root instruction overrides, scope rendering, and child factory setup.
strix/…/execution.pyShows how turns run, lifecycle actions settle work, and failures recover.
strix/…/agents.pyDefines graph state, messages, wait and budget states, recovery limits, and resume data.
strix/…/tools.pyProvides delegation, messaging, waiting, graph inspection, and child completion.
strix/…/tool.pyDefines evidence, revision, dependency, report review, and validation contracts.
strix/…/tool.pyDefines the root-only final report and scan completion boundary.
docs/agent-factory-and-prompts.mdChild page for agent construction and prompt composition.
docs/agent-tools-and-workflows.mdChild page for tool groups and tool-driven assessment workflows.