k9x-satan 0.1.0__tar.gz

k9x_satan-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: k9x-satan
+Version: 0.1.0
+Summary: K9X Satan — adversarial red-team harness for K9-AIF. Fires structured attacks at a live K9-AIF pipeline and proves K9X Shield containment.
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: k9-aif>=1.8.1
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0.0
+
+# K9x Satan — Security Analysis Tool for Agentic Networks
+
+Adversarial test harness for K9X Shield.
+
+Satan generates structured attacks against a live K9-AIF pipeline and verifies
+that every attack is stopped at the Router or Orchestrator boundary. Any attack
+that reaches a Squad or Agent is a finding — not a partial pass.
+
+---
+
+## Containment Contract
+
+```
+Attack → Router (ingress gate)       → BLOCKED  ✓
+              ↓ if not blocked
+         Orchestrator (egress gate)  → BLOCKED  ✓
+              ↓ if not blocked
+         Squad / Agent               → FINDING  ✗  (Shield failed)
+```
+
+---
+
+## Defense in Depth — Two Independent Layers
+
+**K9X Shield** applies deterministic, policy-driven checks — 13 handlers total,
+wired into the Router's ingress `VulnerabilityChain` and the Orchestrator's
+egress `VulnerabilityChain`. Explainable, zero LLM cost, evaluated identically
+every run. Evadable by paraphrase, encoding, or wording changes no regex list
+can enumerate in advance.
+
+**IBM Guardian** (`granite4.1-guardian:8b` via Ollama) is an optional semantic
+layer wrapping every agent's pre/post hooks — it catches paraphrased injection,
+subtle goal hijacking, and disguised privilege escalation that survive the
+pattern layer. Neither replaces the other: Shield holds with Guardian disabled
+entirely (`NoopGovernance`, the default); Guardian only ever adds coverage on
+top.
+
+Guardian unavailability (timeout, HTTP error, unreachable endpoint) is never
+silently treated as "SAFE" — it produces an explicit `UNAVAILABLE` verdict, and
+`governance.on_guardian_unavailable` in `config/config.yaml` decides the policy:
+`fail_closed` (default — blocks/redacts), `fail_open` (documented risk), or
+`inconclusive` (flags without blocking).
+
+A third governance option, `ShieldGovernance` (`k9_aif_abb.k9_security.vulnerability`),
+wires the *same* check classes Router/Orchestrator already use, but at the
+agent pre/post hook level — a second valid architectural point for the same
+`VulnerabilityChain` ABB.
+
+Prove what Guardian adds instead of asserting it:
+
+```bash
+python -m k9x_satan.runner.satan_runner --target http://localhost:6660 \
+    --suite full --compare-governance
+```
+
+Fires every attack twice — deterministic-only, then deterministic + Guardian —
+and reports which findings Guardian closed. A regression (Guardian making a
+previously-contained attack pass) is flagged as a bug, not a result.
+
+---
+
+## Complete Check Inventory
+
+| # | Check | Stage | Owner | Threat Class |
+|---|---|---|---|---|
+| 1 | `RequestFrequencyCheck` | Ingress | Satan SBB | Unbounded Consumption — OWASP LLM10 |
+| 2 | `InputSizeCheck` | Ingress | Framework OOB | Token-flood / oversized payload — OWASP LLM10 |
+| 3 | `PromptInjectionCheck` | Ingress | Framework OOB | Indirect Prompt Injection — Zscaler #1 · OWASP LLM01 |
+| 4 | `FieldAnomalyCheck` | Ingress | Satan SBB | Authority-override social engineering |
+| 5 | `MemoryPoisoningCheck` | Ingress | Satan SBB | Memory Poisoning — Zscaler #3 · OWASP LLM04 |
+| 6 | `SemanticDriftCheck` | Egress | Framework OOB | Goal Hijacking & Privilege Escalation — Zscaler #2 · OWASP LLM06 |
+| 7 | `ExecutionGuardCheck` | Egress | Framework OOB | Destructive execution — Zscaler #2 · OWASP LLM06 |
+| 8 | `PIIBoundaryCheck` | Egress | Framework OOB | Sensitive Info Disclosure — OWASP LLM02 |
+| 9 | `ToolArgumentCheck` | Egress | Framework OOB | Tool Abuse — poisoned arguments — Zscaler #4 · OWASP LLM05 |
+| 10 | `HardcodedCredentialCheck` | Egress | Framework OOB | Supply chain / secret leakage — OWASP LLM03 |
+| 11 | `ToolAuthorizationCheck` | Egress | Satan SBB | Shadow AI — unapproved tool — Zscaler #4 |
+| 12 | `SystemPromptLeakageCheck` | Egress | Satan SBB | System Prompt Leakage — OWASP LLM07 |
+| 13 | `OutputSanitizationCheck` | Egress | Satan SBB | Improper Output Handling — OWASP LLM05 |
+| — | `GuardianGovernance` | Agent pre/post | Satan SBB | Semantic evasion of all 13 above (cross-cutting, optional) |
+
+Out of scope by design (not runtime-checkable at the payload level): training-data
+poisoning, vector/embedding attacks (no RAG in this target), misinformation/hallucination.
+
+---
+
+## Structure
+
+```
+k9x_satan/
+├── target/               ← the pipeline under test (SBBs extending K9-AIF ABBs)
+│   ├── router.py              DocumentRouter — ingress Shield (5 checks)
+│   ├── orchestrator.py        DocumentOrchestrator — egress Shield (8 checks)
+│   ├── squad.py               DocumentProcessingSquad + governance selection
+│   ├── agents.py               DocumentExtractionAgent, AuditAgent
+│   ├── guardian_governance.py  IBM Granite Guardian semantic layer
+│   ├── field_anomaly_check.py, memory_poisoning_check.py,
+│   │   tool_authorization_check.py, system_prompt_leakage_check.py,
+│   │   output_sanitization_check.py, request_frequency_check.py
+│   │                           Satan-local BaseVulnerabilityCheck SBBs
+│   └── extractor.py            DoclingExtractor — pre-Shield field extraction
+├── attacks/               ← BaseAttack subclasses (the red team) — 13 implemented
+├── corpus/                ← malicious document and payload samples
+├── fake_search/           ← lightweight server returning poisoned search results
+├── runner/                ← sends attacks through a real K9-AIF pipeline
+├── report/                ← formats BLOCKED / FLAGGED / PASSED results
+└── diagrams/              ← shield_class.puml (PlantUML class diagram)
+```
+
+---
+
+## Running Satan
+
+```bash
+./run.sh                                                                 # dashboard on :6660
+python -m k9x_satan.runner.satan_runner --target http://localhost:6660 --suite full
+python -m k9x_satan.runner.satan_runner --target http://localhost:6660 --suite full --compare-governance
+```
+
+### Output
+
+```
+K9x Satan — Attack Report
+=========================
+[BLOCKED]  prompt_injection_document     depth=router       ✓
+[BLOCKED]  search_poisoning              depth=router       ✓
+[BLOCKED]  payload_flood                 depth=router       ✓
+[BLOCKED]  memory_poisoning              depth=router       ✓
+[BLOCKED]  request_flood                 depth=router       ✓
+[BLOCKED]  semantic_drift                depth=orchestrator ✓
+[BLOCKED]  execution_bypass              depth=orchestrator ✓
+[BLOCKED]  pii_exfiltration              depth=orchestrator ✓
+[BLOCKED]  tool_argument_poison          depth=orchestrator ✓
+[BLOCKED]  hardcoded_credential          depth=orchestrator ✓
+[BLOCKED]  shadow_tool                   depth=orchestrator ✓
+[BLOCKED]  system_prompt_leakage         depth=orchestrator ✓
+[BLOCKED]  output_sanitization           depth=orchestrator ✓
+=========================
+13/13 contained  |  0 findings
+```
+
+---
+
+## Adding a New Attack
+
+1. Create `attacks/my_attack.py` extending `BaseAttack` (`k9_aif_abb.k9_security.attacks.base_attack`)
+2. Fire via the shared `attacks/_fire.py` helper — it POSTs to `/api/attack/fire` and
+   correctly reports connection failures as `FLAGGED` (inconclusive), never a fabricated `BLOCKED`
+3. Add malicious payload to `corpus/` if document-based
+4. Register in `runner/attack_registry.py`
+5. Run: `python -m k9x_satan.runner.satan_runner --attack my_attack --target http://localhost:6660`
+
+## Adding a New Check
+
+1. Create `target/my_check.py` extending `BaseVulnerabilityCheck` (`k9_aif_abb.k9_security.vulnerability.base_vulnerability_check`)
+2. Wire it into `DocumentRouter._build_ingress_chain()` or `DocumentOrchestrator._build_egress_chain()`
+3. Write the matching attack (above) to prove it holds
+
+---
+
+## Relationship to K9X Shield
+
+Satan and Shield are symmetric. Every `BaseAttack` targets a specific
+`BaseVulnerabilityCheck`. A PASSED result means a new check is needed in Shield.
+
+| Satan Attack | Shield Check |
+|---|---|
+| `PromptInjectionAttack` | `PromptInjectionCheck` |
+| `SearchPoisoningAttack` | `PromptInjectionCheck` (real tool-response fetch from fake_search) |
+| `PayloadFloodAttack` | `InputSizeCheck` |
+| `MemoryPoisoningAttack` | `MemoryPoisoningCheck` |
+| `RequestFloodAttack` | `RequestFrequencyCheck` |
+| `SemanticDriftAttack` | `SemanticDriftCheck` |
+| `ExecutionBypassAttack` | `ExecutionGuardCheck` |
+| `PIIExfiltrationAttack` | `PIIBoundaryCheck` |
+| `ToolArgumentAttack` | `ToolArgumentCheck` |
+| `HardcodedCredentialAttack` | `HardcodedCredentialCheck` |
+| `ShadowToolAttack` | `ToolAuthorizationCheck` |
+| `SystemPromptLeakageAttack` | `SystemPromptLeakageCheck` |
+| `OutputSanitizationAttack` | `OutputSanitizationCheck` |

