citadel-shield 3.0.2__tar.gz

citadel_shield-3.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Bailey (WhiteMagic Labs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

citadel_shield-3.0.2/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: citadel-shield
+Version: 3.0.2
+Summary: Thermodynamic, negative-expected-value (-EV) active cyberdefense framework for modern web and decentralized infrastructure.
+Author-email: Lucas Bailey & WhiteMagic Sangha <ops@whitemagic.dev>
+Project-URL: Homepage, https://github.com/lbailey94/citadel-defense
+Project-URL: Whitepaper, https://github.com/lbailey94/citadel-defense/blob/main/docs/CITADEL_THEORY_AND_ARCHITECTURE.md
+Project-URL: Live Telemetry, https://mcp.whitemagic.dev/defense
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: Proxy Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: eth-account>=0.8.0
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# 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](docs/AUDIT_SCOPE.md). The old
+[practice audit report](docs/PRACTICE_AUDIT_REPORT.md) 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
+
+| Area | Artifact | Evidence boundary |
+|---|---|---|
+| Signature experiments | `defense/violet_pqc.py` | Ed25519 plus custom hash-chain code. This is not a complete SLH-DSA implementation, a FIPS conformance claim, or a measured quantum-security margin. |
+| Single-packet authorization | `defense/violet_spa.py`, `defense/violet_xdp_spa.py`, `defense/violet_xdp_spa.c` | The Python benchmark exercises signed knocks, replay/tamper cases, and a Python packet-table simulation. Compiling a BPF ELF does not load it into a kernel. Its Python timings are not NIC/driver drop latency. |
+| Proof-of-work puzzle gate | `defense/violet_pow_gate.py`, `citadel_shield/middleware.py` | HMAC-SHA256 challenge issuance, bounded solution verification and process-local single-use admission. Expected brute-force solving takes 16^difficulty hashes; this does not measure an operator's cost or establish general attack prevention. Solvers run locally in tests. |
+| Web3 sweeper gas-trap | `defense/violet_gas_trap.py` | Deceptive zero-native-gas honeypot wallet and front-running simulation. Dual-hash forensic ledger of captured attacker gas. Simulates mempool counter-drains under controlled conditions. |
+| Monetized lanes & bounty ledger | `defense/violet_bounty_ledger.py` | Tamper-evident dual-hash accounting ledger tracking on-chain gas sweeps, cognitive token burns, forced PoW hashes, and x402 revenue extracted from adversaries. |
+| Comprehensive benchmark | `defense/citadel_comprehensive_benchmark.py` | Six-track micro-benchmark of PoW gates, LLM token sponges, canary minting/verification, Web3 traps, flytrap taxonomy, and SPA knock generation. Metrics reflect local host throughput. |
+| Theory & architecture | `docs/CITADEL_THEORY_AND_ARCHITECTURE.md` | Comprehensive theoretical foundation and operational blueprint detailing biomimetic defense, counter-economics, and line-rate hardware defenses. |
+| Decoys and canaries | `defense/violet_digital_twin.py` | Controlled decoy and token-detection exercises. Detection rates apply to the supplied cases. The historical economic ratio used assumed token and CPU prices; it is not evidence of adversaries' real costs or general defensive advantage. |
+| Replay filters | `defense/violet_immunize.py` | Deterministic rule generation and replay against a finite corpus. No general zero-false-positive guarantee follows. |
+| Peer notifications and chunks | `defense/violet_mesh_event.py`, `defense/sangha_iroh_swarm.py` | Local protocol and chunk-integrity exercises. They do not establish independent multi-host coordination or a deployed network's behavior. |
+| Confinement and airlock | `defense/mandala_kekkai.py`, `defense/sangha_kekkai.py`, `plugins/opencode-citadel-airlock.js` | Experimental filesystem/network restrictions and environment filtering. Qualification requires actual kernel/support identity, readable and writable positive controls, denied negative controls, subprocess startup evidence, and precise runtime integration. |
+| Algebraic examples | `proofs/citta_pac_laws.bend` | Nine Bool/Nat lemmas. These do not prove implementation-level capability attenuation, anti-rollback correctness, safe fallback, or model-weight behavior. |
+| Synthetic folds | `proofs/citta_pac_swarm.bend`, `proofs/cpr_batch.bend` | Fixed-depth U32 arithmetic tree folds. Leaves are not running agents or cryptographically verified receipts. |
+
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```sh
+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`](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/AUDIT_SCOPE.md).
+
+[`docs/OPENCODE_2_1_1_SECURITY_ALIGNMENT_REPORT.md`](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](LICENSE) · 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.

