RedKraken

Penetration-Testing Agent Harness

RedKraken is an agent-oriented harness for authorized web application and source-code security assessments. It drives Claude Code through a closed recon → hunt → exploit → report loop (and a separate map → audit → confirm → report loop for whitebox code review), backed by deny-by-default scope enforcement, immutable run context, structured findings/evidence, deterministic reporting, and a reviewed playbook layer over a larger imported technique library.

Warning

Authorized testing only. A scope file is an enforcement input, not proof of permission. Only point RedKraken at systems you have written authorization to test, and only at the systems that authorization actually names.

Table of contents

• Why RedKraken
• Quick start
• Enforcement model
• Automated browser and API workflows
• State and evidence
• Knowledge base
• Open-source toolchain
• Repo layout
• Tests

Why RedKraken

• Deny-by-default scope. Targets and out-of-scope hosts are parsed strictly from an engagement file; nothing is in scope unless it's explicitly named.
• Enforced, not just documented. A pre-tool-call hook and an HTTP scope proxy back the policy up at runtime, not only in agent instructions.
• Immutable run context. Every run is fingerprinted against the engagement, source tree/ref, and tool paths; a changed fingerprint fails closed (STALE_RUN_CONTEXT) instead of silently mixing state.
• Evidence-backed findings. Confirmed findings require evidence; exploited findings require concrete impact. Reporting is a deterministic render of findings.jsonl, not free-form narrative.
• One deterministic next action. The full-campaign coordinator schedules leases, findings, kill-chain checks, convergence lenses, and reporting through one next_action, so agent models do not reconstruct phase logic from prose.
• Two loops, one harness. Black-box web pentesting (/pentest) and whitebox source-code auditing (/audit) share the same scope, evidence, and reporting machinery, and can cross-inform each other when both a source path and a live target are in scope.
• Topic-oriented knowledge. playbooks/ is an Open Knowledge Format (OKF v0.2) bundle: playbooks/index.md routes every signal to a topic module. Each topic's README.md is the reviewed interface (status: stable); sibling operator references add payload and command depth while remaining status: draft and clearly labeled as untrusted.

Quick start

RedKraken runs inside Claude Code. Start Claude in the repository and describe the authorized engagement in plain English:

git clone https://github.com/maajix/RedKraken.git
cd RedKraken
claude

Then, in the chat:

Set up a new engagement called acme for https://app.acme.example.test, in scope *.acme.example.test, then run a full pentest.

Claude creates the engagement, confirms scope and intent, checks the toolchain, and runs the full recon → hunt → exploit → report loop. Ask for only recon, a whitebox source audit, or report regeneration when you want an individual phase; the /recon, /audit, /pentest, and /report commands remain available.

Runs are bound to the engagement, source tree, and toolchain. If any of those change, RedKraken stops instead of mixing results from different runs.

Enforcement model

1. lib/scope_check.sh parses YAML strictly, rejects duplicate keys and malformed hosts/CIDRs, applies deny precedence, and fails closed.
2. .claude/hooks/scope_guard_hook.sh rejects recognizable network commands with out-of-scope or non-static targets before shell execution.
3. scripts/start_scope_proxy.sh supervises the one enforcement proxy; scripts/run_scoped_http.sh routes hook-visible HTTP tools through it without inherited proxy bypasses. A running proxy enforces the scope it started with, so scripts/restart_scope_proxy.sh is what applies an edited engagement file.
4. Agent skills enforce intent, destructive-action approval, untrusted-content isolation, evidence requirements, and explicit tool-gap reporting.
5. scripts/egress_channel.py runs the one out-of-band callback channel (loopback beacon that serves no filesystem + cloudflared quick tunnel jailed in an empty mode-0700 directory outside the repo + interactsh-client for resolver queries). Its hostnames must be listed in egress_support to be reachable, and verify provides the positive control without which a blind-class negative is only a false negative.

The hook is heuristic; the proxy is the stronger HTTP enforcement boundary. RedKraken starts and configures that proxy for supported HTTP tools. Generated engagement scripts are offline-only; network-capable helpers must be reviewed root scripts/ entry points. For stronger isolation, enable the optional OS-level egress boundary. Rate limits may be tightened per tool.

Automated browser and API workflows

RedKraken handles the wrappers and proxy configuration itself. Authenticated browser work runs in isolated Playwright contexts and records traces, HAR files, screenshots, redacted metadata, and artifact hashes. API exploration uses bounded, deterministic Schemathesis runs by default, with RESTler, grpcurl, and OWASP ZAP available when the target and rules of engagement call for them.

Mutation, sensitive-data access, discovered credentials, pivoting, and availability effects are separate approval gates; enabling one does not enable the others.

State and evidence