k9x_satan-0.1.0/README.md

@@ -0,0 +1,179 @@
+# K9x Satan — Security Analysis Tool for Agentic Networks
+
+Adversarial test harness for K9X Shield.
+
+Satan generates structured attacks against a live K9-AIF pipeline and verifies
+that every attack is stopped at the Router or Orchestrator boundary. Any attack
+that reaches a Squad or Agent is a finding — not a partial pass.
+
+---
+
+## Containment Contract
+
+```
+Attack → Router (ingress gate)       → BLOCKED  ✓
+              ↓ if not blocked
+         Orchestrator (egress gate)  → BLOCKED  ✓
+              ↓ if not blocked
+         Squad / Agent               → FINDING  ✗  (Shield failed)
+```
+
+---
+
+## Defense in Depth — Two Independent Layers
+
+**K9X Shield** applies deterministic, policy-driven checks — 13 handlers total,
+wired into the Router's ingress `VulnerabilityChain` and the Orchestrator's
+egress `VulnerabilityChain`. Explainable, zero LLM cost, evaluated identically
+every run. Evadable by paraphrase, encoding, or wording changes no regex list
+can enumerate in advance.
+
+**IBM Guardian** (`granite4.1-guardian:8b` via Ollama) is an optional semantic
+layer wrapping every agent's pre/post hooks — it catches paraphrased injection,
+subtle goal hijacking, and disguised privilege escalation that survive the
+pattern layer. Neither replaces the other: Shield holds with Guardian disabled
+entirely (`NoopGovernance`, the default); Guardian only ever adds coverage on
+top.
+
+Guardian unavailability (timeout, HTTP error, unreachable endpoint) is never
+silently treated as "SAFE" — it produces an explicit `UNAVAILABLE` verdict, and
+`governance.on_guardian_unavailable` in `config/config.yaml` decides the policy:
+`fail_closed` (default — blocks/redacts), `fail_open` (documented risk), or
+`inconclusive` (flags without blocking).
+
+A third governance option, `ShieldGovernance` (`k9_aif_abb.k9_security.vulnerability`),
+wires the *same* check classes Router/Orchestrator already use, but at the
+agent pre/post hook level — a second valid architectural point for the same
+`VulnerabilityChain` ABB.
+
+Prove what Guardian adds instead of asserting it:
+
+```bash
+python -m k9x_satan.runner.satan_runner --target http://localhost:6660 \
+    --suite full --compare-governance
+```
+
+Fires every attack twice — deterministic-only, then deterministic + Guardian —
+and reports which findings Guardian closed. A regression (Guardian making a
+previously-contained attack pass) is flagged as a bug, not a result.
+
+---
+
+## Complete Check Inventory
+
+| # | Check | Stage | Owner | Threat Class |
+|---|---|---|---|---|
+| 1 | `RequestFrequencyCheck` | Ingress | Satan SBB | Unbounded Consumption — OWASP LLM10 |
+| 2 | `InputSizeCheck` | Ingress | Framework OOB | Token-flood / oversized payload — OWASP LLM10 |
+| 3 | `PromptInjectionCheck` | Ingress | Framework OOB | Indirect Prompt Injection — Zscaler #1 · OWASP LLM01 |
+| 4 | `FieldAnomalyCheck` | Ingress | Satan SBB | Authority-override social engineering |
+| 5 | `MemoryPoisoningCheck` | Ingress | Satan SBB | Memory Poisoning — Zscaler #3 · OWASP LLM04 |
+| 6 | `SemanticDriftCheck` | Egress | Framework OOB | Goal Hijacking & Privilege Escalation — Zscaler #2 · OWASP LLM06 |
+| 7 | `ExecutionGuardCheck` | Egress | Framework OOB | Destructive execution — Zscaler #2 · OWASP LLM06 |
+| 8 | `PIIBoundaryCheck` | Egress | Framework OOB | Sensitive Info Disclosure — OWASP LLM02 |
+| 9 | `ToolArgumentCheck` | Egress | Framework OOB | Tool Abuse — poisoned arguments — Zscaler #4 · OWASP LLM05 |
+| 10 | `HardcodedCredentialCheck` | Egress | Framework OOB | Supply chain / secret leakage — OWASP LLM03 |
+| 11 | `ToolAuthorizationCheck` | Egress | Satan SBB | Shadow AI — unapproved tool — Zscaler #4 |
+| 12 | `SystemPromptLeakageCheck` | Egress | Satan SBB | System Prompt Leakage — OWASP LLM07 |
+| 13 | `OutputSanitizationCheck` | Egress | Satan SBB | Improper Output Handling — OWASP LLM05 |
+| — | `GuardianGovernance` | Agent pre/post | Satan SBB | Semantic evasion of all 13 above (cross-cutting, optional) |
+
+Out of scope by design (not runtime-checkable at the payload level): training-data
+poisoning, vector/embedding attacks (no RAG in this target), misinformation/hallucination.
+
+---
+
+## Structure
+
+```
+k9x_satan/
+├── target/               ← the pipeline under test (SBBs extending K9-AIF ABBs)
+│   ├── router.py              DocumentRouter — ingress Shield (5 checks)
+│   ├── orchestrator.py        DocumentOrchestrator — egress Shield (8 checks)
+│   ├── squad.py               DocumentProcessingSquad + governance selection
+│   ├── agents.py               DocumentExtractionAgent, AuditAgent
+│   ├── guardian_governance.py  IBM Granite Guardian semantic layer
+│   ├── field_anomaly_check.py, memory_poisoning_check.py,
+│   │   tool_authorization_check.py, system_prompt_leakage_check.py,
+│   │   output_sanitization_check.py, request_frequency_check.py
+│   │                           Satan-local BaseVulnerabilityCheck SBBs
+│   └── extractor.py            DoclingExtractor — pre-Shield field extraction
+├── attacks/               ← BaseAttack subclasses (the red team) — 13 implemented
+├── corpus/                ← malicious document and payload samples
+├── fake_search/           ← lightweight server returning poisoned search results
+├── runner/                ← sends attacks through a real K9-AIF pipeline
+├── report/                ← formats BLOCKED / FLAGGED / PASSED results
+└── diagrams/              ← shield_class.puml (PlantUML class diagram)
+```
+
+---
+
+## Running Satan
+
+```bash
+./run.sh                                                                 # dashboard on :6660
+python -m k9x_satan.runner.satan_runner --target http://localhost:6660 --suite full
+python -m k9x_satan.runner.satan_runner --target http://localhost:6660 --suite full --compare-governance
+```
+
+### Output
+
+```
+K9x Satan — Attack Report
+=========================
+[BLOCKED]  prompt_injection_document     depth=router       ✓
+[BLOCKED]  search_poisoning              depth=router       ✓
+[BLOCKED]  payload_flood                 depth=router       ✓
+[BLOCKED]  memory_poisoning              depth=router       ✓
+[BLOCKED]  request_flood                 depth=router       ✓
+[BLOCKED]  semantic_drift                depth=orchestrator ✓
+[BLOCKED]  execution_bypass              depth=orchestrator ✓
+[BLOCKED]  pii_exfiltration              depth=orchestrator ✓
+[BLOCKED]  tool_argument_poison          depth=orchestrator ✓
+[BLOCKED]  hardcoded_credential          depth=orchestrator ✓
+[BLOCKED]  shadow_tool                   depth=orchestrator ✓
+[BLOCKED]  system_prompt_leakage         depth=orchestrator ✓
+[BLOCKED]  output_sanitization           depth=orchestrator ✓
+=========================
+13/13 contained  |  0 findings
+```
+
+---
+
+## Adding a New Attack
+
+1. Create `attacks/my_attack.py` extending `BaseAttack` (`k9_aif_abb.k9_security.attacks.base_attack`)
+2. Fire via the shared `attacks/_fire.py` helper — it POSTs to `/api/attack/fire` and
+   correctly reports connection failures as `FLAGGED` (inconclusive), never a fabricated `BLOCKED`
+3. Add malicious payload to `corpus/` if document-based
+4. Register in `runner/attack_registry.py`
+5. Run: `python -m k9x_satan.runner.satan_runner --attack my_attack --target http://localhost:6660`
+
+## Adding a New Check
+
+1. Create `target/my_check.py` extending `BaseVulnerabilityCheck` (`k9_aif_abb.k9_security.vulnerability.base_vulnerability_check`)
+2. Wire it into `DocumentRouter._build_ingress_chain()` or `DocumentOrchestrator._build_egress_chain()`
+3. Write the matching attack (above) to prove it holds
+
+---
+
+## Relationship to K9X Shield
+
+Satan and Shield are symmetric. Every `BaseAttack` targets a specific
+`BaseVulnerabilityCheck`. A PASSED result means a new check is needed in Shield.
+
+| Satan Attack | Shield Check |
+|---|---|
+| `PromptInjectionAttack` | `PromptInjectionCheck` |
+| `SearchPoisoningAttack` | `PromptInjectionCheck` (real tool-response fetch from fake_search) |
+| `PayloadFloodAttack` | `InputSizeCheck` |
+| `MemoryPoisoningAttack` | `MemoryPoisoningCheck` |
+| `RequestFloodAttack` | `RequestFrequencyCheck` |
+| `SemanticDriftAttack` | `SemanticDriftCheck` |
+| `ExecutionBypassAttack` | `ExecutionGuardCheck` |
+| `PIIExfiltrationAttack` | `PIIBoundaryCheck` |
+| `ToolArgumentAttack` | `ToolArgumentCheck` |
+| `HardcodedCredentialAttack` | `HardcodedCredentialCheck` |
+| `ShadowToolAttack` | `ToolAuthorizationCheck` |
+| `SystemPromptLeakageAttack` | `SystemPromptLeakageCheck` |
+| `OutputSanitizationAttack` | `OutputSanitizationCheck` |

k9x_satan-0.1.0/__init__.py

@@ -0,0 +1 @@
+"""K9x Satan — Security Analysis Tool for Agentic Networks."""