Kuroko

An agent-native, programmable web security testing platform written in Rust.

Kuroko aims to combine the interactive testing workflow of Burp Suite, the open-source foundation of OWASP ZAP, the template-driven automation of Nuclei, and a native Model Context Protocol (MCP) interface for security and coding agents.

[!IMPORTANT] Kuroko is in an early MVP phase. The repository now contains a runnable local HTTP/HTTPS proxy, Cap'n Proto daemon RPC, CLI controls, and a basic native traffic-history GUI. It is not yet a complete interception suite or scanner.

Vision

Modern web testing tools capture large amounts of traffic, but that traffic is often difficult to search, weakly connected to the discovered attack surface, and exposed to automation only through UI wrappers or coarse REST APIs.

Kuroko is designed around a different workflow:

1. Capture HTTP traffic without losing the evidence required for manual testing.
2. Turn traffic into searchable, evidence-backed security observations.
3. Build a typed site graph that connects origins, endpoints, parameters, identities, technologies, components, findings, and scan activity.
4. Let humans, scripts, and authorized agents use the same application services.
5. Require explicit scope, budgets, capabilities, and approvals for operations that send traffic or reveal secrets.

The intended north-star experience is:

capture traffic
  -> search history
  -> expand the site graph
  -> propose a bounded scan plan
  -> obtain approval
  -> execute the plan
  -> return findings linked to exact request/response evidence

Product Principles

• Evidence first — findings and graph relations must link back to captured traffic or another explicit source.
• Agent native, not agent controlled — MCP is a first-class application adapter, but policy and local user control remain authoritative.
• Safe by default — remote access is disabled by default, secrets are redacted by default, and effectful operations require scoped capabilities.
• Raw when necessary — normal traffic uses safe HTTP stacks, while advanced testing can opt into a separate raw HTTP path that preserves malformed input.
• Programmable without surrendering the host — extensions receive narrow, versioned capabilities instead of unrestricted process access.
• Rebuildable intelligence — search indexes and graph views are projections; captured project data remains the source of truth.
• Incremental delivery — build a complete vertical slice before pursuing broad feature parity with existing suites.
• Library first — adopt and wrap maintained libraries, maintain narrow forks only for product-critical behavior, and rewrite only the missing layer.

Planned Capabilities

Interception and manual testing

• HTTP/1.1 and HTTP/2 interception with local certificate authority support.
• Request/response interception, history, message editing, and repeater flows.
• WebSocket and Server-Sent Events history.
• A separate raw HTTP/1 transport for desynchronization, smuggling, duplicate header, and malformed-message research.
• Burp-inspired workflows presented through an egui/wgpu desktop interface.

Search and traffic intelligence

• Tantivy full-text search across sanitized request, response, and operational fields.
• Structured filters for project, scope, host, path, status, MIME type, tags, technologies, findings, and timestamps.
• Explicit projection checkpoints so callers can see search and graph lag.
• Metadata observations for JWT, OAuth/OIDC, cookies, technologies, JavaScript components, API schemas, and rule-based extraction.

Evidence-backed site graph

• Typed nodes and relations for origins, hosts, endpoints, parameters, identities, authentication artifacts, technologies, components, findings, exchanges, and scan jobs.
• Confidence, provenance, temporal validity, and evidence references on derived data.
• Bounded graph queries suitable for both the desktop UI and MCP clients.

Scanner and crawler

• Durable scan jobs with progress, cancellation, request budgets, duration budgets, rate limits, and per-target scope enforcement.
• Declarative YAML templates and dependency-aware scan playbooks.
• Passive and active checks that emit normalized findings with exact evidence.
• A graph-aware crawler that can combine passive links, HTML and JavaScript discovery, API descriptions, and an optional browser/CDP worker.

TLS fingerprint profiles

