Strix — Start Here

docs / 00_START_HERE

← all docs

Strix — Start Here

This is the onboarding documentation kit for Strix (usestrix/strix), an open-source autonomous AI penetration-testing tool. It was written for new joiners on the security/engineering team who need to understand how Strix works before they use it, extend it, or review it -- whether or not they have a software background.

Every claim in this kit was checked against the real source code (grep/read, never guessed), and against real dependency data from two code-intelligence tools (CodeGraph and Graphify) run directly against the repository. See STRIX — Graph Intelligence Findings for the numbers.

Pick your path

You are... Read in this order
Non-technical (product, compliance, leadership) 1) 01_overview.md (the assembly-line analogy + glossary) -> 2) ../diagrams/03_context_dfd.html (one picture: what goes in, what comes out) -> 3) process/00_process-and-runbooks-index.md for "what does running it actually look like"
Security analyst 1) 01_overview.md -> 2) design/data-flow.md -> 3) modules/README.md, especially modules/tools.md and modules/report.md (how findings are validated & written) -> 4) process/runbooks/run-a-detection-scan.md
Junior developer 1) 01_overview.md -> 2) design/HLD.md -> 3) ../diagrams/01_architecture.html and ../diagrams/04_module_dependencies.svg -> 4) modules/core.md, modules/agents.md (the orchestration engine) -> 5) modules/README.md for everything else
Reviewer / architect 1) design/HLD.md -> 2) design/LLD.md -> 3) ../diagrams/05_agent_graph_orchestration.svg (the multi-agent "graph of agents") -> 4) tools/graph-intelligence.md (how the diagrams were grounded in real code data)
Operator (running scans day to day) 1) process/runbooks/setup-and-credentials.md -> 2) process/runbooks/run-a-detection-scan.md -> 3) process/runbooks/review-and-triage-findings.md

Project folder map

STRIX/                  <- this harness folder (the "working" project)
├── docs/                                   <- you are here — the documentation product
│   ├── 00_START_HERE.md                    <- this file
│   ├── 01_overview.md                      <- read this first
│   ├── design/
│   │   ├── HLD.md                          <- High-Level Design: the components picture
│   │   ├── LLD.md                          <- Low-Level Design: cross-cutting internals
│   │   ├── data-flow.md                    <- DFD levels 0/1/2 + narrative
│   │   └── agentic-framework.md            <- deterministic vs. LLM-driven tooling; confirms
│   │                                          no LangChain/LangGraph — OpenAI Agents SDK only
│   ├── modules/
│   │   ├── README.md                       <- index of all strix/ packages
│   │   └── <package>.md                    <- one file per package (agents, core, tools, runtime, report, ...)
│   ├── process/
│   │   ├── 00_process-and-runbooks-index.md
│   │   ├── process-operate-strix.md        <- the SOP
│   │   └── runbooks/                       <- step-by-step, copy-paste-verified commands
│   └── tools/
│       └── graph-intelligence.md           <- how CodeGraph + Graphify + codeviz were used
├── diagrams/                                <- 6 diagrams (architecture, dataflow, context,
│   ├── 01_architecture.html                    module deps, agent graph, sandbox contents),
│   ├── 02_dataflow_pipeline.html               each shipped as an openable file + a .mmd/.dot
│   ├── 03_context_dfd.html                     source in diagrams/src/
│   ├── 04_module_dependencies.svg
│   ├── 05_agent_graph_orchestration.svg
│   ├── 06_sandbox_container.html
│   └── src/                                <- raw Mermaid (.mmd) / Graphviz (.dot) sources
├── tool-outputs/                            <- raw + curated exports from CodeGraph, Graphify,
│   ├── README.md                               and codeviz — see tool-outputs/README.md
│   ├── codegraph/
│   ├── graphify/
│   └── codeviz/
├── tools/                                   <- the generator scripts that produced the above
│   └── codeviz/codeviz.py                      (project-agnostic — reused, not rewritten)
├── samples/strix/                           <- a full runnable copy of the real Strix source,
│                                                kept so every command in the runbooks is
│                                                copy-paste verified against real --help output
└── scratchpad/                              <- throwaway working files (not a deliverable)

[!warning] Strix is a real, active penetration-testing tool. It runs actual exploitation attempts, browser automation, and shell commands inside a Docker sandbox against whatever target you point it at. Per the project's own warning: only scan targets you own or have explicit, written authorization to test. Unauthorized use is illegal in most jurisdictions. Nothing in this documentation kit changes that — it explains how the tool works, not a license to point it anywhere.

One-paragraph summary

Strix is a CLI tool that spins up a disposable Docker sandbox (pre-loaded with real pentesting tools -- nmap, sqlmap, nuclei, a Caido intercepting proxy, a headless browser, and more), then hands control to a tree of AI agents built on the OpenAI Agents SDK. A root agent reads the target and scope, then spawns specialist child agents (e.g. "XSS Specialist," "IDOR Specialist") that actually run tools and probe the target inside the shared sandbox. When a child finds and validates a real vulnerability, it calls a reporting tool that deduplicates the finding against everything already found (using an LLM as the judge) and persists it. When the root agent decides coverage is sufficient, it calls a lifecycle tool that ends the scan and triggers the final report to be written: a human-readable Markdown report, one file per vulnerability, a CSV/JSON index, and a SARIF file for CI/CD pipelines.

Docs also ship as HTML

design/HLD.md, design/LLD.md, and the module docs that benefit most from a styled read are also available as .html files with the same name, rendered via tools/gen_design_html.py-style tooling with Mermaid diagrams via CDN. The Markdown is always the source of truth -- regenerate the HTML from it, never hand-edit the HTML.

Diagram index

Every diagram ships as .svg + .png (rendered via Graphviz from the .dot source in diagrams/src/) plus an interactive .html version (Mermaid-driven, same content, click-to-zoom) — open whichever is more convenient.

  1. ../diagrams/01_architecture.svg (interactive) — the layered architecture (interface -> core -> agents -> tools -> runtime -> report -> config).
  2. ../diagrams/02_dataflow_pipeline.svg (interactive) — one scan, start to finish.
  3. ../diagrams/03_context_dfd.svg (interactive) — the system as one box against its external actors (DFD Level 0).
  4. ../diagrams/04_module_dependencies.svg — package dependency graph, generated directly from CodeGraph's real edge data.
  5. ../diagrams/05_agent_graph_orchestration.svg — the "Graph of Agents": how root/child/grandchild agents spawn, message, and report back through the shared sandbox.
  6. ../diagrams/06_sandbox_container.svg (interactive) — what's actually installed inside the Docker sandbox and how traffic flows through the Caido proxy.