citadel_shield-3.0.2/README.md

@@ -0,0 +1,178 @@
+# 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](docs/AUDIT_SCOPE.md). The old
+[practice audit report](docs/PRACTICE_AUDIT_REPORT.md) 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
+
+| Area | Artifact | Evidence boundary |
+|---|---|---|
+| Signature experiments | `defense/violet_pqc.py` | Ed25519 plus custom hash-chain code. This is not a complete SLH-DSA implementation, a FIPS conformance claim, or a measured quantum-security margin. |
+| Single-packet authorization | `defense/violet_spa.py`, `defense/violet_xdp_spa.py`, `defense/violet_xdp_spa.c` | The Python benchmark exercises signed knocks, replay/tamper cases, and a Python packet-table simulation. Compiling a BPF ELF does not load it into a kernel. Its Python timings are not NIC/driver drop latency. |
+| Proof-of-work puzzle gate | `defense/violet_pow_gate.py`, `citadel_shield/middleware.py` | HMAC-SHA256 challenge issuance, bounded solution verification and process-local single-use admission. Expected brute-force solving takes 16^difficulty hashes; this does not measure an operator's cost or establish general attack prevention. Solvers run locally in tests. |
+| Web3 sweeper gas-trap | `defense/violet_gas_trap.py` | Deceptive zero-native-gas honeypot wallet and front-running simulation. Dual-hash forensic ledger of captured attacker gas. Simulates mempool counter-drains under controlled conditions. |
+| Monetized lanes & bounty ledger | `defense/violet_bounty_ledger.py` | Tamper-evident dual-hash accounting ledger tracking on-chain gas sweeps, cognitive token burns, forced PoW hashes, and x402 revenue extracted from adversaries. |
+| Comprehensive benchmark | `defense/citadel_comprehensive_benchmark.py` | Six-track micro-benchmark of PoW gates, LLM token sponges, canary minting/verification, Web3 traps, flytrap taxonomy, and SPA knock generation. Metrics reflect local host throughput. |
+| Theory & architecture | `docs/CITADEL_THEORY_AND_ARCHITECTURE.md` | Comprehensive theoretical foundation and operational blueprint detailing biomimetic defense, counter-economics, and line-rate hardware defenses. |
+| Decoys and canaries | `defense/violet_digital_twin.py` | Controlled decoy and token-detection exercises. Detection rates apply to the supplied cases. The historical economic ratio used assumed token and CPU prices; it is not evidence of adversaries' real costs or general defensive advantage. |
+| Replay filters | `defense/violet_immunize.py` | Deterministic rule generation and replay against a finite corpus. No general zero-false-positive guarantee follows. |
+| Peer notifications and chunks | `defense/violet_mesh_event.py`, `defense/sangha_iroh_swarm.py` | Local protocol and chunk-integrity exercises. They do not establish independent multi-host coordination or a deployed network's behavior. |
+| Confinement and airlock | `defense/mandala_kekkai.py`, `defense/sangha_kekkai.py`, `plugins/opencode-citadel-airlock.js` | Experimental filesystem/network restrictions and environment filtering. Qualification requires actual kernel/support identity, readable and writable positive controls, denied negative controls, subprocess startup evidence, and precise runtime integration. |
+| Algebraic examples | `proofs/citta_pac_laws.bend` | Nine Bool/Nat lemmas. These do not prove implementation-level capability attenuation, anti-rollback correctness, safe fallback, or model-weight behavior. |
+| Synthetic folds | `proofs/citta_pac_swarm.bend`, `proofs/cpr_batch.bend` | Fixed-depth U32 arithmetic tree folds. Leaves are not running agents or cryptographically verified receipts. |
+
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```sh
+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`](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/AUDIT_SCOPE.md).
+
+[`docs/OPENCODE_2_1_1_SECURITY_ALIGNMENT_REPORT.md`](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](LICENSE) · 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.

citadel_shield-3.0.2/citadel_shield/__init__.py

