The Citadel

Experimental security tools for agent workflows: Linux confinement, environment filtering, signed single-packet authorization, decoy services, receipt tooling, and small Bend algebraic examples. Code is MIT licensed.

Start with audit scope and evidence boundaries. The old practice audit report is withdrawn as an assurance claim. No independent security audit or production qualification is established by this repository's internal checks.

What each part currently demonstrates

The seven-ring arrangement is a design organization. It does not mean an attacker must defeat every component or that touching one decoy prevents an attack. Source modules may retain historical names; use the boundaries above when interpreting those names and older reports.

Reproduce a bounded check

Requirements: Python 3.10+ and a compatible Bend compiler on PATH (the current local reproduction used Bend 2.0.39). The report command does not import the product modules, read personal keys, or mutate a personal WhiteMagic store. Select an output directory outside this checkout to keep your working tree clean:

python3 defense/practice_audit_battery.py --checks bend --output-dir /tmp/citadel-internal-checks
python3 -m unittest discover -s defense -p test_practice_audit_reporting.py -v

To run the Citadel Comprehensive Benchmark across all defense and counter-economic tracks:

python3 defense/citadel_comprehensive_benchmark.py
python3 -m pytest -v defense/test_citadel_benchmark.py defense/test_pow_gate.py defense/test_gas_trap.py

With cryptography installed, python3 -m unittest discover -s defense -p test_pqc_claim_boundaries.py -v also checks experimental output disclosures, an isolated signature/tamper fixture, and failure exit status. It uses temporary fixture keys and does not qualify the custom construction for security use.

The Bend selection runs both the front-end check and the separate --verdict kernel recheck. The latter needs the kernel dependencies reported by Bend (the local tool requests Lean 4.34.0 or a built BENDTT kernel). Missing kernel infrastructure is NOT_EVALUATED, even if the front-end checker succeeds.

The paired JSON/Markdown reports record compiler and source hashes, command outputs, process wall times, and synthetic leaves per second calculated from the same measurement. Wall time includes compiler checking and startup. PASS applies to the selected checks only; unsupported lanes remain NOT_EVALUATED with reasons.

Exit status is 0 when all selected checks pass, 1 for an actual failed check, and 2 when selected checks cannot be evaluated. Missing engines, matching crashes, empty output, and malformed verifier results cannot create parity.

For a separate CPR agreement check, first build the Python/Rust/JavaScript verifiers according to the selected CPR checkout's own instructions, then pass its exact location explicitly:

python3 defense/practice_audit_battery.py --checks differential --cpr-dir /path/to/continuity-receipt --output-dir /tmp/citadel-cpr-agreement

This checks the three bundle manifests, honors their anchor options, and compares verdicts and error codes against each other and the declared expected outcomes. Manifests themselves are not counted as receipt fixtures. Agreement between three implementations maintained in the same project is useful consistency evidence; an independent oracle and source-to-binary build provenance still need separate evidence.

Optional ASGI proof-of-work admission

Enable the gate explicitly with CitadelShieldMiddleware(app, enable_pow_gate=True, pow_difficulty=4). Difficulty is an integer from 1 through 8, measured in leading hexadecimal zeros. The default is 4. Invalid settings or an enabled gate's initialization failure stop startup rather than enabling passthrough.

Requests under /api/heavy receive HTTP 428 and a JSON challenge. Solve it with PoWGate.solve(challenge), then send X-Citadel-PoW-Solution containing a JSON object {"challenge": <the issued object>, "nonce": "<solver nonce>"}. The middleware verifies the signature, transport-peer IP, lifetime, configured minimum difficulty and work before calling the application. The header is limited to 4096 bytes; duplicate, malformed and invalid solutions receive a new challenge. Each challenge admits one request, including when different valid nonces are submitted concurrently. Ledger work counts remain estimates rather than measured hashes performed by a client.

Replay custody is in memory for one PoWGate instance and has a bounded cache. When full, it refuses new redemptions until entries expire; it does not evict live entries to make replay possible. This is not shared multiworker replay protection: workers using one signing secret require shared replay custody or challenge routing to the issuing instance. Ephemeral fallback secrets also do not survive process restarts. Proxy deployments must establish the trusted transport peer upstream; this admission path does not trust client-supplied X-Forwarded-For. No deployed service or outside attack resistance is qualified by these local ASGI and gate tests.

Standalone launcher smoke

defense/opencode_kekkai_launcher.py uses Python's standard library. The Linux backend needs x86_64 or arm64 and a kernel exposing Landlock; unsupported hosts fail before spawning the child. Run a harmless owned-workspace fixture with a deliberately minimal environment:

scratch=$(mktemp -d) || exit 1
workspace="$scratch/workspace"
mkdir "$scratch/home" "$workspace"
printf '%s\n' 'owned launcher fixture' > "$workspace/probe.txt"
env -i PATH=/usr/bin:/bin HOME="$scratch/home" python3 \
  defense/opencode_kekkai_launcher.py --workspace "$workspace" -- \
  /usr/bin/cat "$workspace/probe.txt"
rm -r -- "$scratch"

The launcher installs filesystem restrictions only. It inherits the child environment and leaves networking unrestricted; it does not scrub credentials or establish an OpenCode/Devin client integration. The fixture above only checks child startup and an allowed read. Use the separate confinement positive/negative controls before making a containment claim. macOS has a separate Seatbelt path; this Linux fixture does not qualify it.

Demonstrations and integration work

arena/halo_ctf_visualizer.html is an illustrative animation. Its scripted scores, killfeed, and timing labels are not live red-team telemetry. The legacy master benchmark and escape/mutation scripts also need review before their printed success labels can serve as acceptance criteria; see the open review list.

docs/OPENCODE_2_1_1_SECURITY_ALIGNMENT_REPORT.md is a maintainer-authored study of a named historical version. The plugin and launcher need qualification against the exact host/runtime being used. Installing an environment filter alone does not establish protection of credentials, transcripts, or every execution path.

License

MIT · Copyright (c) 2026 Lucas Bailey / WhiteMagic Labs.

Supported middleware deployment contract

Use one process with one PoWGate per admission domain. Multiple middleware instances in that process may receive the same pow_gate= object, sharing its atomic replay cache. Separate workers and restarts do not share consumed challenges; shared signing keys alone do not solve that problem. A multiworker or restart-persistent deployment needs an independently qualified shared atomic consumption backend. The default ephemeral signing key invalidates old puzzles on restart; do not infer this for an operator-supplied persistent key.

protected_prefixes=("/api/heavy",) matches that path and its child paths, not /api/heavy-other. Configure other absolute path prefixes explicitly. admission_counts exposes process-local outcome counts for application-owned metrics; it contains no IPs, request bodies or solution tokens. Both puzzle binding and decoy attribution use the ASGI peer. Configure any trusted proxy's sanitized peer handling at the ASGI server; client-provided forwarded headers are never trusted directly by this middleware.

The offline CI uses synthetic puzzles, fixtures and installed-package imports. It does not run sweepers, contact targets, use wallets or qualify a live host.