Yummi

A privacy-first, fail-closed AI pentest conductor and autonomous Red Team platform.

Full Documentation · Installation · Architecture · Security Model · Usage Guide · API Reference

Yummi translates natural language into verified security workflows while enforcing strict operator authority and fail-closed network control. An autonomous agent drives a hardened Kali Linux workbench equipped with 58 native MCP tools, 99 battle-tested offensive skills, and 52 specialist sub-agents, while an independent Rust gateway enforces packet-level policy outside the model's reach.

_{Drop a target, state a goal in one sentence, and Yummi plans before it acts. See the Usage Guide for every tab, including a real completed run.}

Key Capabilities

Security Boundary & Traffic Governance

• Fail-Closed Rust Gateway — Packet filtering is enforced by an independent Rust daemon (yummi-gateway) via Linux kernel nftables rules. Default-deny policies install at startup and persist even if the daemon terminates. The AI agent never manages firewall rules.
• Runtime 4-Way Egress Mode — Operator controls egress on the fly: block_all (complete airgap, drops all outbound egress unconditionally), block_all_except_rules (strict scope, permits only explicitly authorized targets and active temporary rules), allow_all (blanket external connectivity for public destinations), or ask_every_time (destination-by-destination interactive operator approval). Resets to block_all on daemon restart.
• Tamper-Evident Audit Chain — Every routing decision, temporary rule, and egress evaluation is cryptographically chained using SHA-256 in a local SQLite WAL journal.

Offensive Arsenal & Pwnbox Environment

• Unified Kali Sandbox (yummi-pwnbox) — Single hardened container running as an unprivileged user (UID 1000). Shares operator Bash (tmux), graphical desktop (noVNC/XFCE), and agent execution.
• 58 Native MCP Tools — Six-tier tool strategy: 6 typed core tools (Nmap, WhatWeb, cURL, Gobuster, ffuf, Nikto), 32 cataloged offensive utilities, 2 Go recon pipelines, 7 persistent tmux terminal tools, 9 full-capability browser automation tools, and 2 sandboxed web research tools.
• Full-Capability Browser Automation — Native Chromium automation via Rod with compact accessibility tree snapshots (@eN refs including semantic content elements li, td, th, blockquote, code), multi-tab lifecycle, session cookie isolation, and in-sandbox connection proxy for HTTP/S and WS/WSS enforcing gateway hostname policy.
• Controlled Sandboxed Web Research — Privacy-first research tools (web_search, web_fetch) with OpenRouter/Exa cited sources, direct HTTPS plaintext extraction/pagination/find, RFC 1918/metadata IP rejection, operator-controlled UI toggle button (btn-web-search), and prompt-injection defense (UNTRUSTED_WEB_CONTENT).
• Persistent Tmux Terminal Verbs — Full session lifecycle (term_open, term_run, term_read, term_wait, term_keys, term_list, term_close) for long-running listeners, background tunnels, reverse shells, and interactive prompts.
• Active Directory & Network Pivoting — Pre-staged Kerberos (krb5-user, kerbrute), Impacket, NetExec, Nishang, Metasploit Framework, OpenVPN lab profiles (/dev/net/tun), and an automatic reverse shell generator (revshell).

Autonomous Reasoning & Specialized Agents

• Dual Agent Backends — A deterministic 11-node Graph State Machine (closed tag protocol) or CloudWeGo's Eino ADK (native tool-calling). Both architectures scale down to small local models, but live-tested autonomous reliability needs a 120B+ local model or a cloud model — see Agent Overview for the tested floor and a specific recommendation.
• 99 Offensive Skills & 52 Specialist Sub-Agents — Declarative offensive methodologies and bounded depth-1 specialist roles spanning Active Directory, Web/APIs, Cloud/K8s, Binary RE, Hardware/RF, and Adversary Emulation.
• Active Exploit Verification Oracles — Findings require deterministic proof (OracleActivePoC, OracleDOMExecution, OracleOOBInteraction, OracleDifferential) before acceptance, eliminating hallucinated vulnerabilities.

Operator Surface & Attack Surface Management

• Single Web-Managed Workspace — Clean React 18 dashboard on port 3000 featuring eight dedicated tabs: [AGENT] [TERMINALS] [TRACE] | [BASH] [DESKTOP] [LOGS] [GATEWAY] [HEALTH].
• Persistent Task Summary Cards — First-class terminal summary cards with status pills, step metrics, executive summary prose, and structured findings with automatic CTF/pentest flag extraction, copy interaction, and CVE tagging.
• On-Demand Desktop Activation — Lazy-loaded XFCE desktop session with click-to-activate protection to preserve memory/VRAM and maintain container security.
• Attack Surface Management (ASM) — Hierarchical asset graph tracking domains, subdomains, IPs, ports, endpoints, query parameters, secrets, and cloud storage buckets.
• Proxy Ingestion & Multi-Format Reporting — Live HTTP stream ingestion from Burp Suite, Caido, or Mitmproxy, with one-click report generation in HackerOne Markdown, Bugcrowd VRT, Executive Summary, or structured JSON.