@@ -0,0 +1,33 @@
+"""citadel_shield — Negative Expected Value (-EV) Active Cyberdefense Framework."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Add defense directory to sys.path
+DEFENSE_DIR = Path(__file__).resolve().parent.parent / "defense"
+if str(DEFENSE_DIR) not in sys.path:
+    sys.path.insert(0, str(DEFENSE_DIR))
+
+try:
+    from canary_manager import CanaryManager
+    from violet_bounty_ledger import BountyLedger
+    from violet_digital_twin import ProceduralDigitalTwin
+    from violet_gas_trap import GasTrapHoneypot
+    from violet_live_sweeper import LiveGasSweeper
+    from violet_pow_gate import PoWGate
+except ImportError:
+    pass
+
+from citadel_shield.middleware import CitadelShieldMiddleware
+
+__version__ = "3.0.2"
+__all__ = [
+    "CitadelShieldMiddleware",
+    "PoWGate",
+    "ProceduralDigitalTwin",
+    "CanaryManager",
+    "BountyLedger",
+    "GasTrapHoneypot",
+    "LiveGasSweeper",
+]

citadel_shield-3.0.2/citadel_shield/middleware.py

@@ -0,0 +1,173 @@
+"""citadel_shield.middleware — Drop-in ASGI / FastAPI Middleware for Citadel Active Defense.
+
+Provides optional decoys and client puzzle admission for Python ASGI applications:
+  * Intercepts hostile probe paths (/.env, /wp-admin, /latest/meta-data, /api/v1/namespaces)
+  * Serves realistic procedural digital twin decoys with watermarked canaries
+  * Requires verified, single-use PoW solutions on /api/heavy routes when enabled
+
+Usage:
+    from fastapi import FastAPI
+    from citadel_shield.middleware import CitadelShieldMiddleware
+
+    app = FastAPI()
+    app.add_middleware(CitadelShieldMiddleware, enable_pow_gate=True, pow_difficulty=4)
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import pathlib
+import sys
+from typing import Callable
+
+# Ensure local imports resolve
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "defense"))
+
+try:
+    import violet_digital_twin as vdt
+except ImportError:
+    vdt = None
+
+from defense import violet_pow_gate as vpg
+
+logger = logging.getLogger("citadel_shield")
+
+DEFAULT_DECOY_PATHS = {
+    "/.env", "/.env.local", "/.env.production", "/latest/meta-data",
+    "/computeMetadata/v1", "/wp-admin", "/wp-login.php", "/xmlrpc.php",
+    "/api/v1/namespaces", "/v1.24/containers/json", "/aws/credentials"
+}
+MAX_POW_HEADER_BYTES = 4096
+
+
+class CitadelShieldMiddleware:
+    """Drop-in ASGI middleware providing automated deception and client puzzles."""
+
+    def __init__(
+        self,
+        app: Callable,
+        enable_deception: bool = True,
+        enable_pow_gate: bool = False,
+        pow_difficulty: int = 4,
+        decoy_paths: set[str] | None = None,
+        state_dir: pathlib.Path | None = None,
+        protected_prefixes: tuple[str, ...] = ("/api/heavy",),
+        pow_gate: vpg.PoWGate | None = None,
+    ):
+        self.app = app
+        self.enable_deception = enable_deception
+        self.enable_pow_gate = enable_pow_gate
+        self.pow_difficulty = pow_difficulty
+        if (not isinstance(protected_prefixes, tuple) or not protected_prefixes or
+                any(not isinstance(prefix, str) or not prefix.startswith("/") or
+                    "?" in prefix or "#" in prefix for prefix in protected_prefixes)):
+            raise ValueError("protected_prefixes must be a nonempty tuple of absolute path prefixes")
+        self.protected_prefixes = tuple(prefix.rstrip("/") or "/" for prefix in protected_prefixes)
+        self.admission_counts: dict[str, int] = {}
+        self.decoy_paths = decoy_paths or DEFAULT_DECOY_PATHS
+        self.state_dir = state_dir or pathlib.Path(os.environ.get("VIOLET_STATE_DIR", "/tmp/citadel"))
+
+        self.twin = None
+        self.pow_gate = None
+        if self.enable_deception:
+            try:
+                self.twin = vdt.ProceduralDigitalTwin()
+            except Exception as e:
+                logger.warning("Could not initialize ProceduralDigitalTwin: %s", e)
+
+        if self.enable_pow_gate:
+            if (type(pow_difficulty) is not int or
+                    not vpg.MIN_POW_DIFFICULTY <= pow_difficulty <= vpg.MAX_POW_DIFFICULTY):
+                raise ValueError("pow_difficulty must be an integer between 1 and 8")
+            # An explicitly enabled protection must not silently become passthrough.
+            self.pow_gate = pow_gate if pow_gate is not None else vpg.PoWGate()
+
+    async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+
+        # 1. Inspect for decoy paths
+        if self.enable_deception and self.twin and (path in self.decoy_paths or path.startswith("/.env")):
+            # Resolve client IP
+            client_ip = scope.get("client", ("127.0.0.1", 0))[0]
+
+            if path.startswith("/.env"):
+                body = self.twin.get_env_file(src_ip=client_ip).encode("utf-8")
+                await self._send_response(send, 200, b"text/plain; charset=utf-8", body)
+                return
+
+            if "meta-data" in path or "computeMetadata" in path:
+                meta = self.twin.get_aws_metadata(path, src_ip=client_ip)
+                body = (json.dumps(meta) if isinstance(meta, dict) else str(meta)).encode("utf-8")
+                await self._send_response(send, 200, b"application/json", body)
+                return
+
+        # 2. Explicitly enabled PoW admission on the protected route prefix.
+        if self.enable_pow_gate and any(prefix == "/" or path == prefix or path.startswith(prefix + "/")
+                                        for prefix in self.protected_prefixes):
+            client = scope.get("client")
+            if not client or not isinstance(client[0], str) or self.pow_gate is None:
+                await self._send_response(send, 503, b"application/json", b'{"error":"PoW gate unavailable"}')
+                return
+            # Use the ASGI transport peer. Forwarded headers require a trusted proxy
+            # configuration outside this middleware; client-controlled XFF is not identity.
+            client_ip = client[0]
+            submitted = [value for name, value in scope.get("headers", [])
+                         if name.lower() == b"x-citadel-pow-solution"]
+            verified, reason = False, "missing_solution"
+            if len(submitted) == 1:
+                if len(submitted[0]) > MAX_POW_HEADER_BYTES:
+                    reason = "solution_too_large"
+                else:
+                    try:
+                        solution = json.loads(submitted[0].decode("utf-8"))
+                        if not isinstance(solution, dict) or set(solution) != {"challenge", "nonce"}:
+                            raise ValueError("expected challenge and nonce")
+                        challenge, nonce = solution["challenge"], solution["nonce"]
+                        if not isinstance(challenge, dict) or type(challenge.get("difficulty")) is not int:
+                            raise ValueError("invalid challenge")
+                        if challenge["difficulty"] < self.pow_difficulty:
+                            reason = "difficulty_below_policy"
+                        else:
+                            verified, reason = self.pow_gate.verify_solution(
+                                challenge, nonce, client_ip, check_replay=True,
+                            )
+                    except (ValueError, TypeError, UnicodeError, RecursionError):
+                        reason = "malformed_solution"
+            elif submitted:
+                reason = "duplicate_solution_header"
+            self.admission_counts[reason] = self.admission_counts.get(reason, 0) + 1
+            if not verified:
+                challenge = self.pow_gate.generate_challenge(client_ip=client_ip, difficulty=self.pow_difficulty)
+                body = json.dumps({
+                    "error": "PoW challenge required",
+                    "reason": reason,
+                    "challenge": challenge,
+                    "header_required": "X-Citadel-PoW-Solution",
+                    "solution_format": {"challenge": "the issued challenge object", "nonce": "solver nonce"},
+                }).encode("utf-8")
+                await self._send_response(send, 428, b"application/json", body)
+                return
+
+        # 3. Allow legitimate request to proceed
+        await self.app(scope, receive, send)
+
+    async def _send_response(self, send: Callable, status: int, content_type: bytes, body: bytes) -> None:
+        await send({
+            "type": "http.response.start",
+            "status": status,
+            "headers": [
+                (b"content-type", content_type),
+                (b"content-length", str(len(body)).encode("ascii")),
+                (b"server", b"Citadel-Shield/3.0"),
+                (b"x-citadel-defense", b"ACTIVE"),
+            ],
+        })
+        await send({
+            "type": "http.response.body",
+            "body": body,
+        })