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