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.

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

Related MCP server: agentguard

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

Technology Direction

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.

Current Repository State

The repository contains a scaffolded Cargo workspace with application and crate boundaries under apps/ and crates/. Strategic wreq and wreq-util forks live under libs/. Each Kuroko package has a local README describing its responsibility and planned integrations.

The packages are currently documentation-only scaffolds. The daemon, proxy, persistence layer, UI, scanner, and MCP server do not yet implement product behavior.

Build and installation instructions will be added after the Phase 1 vertical slice exists.

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.