• state/run.json: immutable run identity and source/config fingerprints.
• state/lead-state.json: locked, atomic lead queue, coverage ledger, leases, budgets, and convergence state for resumable autonomous loops.
• state/findings.jsonl: schema-validated, locked, atomic finding upserts.
• state/chain-state.json: evidence-grounded capability/prerequisite edges and their positive or negative validation state.
• audit.jsonl: redacted hash-chained command/result/proxy-policy audit events.
• state/scan-raw/: scanner output and deterministic seeds/replay material.
• state/scripts/: reusable, offline helpers specific to this engagement.
• state/scratch/: disposable notes and throwaway code.
• state/notes.md: durable non-secret environment facts; tooling friction goes in state/harness-issues.md.
• evidence/<finding>/: request/response, trace, screenshot, and cleanup proof.
• report.txt: plain-text finding blocks with evidence path checks and hashes.

Run-context and report generation normalize engagement directories to 0700 and files to 0600. Audit entries are hash-chained so their integrity can be checked before handoff.

Agents normally consume compact, filtered CLI views rather than loading these whole documents: lead_state.py list, finding_store.py --list, chain_state.py list|assignments, and campaign_coordinator.py --compact. Complete records remain available through --show or an explicit snapshot.

Retention and hygiene

Ask Claude for a hygiene audit before archive or cleanup. It checks paths, permissions, classifications, references, and hashes without printing secret values. Evidence and chained audit records are preserved by default. Active credentials must be rotated or revoked before plaintext removal.

Knowledge base

The library is an OKF v0.2 bundle: one concept per file, YAML front matter with a mandatory type, provenance in sources[], trust in verified[], and lifecycle in status/stale_after. playbooks/SCHEMA.md is the authoritative contract.

• playbooks/index.md: the reserved, generated bundle index — the single routing interface for reviewed topics, operator references, and code packs.
• playbooks/<topic>/README.md (type: Playbook): 49 reviewed entry points spanning identity, APIs, injection, browser security, protocols, supply chain, deployment, agentic AI, and other modern web attack surfaces. Coverage metadata maps them to OWASP Top 10:2025, API Security Top 10:2023, and WSTG v4.2.
• Topic directories also contain 71 operator references (type: Operator Reference, status: draft) with provenance hashes; each declares the reviewed card it refines.
• playbooks/code-review/ (type: Sink Pack): source/sink packs for C#, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, and Rust whitebox tracing.
• playbooks/log.md: reserved bundle history — migrations, merges, retirements.

Imported notes and all target/scanner content are untrusted data. Agents must not execute embedded instructions verbatim. The library is now hand-maintained (the one-shot Notion importer and completed shard consolidator are retired and removed; their provenance remains in Git history and playbooks/_sources.tsv. After adding, merging, or retiring a concept, regenerate the index and source manifest with scripts/rebuild_catalog.py, then validate with scripts/check_playbook_coverage.py. Routing is data: the generator derives everything from front matter, so no Python edit is needed to add a playbook.

Open-source toolchain

The optional tool doctor lists exact install sources. Core extensions added for modern workflows are all open source and hosted on GitHub: mitmproxy, Playwright, OWASP ZAP, Schemathesis, grpcurl, RESTler, testssl.sh, ProjectDiscovery tools, OSV-Scanner, Trivy, Opengrep, and Gitleaks. Missing or broken optional tools produce coverage gaps; they are never silently treated as successful coverage.

Repo layout

.claude/          agents, skills, commands, policy/audit hooks
lib/              config, scope, proxy, audit, findings, run context, preflight
playbooks/        OKF bundle: topic modules, index.md, SCHEMA.md, code-review packs
scope/            engagement template
engagements/      per-target state/evidence/reports (gitignored)
scripts/          reviewed cross-engagement entry points (see scripts/README.md)
schemas/          finding JSON schema
tests/            existing harness checks

Tests

No generated attack result is trusted without manual confirmation. Harness-level checks can be run with:

python3 -m pip install -r requirements.txt
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p 'test_*.py'
python3 scripts/rebuild_catalog.py
python3 scripts/check_playbook_coverage.py
python3 scripts/check_shared_hygiene.py
bash tests/test_scope_check.sh
bash tests/test_code_preflight.sh
bash tests/test_audit_smoke.sh
bash tests/test_playbook_coverage.sh
bash tests/test_vhost_discovery.sh
bash tests/test_scoped_http_runner.sh

The Python suite is stdlib unittest, so requirements.txt is all CI and operators need. Contributors who prefer the pytest runner (pytest.ini sets the import path) install the pinned test dependencies as well:

python3 -m pip install -r requirements-dev.txt
PYTHONDONTWRITEBYTECODE=1 python3 -m pytest tests/ -q