battle

> STOP. READ THIS ENTIRE SKILL.MD BEFORE CALLING ANY ENDPOINT. # Battle Skill **Red vs Blue Team Security Competition Orchestrator** Pits a Red Team (attack) against a Blue Team (defense) in a long-running competitive loop. Each team leverages all `.pi/skills` to attack or defend a target codebase. ## Invariant battles (the common case) Battle's default scoring targets exploitation (system-down, command injection), but the most frequent real use of an adversarial Red/Blue loop is verifying a PROJECT-SPECIFIC INVARIANT: "no PII value leaks", "the ledger balances", "the parser drops no record", "the authz check cannot be bypassed". Supply a pluggable invariant Judge -- a small independent module `judge(target_dir, params) -> {passed, violations, evidence}` (schema `battle.invariant_result.v1`). Red's objective becomes "produce an input that makes the Judge fail"; Blue's is "make it pass"; the scorekeeper reads the Judge result, never an agent's self-report. Judges are fail-closed: a judge that errors is a FAILED invariant, never a silent pass. ```bash python3 -m battle_skill.invariant_judge \ --judge fixtures/reference-judges/no_data_leak_judge.py \ --target <released-output-dir> \ --params '{"policy": "policy.json", "output_subdir": "corpus"}' ``` `fixtures/reference-judges/no_data_leak_judge.py` is the anonymizer confidentiality invariant as a Judge: it independently scans released output (JSON scalars incl decoded escapes, numeric expansion, SQLite cells + schema DDL + header integers, text/CSV, report.json, and captured stdout/stderr) for any policy value in any representation. ## Contract variation-family research (generic Battle composition) Battle is not project-specific. For any project or skill with an `acceptance_contract.bundle.v1`, Battle should expand each contract item through Dogpile before claiming comprehensive adversarial coverage: ```bash ./run.sh contract-variation-plan \ --acceptance-bundle /path/to/acceptance_bundle.json \ --dogpile-source brave-search \ --dogpile-source arxiv \ --out /tmp/battle-variation-plan.json ``` The output is `battle.contract_variation_plan.v1`. It is a three-phase Battle contract, not a loose note: 1. Phase 1: pass the frozen `acceptance_contract.bundle.v1` floor. 2. Phase 2: after that pass, gather `$project-state`, current Battle receipts, source-filtered `$dogpile` research, and `$ask one-shot` reviewer proposals. 3. Phase 3: freeze useful Phase 2 findings into deterministic cases, run them, and retain adaptive-lineage proof for Red wins, Blue fixes, and replay. The plan maps every acceptance case to source-bearing Dogpile research lanes and reusable variation families. Use repeatable `--dogpile-source` filters when a Battle phase needs only selected Dogpile providers such as `brave-search`, `arxiv`, `github-search`, `youtube`, `brave-questions`, `feeds`, `wayback`, or `context7` instead of the full source fanout. The reusable variation families include representation equivalence, encoding/normalization, parser differentials, release-surface boundaries, lossy conversion, split/composed facts, scale, retry/concurrency, authorization, and failure-leak boundaries. Dogpile and Ask are research input only: they discover meaningful variation families and source evidence. Battle then freezes selected families into deterministic generators, runs the real target in Docker/QEMU/digital-twin evidence gates, emits `battle.case_receipt.v1` per case, aggregates with `battle.campaign_aggregate.v1`, and retains the workflow classes as `$agentic-evals` cases. A serious release gate should expect hundreds of deterministic cases and roughly 20-30 retained eval classes when the contract surface is broad; smaller smoke gates must label themselves as smoke. ## Invariant campaigns (test the contract floor, then attack beyond it) An invariant *battle* judges one output. An invariant *campaign* has Red generate the whole MATRIX of input "versions" the target's spec names -- every format x every representation x the documented edge cases -- PLUS random fuzz, runs the real target on each, and the Judge scores every output. Every case emits a `battle.case_receipt.v1` with fixture precheck, execution, rejection, security Judge, optional functional Judge, and verdict fields. A campaign PASSES only if all case receipts pass, required `MUST_ACCEPT` cases are actually accepted and functionally judged, required `MUST_REJECT` cases are safely rejected, and the computed `battle.campaign_aggregate.v1` has no failed or incomplete cases. One failing version is a concrete, reproducible Red win. For anonymization/privacy targets, the acceptance contract is only the floor. When an `acceptance_contract.bundle.v1` exists, the arena build may pass it as `acceptance_floor` to the production adapter. Battle then fails closed unless every `acceptance_cases[]` id maps to at least one campaign generator case in the profile's `required_case_ids`; those are the bare-minimum adversarial versions that MUST pass before any extra fuzz or beyond-contract cases matter. Battle must also run a beyond-contract campaign that attacks surfaces a client brief often omits: JSON keys and duplicate keys, CSV headers/dialects/multiline cells, SQLite identifiers/defaults/generated values/partial indexes/triggers, filenames, report.json, stdout/stderr, alternate encodings, and same-identity representation traps. A clean brief-matrix replay alone is a smoke proof, not a comprehensive Battle proof. ```bash python3 -m battle_skill.invariant_campaign \ --generator fixtures/reference-generators/anon_brief_matrix.py \ --target-run-cmd 'docker run --rm -v {input}/corpus:/trial/input/corpus:ro -v {input}/policy.json:/trial/input/policy.json:ro -v {output}:/trial/output anonymization-trial run' \ --judge fixtures/reference-judges/no_data_leak_judge.py \ --gen-params '{"fuzz": 20}' --judge-params '{"output_subdir": "corpus"}' ``` `fixtures/reference-generators/anon_brief_matrix.py` yields the anonymization brief's versions: the four formats, JSON string/int/float/scientific, SQLite TEXT/INTEGER/REAL, Unicode NFC/NFD, BOM, JSON \u-escape, SQLite CHECK-literal, plus fuzz. It also carries the oai-trial roundtable edge cases: formatted policy phone values stored as digit-only JSON/SQLite numerics, the same identity seeded across every in-scope format, and lossy leading-zero / large-float traps. `fixtures/reference-generators/anon_beyond_brief_matrix.py` is the required next rung for privacy/anonymization proof: it tries non-obvious schema/path/encoding/ log/release-boundary surfaces that go beyond the literal acceptance contract. A generator + target-run-cmd + judge is a pluggable trio: point it at any project's spec matrix and invariant. The no-data-leak Judge also supports an explicit opt-in interpretation profile for transformation semantics. These guarantees are OFF unless declared in `--judge-params`, so Battle does not silently expand the contract after seeing a failure: ```json { "interpretation_profile": { "decoders": ["base64", "base64url", "hex"], "record_local_reconstruction": true, "max_decoded_bytes": 4096 } } ``` With that profile, whole scalar/token base64/base64url/hex values are decoded once and record-local adjacent JSON/CSV/SQLite scalar fields may reconstruct a complete policy value. Arbitrary recursive decoding, global field joins, and visual-confusable character folding remain out of the default blocking gate. After Red finds failing cases and Blue patches the target, emit the replayable lineage receipt instead of summarizing in prose: ```bash ./run.sh invariant-lineage-receipt \ --red-campaign /tmp/red-result.json \ --replay-campaign /tmp/replay-result.json \ --target oai-trial \ --out /tmp/battle-lineage.json ``` A `battle.invariant_adaptive_lineage.v1` PASS proves Red found contract edge cases, Blue removed those Red wins, and the independent Judge replay passed. Then Battle must produce a `$create-report`-validated report with `$project-state` context and an explicit exploits table. The report is the human-readable decision artifact; receipts remain the authority. Generate fresh project state first, then render the report: ```bash PROJECT_STATE_ROOT=/path/to/target ../project-state/run.sh report --json --output /tmp/project-state.json ./run.sh invariant-report \ --campaign /tmp/battle-brief-fuzz.json \ --campaign /tmp/battle-beyond-brief.json \ --adaptive-lineage /tmp/battle-lineage.json \ --project-state /tmp/project-state.json \ --target oai-trial \ --out-json /tmp/battle-report.json \ --out-md /tmp/battle-report.md ``` For project-agent terminal review, use cards when cases have long evidence: ```bash ./run.sh invariant-report \ --campaign /tmp/battle-brief-fuzz.json \ --campaign /tmp/battle-beyond-brief.json \ --project-state /tmp/project-state.json \ --target oai-trial \ --out-json /tmp/battle-report.json \ --out-md /tmp/battle-report.md \ --terminal-cards ``` `invariant-report` is a Typer CLI command. It writes machine JSON to stdout and keeps the human Battle report on stderr. Use `--terminal-cards` for normal project-agent review of Battle evidence: it groups cards under `Acceptance contract floor`, `Beyond-contract exploits`, `Adaptive lineage`, and fallback `Other campaign cases` headings, then prints one `==============` block per case with `Scope`, `Case`, `Acceptance parent`, `Expect`, `Result`, `Example`, `Why Battle checks this`, `Related research`, `Adaptive lineage`, and `Judge evidence`. If a production-adapter receipt carries `acceptance_floor.case_map`, contract-floor cards show the parent `AC-*` id(s); otherwise `Acceptance parent` is `not recorded in case receipt`. If a receipt has `example`, `why_chosen`, `research_refs`, or `source_refs`, cards show those exact fields; otherwise examples/rationales are deterministic from the case id and research is reported as `not recorded in case receipt`. `--terminal-table` remains the compact overview alias for `--terminal-summary`: both print contract floor, Red pressure, Scorekeeper call, and one case-table row per attack. In an interactive terminal Battle uses Rich's terminal-aware colored table (`RED_WIN` red, clean passes green, fail-closed stops yellow) and honors `NO_COLOR`; under capture/CI it falls back to deterministic plain text so logs and tests stay stable. `invariant-report` writes `create_report.report.v1`, validates it through `skills/create-report/run.sh validate`, renders Markdown through `skills/create-report/run.sh render`, and appends `## Exploits Table`. The table must be plain-spoken and scannable: one row per attack case, with columns for `Scope`, `Contractual?`, `Adaptive lineage?`, `Case`, `Exploit / attack`, `Why chosen`, `Expectation`, `Result`, and `Judge evidence`. `Scope` separates `contractual` acceptance-floor cases from `beyond-contract` probes; `Why chosen` explains non-contractual probes; `Adaptive lineage?` marks Red wins that were fixed and replayed; `RED_WIN` blocks release. The table is derived from `battle.case_receipt.v1` when present, falling back to legacy `case_log` only for older campaign receipts. A Battle closure without that report is missing the decision surface even if campaign receipts pass. ## Purpose Boundary Battle's purpose is the Red/Blue security competition backend: authorized target setup, isolated execution, Red attack generation, Blue defense generation, independent Judge replay, scorekeeper receipts, adaptive lineage, and durable learning. Adaptive lineage is a backend learning loop that spawns, evaluates, selects, and promotes or rejects child Red/Blue evidence from Judge-backed receipts. PixiJS is only a spectator/replay surface for Battle receipts. A PixiJS pass proves that recorded receipts can be inspected in a fun replay; it does not prove the Battle orchestrator, provider-driven subagents, Docker/QEMU isolation, overnight scheduler, scorekeeper, or memory learning works. Do not close core Battle readiness from PixiJS evidence alone, and do not block backend adaptive lineage on replay polish beyond truthful receipt inspectability. ## Architecture Production Battle is an orchestration skill, not a large bespoke security engine. The host-side process should schedule rounds, choose personas, dispatch subagents, provision Docker runtimes, collect receipts, score hard runtime signals, write reports, and persist learning. Target code and team-generated code must execute only inside Docker. Required production invariants: - Red and Blue are subagent teams. Each dispatched subagent must include an explicit persona selected by the orchestrator for that turn. Multiple personas per team may run concurrently when the turn benefits from breadth. - Battle execution requires a `security.target_authorization.v1` manifest before Docker, QEMU, target runtime setup, Hack delegation, proof replay, or patch replay starts. The manifest binds project/operator scope and target identity; it is not a legal opinion and does not prove exploit success or patch effectiveness. - Red-team `$hack` execution is a subagent responsibility, not a Battle Python import. Battle performs or schedules scan/research/memory recall, builds the candidate exploit list, chooses the Red persona, dispatches an `agent-skills/agents`/Tau subagent with that contract, and records the returned exploit receipt. - Subagent handoffs and receipts should follow the compact Tau-style JSON contract shape used by `tau.agent_handoff.v1` and `tau.subagent_receipt.v1`, with Battle-specific fields layered on top rather than a separate ad hoc protocol. - Battle calls modular Tau subagent contracts. Tau and the loop/agentic harness own subagent execution and use `scillm` as the LLM/model caller. Battle owns team selection, persona assignment, Docker runtimes, scorekeeping, artifacts, and memory promotion. - SciLLM is a Tau-owned provider sidecar. Battle operators and project agents must not call `$scillm`, `/scillm`, `http://localhost:4001`, `/v1/chat/completions`, or `/v1/scillm/*` directly for Battle proof work. Express provider work as Tau DAGs, Tau command-loop nodes, or Tau skill nodes, then consume Tau receipts and node outputs. - Model choice is strategic but routed through Tau/loop: SOTA models for planning, small fast models for high-throughput mutation generation and triage, specialist models for language/security niches, and batch calls for broad candidate generation. - Red and Blue have free research access through approved agent-side research skills, including `dogpile`, `brave-search`, `memory`, GitHub/code search, docs, papers, CVEs, and public writeups. - All target apps, exploit probes, fuzzers, payloads, repro scripts, patch builds, tests, migrations, dependency installs, and replay checks run in Docker. The host is control plane only. - Docker target runtimes may be rebuilt and relaunched between rounds. Persist only controlled volumes and artifacts that must survive a rebuild; store durable strategic context and learnings in `$memory`. - Docker runtimes must support dynamic language/toolchain selection. Any code language required by the target may be added to the runtime image or selected adapter; Battle should not hard-code one language. - Battle should be high-throughput when the target runtime is warm: thousands of exploit/defense mutations may be attempted with tight 10-15 second Docker execution windows on capable workstation hardware. - Battle should use combinatorial mutation. Red tries every plausible exploit family and combination within safety/time budgets; Blue tries every plausible patch, hardening, configuration, test, detection, and mitigation combination. Successful combinations receive stronger promotion than isolated tactics. - Research may burst concurrently from the agent side. Red and Blue may fan out multiple `brave-search` and `dogpile` calls, including 10x concurrent Brave search batches when needed, then store useful results and negative evidence in `$memory`. - Dogpile research receipts are design input for Battle, not proof. Use them to seed Red exploit-family menus, Blue hardening/detection menus, GitHub security-tool candidates, DARPA/AIxCC context, and follow-up research questions. Exploit success, patch effectiveness, tool safety, and repository adoption still require Battle-owned Docker/QEMU execution, hard runtime signals, and Judge replay. - Security repositories found through Dogpile must flow through `$github-search` evaluation criteria first. Any adopted repo code, PoC, scanner, or payload still runs only inside Battle's isolated target/runtime gates; do not execute untrusted repo-provided install scripts or payloads on the host. - Target containers default to no network. External research happens from the agent side through controlled skills unless a scenario explicitly grants target-container network access. - The scorekeeper records objective outcomes: system down, system still up after the allotted time, exploit success, crash artifacts, patch timing, regression behavior, resource limits, and replay results. It is not an LLM judge. Based on research into RvB framework, DARPA AIxCC, and Microsoft PyRIT: ``` ┌─────────────────────────────────────────────────────────┐ │ Battle Orchestrator │ │ - Game loop (RvB pattern) │ │ - Concurrent Red/Blue execution │ │ - Entropy-driven termination │ │ - Checkpointing for overnight runs │ └─────────────────────────────────────────────────────────┘ │ │ ┌────┴────┐ ┌────┴────┐ │ Red Team │ │ Blue Team│ │ (Thread) │ │ (Thread) │ ├──────────┤ ├──────────┤ │ Skills: │ │ Skills: │ │ - hack │ │ - anvil │ │ - memory │ │ - memory │ └──────────┘ └──────────┘ │ │ └──────────┬───────────────────┘ │ ┌───────────────┴────────────────────┐ │ Digital Twin │ │ ┌─────────────────────────────┐ │ │ │ Mode: git_worktree │ │ │ │ - Red attacks arena │ │ │ │ - Blue patches workspace │ │ │ │ - Cherry-pick to test │ │ │ ├─────────────────────────────┤ │ │ │ Mode: docker │ │ │ │ - Isolated containers │ │ │ │ - Battle network │ │ │ ├─────────────────────────────┤ │ │ │ Mode: qemu │ │ │ │ - Emulated firmware │ │ │ │ - GDB attach points │ │ │ └─────────────────────────────┘ │ └────────────────────────────────────┘ ``` ## Digital Twin Modes The battle skill supports multiple target types through its Digital Twin system: ### 1. Source Code (git_worktree) For battling over git repositories. Creates isolated git worktrees for each team. ```bash ./run.sh battle /path/to/repo --rounds 100 ``` ### 2. Docker Container (docker) For battling over containerized applications. Spins up separate containers for each team. ```bash # Using a Docker image ./run.sh battle --docker-image nginx:latest --rounds 100 # Using a Dockerfile in the target directory ./run.sh battle /path/with/Dockerfile --mode docker ``` ### 3. Firmware/Microprocessor (qemu) For battling over firmware and embedded systems. Boots firmware in QEMU emulator. ```bash # Auto-detect architecture from ELF header ./run.sh battle firmware.elf --rounds 100 # Specify machine type explicitly ./run.sh battle firmware.bin --qemu-machine arm ./run.sh battle firmware.bin --qemu-machine riscv64 ./run.sh battle bios.rom --qemu-machine x86_64 ``` Supported QEMU machines: - `arm` - ARM Cortex-M (STM32, etc.) - `aarch64` - ARM64 - `riscv32`/`riscv64` - RISC-V - `x86_64`/`i386` - x86 - `mips` - MIPS (routers, embedded) ### 3b. Full-system VM (qemu-vm) For battling over host-level policy (systemd units, AppArmor profiles, cgroup-BPF IP filters) that Docker twins cannot host because containers share the host kernel. Boots a base cloud image (e.g. Ubuntu 24.04 qcow2) with a fresh overlay per round, KVM acceleration, ephemeral SSH key via NoCloud cloud-init, executes one payload inside the VM, and writes a `battle.vm_round.v1` receipt. Requires a `security.target_authorization.v1` manifest binding the image path AND sha256 before QEMU starts. ```bash