• A wreq/BoringSSL-based outbound transport for configurable TLS and HTTP client profiles.
• Typed, versioned browser/client profiles maintained in the wreq-util fork, including TLS, ALPN, HTTP/2, header-order, and emulation settings.
• Project selection by profile ID, revision, and bounded typed overrides rather than a second file-defined profile subsystem.
• JA3/JA4 observations for the client-to-proxy, proxy-to-target, and target-to-proxy portions of a connection.

Native MCP

• An embedded MCP server backed directly by Kuroko application services.
• Local stdio and authenticated remote Streamable HTTP transports.
• Resources for projects, exchanges, graph entities, findings, and jobs.
• Read-only capabilities by default; scoped and audited tools for replay, crawling, scanning, proxy control, and profile activation.
• Progress, cancellation, durable tasks, redaction, and local approval flows.

Extensions

• WebAssembly Component Model extensions with versioned WIT interfaces.
• Capability-gated access to history, findings, extension storage, and controlled network operations.
• Optional Lua scripting for trusted local automation.
• Python integrations through an isolated worker process rather than an embedded interpreter.
• Declarative commands, filters, table columns, inspectors, and panels instead of exposing internal egui or Rust types across the extension boundary.

Architecture

Kuroko is designed as a daemon-first modular monolith. The desktop UI, CLI, and MCP server are adapters around the same application layer.

Captured traffic is committed before optional search, graph, and intelligence projectors process it. See the traffic and data-flow diagram for the complete pipeline.

See ARCHITECTURE.md for the component model, dependency rules, data flows, security boundaries, and proposed Cargo workspace.

Contributor references:

• Component model
• Package map
• Dependency and fork strategy
• D2 diagram sources and regeneration

Architecture decisions are recorded in docs/adr:

• ADR-0001: Turso canonical storage and rebuildable projections
• ADR-0002: Native MCP as an application adapter
• ADR-0003: WASM/WIT extension boundary
• ADR-0004: Library-first implementation and fork policy
• ADR-0005: Cap'n Proto local daemon RPC

Technology Direction

Technology	Intended role
Rust and Tokio	Core implementation and asynchronous runtime
Hyper	Standards-compliant inbound HTTP and common proxy traffic
libs/hudsucker	Strategic fork for inbound HTTP/TLS interception and extension hooks
libs/wreq	Strategic fork for fingerprinted outbound HTTP/TLS transport
libs/wreq-util	Strategic fork for typed browser/client emulation profiles
Turso Database	Embedded SQLite-compatible canonical project store
Content-addressed local blobs	Raw request/response bodies and large evidence
Tantivy	Rebuildable full-text search projection
egui and wgpu	Cross-platform desktop UI
Cap'n Proto	Versioned local CLI/GUI-to-daemon RPC
Official Rust MCP SDK (rmcp)	Native local and remote MCP transports
Wasmtime and WIT	Sandboxed, versioned extension interface

Technology choices are isolated behind application ports where practical. A storage engine, transport, or index implementation must not define the domain model.

Roadmap

Phase 0 — Foundation

• Evolve the scaffolded Cargo workspace and enforce dependency rules.
• Port or implement typed domain contracts, IDs, sensitivity classes, and durable event/outbox envelopes.
• Implement Turso project storage, migrations, retention, and secret handling.
• Establish the local daemon protocol and security model.

Phase 1 — Golden vertical slice

• Capture HTTP/1.1 and HTTP/2 traffic through a local MITM proxy.
• Persist exchanges and body references.
• Search history through Tantivy.
• Provide desktop history, intercept, message editor, and repeater workflows.
• Expose read-only history search and exchange resources over local MCP stdio.

Phase 2 — Traffic intelligence

• Add metadata detectors for authentication, technologies, and components.
• Build the evidence-backed site graph.
• Add passive scanning and graph-aware crawling.
• Extend typed wreq-util profiles and add emitted-fingerprint verification.

Phase 3 — Agent-native active testing

