Kuroko Server

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, manual request and response Forward/Drop/Edit interception, Cap'n Proto daemon RPC, CLI controls, and a native traffic workbench. 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 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 workbench. Manual Intercept has separate request and response toggles, with response interception off by default. Its unified native queue and editor can edit, forward, or drop paused requests and fully buffered bounded responses. Dropping a response closes the downstream connection without synthesizing a 502, while history retains the captured upstream response with a marker. A one-shot request action can force interception of that request's response. Timeouts, disabled interception, queue capacity, and response body overflow all fail open. Protocol 1.3 carries the response methods and gates them when a client connects to an older daemon; response CLI controls remain deferred. 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 desktop. It resolves platform-standard per-user state, starts or reuses the sibling daemon, and connects automatically:

cargo run -p kuroko-desktop

Normal CLI commands also start or reuse the shared daemon. It remains available after the desktop exits:

cargo run -p kuroko-cli -- daemon status
cargo run -p kuroko-cli -- daemon start
cargo run -p kuroko-cli -- proxy status
cargo run -p kuroko-cli -- proxy intercept on
cargo run -p kuroko-cli -- browser status
cargo run -p kuroko-cli -- browser open
cargo run -p kuroko-cli -- intercept list
cargo run -p kuroko-cli -- intercept show 1
cargo run -p kuroko-cli -- intercept forward 1
cargo run -p kuroko-cli -- intercept drop 2
cargo run -p kuroko-cli -- history list
cargo run -p kuroko-cli -- history show 1
cargo run -p kuroko-cli -- daemon stop

The desktop's Open browser action launches an isolated persistent CloakBrowser profile through the active Kuroko listener. That dedicated profile accepts Kuroko-generated interception certificates; the proxy still validates the target's upstream TLS certificate. Do not use this profile as a daily browser or save real credentials in it. On macOS it uses Chromium's mock Keychain mode to avoid requesting the user's login password. An external browser can instead trust the generated CA or test with:

curl --proxy http://127.0.0.1:8080 \
  --cacert "$HOME/Library/Application Support/Kuroko/ca/kuroko-ca.pem" \
  https://example.com/

Installed local state lives beneath the platform application-data directory (~/Library/Application Support/Kuroko/ on macOS). KUROKO_HOME, KUROKO_SOCKET, and companion-binary environment overrides are available for development. The state contains a CA private key, browser cookies, and captured traffic; protect it and enable --capture-secrets only for authorized testing.

The desktop embeds Inter and JetBrains Mono under the SIL Open Font License; the corresponding license texts live beside the font assets in crates/kuroko-gui/assets/fonts/.

Personal macOS package

Install the pinned release tool once, then create a local .app/.dmg:

bun run package:setup
bun run package:macos:personal

The package contains kuroko-desktop, kuroko-daemon, and kuroko-cli under Kuroko.app/Contents/MacOS. The personal workflow also stages a lawfully downloaded CloakBrowser from ~/.cloakbrowser or CLOAKBROWSER_BINARY_PATH.

Do not redistribute a package containing CloakBrowser. Its compiled binary uses the separate license at third_party/cloakbrowser/BINARY-LICENSE.md and requires a CloakHQ OEM agreement for redistribution or third-party embedding. The guarded staging command is only for personal/internal packages.

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.