Architecture Topology

                        +----------------------+
       Operator ------->|   ui (React/nginx)   |  :3000
                        +----------+-----------+
                                   | /api, /ws (proxied)
                        +----------v-----------+
       CLI ------------>|  orchestrator (Go)   |  :9080 (127.0.0.1 only)
                        |  conductor + agent   |
                        +----+------------+----+
                             |            |
                 IPC Socket  |            | Docker Exec (via docker-proxy)
        (Length-prefixed)    |            |
                        +----v-------+    |
                        | gateway    |    |
                        | (Rust)     |    |
                        | nftables   |    |
                        +----+-------+    |
                             |            |
               FORWARD Chain |            |
                (Allow/Deny) |            |
                        +----v------------v----+
                        |    sandbox (Kali)    |  No direct internet route;
                        |                      |  egress gated by gateway's
                        |                      |  FORWARD chain.
                        +----------------------+

Five runtime components collaborate in a fail-closed architecture:

1. orchestrator (Go) — AI conductor, agentic state machine (Graph / Eino), execution store, and REST/WebSocket API.
2. gateway (Rust) — Fail-closed nftables policy engine, IP/hostname scope evaluator, and tamper-evident SHA-256 audit log.
3. sandbox (Yummi Pwnbox / Kali Linux) — Hardened offensive workbench running 58 pentest, browser, and terminal MCP tools, Metasploit, Nishang, tmux shell, and XFCE/noVNC desktop.
4. docker-proxy — Restricts orchestrator access strictly to container exec/inspect operations; blocks host daemon mutations.
5. ui (React 18 + Vite) — Modern, web-only operator surface served via nginx on port 3000.

Read the full architecture documentation ->

Documentation

Comprehensive guides and technical references live in the docs/ directory. Start at docs/README.md:

• Architecture — Runtime components, isolation boundaries, and core data flows
• Security Model — Fail-closed network design, threat scanner, and SHA-256 audit chain
• Installation — Environment prerequisites, container engines, and model setup
• Usage Guide — Target-First launcher, UI tabs, approval flows, and CLI helper
• Agent Internals — Graph state machine, Eino ADK, memory store, and verification oracles
• Skills & Sub-Agents — The 99 built-in playbooks and 52 specialist sub-agents
• API Reference — Complete REST endpoints, WebSocket streams, and wire schemas
• Development — Multi-module Go workflow, Rust builds, and test harnesses

Quick Start

1. Platform Prerequisites

• Linux (x86_64 / arm64): Native Docker Engine (reference production platform).
• macOS (Apple Silicon): Docker with OrbStack strongly recommended for native container bridge performance.
• Windows 10/11: WSL2 with Ubuntu and Docker Desktop WSL2 engine (clone repo inside ~/yummi, not /mnt/c/).

2. Bootstrap & Start

# 1. Install prerequisites (Docker, Go, Rust, Node, Ollama)
make install

# 2. Interactive setup wizard (run once to configure engine, language, and model)
make conf

# 3. Build images and start the full stack
make start

Yummi is managed entirely from the web UI at http://localhost:3000. The root CLI binary (./bin/yummi) handles container lifecycle (--start, --stop, --status, --doctor) and opens the web UI in an app-style window.

Configuration Matrix (make conf)

Running make conf writes your settings to .yummi.conf so subsequent commands never require repetitive flags:

Recommended OpenRouter model: minimax/minimax-m2.1. Live-tested
completing a full CVE-to-root chain end to end — exploit, reverse-shell
terminal, privesc, both flags — plus memory recall and a sub-agent
handoff, at a fraction of a general frontier model's cost. Set
YUMMI_EINO_MODEL_NAME=minimax/minimax-m2.1 (and
YUMMI_EINO_PROVIDER=openrouter) in .yummi.conf, or via make conf.
See orchestrator/internal/conductor/tier.go's DefaultTierRegistry doc
comment for the full writeup.

Development

make build   # Builds CLI + orchestrator + gateway binaries AND UI (dist)
make test    # Runs all test suites (Go root, Go orchestrator, Go sandbox-mcp, Rust gateway, UI)
make lint    # Runs golangci-lint across all three Go modules

Note: The repository consists of three separate Go modules (root CLI, orchestrator/, and sandbox-mcp/). When running ad-hoc go test commands, prefix with the module path (e.g. cd orchestrator && go test ./...). See docs/development.md.

License

Apache License 2.0