YoloPentest — AI Agent Workbench for Security Assessment

YoloPentest is an open-source, fully autonomous penetration testing agent platform. It runs real security tools (Nmap, sqlmap, httpx, nuclei, ffuf, AppScan, nikto) inside sandboxed Docker/Podman containers and delivers professional assessment reports through an integrated React UI. Built with a Rust backend and React frontend, it supports multiple AI models including DeepSeek, OpenAI, Anthropic Claude, and OpenRouter.

---

What is YoloPentest?

YoloPentest is a fully autonomous AI-powered penetration testing platform designed for defensive security assessment. It combines a high-performance Rust backend (yolo-harness) with a modern React frontend to provide:

• Real tool execution — runs Nmap, sqlmap, httpx, AppScan, nikto, nuclei, ffuf, and more inside sandboxed containers
• Multi-model AI support — DeepSeek, OpenAI, Anthropic Claude, OpenRouter, Ollama
• Integrated report editor — rich-text WYSIWYG with floating toolbar and keyboard shortcuts
• Plugin tools — extensible via MCP protocol
• Container isolation — all shell commands execute inside Docker/Podman for safety
• Session management — full conversation history, pause/resume, and task board

When to Use YoloPentest

Use Case	Description
Security assessment	Automated vulnerability scanning and reporting for web applications
Penetration testing	AI-driven attack simulation with real security tools
Compliance auditing	Generate professional security reports for audits
Security research	Explore attack surfaces with AI guidance
Red team operations	Automated reconnaissance and exploitation workflows

Technology Stack

Component	Technology	Purpose
Backend	Rust (2024 edition)	High-performance task loop, model calls, tool execution
Frontend	React 18 + Vite	SPA with session management, message stream, task board
Containerization	Docker / Podman	Sandboxed tool execution environment
AI Models	DeepSeek, OpenAI, Claude, OpenRouter, Ollama	Multi-model support with streaming
Protocol	MCP (Model Context Protocol)	Plugin tool system

---

Architecture

Component	Path	Description
Backend runtime	yolo-harness/	Rust workspace — task loop, model calls, tool execution, session storage, event stream
Domain types	yolo-harness/crates/domain	Shared domain types and event structures
LLM client	yolo-harness/crates/llm-client	Model protocol adapters (Anthropic/OpenAI) and streaming
Built-in tools	yolo-harness/crates/tools	Task board, file ops, command execution, browser tools
HTTP service	yolo-harness/crates/harness	HTTP entry, config loading, auth, session interfaces
Prompts	yolo-harness/prompts/	Main agent, report generation, and context compaction prompts
Sub-agents	yolo-harness/agents/	Sub-agent configurations
Frontend	frontend/	Vite + React SPA with session management, message stream, task board, report editor
Design docs	docs/	Architecture decisions, implementation plans, historical records

Quick Start

Prerequisites

• Rust toolchain — 2024 edition support required
• Node.js and npm — for the React frontend
• Podman or Docker — for containerized tool execution (or set provider = "none" for local commands)
• AI model API key — DeepSeek (default), OpenAI, Anthropic, or OpenRouter

Step 1: Start the Backend

cd yolo-harness
Copy-Item .env.example .env
cargo run -p yolo-harness

The backend starts at http://127.0.0.1:18080. Configuration loads in order: YOLO_CONFIG_PATH → config.toml → config.example.toml.

Step 2: Build the Toolbox Image

cd yolo-harness
podman build -f Containerfile.tools -t yolopentest-tools:latest .

Step 3: Start the Frontend

cd frontend
npm install
npm run dev

The frontend runs at http://127.0.0.1:5173. API requests at /api are proxied to the backend.

Environment Variables

Variable	Description
DEEPSEEK_API_KEY	API key for the default model configuration
EXA_API_KEY	Optional API key for the external search tool
YOLO_INITIAL_ADMIN_USERNAME	Initial administrator username
YOLO_INITIAL_ADMIN_PASSWORD	Initial administrator password

Shell Execution Configuration

shell_exec configuration lives under [shell_exec]. Key fields: provider, image, timeout_secs, network_mode, cap_add, privileged.

TUN Proxy (Podman Mode)

Enable managed TUN proxy through [shell_exec.proxy] to route specific traffic through the container:

[shell_exec.proxy]
enabled = true
routes = ["1.0.1.0/24"]

When enabled, the harness starts a host-side relay and Podman Machine internal relay. Session containers use an isolated bridge network with /dev/net/tun mounted. Traffic matching routes is routed through tun2socks; other traffic uses the container's original network. Supports TCP only (no UDP, ICMP, or raw packets).

Development

Verification Commands

Backend:

cd yolo-harness
cargo fmt
cargo check
cargo test

Frontend:

cd frontend
npm run typecheck
npm run test
npm run build

Run the smallest relevant tests during development. Before committing, expand verification based on change scope.

Development Conventions

• Shared types — place in domain crate to avoid duplication across crates
• Tool changes — update tool schema, main prompts, and related tests together
• Frontend interactions — cover empty states, loading states, error states, and key regression tests
• Configuration — update config.example.toml when changing examples; never commit real secrets
• API changes — update docs/ design documentation when changing runtime semantics, event structures, or APIs
• Bug fixes — add regression test before implementing the fix

Commit Flow

git status --short
git commit -m "完善任务审计提示词"

Commit messages use Chinese by default. Keep titles short and describe the scope of the change.