RedChain — PhalanxCyber

01Overview

Most autonomous red-team agents put one LLM in a tool-use loop and hope it stays on task across a multi-day engagement. RedChain takes the opposite stance: it runs an offensive security engagement as a deterministic state machine of Kill Chain phases, where each phase is driven by a purpose-built specialist agent, produces a schema-validated artifact, and cannot advance until a hard-coded gate confirms that artifact is complete. The orchestrator — not the model — owns every phase transition.

Built on the Anthropic SDK, RedChain trades the freewheeling autonomy of loop-based agents for reproducibility, auditability, and structured deliverables. Every engagement lives in a self-contained directory: a manifest, a SQLite state store recording phase status and gate decisions, one markdown artifact per phase, and a full JSONL prompt/response transcript for every agent run. Engagements checkpoint to disk and resume exactly where a gate paused them, which is what makes multi-day, multi-analyst campaigns tractable.

The comparison the README draws is precise — autonomous loops track phases but never enforce them, decide their own next step, and leave you a conversation log; RedChain enforces phases in code, keeps transitions deterministic, and leaves you an artifact-per-phase plus a per-gate transcript audit trail. It is the right tool when a red team needs signed-off scope, defensible evidence, and a report they can hand to a SOC — not when they want a model to freelance against a live target.

This is an honest Alpha (v0.1.0): three of the nine Kill Chain phases — scope, recon, and report — are wired end-to-end behind the webapp preset, with the remaining six (weaponize, delivery, exploit, installation, C2, objectives) documented as planned but not yet implemented (no phase modules or PHASE_REGISTRY entries yet). Critically, the MVP plans and validates rather than weaponizes: agents synthesize scope briefs and recon dossiers and explicitly refuse to actively scan or exploit, making it safe to demonstrate while the offensive phases mature.

02Key Capabilities

Gated phase state machine

Each phase must pass a code-enforced gate before the orchestrator advances, so a scope brief with no objectives or a recon dossier with no entrypoints hard-stops the pipeline instead of silently proceeding.

Specialist agent per phase

Distinct system-prompted agents (Planner for scope/report, Network Analyst for recon) each own a narrow deliverable, rather than one general agent improvising every step.

Validated artifact per phase

Every phase emits a Pydantic-modeled, Jinja2-rendered markdown artifact where the structured model is the source of truth and the markdown is the human-readable view.

Checkpoint and resume

Engagement state persists to SQLite between phases so `redchain resume` picks up at the next unsatisfied phase — built for multi-day campaigns that span sessions.

Full transcript audit trail

Every agent invocation writes a JSONL prompt/response transcript with token-usage metadata, giving a defensible, replayable record of exactly what each agent saw and produced.

Dry-run mode with fixtures

`--dry-run` swaps live API calls for canned fixture responses, letting the entire orchestrator run end-to-end in CI or offline without an API key.

Prompt caching built in

System prompts are sent with ephemeral cache_control so repeated agent calls across a long engagement reuse cached context and cut token cost.

Preset-driven engagements

YAML presets declare the phase order and default model for an engagement class (e.g. webapp), making engagement types reproducible and versionable.

Plan-not-weaponize safety posture

Recon and scope agents are instructed to synthesize passive findings and never actively scan or exploit, keeping the MVP safe to demonstrate against real targets.

Queryable vulnerability reference

A CWE-tagged pattern library (SQLi, XSS, IDOR, SSRF, open redirect) is loadable by tag to seed findings with validation and remediation guidance.

Tool integration wrappers

A subprocess integration layer (nmap -sV with XML parsing) degrades gracefully to an explanatory stub when the binary is absent, rather than crashing the phase.

Rich CLI with status inspection

`engage`, `resume`, `status`, and `list-presets` commands render phase state, gate reasons, and artifacts as color tables or machine-readable JSON.

03Architecture

RedChain is a Python package (src/redchain) layered as a runtime that owns control flow, a set of Kill Chain phases each paired with a gate, specialist agents that wrap the Anthropic SDK, and supporting skills, integrations, templates, presets, and a vulnerability reference. The CLI loads a YAML preset, provisions an engagement directory with a SQLite state store and manifest, then the Orchestrator iterates the preset's phases: for each it runs the phase's agent(s), renders a Pydantic-validated artifact from a Jinja2 template, and calls the gate; a failed gate marks the phase failed_gate and pauses the run for resume, while a pass records completion and advances.

runtime/ (Orchestrator + stores)

Orchestrator drives phase transitions; EngagementState is the SQLite store (phases, gate_decisions, transcripts tables); ArtifactStore renders/persists Jinja2 artifacts; AgentSession is the Anthropic wrapper with dry-run and transcript logging.

phases/ (Kill Chain stages)

One module per phase (scope, recon, report wired; the remaining six not yet implemented) defining the artifact model, agent dispatch, and prompt; PHASE_REGISTRY maps preset names to (Phase, Gate) pairs.

gates/ (artifact validators)

Per-phase validators (ScopeGate, ReconGate, ReportGate) that inspect the rendered artifact for required sections and non-empty content and return a pass/fail GateDecision that blocks advance.

agents/ (specialist LLM roles)

System-prompted Agent subclasses — Planner (scope + report) and NetworkAnalyst (recon) — registered in AGENT_REGISTRY, each producing JSON-only responses parsed into artifact models.

skills/ + integrations/ (reusable helpers + tools)

