How 299710583/autoflow works
Purpose and entry points
AutoFlow is a Python multi-agent framework for authorized security assessments, lab testing, and internal red-team workflows. It transforms target/scope input into recon, evidence-backed validation, and reports. Primary runtime entry points are autoflow/main.py, CLI runners scripts/run_assessment.py and scripts/run_stepwise_assessment.py; an HTTP integration surface exists in autoflow/api/app.py with project, task, finding, and approval routes.
Workflow orchestration
LangGraph is the primary control plane. The graph builder assembles nodes, conditional edges, state transitions, and checkpoint integration in autoflow/graph/builder.py, autoflow/graph/nodes.py, and autoflow/graph/edges.py. Workflow state is modeled separately in autoflow/graph/state.py and business flow state/models in autoflow/flows/state.py and autoflow/flows/models.py. The key loop is planning → discovery/recon → execution → finding verification → validation; validation reasoning may route back to discovery before reporting.
Agent stages and reasoning boundary
Agents separate LLM judgment from deterministic collection and execution. autoflow/agents/planner.py establishes assessment direction; autoflow/agents/recon.py performs factual target collection; autoflow/agents/discovery_reasoner.py converts observations, memory, and tool availability into test plans. autoflow/agents/executor.py, autoflow/agents/verifier.py, autoflow/agents/validation.py, and autoflow/agents/validation_reasoner.py execute plans, promote signals into candidate findings, produce validation plans, and make iterative evidence decisions. LLM access is isolated behind autoflow/llm/client.py, while shared agent/tool-call iteration is centralized in autoflow/agents/tool_loop.py.
Controlled tool-execution plane
LLMs receive declared tool schemas rather than host-shell access. autoflow/tools/catalog.py, autoflow/tools/manifest.py, and autoflow/tools/dispatcher.py expose and dispatch approved calls. Execution adapters build commands and run them in Docker/Kali, scripts, bounded shell, or SSH through autoflow/executor/docker_executor.py, autoflow/executor/task_container_executor.py, autoflow/executor/script_runner.py, and autoflow/executor/shell_runner.py. Tool output parsers, including autoflow/executor/parsers/nmap.py and autoflow/executor/parsers/nuclei.py, normalize external results. The material execution environment is the Docker image defined by docker/autoflow-kali-tools/Dockerfile; tool availability and installation policy are configuration-driven under configs/tools.yaml, configs/tool_manifest.yaml, and configs/tool_installs.yaml.
Evidence, domain, and persistence
The evidence pipeline is raw tool result → observation/signal → candidate finding → validation plan/result → report. Core domain records reside in autoflow/domain/project.py, autoflow/domain/task.py, autoflow/domain/finding.py, and autoflow/domain/evidence.py; observation parsing and models are in autoflow/observations/parser.py and autoflow/observations/models.py. Relational persistence is abstracted through autoflow/db/models.py, autoflow/db/repositories.py, and autoflow/db/session.py. Large raw evidence is stored outside LLM context through autoflow/artifacts/store.py and autoflow/artifacts/paths.py.
Memory, recovery, and safety controls
Redis is the runtime memory and checkpoint backend: agent memory, retrieval, embeddings/vector support, and Redis storage are represented by autoflow/memory/agent_memory.py, autoflow/memory/retrieval.py, and autoflow/memory/redis_store.py; graph checkpoint handling is in autoflow/graph/checkpoints.py. This boundary supports multi-turn context, interruption recovery, and future approval-resume flows. Authorization scope, tool risk, approval requirements, and policy rules are enforced through autoflow/policy/engine.py, autoflow/policy/risk.py, and autoflow/policy/approval.py; execution supervision is provided by autoflow/supervision/limits.py and autoflow/supervision/monitor.py.
Reporting and operational infrastructure
autoflow/agents/reporter.py aggregates assets, observations, findings, validation evidence, and remediation guidance. autoflow/reporting/generator.py emits reports through Markdown, HTML, and PDF exporters, with autoflow/reporting/exporters/markdown.py the stated primary output path. Runtime scheduling primitives—queueing, locks, conflict detection, and heartbeats—are isolated in autoflow/scheduler/dispatcher.py, autoflow/scheduler/locks.py, and autoflow/scheduler/conflict.py. Required external services/runtimes are Python 3.11+, Docker, Redis/Redis Stack, and an OpenAI-compatible LLM API.
Main entry points: builder.py LangGraph workflow · validation_reasoner.py Execution and validation · docker_executor.py Execution adapters · discovery_reasoner.py Recon and discovery
Components 21
Entry surfaces
- Assessment CLI
scripts/run_assessment.py - HTTP API · Exposes project, task, finding, and approval routes.
autoflow/api/app.py
Workflow control
- LangGraph workflow · Builds conditional stages and state transitions.
autoflow/graph/builder.py - Workflow state
autoflow/graph/state.py - Checkpoints
autoflow/graph/checkpoints.py
Agent pipeline
- Planning · Establishes assessment direction.
autoflow/agents/planner.py - Recon and discovery · Collects facts and turns them into test plans.
autoflow/agents/discovery_reasoner.py - Execution and validation · Executes plans, verifies signals, and makes iterative evidence decisions.
autoflow/agents/validation_reasoner.py - LLM client · OpenAI-compatible LLM access is isolated here.
autoflow/llm/client.py - Tool-call loop
autoflow/agents/tool_loop.py
Controlled execution
- Tool catalog and dispatch · Provides declared schemas and dispatches approved calls.
autoflow/tools/dispatcher.py - Execution adapters · Runs bounded Docker, task-container, script, shell, or SSH work.
autoflow/executor/docker_executor.py - Kali tool image
docker/autoflow-kali-tools/Dockerfile
Evidence and runtime state
- Observations · Parses external output into observations and signals.
autoflow/observations/parser.py - Projects, tasks and findings
autoflow/domain/finding.py - Relational persistence
autoflow/db/repositories.py - Raw evidence artifacts · Keeps large raw evidence outside LLM context.
autoflow/artifacts/store.py - Redis memory · Supports agent context, retrieval, embeddings, and recovery.
autoflow/memory/redis_store.py
Governance and outputs
- Policy and approvals · Enforces scope, risk, and approval requirements.
autoflow/policy/engine.py - Report generation · Exports Markdown, HTML, and PDF reports.
autoflow/reporting/generator.py - Scheduler and locks · Provides queueing, locks, conflict detection, and heartbeats.
autoflow/scheduler/dispatcher.py
Connections 25
- Assessment CLI → LangGraph workflow: starts assessment
- HTTP API → LangGraph workflow: creates and resumes workflows
- HTTP API → Projects, tasks and findings: manages records and approvals
- LangGraph workflow → Workflow state: reads and updates
- LangGraph workflow → Planning: routes to
- Planning → Recon and discovery: assessment direction
- Recon and discovery → Execution and validation: test plans and observations
- Execution and validation → Recon and discovery: needs more discovery
- Planning → LLM client: reasoning
- Recon and discovery → LLM client: reasoning
- Execution and validation → LLM client: evidence decisions
- Execution and validation → Tool-call loop: tool iterations
- Tool-call loop → Tool catalog and dispatch: declared tool calls
- Tool catalog and dispatch → Policy and approvals: authorize call
- Policy and approvals → Execution adapters: approved execution
- Execution adapters → Kali tool image: runs tools in
- Execution adapters → Observations: external output
- Observations → Projects, tasks and findings: signals and candidate findings
- Execution adapters → Raw evidence artifacts: raw evidence
- Projects, tasks and findings → Relational persistence: stored through
- LangGraph workflow → Checkpoints: checkpoint lifecycle
- Checkpoints → Redis memory: persists runtime state
- Execution and validation → Report generation: validated evidence
- Report generation → Raw evidence artifacts: reads evidence
- Scheduler and locks → LangGraph workflow: dispatches coordinated runs