# 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, 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:

```text
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.

![Kuroko component model](docs/diagrams/generated/component-model.png)

Captured traffic is committed before optional search, graph, and intelligence
projectors process it. See the
[traffic and data-flow diagram](docs/diagrams/generated/traffic-data-flow.png)
for the complete pipeline.

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

Contributor references:

- [Component model](docs/architecture/COMPONENT-MODEL.md)
- [Package map](docs/architecture/PACKAGE-MAP.md)
- [Dependency and fork strategy](docs/DEPENDENCIES.md)
- [D2 diagram sources and regeneration](docs/diagrams/README.md)
- [Competitor-informed feature catalog](docs/FEATURES.md)

Architecture decisions are recorded in [docs/adr](docs/adr/README.md):

- [ADR-0007: SQLx bundled SQLite canonical history](docs/adr/0007-sqlx-bundled-sqlite-canonical-history.md)
- [ADR-0002: Native MCP as an application adapter](docs/adr/0002-native-mcp-application-adapter.md)
- [ADR-0003: WASM/WIT extension boundary](docs/adr/0003-wasm-wit-extension-boundary.md)
- [ADR-0004: Library-first implementation and fork policy](docs/adr/0004-library-first-and-fork-policy.md)
- [ADR-0005: Cap'n Proto local daemon RPC](docs/adr/0005-capn-proto-local-daemon-rpc.md)

## 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 |
| SQLx 0.9 bundled SQLite | Normalized canonical capture history and preview BLOBs |
| 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 the broader project store, 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,
daemon-owned SQLite history, private-memory mode, 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. Protocol 1.4 adds the managed build identity used
for exact packaged-component matching; response CLI controls remain deferred. Repeater,
Tantivy, MCP, and scanning remain planned.

### 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:

```bash
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:

```bash
cargo run -p kuroko-desktop
```

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

```bash
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. Chromium's normal
certificate verification remains active. On macOS, open Settings, choose
**Trust CA…**, confirm opening Keychain Access, import the daemon-reported CA
file into the `login` keychain, expand **Trust**, set **Secure Sockets Layer
(SSL)** to **Always Trust**, then fully quit and relaunch the browser. Kuroko
does not auto-trust the CA. 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
isolate credentials from the user's login password. An external browser can
instead trust the generated CA or test with:

```bash
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`:

```bash
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:

```bash
bun install
```

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

```bash
bun run format:rust:check
```

Apply formatting with:

```bash
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](https://github.com/zaproxy/zaproxy) for open-source interception
  and scanning workflows.
- [PortSwigger Burp Suite and Bambdas](https://github.com/PortSwigger/bambdas)
  for interactive testing and programmable workflow ideas.
- [Nuclei](https://github.com/projectdiscovery/nuclei) for declarative templates
  and playbooks.
- [TLS+](https://github.com/nguyenthdat/tlsplus) for native TLS profile and
  JA3/JA4 work.
- [HaE](https://github.com/overspace-labs/HaE) for modular traffic extraction.
- [WappalyzerGo](https://github.com/projectdiscovery/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](LICENSE).