• Add authenticated remote MCP over Streamable HTTP.
• Add principals, capabilities, target scopes, budgets, approvals, and audit trails.
• Implement scan-plan DAGs, active templates, durable jobs, and OAST lifecycle support.
• Return normalized findings linked to request/response evidence.

Phase 4 — Extension platform

• Stabilize WIT host interfaces and extension packaging.
• Add Wasmtime resource controls and capability policy.
• Add optional Lua scripting and an isolated Python worker protocol.
• Add declarative UI contributions and an extension registry.

Phase 5 — Advanced protocol testing

• Add raw malformed HTTP/1 workflows and desynchronization tooling.
• Deepen WebSocket and SSE support.
• Add HTTP/3 and browser/CDP crawling where justified by user workflows.
• Evaluate distributed workers only after the local job model is stable.

The roadmap intentionally prioritizes an end-to-end useful workflow over class-by-class or feature-by-feature parity with ZAP or Burp Suite.

Proxy and GUI MVP

The first runnable slice provides HTTP/HTTPS forwarding with a generated local CA, bounded request/response previews, redacted credential headers by default, JSONL history, daemon-owned in-memory history, CLI controls, and a native egui history/inspector window. Manual forward/drop/edit interception, repeater, Turso, Tantivy, MCP, and scanning are not implemented yet.

Prerequisites

• Rust 1.95 or newer.
• Cap'n Proto compiler 1.5 or a compatible release (capnp --version).
• macOS or another Unix platform for the MVP Unix-socket transport.
• Initialized Git submodules: git submodule update --init --recursive.

On macOS, install the schema compiler with brew install capnp if needed.

Build and run

Build the three runnable applications:

cargo build -p kuroko-daemon -p kuroko-desktop -p kuroko-cli

Start the daemon in one terminal. It starts the proxy on 127.0.0.1:8080 by default and creates .kuroko/kuroko.sock for Cap'n Proto RPC:

cargo run -p kuroko-daemon

Start the desktop in another terminal:

cargo run -p kuroko-desktop

Or inspect/control the daemon through the CLI:

cargo run -p kuroko-cli -- proxy status
cargo run -p kuroko-cli -- history list
cargo run -p kuroko-cli -- history show 1

Configure a browser to use HTTP proxy 127.0.0.1:8080. For HTTPS interception, trust the generated .kuroko/ca/kuroko-ca.pem certificate in that browser or test explicitly with:

curl --proxy http://127.0.0.1:8080 \
  --cacert .kuroko/ca/kuroko-ca.pem \
  https://example.com/

Local state is ignored by Git. .kuroko/ contains the CA private key and may contain captured traffic. Body content can include secrets even when credential headers are redacted; protect this directory and enable --capture-secrets only for authorized testing.

Development Hooks

Kuroko uses Bun and Husky for local Git hooks:

bun install

The pre-commit hook checks Rust formatting for Kuroko-owned packages under apps/ and crates/kuroko-*:

bun run format:rust:check

Apply formatting with:

bun run format:rust

The strategic forks under libs/wreq and libs/wreq-util are intentionally excluded. They follow the formatting toolchain and checks of their own repositories.

Inspirations

Kuroko learns from, but does not intend to clone the internal architecture of:

• OWASP ZAP for open-source interception and scanning workflows.
• PortSwigger Burp Suite and Bambdas for interactive testing and programmable workflow ideas.
• Nuclei for declarative templates and playbooks.
• TLS+ for native TLS profile and JA3/JA4 work.
• HaE for modular traffic extraction.
• WappalyzerGo for technology-fingerprint workflows.

Code, templates, rules, and fingerprint data from other projects must not be copied into Kuroko without an explicit license and provenance review.

Responsible Use

Kuroko is intended for systems that the operator owns or is explicitly authorized to test. Remote MCP, active scanning, raw HTTP features, and extension capabilities must be designed to preserve that authorization boundary.

License

Kuroko is licensed under the Apache License, Version 2.0.