Skills are reusable Python helpers (recon_osint stub); integrations are subprocess tool wrappers (nmap) with timeout handling and graceful degradation when the tool is missing.

templates/ + presets/ + vulnref/ (content)

Jinja2 templates render artifacts (scope brief, recon dossier, executive report); YAML presets declare phase order and default model; vulnref is a CWE-tagged, tag-queryable vulnerability pattern library.

04Project Structure

src/redchain/runtime/Orchestrator, SQLite state store, artifact store, and the Anthropic AgentSession wrapper with dry-run support.

src/redchain/phases/One module per Kill Chain phase (scope, recon, report implemented) plus base Phase class and PHASE_REGISTRY.

src/redchain/gates/Artifact-completeness validators (scope_gate, recon_gate, report_gate) that block phase advancement.

src/redchain/agents/Specialist agent classes (Planner, NetworkAnalyst) with system prompts and the AGENT_REGISTRY.

src/redchain/templates/Jinja2 templates for the three artifacts: scope_brief, recon_dossier, executive_report.

src/redchain/presets/YAML engagement templates; webapp.yaml defines the MVP scope->recon->report flow and default model.

src/redchain/vulnref/CWE-tagged vulnerability pattern library (patterns.json) with load/find-by-tag helpers.

src/redchain/integrations/Subprocess tool wrappers; nmap.py runs nmap -sV and parses XML, stubbing out when nmap is absent.

src/redchain/skills/Reusable Python helpers invokable from any phase; recon_osint is a stub for future passive OSINT providers.

src/redchain/cli.pyTyper CLI exposing engage, resume, status, list-presets, and version commands.

src/redchain/_fixtures/Bundled canned agent responses (planner, network_analyst, report_writer) powering --dry-run runs.

tests/Pytest suite (test_gates, test_orchestrator_dryrun, test_state) exercising gates, the dry-run pipeline, and state store.

05Security Controls

Kill Chain phase model

Structures engagements as a nine-stage Kill Chain (scope, recon, weaponize, delivery, exploit, installation, C2, objectives, report); v0.1.0 enforces scope, recon, and report end-to-end.

Scope gate

Blocks advance unless the scope brief contains In Scope, Objectives, and Authorization sections and the In Scope and Objectives sections are non-empty (placeholder-aware).

Recon gate

Requires the recon dossier to declare at least one entrypoint or service (via list/table row counting) so downstream weaponization has something to act on.

Report gate

Requires Executive Summary, Findings, and Next Steps sections and a substantive (>=60 char) executive summary before the engagement can complete.

Authorization discipline

Agents assume authorized engagements, mark proposed defaults explicitly in the scope brief, and capture authorization_notes and rules_of_engagement as first-class artifact fields.

Non-active reconnaissance

The Network Analyst synthesizes recon from scope and public knowledge, separates confirmed facts from hypotheses (leads), and is instructed not to actively scan the target in the MVP.

CWE-tagged vulnerability patterns

Ships five web vulnerability patterns — SQLi (CWE-89), Reflected XSS (CWE-79), IDOR (CWE-639), SSRF (CWE-918), Open Redirect (CWE-601) — each with validation and remediation notes.

Severity-graded findings

The report artifact model constrains findings to a fixed severity scale (critical/high/medium/low/info) with title, description, evidence, and recommendation.

Secret hygiene in transcripts

Convention mandates that agent transcripts never store secrets; integrations must accept a timeout and never inject unsanitized strings into subprocess calls.

Auditable evidence chain

SQLite records every gate decision with reason and timestamp, and each agent run persists a full JSONL transcript with token usage for post-engagement review.

06Technology Stack

Language: Python 3.10+ (src layout, hatchling build)
LLM SDK: anthropic >=0.40 (default model claude-sonnet-4-6, ephemeral prompt caching)
CLI: typer >=0.12 + rich >=13.7 for tables/console output
Data modeling: pydantic >=2.5 artifact models; jinja2 >=3.1 templating; pyyaml presets/manifest
State: SQLite (stdlib sqlite3), one state.sqlite per engagement
Testing: pytest >=8 with pytest-cov; live tests gated behind a 'live' marker
Lint/Types: ruff >=0.5 (E/F/W/I/UP/B/C4/SIM) and mypy >=1.10
Packaging: hatchling wheel/sdist; console script entrypoint redchain = redchain.cli:app

07Quick Start

$ pip install -e ".[dev]"  # editable install with dev tooling
$ export ANTHROPIC_API_KEY=sk-ant-...  # required for live agent calls
$ redchain engage --preset webapp --target https://app.example.com --out ./engagements/eng-001
$ redchain resume ./engagements/eng-001  # pick up at the phase where a gate paused
$ redchain status ./engagements/eng-001  # inspect phase status and gate reasons
$ redchain engage --preset webapp --target https://app.example.com --out ./engagements/dryrun --dry-run  # no API calls, CI-friendly

08Compliance & Frameworks

Cyber Kill Chain

Engagements are modeled as the classic nine-stage Kill Chain, from scope/recon through weaponize, delivery, exploit, installation, C2, objectives, to report.

CWE

Vulnerability reference patterns map to specific CWE identifiers (CWE-89, CWE-79, CWE-639, CWE-918, CWE-601) with validation and remediation guidance.

09Integrations & Outputs

Explore RedChain

Full source, documentation, and deployment guides live on GitHub.

View on GitHub Browse all tools