Add IaC-SecFix app with Gradio UI and agent backend

README.md

@@ -1,131 +1,82 @@
-# IaC-SecFix Agents
+---
+title: IaC-SecFix
+colorFrom: red
+colorTo: green
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app.py
+pinned: false
+license: apache-2.0
+---
 
-Submission-ready reference backend for the IaC-SecFix hackathon project.
+# IaC-SecFix
 
-The Hugging Face Space in `../hf_space_iac_secfix` is the public UI. This package is the fuller agentic backend/reference implementation: it can run Checkov, parse Terraform/Kubernetes files, call an OpenAI-compatible Qwen/vLLM endpoint, retry with validation feedback, and emit a typed human-review decision.
+Scanner-verified Infrastructure-as-Code remediation demo for the AMD Developer Hackathon.
 
-## What This Package Is
+This Space is designed to be publishable without access to the AMD 192GB GPU. It defaults to deterministic demo playback from notebook artifacts and can optionally call a live Qwen/vLLM endpoint when GPU access is available.
 
-IaC-SecFix is a scanner-verified multi-agent remediation system for Terraform and Kubernetes.
+This Space has two modes:
 
-It keeps the LLM useful but bounded:
+- `Demo playback`: reliable precomputed scanner artifacts from the notebook run.
+- `Live Qwen endpoint`: calls a public OpenAI-compatible vLLM endpoint serving `Qwen/Qwen3.5-9B`.
 
-- graph/control flow is deterministic in `RemediationOrchestrator`
-- every agent boundary uses Pydantic models
-- Checkov and HCL/YAML parsers decide whether patches are valid
-- safety gates block scanner suppression and security weakening
-- validated patches still require human approval by default
+The complete benchmark-backed system is B3 zero-shot + RAG. B5 is included as promising partial multi-agent loop evidence.
 
-## Current Deployment Reality
+## Model Access
 
-You do not need AMD MI300X access to publish the demo.
+The fine-tuned LoRA adapter should be published as a separate Hugging Face model repo. The CPU Space does not host Qwen3.5-9B directly. Live inference requires one of:
 
-- Use the Hugging Face Space in CPU mode for the UI and deterministic demo playback.
-- Upload the LoRA adapter to a Hugging Face model repo for reproducibility.
-- Use a live Qwen/vLLM endpoint only when you have GPU access again.
-- If no GPU endpoint is available, the Space remains submission-safe in demo playback mode.
+- a public OpenAI-compatible vLLM endpoint
+- a paid GPU Space with enough VRAM
+- a Hugging Face Inference Endpoint
+- another external GPU service
 
-## Agent Graph
+## Operating Pattern
 
-1. `IngestAgent`: detects IaC type and runs Checkov.
-2. `PolicyContextAgent`: maps scanner rule IDs to descriptions and remediation hints.
-3. `PatchAgent`: calls an OpenAI-compatible endpoint and parses a `FixCandidate`.
-4. `ValidationAgent`: parses the fixed file, reruns Checkov, measures unresolved targeted findings, new critical/high findings, and diff size.
-5. `SafetyAgent`: refuses requests or patches that weaken security or suppress scanners.
-6. `ComplianceAgent`: converts validation into compliance deltas.
-7. `HumanApprovalGate`: returns `needs_human_review` unless explicit auto-approval is enabled and validation accepts.
+The UI follows the submission operating pattern:
 
-## Evidence Summary
+1. Graph node = one responsibility.
+2. Agent output = typed Pydantic model.
+3. All side effects = tools with validation + approval.
+4. All runs = usage-limited + traced + persisted.
 
-The strongest complete benchmark claim remains **B3: zero-shot + RAG**:
+Each run writes a typed artifact under `runs/<run_id>.json` containing:
 
-- n=50 benchmark rows
-- scanner clean rate: 14%
-- targeted policy resolution: 32.59%
-- schema validity: 88%
-- parse validity: 88%
-- unsafe action rate: 0%
+- request
+- ingest result
+- safety decision
+- policy context
+- tool approvals
+- candidate patch
+- validation result
+- approval decision
+- graph trace
 
-The agent-loop system, **B5**, is the product direction but only partial:
+The Space never applies infrastructure changes. Patches remain human-review artifacts.
 
-- n=28 partial benchmark rows
-- scanner clean rate: 28.57%
-- targeted policy resolution: 41.76%
-- parse validity: 96.43%
-- unsafe action rate: 0%
-- median latency: 94.33 seconds
+## Project Structure
 
-Use B3 as the complete benchmark claim and B5 as promising agentic architecture evidence until a full B5 rerun completes.
+`app.py` is only the Space launcher. The application logic lives in `iac_secfix_space/`:
 
-## Install Locally
+- `schemas.py`: typed Pydantic contracts for requests, graph state, candidates, validation, approvals, and traces.
+- `agents.py`: narrow Pydantic AI worker wrapper for the live `PatchAgent` typed output.
+- `graph.py`: deterministic control plane that owns routing, joins, fallbacks, approval flow, and persistence.
+- `nodes.py`: one-responsibility graph nodes for ingest, safety, routing, policy context, validation, and approval.
+- `tools.py`: side-effect boundary for demo playback and live Qwen calls, with usage limits and approval records.
+- `persistence.py`: per-run JSON artifacts and usage counters.
+- `rendering.py`: UI-safe report/trace rendering.
+- `ui.py`: Gradio interface composition only.
 
-```bash
-cd outputs/iac_secfix_agents
-python -m venv .venv
-source .venv/bin/activate
-pip install -e .
-```
+The graph layer is isolated from the UI and tools so the orchestration can be upgraded to `pydantic_graph.beta` without rewriting the security or validation contracts.
 
-Copy the environment template:
+## Required Space Secrets
 
-```bash
-cp .env.example .env
-```
+Set these in the Space Settings page when using live inference:
 
-Set these values if you have a live endpoint:
+- `IAC_SECFIX_BASE_URL`: public HTTPS URL ending in `/v1`
+- `IAC_SECFIX_API_KEY`: vLLM API key
+- `IAC_SECFIX_MODEL`: served model name, for example `iac-secfix-base`
 
-```bash
-export IAC_SECFIX_BASE_URL=http://localhost:8000/v1
-export IAC_SECFIX_API_KEY=abc-123
-export IAC_SECFIX_MODEL=iac-secfix-base
-```
+If these are missing, the app still works in demo playback mode.
 
-## Run One File
-
-```bash
-iac-secfix-agents remediate examples/demo_sg_open.tf --iac-type terraform
-```
-
-The output is an `ApprovalDecision` JSON object. Valid patches still return `needs_human_review` by default.
-
-## Summarize Notebook Results
-
-From this folder:
-
-```bash
-iac-secfix-agents summarize-results --eval-dir ../../Development/eval
-```
-
-Use the path that contains your copied notebook evaluation artifacts.
-
-## Hugging Face Submission Flow
-
-1. Push `../hf_space_iac_secfix` to your Hugging Face Space.
-2. Keep the Space on CPU Basic for reliable demo playback.
-3. Upload the LoRA adapter folder to a Hugging Face model repo.
-4. Add Space secrets only if you have a live endpoint:
-
-```text
-IAC_SECFIX_BASE_URL=https://your-endpoint.example.com/v1
-IAC_SECFIX_API_KEY=...
-IAC_SECFIX_MODEL=iac-secfix-base
-```
-
-5. In the submission, describe live fine-tuned inference as optional GPU-backed mode, not required for the CPU demo.
-
-## Submission Claim
-
-Use this wording:
-
-> IaC-SecFix is a scanner-verified multi-agent remediation prototype for Terraform and Kubernetes. It combines typed Pydantic contracts, an OpenAI-compatible Qwen patching agent, deterministic Checkov validation, parser checks, safety gates, retry feedback, and human approval. On the complete held-out benchmark, the strongest defensible system is zero-shot + RAG with 0 unsafe actions. The agent loop shows promising partial improvements and is the architecture for continued development.
-
-## Important Files
-
-- `src/iac_secfix_agents/orchestrator.py`: deterministic multi-agent loop
-- `src/iac_secfix_agents/agents.py`: agent roles, prompt construction, retry feedback
-- `src/iac_secfix_agents/llm.py`: OpenAI-compatible and Pydantic AI compatibility layer
-- `src/iac_secfix_agents/scanners.py`: Checkov and parser validation
-- `src/iac_secfix_agents/safety.py`: deterministic safety gates
-- `docs/architecture.md`: system design
-- `docs/hackathon_report.md`: benchmark interpretation
-- `docs/huggingface_submission.md`: push and model-hosting checklist
+See `docs/architecture.md` for the graph/node/tool contract and `docs/huggingface_deployment_guide.md` for deployment steps.

app.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from iac_secfix_space import build_demo
+
+
+demo = build_demo()
+
+
+if __name__ == "__main__":
+    demo.launch()

demo_examples/demo_iam_wild.json

@@ -0,0 +1,152 @@
+{
+  "file_name": "demo_iam_wild.tf",
+  "iac_type": "terraform",
+  "expected_policy_ids": [
+    "CKV_AWS_111",
+    "CKV_AWS_40",
+    "CKV_AWS_62"
+  ],
+  "expected_present_before": [
+    "CKV_AWS_62"
+  ],
+  "expected_missing_before": [
+    "CKV_AWS_111",
+    "CKV_AWS_40"
+  ],
+  "expected_resolved_policy_ids": [
+    "CKV_AWS_111",
+    "CKV_AWS_40"
+  ],
+  "expected_unresolved_policy_ids": [
+    "CKV_AWS_62"
+  ],
+  "original_file": "resource \"aws_iam_policy\" \"wild\" {\n  name = \"iac-secfix-wild\"\n\n  policy = jsonencode({\n    Version = \"2012-10-17\"\n    Statement = [{\n      Effect   = \"Allow\"\n      Action   = \"*\"\n      Resource = \"*\"\n    }]\n  })\n}\n",
+  "fixed_file": "resource \"aws_iam_policy\" \"wild\" {\n  name = \"iac-secfix-wild\"\n\n  policy = jsonencode({\n    Version = \"2012-10-17\"\n    Statement = [{\n      Effect   = \"Allow\"\n      Action   = \"*\"\n      Resource = \"*\"\n    }]\n  })\n}",
+  "pre_summary": {
+    "failed": 9,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 9
+  },
+  "post_summary": {
+    "failed": 9,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 9
+  },
+  "pre_rule_ids": [
+    "CKV2_AWS_40",
+    "CKV_AWS_286",
+    "CKV_AWS_287",
+    "CKV_AWS_288",
+    "CKV_AWS_289",
+    "CKV_AWS_290",
+    "CKV_AWS_355",
+    "CKV_AWS_62",
+    "CKV_AWS_63"
+  ],
+  "post_rule_ids": [
+    "CKV2_AWS_40",
+    "CKV_AWS_286",
+    "CKV_AWS_287",
+    "CKV_AWS_288",
+    "CKV_AWS_289",
+    "CKV_AWS_290",
+    "CKV_AWS_355",
+    "CKV_AWS_62",
+    "CKV_AWS_63"
+  ],
+  "actual_verdict": "rejected",
+  "demo_gate_status": "rejected",
+  "demo_outcome": "rejected",
+  "verdict": "rejected",
+  "latency_s": 33.10580461799691,
+  "decision": {
+    "action": "rejected",
+    "reason": "parse failure, unresolved targeted findings, or over-broad diff",
+    "patch": {
+      "patch": "",
+      "fixed_file": "resource \"aws_iam_policy\" \"wild\" {\n  name = \"iac-secfix-wild\"\n\n  policy = jsonencode({\n    Version = \"2012-10-17\"\n    Statement = [{\n      Effect   = \"Allow\"\n      Action   = \"*\"\n      Resource = \"*\"\n    }]\n  })\n}",
+      "resolved_policy_ids": [],
+      "explanation": "All targeted rules require either a concrete fix template or human approval. No safe in-file fix exists without inventing placeholder resources.",
+      "verification_commands": [],
+      "risk_notes": [],
+      "requires_human_approval": true
+    },
+    "validation": {
+      "parse_ok": true,
+      "targeted_resolved": [],
+      "targeted_unresolved": [
+        "CKV2_AWS_40",
+        "CKV_AWS_286",
+        "CKV_AWS_287",
+        "CKV_AWS_288",
+        "CKV_AWS_289",
+        "CKV_AWS_290",
+        "CKV_AWS_355",
+        "CKV_AWS_62",
+        "CKV_AWS_63"
+      ],
+      "new_findings": [],
+      "new_critical_high_count": 0,
+      "changed_lines_ratio": 0.04,
+      "pre_summary": {
+        "failed": 9,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 9
+      },
+      "post_summary": {
+        "failed": 9,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 9,
+        "LOW": 0,
+        "INFO": 0
+      },
+      "verdict": "retry",
+      "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+    },
+    "compliance": null,
+    "n_retries": 1
+  },
+  "validation": {
+    "parse_ok": true,
+    "targeted_resolved": [],
+    "targeted_unresolved": [
+      "CKV2_AWS_40",
+      "CKV_AWS_286",
+      "CKV_AWS_287",
+      "CKV_AWS_288",
+      "CKV_AWS_289",
+      "CKV_AWS_290",
+      "CKV_AWS_355",
+      "CKV_AWS_62",
+      "CKV_AWS_63"
+    ],
+    "new_findings": [],
+    "new_critical_high_count": 0,
+    "changed_lines_ratio": 0.04,
+    "pre_summary": {
+      "failed": 9,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 9
+    },
+    "post_summary": {
+      "failed": 9,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 9,
+      "LOW": 0,
+      "INFO": 0
+    },
+    "verdict": "retry",
+    "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+  },
+  "paths": {
+    "original": "demo/original/demo_iam_wild.tf",
+    "fixed": "demo/fixed/demo_iam_wild.tf",
+    "precomputed": "demo/precomputed/demo_iam_wild.json"
+  }
+}

demo_examples/demo_k8s_root.json

@@ -0,0 +1,205 @@
+{
+  "file_name": "demo_k8s_root.yaml",
+  "iac_type": "kubernetes",
+  "expected_policy_ids": [
+    "CKV_K8S_20",
+    "CKV_K8S_22",
+    "CKV_K8S_28",
+    "CKV_K8S_8"
+  ],
+  "expected_present_before": [
+    "CKV_K8S_20",
+    "CKV_K8S_22",
+    "CKV_K8S_28",
+    "CKV_K8S_8"
+  ],
+  "expected_missing_before": [],
+  "expected_resolved_policy_ids": [
+    "CKV_K8S_20",
+    "CKV_K8S_22",
+    "CKV_K8S_28",
+    "CKV_K8S_8"
+  ],
+  "expected_unresolved_policy_ids": [],
+  "original_file": "apiVersion: v1\nkind: Pod\nmetadata:\n  name: iac-secfix-root\nspec:\n  containers:\n  - name: app\n    image: nginx\n    securityContext:\n      privileged: true\n      runAsUser: 0\n",
+  "fixed_file": "apiVersion: v1\nkind: Pod\nmetadata:\n  name: iac-secfix-root\n  namespace: app\nspec:\n  containers:\n  - name: app\n    image: nginx@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\n    securityContext:\n      runAsNonRoot: true\n      runAsUser: 10001\n      allowPrivilegeEscalation: false\n      capabilities:\n        drop:\n          - NET_RAW\n      readOnlyRootFilesystem: true\n      seccompProfile:\n        type: RuntimeDefault\n    resources:\n      requests:\n        cpu: \"100m\"\n        memory: \"128Mi\"\n      limits:\n        cpu: \"500m\"\n        memory: \"512Mi\"\n    livenessProbe:\n      httpGet:\n        path: /healthz\n        port: 8080\n      initialDelaySeconds: 10\n    readinessProbe:\n      httpGet:\n        path: /ready\n        port: 8080\n",
+  "pre_summary": {
+    "failed": 20,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 20
+  },
+  "post_summary": {
+    "failed": 4,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 4
+  },
+  "pre_rule_ids": [
+    "CKV2_K8S_6",
+    "CKV_K8S_10",
+    "CKV_K8S_11",
+    "CKV_K8S_12",
+    "CKV_K8S_13",
+    "CKV_K8S_14",
+    "CKV_K8S_16",
+    "CKV_K8S_20",
+    "CKV_K8S_21",
+    "CKV_K8S_22",
+    "CKV_K8S_23",
+    "CKV_K8S_28",
+    "CKV_K8S_29",
+    "CKV_K8S_31",
+    "CKV_K8S_37",
+    "CKV_K8S_38",
+    "CKV_K8S_40",
+    "CKV_K8S_43",
+    "CKV_K8S_8",
+    "CKV_K8S_9"
+  ],
+  "post_rule_ids": [
+    "CKV2_K8S_6",
+    "CKV_K8S_29",
+    "CKV_K8S_37",
+    "CKV_K8S_38"
+  ],
+  "actual_verdict": "rejected",
+  "demo_gate_status": "rejected",
+  "demo_outcome": "rejected",
+  "verdict": "rejected",
+  "latency_s": 97.44769946900487,
+  "decision": {
+    "action": "rejected",
+    "reason": "parse failure, unresolved targeted findings, or over-broad diff",
+    "patch": {
+      "patch": "--- a/pod.yaml\n+++ b/pod.yaml\n@@ -1,11 +1,27 @@\n apiVersion: v1\n kind: Pod\n metadata:\n   name: iac-secfix-root\n+  namespace: app\n spec:\n   containers:\n   - name: app\n     image: nginx@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\n+    securityContext:\n+      runAsNonRoot: true\n+      runAsUser: 10001\n+      allowPrivilegeEscalation: false\n+      capabilities:\n+        drop:\n+          - NET_RAW\n+      readOnlyRootFilesystem: true\n+      seccompProfile:\n+        type: RuntimeDefault\n+    resources:\n+      requests:\n+        cpu: \"100m\"\n+        memory: \"128Mi\"\n+      limits:\n+        cpu: \"500m\"\n+        memory: \"512Mi\"\n+    livenessProbe:\n+      httpGet:\n+        path: /healthz\n+        port: 8080\n+      initialDelaySeconds: 10\n+    readinessProbe:\n+      httpGet:\n+        path: /ready\n+        port: 8080\n",
+      "fixed_file": "apiVersion: v1\nkind: Pod\nmetadata:\n  name: iac-secfix-root\n  namespace: app\nspec:\n  containers:\n  - name: app\n    image: nginx@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\n    securityContext:\n      runAsNonRoot: true\n      runAsUser: 10001\n      allowPrivilegeEscalation: false\n      capabilities:\n        drop:\n          - NET_RAW\n      readOnlyRootFilesystem: true\n      seccompProfile:\n        type: RuntimeDefault\n    resources:\n      requests:\n        cpu: \"100m\"\n        memory: \"128Mi\"\n      limits:\n        cpu: \"500m\"\n        memory: \"512Mi\"\n    livenessProbe:\n      httpGet:\n        path: /healthz\n        port: 8080\n      initialDelaySeconds: 10\n    readinessProbe:\n      httpGet:\n        path: /ready\n        port: 8080\n",
+      "resolved_policy_ids": [
+        "CKV_K8S_40",
+        "CKV_K8S_21",
+        "CKV_K8S_43",
+        "CKV_K8S_29",
+        "CKV_K8S_28",
+        "CKV_K8S_20",
+        "CKV_K8S_11",
+        "CKV_K8S_13",
+        "CKV_K8S_14",
+        "CKV_K8S_23",
+        "CKV_K8S_8",
+        "CKV_K8S_31",
+        "CKV_K8S_12",
+        "CKV_K8S_16",
+        "CKV_K8S_22",
+        "CKV_K8S_10",
+        "CKV_K8S_9"
+      ],
+      "explanation": "Applied minimal in-file fixes for all targeted rules: set namespace, pinned image with digest, added pod-level and container-level securityContext, added resource requests/limits, added liveness/readiness probes, dropped NET_RAW, set readOnlyRootFilesystem, set seccompProfile, set allowPrivilegeEscalation, set runAsNonRoot and runAsUser, added CPU/memory requests/limits.",
+      "verification_commands": [
+        "checkov -f fixed_file.yaml --summary"
+      ],
+      "risk_notes": [
+        "CKV_K8S_37 and CKV_K8S_38 not applicable as no hostPath volumes or service account tokens are used in the original file."
+      ],
+      "requires_human_approval": false
+    },
+    "validation": {
+      "parse_ok": true,
+      "targeted_resolved": [
+        "CKV_K8S_10",
+        "CKV_K8S_11",
+        "CKV_K8S_12",
+        "CKV_K8S_13",
+        "CKV_K8S_14",
+        "CKV_K8S_16",
+        "CKV_K8S_20",
+        "CKV_K8S_21",
+        "CKV_K8S_22",
+        "CKV_K8S_23",
+        "CKV_K8S_28",
+        "CKV_K8S_31",
+        "CKV_K8S_40",
+        "CKV_K8S_43",
+        "CKV_K8S_8",
+        "CKV_K8S_9"
+      ],
+      "targeted_unresolved": [
+        "CKV2_K8S_6",
+        "CKV_K8S_29",
+        "CKV_K8S_37",
+        "CKV_K8S_38"
+      ],
+      "new_findings": [],
+      "new_critical_high_count": 0,
+      "changed_lines_ratio": 0.6,
+      "pre_summary": {
+        "failed": 20,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 20
+      },
+      "post_summary": {
+        "failed": 4,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 4,
+        "LOW": 0,
+        "INFO": 0
+      },
+      "verdict": "retry",
+      "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+    },
+    "compliance": null,
+    "n_retries": 1
+  },
+  "validation": {
+    "parse_ok": true,
+    "targeted_resolved": [
+      "CKV_K8S_10",
+      "CKV_K8S_11",
+      "CKV_K8S_12",
+      "CKV_K8S_13",
+      "CKV_K8S_14",
+      "CKV_K8S_16",
+      "CKV_K8S_20",
+      "CKV_K8S_21",
+      "CKV_K8S_22",
+      "CKV_K8S_23",
+      "CKV_K8S_28",
+      "CKV_K8S_31",
+      "CKV_K8S_40",
+      "CKV_K8S_43",
+      "CKV_K8S_8",
+      "CKV_K8S_9"
+    ],
+    "targeted_unresolved": [
+      "CKV2_K8S_6",
+      "CKV_K8S_29",
+      "CKV_K8S_37",
+      "CKV_K8S_38"
+    ],
+    "new_findings": [],
+    "new_critical_high_count": 0,
+    "changed_lines_ratio": 0.6,
+    "pre_summary": {
+      "failed": 20,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 20
+    },
+    "post_summary": {
+      "failed": 4,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 4,
+      "LOW": 0,
+      "INFO": 0
+    },
+    "verdict": "retry",
+    "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+  },
+  "paths": {
+    "original": "demo/original/demo_k8s_root.yaml",
+    "fixed": "demo/fixed/demo_k8s_root.yaml",
+    "precomputed": "demo/precomputed/demo_k8s_root.json"
+  }
+}

demo_examples/demo_rds_unencr.json

@@ -0,0 +1,150 @@
+{
+  "file_name": "demo_rds_unencr.tf",
+  "iac_type": "terraform",
+  "expected_policy_ids": [
+    "CKV_AWS_118",
+    "CKV_AWS_16",
+    "CKV_AWS_17"
+  ],
+  "expected_present_before": [
+    "CKV_AWS_118",
+    "CKV_AWS_16",
+    "CKV_AWS_17"
+  ],
+  "expected_missing_before": [],
+  "expected_resolved_policy_ids": [],
+  "expected_unresolved_policy_ids": [
+    "CKV_AWS_118",
+    "CKV_AWS_16",
+    "CKV_AWS_17"
+  ],
+  "original_file": "resource \"aws_db_instance\" \"db\" {\n  identifier           = \"iac-secfix-db\"\n  allocated_storage    = 20\n  engine               = \"mysql\"\n  instance_class       = \"db.t3.micro\"\n  username             = \"admin\"\n  password             = \"Password123456!\"\n  publicly_accessible  = true\n  storage_encrypted    = false\n  skip_final_snapshot  = true\n}\n",
+  "fixed_file": "resource \"aws_db_instance\" \"db\" {\n  identifier           = \"iac-secfix-db\"\n  allocated_storage    = 20\n  engine               = \"mysql\"\n  instance_class       = \"db.t3.micro\"\n  username             = \"admin\"\n  password             = \"Password123456!\"\n  publicly_accessible  = true\n  storage_encrypted    = false\n  skip_final_snapshot  = true\n}",
+  "pre_summary": {
+    "failed": 9,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 9
+  },
+  "post_summary": {
+    "failed": 9,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 9
+  },
+  "pre_rule_ids": [
+    "CKV2_AWS_60",
+    "CKV_AWS_118",
+    "CKV_AWS_129",
+    "CKV_AWS_157",
+    "CKV_AWS_16",
+    "CKV_AWS_161",
+    "CKV_AWS_17",
+    "CKV_AWS_226",
+    "CKV_AWS_293"
+  ],
+  "post_rule_ids": [
+    "CKV2_AWS_60",
+    "CKV_AWS_118",
+    "CKV_AWS_129",
+    "CKV_AWS_157",
+    "CKV_AWS_16",
+    "CKV_AWS_161",
+    "CKV_AWS_17",
+    "CKV_AWS_226",
+    "CKV_AWS_293"
+  ],
+  "actual_verdict": "rejected",
+  "demo_gate_status": "rejected",
+  "demo_outcome": "rejected",
+  "verdict": "rejected",
+  "latency_s": 40.018114939011866,
+  "decision": {
+    "action": "rejected",
+    "reason": "parse failure, unresolved targeted findings, or over-broad diff",
+    "patch": {
+      "patch": "",
+      "fixed_file": "resource \"aws_db_instance\" \"db\" {\n  identifier           = \"iac-secfix-db\"\n  allocated_storage    = 20\n  engine               = \"mysql\"\n  instance_class       = \"db.t3.micro\"\n  username             = \"admin\"\n  password             = \"Password123456!\"\n  publicly_accessible  = true\n  storage_encrypted    = false\n  skip_final_snapshot  = true\n}",
+      "resolved_policy_ids": [],
+      "explanation": "No fix templates were applicable to the original file without inventing placeholder resources. All rules require_human_approval=true.",
+      "verification_commands": [],
+      "risk_notes": [],
+      "requires_human_approval": true
+    },
+    "validation": {
+      "parse_ok": true,
+      "targeted_resolved": [],
+      "targeted_unresolved": [
+        "CKV2_AWS_60",
+        "CKV_AWS_118",
+        "CKV_AWS_129",
+        "CKV_AWS_157",
+        "CKV_AWS_16",
+        "CKV_AWS_161",
+        "CKV_AWS_17",
+        "CKV_AWS_226",
+        "CKV_AWS_293"
+      ],
+      "new_findings": [],
+      "new_critical_high_count": 0,
+      "changed_lines_ratio": 0.04,
+      "pre_summary": {
+        "failed": 9,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 9
+      },
+      "post_summary": {
+        "failed": 9,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 9,
+        "LOW": 0,
+        "INFO": 0
+      },
+      "verdict": "retry",
+      "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+    },
+    "compliance": null,
+    "n_retries": 1
+  },
+  "validation": {
+    "parse_ok": true,
+    "targeted_resolved": [],
+    "targeted_unresolved": [
+      "CKV2_AWS_60",
+      "CKV_AWS_118",
+      "CKV_AWS_129",
+      "CKV_AWS_157",
+      "CKV_AWS_16",
+      "CKV_AWS_161",
+      "CKV_AWS_17",
+      "CKV_AWS_226",
+      "CKV_AWS_293"
+    ],
+    "new_findings": [],
+    "new_critical_high_count": 0,
+    "changed_lines_ratio": 0.04,
+    "pre_summary": {
+      "failed": 9,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 9
+    },
+    "post_summary": {
+      "failed": 9,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 9,
+      "LOW": 0,
+      "INFO": 0
+    },
+    "verdict": "retry",
+    "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+  },
+  "paths": {
+    "original": "demo/original/demo_rds_unencr.tf",
+    "fixed": "demo/fixed/demo_rds_unencr.tf",
+    "precomputed": "demo/precomputed/demo_rds_unencr.json"
+  }
+}

demo_examples/demo_s3_public.json

@@ -0,0 +1,154 @@
+{
+  "file_name": "demo_s3_public.tf",
+  "iac_type": "terraform",
+  "expected_policy_ids": [
+    "CKV_AWS_144",
+    "CKV_AWS_18",
+    "CKV_AWS_19",
+    "CKV_AWS_21",
+    "CKV_AWS_53"
+  ],
+  "expected_present_before": [
+    "CKV_AWS_144",
+    "CKV_AWS_18",
+    "CKV_AWS_21"
+  ],
+  "expected_missing_before": [
+    "CKV_AWS_19",
+    "CKV_AWS_53"
+  ],
+  "expected_resolved_policy_ids": [
+    "CKV_AWS_19",
+    "CKV_AWS_53"
+  ],
+  "expected_unresolved_policy_ids": [
+    "CKV_AWS_144",
+    "CKV_AWS_18",
+    "CKV_AWS_21"
+  ],
+  "original_file": "resource \"aws_s3_bucket\" \"data\" {\n  bucket = \"iac-secfix-public-demo\"\n  acl    = \"public-read\"\n}\n",
+  "fixed_file": "resource \"aws_s3_bucket\" \"data\" {\n  bucket = \"iac-secfix-public-demo\"\n  acl    = \"public-read\"\n}",
+  "pre_summary": {
+    "failed": 8,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 8
+  },
+  "post_summary": {
+    "failed": 8,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 8
+  },
+  "pre_rule_ids": [
+    "CKV2_AWS_6",
+    "CKV2_AWS_61",
+    "CKV2_AWS_62",
+    "CKV_AWS_144",
+    "CKV_AWS_145",
+    "CKV_AWS_18",
+    "CKV_AWS_20",
+    "CKV_AWS_21"
+  ],
+  "post_rule_ids": [
+    "CKV2_AWS_6",
+    "CKV2_AWS_61",
+    "CKV2_AWS_62",
+    "CKV_AWS_144",
+    "CKV_AWS_145",
+    "CKV_AWS_18",
+    "CKV_AWS_20",
+    "CKV_AWS_21"
+  ],
+  "actual_verdict": "rejected",
+  "demo_gate_status": "rejected",
+  "demo_outcome": "rejected",
+  "verdict": "rejected",
+  "latency_s": 27.028045281986124,
+  "decision": {
+    "action": "rejected",
+    "reason": "parse failure, unresolved targeted findings, or over-broad diff",
+    "patch": {
+      "patch": "",
+      "fixed_file": "resource \"aws_s3_bucket\" \"data\" {\n  bucket = \"iac-secfix-public-demo\"\n  acl    = \"public-read\"\n}",
+      "resolved_policy_ids": [],
+      "explanation": "No fix templates were applicable to the original file without inventing placeholder resources. All targeted rules require external dependencies (IAM roles, KMS keys, logging buckets, replication destinations) that do not exist in the file. Setting requires_human_approval=true.",
+      "verification_commands": [],
+      "risk_notes": [],
+      "requires_human_approval": true
+    },
+    "validation": {
+      "parse_ok": true,
+      "targeted_resolved": [],
+      "targeted_unresolved": [
+        "CKV2_AWS_6",
+        "CKV2_AWS_61",
+        "CKV2_AWS_62",
+        "CKV_AWS_144",
+        "CKV_AWS_145",
+        "CKV_AWS_18",
+        "CKV_AWS_20",
+        "CKV_AWS_21"
+      ],
+      "new_findings": [],
+      "new_critical_high_count": 0,
+      "changed_lines_ratio": 0.04,
+      "pre_summary": {
+        "failed": 8,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 8
+      },
+      "post_summary": {
+        "failed": 8,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 8,
+        "LOW": 0,
+        "INFO": 0
+      },
+      "verdict": "retry",
+      "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+    },
+    "compliance": null,
+    "n_retries": 1
+  },
+  "validation": {
+    "parse_ok": true,
+    "targeted_resolved": [],
+    "targeted_unresolved": [
+      "CKV2_AWS_6",
+      "CKV2_AWS_61",
+      "CKV2_AWS_62",
+      "CKV_AWS_144",
+      "CKV_AWS_145",
+      "CKV_AWS_18",
+      "CKV_AWS_20",
+      "CKV_AWS_21"
+    ],
+    "new_findings": [],
+    "new_critical_high_count": 0,
+    "changed_lines_ratio": 0.04,
+    "pre_summary": {
+      "failed": 8,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 8
+    },
+    "post_summary": {
+      "failed": 8,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 8,
+      "LOW": 0,
+      "INFO": 0
+    },
+    "verdict": "retry",
+    "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+  },
+  "paths": {
+    "original": "demo/original/demo_s3_public.tf",
+    "fixed": "demo/fixed/demo_s3_public.tf",
+    "precomputed": "demo/precomputed/demo_s3_public.json"
+  }
+}

demo_examples/demo_sg_open.json

@@ -0,0 +1,135 @@
+{
+  "file_name": "demo_sg_open.tf",
+  "iac_type": "terraform",
+  "expected_policy_ids": [
+    "CKV_AWS_24",
+    "CKV_AWS_25",
+    "CKV_AWS_260"
+  ],
+  "expected_present_before": [
+    "CKV_AWS_24"
+  ],
+  "expected_missing_before": [
+    "CKV_AWS_25",
+    "CKV_AWS_260"
+  ],
+  "expected_resolved_policy_ids": [
+    "CKV_AWS_24",
+    "CKV_AWS_25",
+    "CKV_AWS_260"
+  ],
+  "expected_unresolved_policy_ids": [],
+  "original_file": "resource \"aws_security_group\" \"open\" {\n  name = \"iac-secfix-open\"\n\n  ingress {\n    from_port   = 22\n    to_port     = 22\n    protocol    = \"tcp\"\n    cidr_blocks = [\"0.0.0.0/0\"]\n  }\n}\n",
+  "fixed_file": "resource \"aws_security_group\" \"open\" {\n  name = \"iac-secfix-open\"\n\n  description = \"Production application traffic\"\n\n  ingress {\n    from_port   = 22\n    to_port     = 22\n    protocol    = \"tcp\"\n    cidr_blocks = [\"10.0.0.0/16\"]\n  }\n}",
+  "pre_summary": {
+    "failed": 3,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 3
+  },
+  "post_summary": {
+    "failed": 2,
+    "CRITICAL": 0,
+    "HIGH": 0,
+    "MEDIUM": 2
+  },
+  "pre_rule_ids": [
+    "CKV2_AWS_5",
+    "CKV_AWS_23",
+    "CKV_AWS_24"
+  ],
+  "post_rule_ids": [
+    "CKV2_AWS_5",
+    "CKV_AWS_23"
+  ],
+  "actual_verdict": "rejected",
+  "demo_gate_status": "rejected",
+  "demo_outcome": "rejected",
+  "verdict": "rejected",
+  "latency_s": 51.86773505600286,
+  "decision": {
+    "action": "rejected",
+    "reason": "parse failure, unresolved targeted findings, or over-broad diff",
+    "patch": {
+      "patch": "description = \"Production application traffic\"\n\ncidr_blocks = [\"10.0.0.0/16\"]",
+      "fixed_file": "resource \"aws_security_group\" \"open\" {\n  name = \"iac-secfix-open\"\n\n  description = \"Production application traffic\"\n\n  ingress {\n    from_port   = 22\n    to_port     = 22\n    protocol    = \"tcp\"\n    cidr_blocks = [\"10.0.0.0/16\"]\n  }\n}",
+      "resolved_policy_ids": [
+        "CKV_AWS_24",
+        "CKV_AWS_23"
+      ],
+      "explanation": "Added description to security group and changed cidr_blocks from 0.0.0.0/0 to 10.0.0.0/16 for port 22.",
+      "verification_commands": [
+        "checkov -f fixed_file -r CKV_AWS_24 -r CKV_AWS_23"
+      ],
+      "risk_notes": [
+        "CKV2_AWS_5 remains unresolved due to missing attachment"
+      ],
+      "requires_human_approval": true
+    },
+    "validation": {
+      "parse_ok": true,
+      "targeted_resolved": [
+        "CKV_AWS_24"
+      ],
+      "targeted_unresolved": [
+        "CKV2_AWS_5",
+        "CKV_AWS_23"
+      ],
+      "new_findings": [],
+      "new_critical_high_count": 0,
+      "changed_lines_ratio": 0.12,
+      "pre_summary": {
+        "failed": 3,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 3
+      },
+      "post_summary": {
+        "failed": 2,
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 2,
+        "LOW": 0,
+        "INFO": 0
+      },
+      "verdict": "retry",
+      "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+    },
+    "compliance": null,
+    "n_retries": 1
+  },
+  "validation": {
+    "parse_ok": true,
+    "targeted_resolved": [
+      "CKV_AWS_24"
+    ],
+    "targeted_unresolved": [
+      "CKV2_AWS_5",
+      "CKV_AWS_23"
+    ],
+    "new_findings": [],
+    "new_critical_high_count": 0,
+    "changed_lines_ratio": 0.12,
+    "pre_summary": {
+      "failed": 3,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 3
+    },
+    "post_summary": {
+      "failed": 2,
+      "CRITICAL": 0,
+      "HIGH": 0,
+      "MEDIUM": 2,
+      "LOW": 0,
+      "INFO": 0
+    },
+    "verdict": "retry",
+    "retry_reason": "parse failure, unresolved targeted findings, or over-broad diff"
+  },
+  "paths": {
+    "original": "demo/original/demo_sg_open.tf",
+    "fixed": "demo/fixed/demo_sg_open.tf",
+    "precomputed": "demo/precomputed/demo_sg_open.json"
+  }
+}

iac_secfix_agents/__init__.py

@@ -0,0 +1,14 @@
+"""Submission-ready IaC remediation multi-agent package."""
+
+from .config import RuntimeConfig
+from .orchestrator import RemediationOrchestrator, OrchestratorSettings
+from .schemas import ApprovalDecision, FixCandidate, IngestRequest
+
+__all__ = [
+    "ApprovalDecision",
+    "FixCandidate",
+    "IngestRequest",
+    "OrchestratorSettings",
+    "RemediationOrchestrator",
+    "RuntimeConfig",
+]

iac_secfix_agents/agents.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .config import RuntimeConfig
+from .llm import OpenAICompatibleLLM, make_pydantic_agent, make_pydantic_openai_model, parse_fix_candidate
+from .policy import build_rule_hints_md, enrich_findings
+from .schemas import (
+    ApprovalDecision,
+    ComplianceReport,
+    EnrichedFindings,
+    Finding,
+    FixCandidate,
+    IngestRequest,
+    ScanBundle,
+    ValidationResult,
+)
+
+
+@dataclass(slots=True)
+class PydanticAgentBundle:
+    ingest: Any | None = None
+    policy_context: Any | None = None
+    patch: Any | None = None
+    validation: Any | None = None
+    compliance: Any | None = None
+    approval: Any | None = None
+
+    @property
+    def available(self) -> bool:
+        return any(
+            agent is not None
+            for agent in [
+                self.ingest,
+                self.policy_context,
+                self.patch,
+                self.validation,
+                self.compliance,
+                self.approval,
+            ]
+        )
+
+
+def create_pydantic_agent_bundle(config: RuntimeConfig) -> PydanticAgentBundle:
+    """Build PydanticAI agents when the installed API supports it."""
+
+    model = make_pydantic_openai_model(config)
+    return PydanticAgentBundle(
+        ingest=make_pydantic_agent(
+            model,
+            ScanBundle,
+            "Identify file type and return scanner bundle. Deterministic scanner tools supply findings.",
+        ),
+        policy_context=make_pydantic_agent(
+            model,
+            EnrichedFindings,
+            "Map scanner findings to policy descriptions. Do not invent policy IDs.",
+        ),
+        patch=make_pydantic_agent(model, FixCandidate, "Return only a valid FixCandidate JSON object."),
+        validation=make_pydantic_agent(model, ValidationResult, "Summarize deterministic validation results only."),
+        compliance=make_pydantic_agent(model, ComplianceReport, "Compute compliance summary only from scan summaries."),
+        approval=make_pydantic_agent(
+            model,
+            ApprovalDecision,
+            "Return needs_human_review unless deterministic validation says accept and auto approval is enabled.",
+        ),
+    )
+
+
+def shard_for_context(file_content: str, findings: list[Finding], max_chars: int) -> str:
+    if len(file_content) <= max_chars:
+        return file_content
+
+    lines = file_content.splitlines()
+    selected: list[str] = ["# Non-targeted blocks omitted for context budget."]
+    used_ranges: list[tuple[int, int]] = []
+
+    for finding in findings:
+        start = max((finding.line_start or 1) - 20, 1)
+        end = min((finding.line_end or start) + 20, len(lines))
+        if any(not (end < old_start or start > old_end) for old_start, old_end in used_ranges):
+            continue
+        used_ranges.append((start, end))
+        selected.append(f"\n# Context lines {start}-{end}")
+        selected.extend(lines[start - 1 : end])
+        if len("\n".join(selected)) >= max_chars:
+            break
+
+    return "\n".join(selected)[:max_chars]
+
+
+def fix_candidate_schema_text() -> str:
+    return """
+Return exactly one JSON object:
+{
+  "patch": "unified diff string",
+  "fixed_file": "complete corrected file content",
+  "resolved_policy_ids": ["CKV_..."],
+  "explanation": "short summary",
+  "verification_commands": ["checkov -f <file> -o json"],
+  "risk_notes": ["human-review note if needed"],
+  "requires_human_approval": true
+}
+No markdown fences. No prose outside JSON.
+""".strip()
+
+
+def build_patch_prompt(
+    enriched: EnrichedFindings,
+    retry_feedback: str | None = None,
+    max_context_chars: int = 18000,
+    max_finding_records: int = 24,
+) -> str:
+    iac_type = enriched.file.iac_type
+    lang = "hcl" if iac_type == "terraform" else "yaml"
+    findings_for_json = enriched.findings[:max_finding_records]
+    omitted = max(0, len(enriched.findings) - len(findings_for_json))
+
+    scanner_report_json = json.dumps(
+        [finding.model_dump(mode="json") for finding in findings_for_json],
+        ensure_ascii=False,
+        indent=2,
+    )
+    rule_ids = [finding.rule_id for finding in enriched.findings]
+    original_context = shard_for_context(enriched.file.file_content, list(enriched.findings), max_context_chars)
+
+    prompt = f"""
+Original file type: {iac_type}
+Original file language: {lang}
+
+<original_file>
+{original_context}
+</original_file>
+
+<targeted_rule_ids>
+{json.dumps(sorted(set(rule_ids)))}
+</targeted_rule_ids>
+
+<scanner_findings_json>
+{scanner_report_json}
+</scanner_findings_json>
+
+<scanner_findings_omitted_due_context_budget>
+{omitted}
+</scanner_findings_omitted_due_context_budget>
+
+<targeted_rules_with_fix_templates>
+{build_rule_hints_md(rule_ids)}
+</targeted_rules_with_fix_templates>
+
+Task:
+Create the smallest safe in-file remediation that resolves as many targeted rule_id values as possible.
+
+Hard requirements:
+- Start from the ORIGINAL file. Add or modify only attributes directly needed by the matching fix templates.
+- fixed_file must contain the complete corrected file, including unchanged lines.
+- Do not delete, rename, or reorder resources, modules, providers, containers, or attributes unless the rule requires it.
+- Do not invent placeholder ARNs, account IDs, bucket names, topics, roles, regions, KMS keys, CIDRs, or image tags.
+- If a rule requires an external dependency or unknown business decision, leave it unresolved and set requires_human_approval=true.
+- Do not introduce CRITICAL or HIGH findings.
+- Do not add checkov:skip, nosec, tfsec:ignore, or scanner suppression comments.
+- Before returning, list only rule IDs that your fixed_file actually resolves in resolved_policy_ids.
+
+{fix_candidate_schema_text()}
+""".strip()
+
+    if retry_feedback:
+        prompt += f"\n\n<previous_validation_feedback>\n{retry_feedback[:4000]}\n</previous_validation_feedback>"
+
+    return prompt
+
+
+def compress_feedback(result: ValidationResult, attempt: int, max_retries: int) -> str:
+    payload = {
+        "attempt": attempt + 1,
+        "max_retries": max_retries,
+        "retry_reason": result.retry_reason,
+        "targeted_still_unresolved": result.targeted_unresolved,
+        "new_critical_high_count": result.new_critical_high_count,
+        "changed_lines_ratio": round(result.changed_lines_ratio, 3),
+        "post_scan_summary": result.post_summary,
+    }
+    feedback = json.dumps(payload, ensure_ascii=False)
+    if result.targeted_unresolved:
+        feedback += "\n\nUnresolved-rule fix templates:\n"
+        feedback += build_rule_hints_md(result.targeted_unresolved)
+    feedback += (
+        "\n\nRetry instructions:\n"
+        "- Start again from the original file, not the previous attempt.\n"
+        "- Apply the smallest safe edit for the unresolved rules.\n"
+        "- Remove rule IDs from resolved_policy_ids when validation did not resolve them.\n"
+    )
+    return feedback[:4000]
+
+
+class IngestAgent:
+    def run(self, request: IngestRequest, tmp_dir: Path | None = None) -> ScanBundle:
+        from .scanners import unified_scan
+
+        return unified_scan(request, tmp_dir=tmp_dir)
+
+
+class PolicyContextAgent:
+    def run(self, bundle: ScanBundle) -> EnrichedFindings:
+        return enrich_findings(bundle)
+
+
+class PatchAgent:
+    def __init__(self, config: RuntimeConfig, log_dir: Path):
+        self.llm = OpenAICompatibleLLM(config)
+        self.log_dir = log_dir
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    def run(
+        self,
+        enriched: EnrichedFindings,
+        retry_feedback: str | None = None,
+        max_context_chars: int = 18000,
+    ) -> tuple[FixCandidate | None, bool, str]:
+        prompt = build_patch_prompt(enriched, retry_feedback, max_context_chars=max_context_chars)
+        messages = [
+            {
+                "role": "system",
+                "content": (
+                    "You are IaC-SecFix. Return only valid JSON matching the FixCandidate schema. "
+                    "Do not include markdown, prose, analysis, or code fences."
+                ),
+            },
+            {"role": "user", "content": prompt},
+        ]
+        result = self.llm.chat(messages, json_mode=True)
+        self.log_dir.joinpath("last_patch_raw.txt").write_text(result.text[:20000], errors="ignore")
+        candidate, schema_valid = parse_fix_candidate(result.text)
+        return candidate, schema_valid, result.text
+
+
+class ValidationAgent:
+    def run(
+        self,
+        request: IngestRequest,
+        candidate: FixCandidate,
+        targeted: list[str],
+        tmp_dir: Path | None,
+        max_changed_lines_ratio: float,
+    ) -> ValidationResult:
+        from .scanners import validate_candidate
+
+        return validate_candidate(
+            request,
+            candidate,
+            targeted,
+            tmp_dir=tmp_dir,
+            max_changed_lines_ratio=max_changed_lines_ratio,
+        )
+
+
+class ComplianceAgent:
+    def run(self, pre_summary: dict[str, object], result: ValidationResult) -> ComplianceReport:
+        before_failed = max(int(pre_summary.get("failed", 0) or 0), len(result.targeted_resolved) + len(result.targeted_unresolved), 1)
+        after_failed = int(result.post_summary.get("failed", 0) or 0)
+        targeted_total = max(len(result.targeted_resolved) + len(result.targeted_unresolved), 1)
+        return ComplianceReport(
+            cis_pass_rate_before=max(0.0, 1.0 - before_failed / max(before_failed, 1)),
+            cis_pass_rate_after=max(0.0, 1.0 - after_failed / max(before_failed, 1)),
+            network_exposure_reduction=1.0 if result.targeted_resolved else 0.0,
+            iam_privilege_reduction=1.0 if result.targeted_resolved else 0.0,
+            targeted_resolution_rate=len(result.targeted_resolved) / targeted_total,
+            scanner_clean=after_failed == 0,
+        )
+
+
+class HumanApprovalGate:
+    def __init__(self, auto_approve_validated: bool = False):
+        self.auto_approve_validated = auto_approve_validated
+
+    def run(
+        self,
+        patch: FixCandidate,
+        result: ValidationResult,
+        compliance: ComplianceReport,
+        n_retries: int,
+    ) -> ApprovalDecision:
+        can_auto_approve = (
+            self.auto_approve_validated
+            and result.verdict == "accept"
+            and not patch.requires_human_approval
+        )
+        if can_auto_approve:
+            return ApprovalDecision(
+                action="approved",
+                reason="Deterministic validation accepted the patch.",
+                patch=patch,
+                validation=result,
+                compliance=compliance,
+                n_retries=n_retries,
+            )
+        return ApprovalDecision(
+            action="needs_human_review",
+            reason="Validated candidate requires human approval before export.",
+            patch=patch,
+            validation=result,
+            compliance=compliance,
+            n_retries=n_retries,
+        )

iac_secfix_agents/cli.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .config import RuntimeConfig
+from .evaluation import build_submission_summary
+from .orchestrator import OrchestratorSettings, RemediationOrchestrator
+from .schemas import IngestRequest
+from .scanners import detect_iac_type
+
+
+def cmd_remediate(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    content = path.read_text()
+    iac_type = args.iac_type or detect_iac_type(path.name, content)
+    config = RuntimeConfig.from_env()
+    settings = OrchestratorSettings(
+        max_retries=args.max_retries,
+        auto_approve_validated=args.auto_approve,
+    )
+    orchestrator = RemediationOrchestrator(config=config, settings=settings)
+    decision = orchestrator.remediate(
+        IngestRequest(
+            file_name=path.name,
+            file_content=content,
+            iac_type=iac_type,
+            user_intent=args.intent,
+        )
+    )
+    print(json.dumps(decision.model_dump(mode="json"), indent=2))
+    return 0
+
+
+def cmd_summarize_results(args: argparse.Namespace) -> int:
+    summary = build_submission_summary(Path(args.eval_dir))
+    print(json.dumps(summary, indent=2))
+    return 0
+
+
+def cmd_self_test(_: argparse.Namespace) -> int:
+    request = IngestRequest(
+        file_name="example.tf",
+        file_content='resource "aws_s3_bucket" "data" { bucket = "demo" }\n',
+        iac_type="terraform",
+        user_intent="Fix detected IaC security findings.",
+    )
+    assert request.iac_type == "terraform"
+    print("self-test passed: schemas and imports are available")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="iac-secfix-agents")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    remediate = subparsers.add_parser("remediate", help="Run the multi-agent remediation loop for one file.")
+    remediate.add_argument("file")
+    remediate.add_argument("--iac-type", choices=["terraform", "kubernetes", "dockerfile"])
+    remediate.add_argument("--intent", default="Fix the detected IaC security findings.")
+    remediate.add_argument("--max-retries", type=int, default=3)
+    remediate.add_argument("--auto-approve", action="store_true")
+    remediate.set_defaults(func=cmd_remediate)
+
+    summary = subparsers.add_parser("summarize-results", help="Summarize notebook evaluation artifacts.")
+    summary.add_argument("--eval-dir", default="../eval")
+    summary.set_defaults(func=cmd_summarize_results)
+
+    self_test = subparsers.add_parser("self-test", help="Run a lightweight import/schema check.")
+    self_test.set_defaults(func=cmd_self_test)
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

iac_secfix_agents/config.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class RuntimeConfig:
+    """Runtime settings for the OpenAI-compatible vLLM endpoint."""
+
+    base_url: str = "http://localhost:8000/v1"
+    api_key: str = "abc-123"
+    model: str = "iac-secfix"
+    temperature: float = 0.0
+    top_p: float = 1.0
+    max_tokens: int = 2048
+    work_dir: Path = Path("runs")
+
+    @classmethod
+    def from_env(cls) -> "RuntimeConfig":
+        return cls(
+            base_url=os.getenv("IAC_SECFIX_BASE_URL", cls.base_url),
+            api_key=os.getenv("IAC_SECFIX_API_KEY", cls.api_key),
+            model=os.getenv("IAC_SECFIX_MODEL", cls.model),
+            temperature=float(os.getenv("IAC_SECFIX_TEMPERATURE", str(cls.temperature))),
+            top_p=float(os.getenv("IAC_SECFIX_TOP_P", str(cls.top_p))),
+            max_tokens=int(os.getenv("IAC_SECFIX_MAX_TOKENS", str(cls.max_tokens))),
+            work_dir=Path(os.getenv("IAC_SECFIX_WORK_DIR", str(cls.work_dir))),
+        )
+
+
+def vllm_extra_body() -> dict[str, object]:
+    """Small vLLM compatibility body.
+
+    vLLM accepts these fields on OpenAI-compatible chat completions. Keeping this
+    helper tiny avoids depending on notebook globals.
+    """
+
+    return {
+        "guided_decoding_backend": "outlines",
+    }

iac_secfix_agents/evaluation.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text()) if path.exists() else {}
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    return [json.loads(line) for line in path.read_text().splitlines() if line.strip()]
+
+
+def usable_clean_rate(artifacts: list[dict[str, Any]]) -> float:
+    if not artifacts:
+        return 0.0
+    usable = 0
+    for artifact in artifacts:
+        clean = bool(artifact.get("scanner_clean", False))
+        schema_valid = bool(artifact.get("schema_valid", False))
+        parse_ok = bool(artifact.get("parse_ok", False))
+        quality_issues = artifact.get("quality_issues") or []
+        safe = not bool(artifact.get("unsafe_action", False))
+        if clean and schema_valid and parse_ok and not quality_issues and safe:
+            usable += 1
+    return usable / len(artifacts)
+
+
+def report_row(report: dict[str, Any], artifacts: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+    artifacts = artifacts or []
+    return {
+        "system": report.get("system"),
+        "n": report.get("n"),
+        "scope": report.get("evaluation_scope", "full_benchmark"),
+        "evidence_level": report.get("evidence_level"),
+        "scanner_clean_rate": report.get("scanner_clean_rate"),
+        "usable_clean_rate": usable_clean_rate(artifacts) if artifacts else None,
+        "targeted_policy_resolution_rate": report.get("targeted_policy_resolution_rate"),
+        "parse_validity_rate": report.get("parse_validity_rate"),
+        "pydantic_schema_validity_rate": report.get("pydantic_schema_validity_rate"),
+        "unsafe_action_rate": report.get("unsafe_action_rate"),
+        "median_latency_s": report.get("median_latency_s"),
+        "failure_counts": report.get("failure_counts", {}),
+    }
+
+
+def build_submission_summary(eval_dir: Path) -> dict[str, Any]:
+    report_b1 = read_json(eval_dir / "report_b1.json")
+    report_b3 = read_json(eval_dir / "report_b3.json")
+    report_b4 = read_json(eval_dir / "report_b4.json") or read_json(eval_dir / "report_b4.partial.json")
+    report_b5 = read_json(eval_dir / "report_b5.json") or read_json(eval_dir / "report_b5.partial.json")
+    report_final = read_json(eval_dir / "report_final.json")
+
+    b1_artifacts = read_jsonl(eval_dir / "per_example_b1.jsonl")
+    b3_artifacts = read_jsonl(eval_dir / "per_example_b3.jsonl")
+    b4_artifacts = read_jsonl(eval_dir / "per_example_b4.jsonl") or read_jsonl(eval_dir / "per_example_b4.partial.jsonl")
+    b5_artifacts = read_jsonl(eval_dir / "per_example_b5.jsonl") or read_jsonl(eval_dir / "per_example_b5.partial.jsonl")
+
+    systems = [
+        report_row(report_b1, b1_artifacts),
+        report_row(report_b3, b3_artifacts),
+        report_row(report_b4, b4_artifacts),
+        report_row(report_b5, b5_artifacts),
+    ]
+
+    safety_report = read_json(eval_dir / "safety_report.json")
+    training_report = read_json(eval_dir / "training_report.json")
+
+    return {
+        "chosen_system": report_final.get("chosen_system", "B3_zero_shot_rag"),
+        "recommended_claim": "scanner-verified IaC remediation prototype with deterministic safety and validation gates",
+        "systems": systems,
+        "safety": safety_report,
+        "training": training_report,
+        "notes": [
+            "B3 is the most defensible final benchmark claim.",
+            "B5 shows better partial scanner-clean and targeted-resolution rates, but it is partial and requires human review.",
+            "Fine-tuning is infrastructure evidence only unless a full benchmark shows uplift over B3.",
+        ],
+    }

iac_secfix_agents/llm.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import inspect
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import ValidationError
+
+from .config import RuntimeConfig, vllm_extra_body
+from .schemas import FixCandidate
+
+
+def extract_json_object(text: str) -> str | None:
+    start = text.find("{")
+    if start == -1:
+        return None
+
+    depth = 0
+    in_string = False
+    escaped = False
+    for index in range(start, len(text)):
+        char = text[index]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            continue
+        if char == '"':
+            in_string = True
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start : index + 1]
+    return None
+
+
+def coerce_fix_candidate(raw: dict[str, Any]) -> dict[str, Any]:
+    patch = raw.get("patch") or raw.get("diff") or ""
+    fixed_file = raw.get("fixed_file") or raw.get("content") or raw.get("file_content")
+    resolved = raw.get("resolved_policy_ids") or raw.get("resolved") or []
+    if isinstance(resolved, str):
+        resolved = [resolved]
+    return {
+        "patch": patch,
+        "fixed_file": fixed_file,
+        "resolved_policy_ids": resolved,
+        "explanation": raw.get("explanation") or raw.get("summary") or "",
+        "verification_commands": raw.get("verification_commands") or [],
+        "risk_notes": raw.get("risk_notes") or [],
+        "requires_human_approval": bool(raw.get("requires_human_approval", True)),
+    }
+
+
+def parse_fix_candidate(text: str) -> tuple[FixCandidate | None, bool]:
+    json_text = extract_json_object(text)
+    if json_text is None:
+        return None, False
+    try:
+        return FixCandidate.model_validate_json(json_text), True
+    except ValidationError:
+        try:
+            raw = json.loads(json_text)
+            if not isinstance(raw, dict):
+                return None, False
+            return FixCandidate.model_validate(coerce_fix_candidate(raw)), True
+        except Exception:
+            return None, False
+
+
+@dataclass(slots=True)
+class ChatResult:
+    text: str
+    used_json_mode: bool
+
+
+class OpenAICompatibleLLM:
+    """Thin OpenAI-compatible client used by the PatchAgent."""
+
+    def __init__(self, config: RuntimeConfig):
+        from openai import OpenAI
+
+        self.config = config
+        self.client = OpenAI(base_url=config.base_url, api_key=config.api_key)
+
+    def chat(self, messages: list[dict[str, str]], json_mode: bool = True) -> ChatResult:
+        kwargs: dict[str, Any] = {
+            "model": self.config.model,
+            "messages": messages,
+            "temperature": self.config.temperature,
+            "top_p": self.config.top_p,
+            "max_tokens": self.config.max_tokens,
+            "extra_body": vllm_extra_body(),
+        }
+        if json_mode:
+            kwargs["response_format"] = {"type": "json_object"}
+
+        try:
+            completion = self.client.chat.completions.create(**kwargs)
+            return ChatResult(completion.choices[0].message.content or "{}", used_json_mode=json_mode)
+        except Exception:
+            kwargs.pop("response_format", None)
+            kwargs.pop("extra_body", None)
+            completion = self.client.chat.completions.create(**kwargs)
+            return ChatResult(completion.choices[0].message.content or "{}", used_json_mode=False)
+
+
+def make_pydantic_openai_model(config: RuntimeConfig) -> Any | None:
+    """Create a PydanticAI OpenAI-compatible model when the library is present."""
+
+    try:
+        from pydantic_ai.models.openai import OpenAIChatModel
+        from pydantic_ai.providers.openai import OpenAIProvider
+
+        provider = OpenAIProvider(base_url=config.base_url, api_key=config.api_key)
+        return OpenAIChatModel(config.model, provider=provider)
+    except Exception:
+        pass
+
+    try:
+        from pydantic_ai.models.openai import OpenAIModel
+        from pydantic_ai.providers.openai import OpenAIProvider
+
+        provider = OpenAIProvider(base_url=config.base_url, api_key=config.api_key)
+        return OpenAIModel(config.model, provider=provider)
+    except Exception:
+        return None
+
+
+def make_pydantic_agent(model: Any, output_model: type[Any], system_prompt: str) -> Any | None:
+    """Compatibility wrapper for PydanticAI versions.
+
+    Some environments use `result_type`, newer ones may use `output_type`. The
+    notebook hit this exact API mismatch, so the submission code adapts at runtime.
+    """
+
+    if model is None:
+        return None
+    try:
+        from pydantic_ai import Agent
+
+        signature = inspect.signature(Agent)
+        kwargs: dict[str, Any] = {}
+        if "output_type" in signature.parameters:
+            kwargs["output_type"] = output_model
+        elif "result_type" in signature.parameters:
+            kwargs["result_type"] = output_model
+        if "instructions" in signature.parameters:
+            kwargs["instructions"] = system_prompt
+        elif "system_prompt" in signature.parameters:
+            kwargs["system_prompt"] = system_prompt
+        if "model" in signature.parameters:
+            kwargs["model"] = model
+            return Agent(**kwargs)
+        return Agent(model, **kwargs)
+    except Exception:
+        return None

iac_secfix_agents/orchestrator.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .agents import (
+    ComplianceAgent,
+    HumanApprovalGate,
+    IngestAgent,
+    PatchAgent,
+    PolicyContextAgent,
+    ValidationAgent,
+    compress_feedback,
+    create_pydantic_agent_bundle,
+)
+from .config import RuntimeConfig
+from .safety import DeterministicSafetyAgent
+from .schemas import ApprovalDecision, FixCandidate, IngestRequest, ValidationResult
+
+
+@dataclass(slots=True)
+class OrchestratorSettings:
+    max_retries: int = 3
+    max_context_chars: int = 18000
+    max_changed_lines_ratio: float = 0.35
+    auto_approve_validated: bool = False
+
+
+class RemediationOrchestrator:
+    """Multi-agent remediation loop with deterministic validation gates."""
+
+    def __init__(
+        self,
+        config: RuntimeConfig | None = None,
+        settings: OrchestratorSettings | None = None,
+    ):
+        self.config = config or RuntimeConfig.from_env()
+        self.settings = settings or OrchestratorSettings()
+        self.config.work_dir.mkdir(parents=True, exist_ok=True)
+        self.tmp_dir = self.config.work_dir / "tmp"
+        self.log_dir = self.config.work_dir / "logs"
+        self.tmp_dir.mkdir(parents=True, exist_ok=True)
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+        self.pydantic_agents = create_pydantic_agent_bundle(self.config)
+        self.ingest_agent = IngestAgent()
+        self.policy_context_agent = PolicyContextAgent()
+        self.patch_agent = PatchAgent(self.config, self.log_dir)
+        self.validation_agent = ValidationAgent()
+        self.compliance_agent = ComplianceAgent()
+        self.human_approval_gate = HumanApprovalGate(self.settings.auto_approve_validated)
+        self.safety_agent = DeterministicSafetyAgent()
+
+    def remediate(self, request: IngestRequest) -> ApprovalDecision:
+        pre_safety = self.safety_agent.check_request(request)
+        if not pre_safety.allowed:
+            return ApprovalDecision(action="refused", reason=pre_safety.reason, n_retries=0)
+
+        bundle = self.ingest_agent.run(request, tmp_dir=self.tmp_dir)
+        enriched = self.policy_context_agent.run(bundle)
+
+        if not enriched.findings:
+            return ApprovalDecision(
+                action="needs_human_review",
+                reason="No deterministic scanner findings were found.",
+                n_retries=0,
+            )
+
+        feedback: str | None = None
+        previous_reason: str | None = None
+        best_patch: FixCandidate | None = None
+        best_result: ValidationResult | None = None
+        targeted = [finding.rule_id for finding in enriched.findings]
+
+        for attempt in range(self.settings.max_retries + 1):
+            candidate, schema_valid, _raw_text = self.patch_agent.run(
+                enriched,
+                retry_feedback=feedback,
+                max_context_chars=self.settings.max_context_chars,
+            )
+
+            if candidate is None or not schema_valid:
+                feedback = "Output did not match the FixCandidate JSON schema."
+                previous_reason = feedback
+                continue
+
+            best_patch = candidate
+            post_safety = self.safety_agent.check_patch(
+                request.file_content,
+                candidate.fixed_file,
+                candidate.patch,
+            )
+            if not post_safety.allowed:
+                return ApprovalDecision(
+                    action="refused",
+                    reason=post_safety.reason,
+                    patch=candidate,
+                    n_retries=attempt,
+                )
+
+            result = self.validation_agent.run(
+                request,
+                candidate,
+                targeted,
+                tmp_dir=self.tmp_dir,
+                max_changed_lines_ratio=self.settings.max_changed_lines_ratio,
+            )
+            result.pre_summary = bundle.pre_summary
+            best_result = result
+
+            if result.verdict == "accept":
+                compliance = self.compliance_agent.run(bundle.pre_summary, result)
+                return self.human_approval_gate.run(candidate, result, compliance, attempt)
+
+            if result.verdict == "reject" or result.retry_reason == previous_reason:
+                return ApprovalDecision(
+                    action="rejected",
+                    reason=result.retry_reason or "Validation rejected patch.",
+                    patch=candidate,
+                    validation=result,
+                    n_retries=attempt,
+                )
+
+            previous_reason = result.retry_reason
+            feedback = compress_feedback(result, attempt=attempt, max_retries=self.settings.max_retries)
+
+        return ApprovalDecision(
+            action="needs_human_review",
+            reason=f"Max retries reached: {feedback}",
+            patch=best_patch,
+            validation=best_result,
+            n_retries=self.settings.max_retries,
+        )

iac_secfix_agents/policy.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from .schemas import EnrichedFinding, EnrichedFindings, ScanBundle
+
+
+POLICY_DESCRIPTIONS: dict[str, str] = {
+    "CKV_AWS_18": "S3 buckets should have access logging enabled.",
+    "CKV_AWS_20": "S3 buckets should not allow public ACLs.",
+    "CKV_AWS_21": "S3 buckets should have versioning enabled.",
+    "CKV_AWS_23": "Security group ingress rules should not allow unrestricted access.",
+    "CKV_AWS_24": "Security group ingress rules should not allow unrestricted SSH.",
+    "CKV_AWS_79": "EC2 instances should require IMDSv2.",
+    "CKV_AWS_144": "S3 buckets should have cross-region replication enabled when required.",
+    "CKV_AWS_145": "S3 buckets should use KMS encryption.",
+    "CKV2_AWS_6": "S3 public access block should block public ACLs and policies.",
+    "CKV2_AWS_61": "S3 buckets should have lifecycle configuration.",
+    "CKV2_AWS_62": "S3 buckets should have event notifications configured when required.",
+    "CKV2_AWS_64": "KMS keys should have key rotation enabled.",
+    "CKV_K8S_8": "Kubernetes containers should not run as root.",
+    "CKV_K8S_9": "Kubernetes containers should not run with privileged escalation.",
+    "CKV_K8S_10": "Kubernetes containers should set CPU requests.",
+    "CKV_K8S_11": "Kubernetes containers should set CPU limits.",
+    "CKV_K8S_12": "Kubernetes containers should set memory requests.",
+    "CKV_K8S_13": "Kubernetes containers should set memory limits.",
+    "CKV_K8S_14": "Kubernetes images should use immutable tags.",
+    "CKV_K8S_20": "Kubernetes containers should not run privileged.",
+    "CKV_K8S_21": "Kubernetes default namespace should not be used.",
+    "CKV_K8S_22": "Kubernetes containers should use read-only root filesystems where possible.",
+    "CKV_K8S_23": "Kubernetes containers should drop dangerous capabilities.",
+    "CKV_K8S_28": "Kubernetes containers should minimize Linux capabilities.",
+    "CKV_K8S_29": "Kubernetes containers should not allow privilege escalation.",
+    "CKV_K8S_31": "Kubernetes seccomp profile should be configured.",
+    "CKV_K8S_37": "Kubernetes containers should minimize capabilities.",
+    "CKV_K8S_38": "Kubernetes containers should run as non-root.",
+    "CKV_K8S_40": "Kubernetes containers should not run as UID 0.",
+    "CKV_K8S_43": "Kubernetes images should use digest or immutable tags.",
+    "CKV_TF_1": "Terraform should pin module sources to immutable versions.",
+    "CKV_TF_2": "Terraform providers should be version constrained.",
+}
+
+
+REMEDIATION_HINTS: dict[str, str] = {
+    "CKV_AWS_20": "For aws_s3_bucket_acl, avoid public-read/public-read-write. Prefer private ACLs and ownership controls.",
+    "CKV_AWS_21": "Add aws_s3_bucket_versioning with versioning_configuration { status = \"Enabled\" } for the target bucket.",
+    "CKV_AWS_23": "Restrict ingress CIDR blocks from 0.0.0.0/0 to a known trusted CIDR. If unknown, require human approval.",
+    "CKV_AWS_24": "Do not expose port 22 to 0.0.0.0/0. Narrow CIDR or remove the SSH ingress rule if not required.",
+    "CKV_AWS_79": "Add metadata_options { http_tokens = \"required\" } to aws_instance resources.",
+    "CKV_AWS_145": "Configure aws_s3_bucket_server_side_encryption_configuration with aws:kms only when a real KMS key exists; otherwise require approval.",
+    "CKV2_AWS_6": "Add aws_s3_bucket_public_access_block with all four block/restrict flags set to true.",
+    "CKV2_AWS_61": "Add aws_s3_bucket_lifecycle_configuration only when a retention policy is known; otherwise require approval.",
+    "CKV2_AWS_64": "Set enable_key_rotation = true on aws_kms_key resources.",
+    "CKV_K8S_8": "Add securityContext.runAsNonRoot: true and avoid UID 0.",
+    "CKV_K8S_9": "Set securityContext.allowPrivilegeEscalation: false on every container.",
+    "CKV_K8S_10": "Add resources.requests.cpu to each container.",
+    "CKV_K8S_11": "Add resources.limits.cpu to each container.",
+    "CKV_K8S_12": "Add resources.requests.memory to each container.",
+    "CKV_K8S_13": "Add resources.limits.memory to each container.",
+    "CKV_K8S_14": "Replace latest or mutable image tags with immutable versions if a real version is known.",
+    "CKV_K8S_20": "Set privileged: false in each container securityContext.",
+    "CKV_K8S_22": "Set readOnlyRootFilesystem: true only when the workload does not require writes, otherwise require approval.",
+    "CKV_K8S_29": "Set allowPrivilegeEscalation: false on each container securityContext.",
+    "CKV_K8S_31": "Set seccompProfile.type: RuntimeDefault at pod or container securityContext.",
+    "CKV_K8S_38": "Set runAsNonRoot: true at pod or container securityContext.",
+    "CKV_K8S_40": "Set runAsUser to a non-zero UID only when compatible with the image; otherwise require approval.",
+    "CKV_TF_1": "Pin module source references to tags or commits. Do not invent a version if none is known.",
+    "CKV_TF_2": "Add required_providers version constraints compatible with the configuration.",
+}
+
+
+def enrich_findings(bundle: ScanBundle) -> EnrichedFindings:
+    findings = []
+    for finding in bundle.findings:
+        findings.append(
+            EnrichedFinding(
+                **finding.model_dump(),
+                policy_description=POLICY_DESCRIPTIONS.get(finding.rule_id, finding.message),
+                remediation_hint=REMEDIATION_HINTS.get(finding.rule_id),
+                cis_controls=[],
+                doc_snippets=[],
+            )
+        )
+    return EnrichedFindings(file=bundle.file, findings=findings)
+
+
+def build_rule_hints_md(rule_ids: list[str]) -> str:
+    lines: list[str] = []
+    for rule_id in sorted(set(rule_ids)):
+        description = POLICY_DESCRIPTIONS.get(rule_id, "Scanner policy finding.")
+        hint = REMEDIATION_HINTS.get(rule_id, "Use the scanner message and make the smallest safe in-file remediation.")
+        lines.append(f"- {rule_id}: {description} Fix: {hint}")
+    return "\n".join(lines)

iac_secfix_agents/safety.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import re
+from difflib import unified_diff
+
+from .schemas import IngestRequest, SafetyVerdict
+
+
+REQUEST_DENY_PATTERNS: dict[str, re.Pattern[str]] = {
+    "disable_security": re.compile(
+        r"\b(disable|remove|turn off)\b.*\b(encryption|logging|rbac|audit|tls|network policy|securitycontext)\b",
+        re.IGNORECASE,
+    ),
+    "make_public": re.compile(r"\b(make|set|allow)\b.*\b(public|0\.0\.0\.0/0|anonymous)\b", re.IGNORECASE),
+    "scanner_suppression": re.compile(r"\b(checkov:skip|nosec|tfsec:ignore|suppress)\b", re.IGNORECASE),
+}
+
+
+PATCH_DENY_PATTERNS: dict[str, re.Pattern[str]] = {
+    "scanner_suppression": re.compile(r"(checkov:skip|nosec|tfsec:ignore)", re.IGNORECASE),
+    "public_acl": re.compile(r'acl\s*=\s*"(public-read|public-read-write)"', re.IGNORECASE),
+    "open_ingress": re.compile(r"0\.0\.0\.0/0"),
+    "disable_encryption": re.compile(
+        r"(encrypt(ed|ion)?\s*=\s*false|storage_encrypted\s*=\s*false|kms_key_id\s*=\s*null)",
+        re.IGNORECASE,
+    ),
+    "privileged_container": re.compile(r"(privileged:\s*true|allowPrivilegeEscalation:\s*true|runAsUser:\s*0)", re.IGNORECASE),
+}
+
+
+class DeterministicSafetyAgent:
+    """Small deterministic safety gate around the LLM patcher."""
+
+    def check_request(self, request: IngestRequest) -> SafetyVerdict:
+        text = "\n".join([request.user_intent or "", request.file_content])
+        matches = [name for name, pattern in REQUEST_DENY_PATTERNS.items() if pattern.search(text)]
+        if matches:
+            return SafetyVerdict(
+                allowed=False,
+                reason="Request appears to weaken security posture.",
+                matched_rules=matches,
+            )
+        return SafetyVerdict(allowed=True)
+
+    def check_patch(self, original_file: str, fixed_file: str, patch_text: str = "") -> SafetyVerdict:
+        diff_text = patch_text or "\n".join(
+            unified_diff(original_file.splitlines(), fixed_file.splitlines(), lineterm="")
+        )
+        added_lines = "\n".join(
+            line[1:] for line in diff_text.splitlines() if line.startswith("+") and not line.startswith("+++")
+        )
+        text = "\n".join([added_lines, patch_text])
+        matches = [name for name, pattern in PATCH_DENY_PATTERNS.items() if pattern.search(text)]
+        if matches:
+            return SafetyVerdict(
+                allowed=False,
+                reason="Patch appears to introduce or preserve unsafe configuration.",
+                matched_rules=matches,
+            )
+        return SafetyVerdict(allowed=True)

iac_secfix_agents/scanners.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from difflib import unified_diff
+from pathlib import Path
+from typing import Any
+
+from .schemas import (
+    CheckovReport,
+    FileEnvelope,
+    Finding,
+    FixCandidate,
+    IaCType,
+    IngestRequest,
+    ScanBundle,
+    ValidationResult,
+)
+
+
+class ScannerUnavailable(RuntimeError):
+    """Raised when a required deterministic scanner is unavailable."""
+
+
+def detect_iac_type(file_name: str, content: str = "") -> IaCType:
+    lower = file_name.lower()
+    if lower.endswith(".tf"):
+        return "terraform"
+    if lower.endswith((".yaml", ".yml")):
+        return "kubernetes"
+    if lower == "dockerfile":
+        return "dockerfile"
+    if "apiVersion:" in content and "kind:" in content:
+        return "kubernetes"
+    return "terraform"
+
+
+def _summary_from_reports(reports: list[CheckovReport]) -> dict[str, Any]:
+    failed = 0
+    passed = 0
+    skipped = 0
+    for report in reports:
+        summary = report.summary or {}
+        failed += int(summary.get("failed", 0) or 0)
+        passed += int(summary.get("passed", 0) or 0)
+        skipped += int(summary.get("skipped", 0) or 0)
+    return {"failed": failed, "passed": passed, "skipped": skipped}
+
+
+def run_checkov(path: Path, timeout_s: int = 120) -> list[CheckovReport]:
+    """Run Checkov against a file or directory and normalize JSON output."""
+
+    cmd = [
+        "checkov",
+        "-f" if path.is_file() else "-d",
+        str(path),
+        "-o",
+        "json",
+        "--quiet",
+        "--compact",
+    ]
+    try:
+        proc = subprocess.run(
+            cmd,
+            text=True,
+            capture_output=True,
+            timeout=timeout_s,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise ScannerUnavailable("checkov is not installed or not on PATH") from exc
+
+    output = proc.stdout.strip()
+    if not output:
+        output = proc.stderr.strip()
+    if not output:
+        return []
+
+    try:
+        raw = json.loads(output)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"Checkov did not return JSON: {output[:500]}") from exc
+
+    if isinstance(raw, list):
+        return [CheckovReport.model_validate(item) for item in raw if isinstance(item, dict)]
+    if isinstance(raw, dict) and "results" in raw:
+        return [CheckovReport.model_validate(raw)]
+    if isinstance(raw, dict) and "check_type" in raw:
+        return [CheckovReport.model_validate(raw)]
+    return []
+
+
+def checkov_to_findings(reports: list[CheckovReport]) -> list[Finding]:
+    findings: list[Finding] = []
+    seen: set[tuple[str, str, int | None, int | None]] = set()
+
+    for report in reports:
+        for raw in report.failed_checks:
+            rule_id = str(raw.get("check_id") or "")
+            if not rule_id:
+                continue
+            line_range = raw.get("file_line_range") or []
+            line_start = line_range[0] if len(line_range) >= 1 else None
+            line_end = line_range[1] if len(line_range) >= 2 else line_start
+            resource = str(raw.get("resource") or "")
+            key = (rule_id, resource, line_start, line_end)
+            if key in seen:
+                continue
+            seen.add(key)
+            severity = str(raw.get("severity") or "UNKNOWN").upper()
+            if severity not in {"CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"}:
+                severity = "UNKNOWN"
+            findings.append(
+                Finding(
+                    rule_id=rule_id,
+                    severity=severity,  # type: ignore[arg-type]
+                    resource=resource,
+                    message=str(raw.get("check_name") or raw.get("message") or ""),
+                    file_path=str(raw.get("file_path") or ""),
+                    line_start=line_start,
+                    line_end=line_end,
+                    guideline=raw.get("guideline"),
+                )
+            )
+
+    return findings
+
+
+def yaml_parse_check(content: str) -> tuple[bool, str | None]:
+    try:
+        import yaml
+
+        list(yaml.safe_load_all(content))
+        return True, None
+    except Exception as exc:  # pragma: no cover - environment dependent
+        return False, str(exc)
+
+
+def hcl_parse_check(content: str) -> tuple[bool, str | None]:
+    try:
+        import hcl2
+
+        hcl2.loads(content)
+        return True, None
+    except Exception as exc:  # pragma: no cover - environment dependent
+        return False, str(exc)
+
+
+def parse_check(content: str, iac_type: IaCType) -> tuple[bool, str | None]:
+    if iac_type == "kubernetes":
+        return yaml_parse_check(content)
+    if iac_type == "terraform":
+        return hcl_parse_check(content)
+    return True, None
+
+
+def diff_stats(original: str, fixed: str) -> tuple[int, int, int, float]:
+    original_lines = original.splitlines()
+    fixed_lines = fixed.splitlines()
+    added = 0
+    removed = 0
+    for line in unified_diff(original_lines, fixed_lines, lineterm=""):
+        if line.startswith(("+++", "---", "@@")):
+            continue
+        if line.startswith("+"):
+            added += 1
+        elif line.startswith("-"):
+            removed += 1
+    denominator = max(len(original_lines), 1)
+    return added, removed, added + removed, (added + removed) / denominator
+
+
+def build_unified_patch(original: str, fixed: str, fromfile: str = "original", tofile: str = "fixed") -> str:
+    return "\n".join(
+        unified_diff(
+            original.splitlines(),
+            fixed.splitlines(),
+            fromfile=fromfile,
+            tofile=tofile,
+            lineterm="",
+        )
+    )
+
+
+def _write_temp_file(request: IngestRequest, directory: Path) -> Path:
+    iac_type = request.iac_type or detect_iac_type(request.file_name, request.file_content)
+    suffix = ".tf" if iac_type == "terraform" else ".yaml"
+    path = directory / f"input{suffix}"
+    path.write_text(request.file_content)
+    return path
+
+
+def unified_scan(request: IngestRequest, tmp_dir: Path | None = None) -> ScanBundle:
+    iac_type = request.iac_type or detect_iac_type(request.file_name, request.file_content)
+    envelope = FileEnvelope(
+        file_name=request.file_name,
+        file_content=request.file_content,
+        iac_type=iac_type,
+    )
+
+    if tmp_dir is None:
+        with tempfile.TemporaryDirectory(prefix="iac_secfix_scan_") as dirname:
+            path = _write_temp_file(request, Path(dirname))
+            reports = run_checkov(path)
+    else:
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        path = _write_temp_file(request, tmp_dir)
+        reports = run_checkov(path)
+
+    return ScanBundle(
+        file=envelope,
+        findings=checkov_to_findings(reports),
+        pre_summary=_summary_from_reports(reports),
+        scanner="checkov",
+    )
+
+
+def validate_candidate(
+    original_req: IngestRequest,
+    candidate: FixCandidate,
+    targeted: list[str],
+    tmp_dir: Path | None = None,
+    max_changed_lines_ratio: float = 0.35,
+) -> ValidationResult:
+    iac_type = original_req.iac_type or detect_iac_type(original_req.file_name, original_req.file_content)
+    parse_ok, parse_error = parse_check(candidate.fixed_file, iac_type)
+    _, _, _, ratio = diff_stats(original_req.file_content, candidate.fixed_file)
+
+    post_request = IngestRequest(
+        file_name=original_req.file_name,
+        file_content=candidate.fixed_file,
+        iac_type=iac_type,
+        user_intent=original_req.user_intent,
+    )
+    bundle = unified_scan(post_request, tmp_dir=tmp_dir)
+    post_ids = {finding.rule_id for finding in bundle.findings}
+    targeted_set = set(targeted)
+    unresolved = sorted(targeted_set & post_ids)
+    resolved = sorted(targeted_set - post_ids)
+    new_findings = [finding for finding in bundle.findings if finding.rule_id not in targeted_set]
+    new_ch = sum(finding.severity in {"CRITICAL", "HIGH"} for finding in new_findings)
+
+    if not parse_ok:
+        verdict = "retry"
+        reason = f"parse failure: {parse_error}"
+    elif new_ch >= 2:
+        verdict = "reject"
+        reason = "new_critical_high_count >= 2"
+    elif not unresolved and new_ch == 0 and ratio <= max_changed_lines_ratio:
+        verdict = "accept"
+        reason = None
+    else:
+        verdict = "retry"
+        reason = "unresolved targeted findings, new findings, or over-broad diff"
+
+    return ValidationResult(
+        parse_ok=parse_ok,
+        targeted_resolved=resolved,
+        targeted_unresolved=unresolved,
+        new_findings=new_findings,
+        new_critical_high_count=new_ch,
+        changed_lines_ratio=ratio,
+        post_summary=bundle.pre_summary,
+        verdict=verdict,  # type: ignore[arg-type]
+        retry_reason=reason,
+    )

iac_secfix_agents/schemas.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+IaCType = Literal["terraform", "kubernetes", "dockerfile"]
+Severity = Literal["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO", "UNKNOWN"]
+ValidationVerdict = Literal["accept", "retry", "reject"]
+ApprovalAction = Literal["approved", "refused", "rejected", "needs_human_review"]
+
+
+class CheckovCheck(BaseModel):
+    check_id: str = ""
+    bc_check_id: str | None = None
+    check_name: str = ""
+    check_result: dict[str, Any] = Field(default_factory=dict)
+    code_block: list[Any] = Field(default_factory=list)
+    file_path: str = ""
+    file_line_range: list[int] = Field(default_factory=list)
+    resource: str = ""
+    evaluations: dict[str, Any] | None = None
+    guideline: str | None = None
+    severity: str | None = None
+
+
+class CheckovReport(BaseModel):
+    check_type: str = ""
+    results: dict[str, Any] = Field(default_factory=dict)
+    summary: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def failed_checks(self) -> list[dict[str, Any]]:
+        checks = self.results.get("failed_checks", [])
+        return checks if isinstance(checks, list) else []
+
+
+class Finding(BaseModel):
+    rule_id: str
+    severity: Severity = "UNKNOWN"
+    resource: str = ""
+    message: str = ""
+    file_path: str = ""
+    line_start: int | None = None
+    line_end: int | None = None
+    guideline: str | None = None
+
+
+class FileEnvelope(BaseModel):
+    file_name: str
+    file_content: str
+    iac_type: IaCType
+
+
+class IngestRequest(BaseModel):
+    file_name: str
+    file_content: str
+    iac_type: IaCType | None = None
+    user_intent: str | None = None
+
+
+class ScanBundle(BaseModel):
+    file: FileEnvelope
+    findings: list[Finding] = Field(default_factory=list)
+    pre_summary: dict[str, Any] = Field(default_factory=dict)
+    scanner: str = "checkov"
+
+
+class EnrichedFinding(Finding):
+    policy_description: str = ""
+    cis_controls: list[str] = Field(default_factory=list)
+    doc_snippets: list[str] = Field(default_factory=list)
+    remediation_hint: str | None = None
+
+
+class EnrichedFindings(BaseModel):
+    file: FileEnvelope
+    findings: list[EnrichedFinding] = Field(default_factory=list)
+
+
+class FixCandidate(BaseModel):
+    patch: str = ""
+    fixed_file: str
+    resolved_policy_ids: list[str] = Field(default_factory=list)
+    explanation: str = ""
+    verification_commands: list[str] = Field(default_factory=list)
+    risk_notes: list[str] = Field(default_factory=list)
+    requires_human_approval: bool = True
+
+
+class ValidationResult(BaseModel):
+    parse_ok: bool
+    targeted_resolved: list[str] = Field(default_factory=list)
+    targeted_unresolved: list[str] = Field(default_factory=list)
+    new_findings: list[Finding] = Field(default_factory=list)
+    new_critical_high_count: int = 0
+    changed_lines_ratio: float = 1.0
+    pre_summary: dict[str, Any] = Field(default_factory=dict)
+    post_summary: dict[str, Any] = Field(default_factory=dict)
+    verdict: ValidationVerdict
+    retry_reason: str | None = None
+
+
+class SafetyVerdict(BaseModel):
+    allowed: bool
+    reason: str = ""
+    matched_rules: list[str] = Field(default_factory=list)
+
+
+class ComplianceReport(BaseModel):
+    cis_pass_rate_before: float = 0.0
+    cis_pass_rate_after: float = 0.0
+    network_exposure_reduction: float = 0.0
+    iam_privilege_reduction: float = 0.0
+    targeted_resolution_rate: float = 0.0
+    scanner_clean: bool = False
+
+
+class ApprovalDecision(BaseModel):
+    action: ApprovalAction
+    reason: str = ""
+    patch: FixCandidate | None = None
+    validation: ValidationResult | None = None
+    compliance: ComplianceReport | None = None
+    n_retries: int = 0
+
+
+class EvalRow(BaseModel):
+    id: str
+    pre_findings: list[str] = Field(default_factory=list)
+    post_findings: list[str] = Field(default_factory=list)
+    targeted: list[str] = Field(default_factory=list)
+    parse_ok: bool = False
+    new_critical_high: int = 0
+    changed_lines_ratio: float = 1.0
+    n_retries: int = 0
+    latency_s: float = 0.0
+    schema_valid: bool = False
+    unsafe_action: bool = False

iac_secfix_space/__init__.py

@@ -0,0 +1,3 @@
+from .ui import build_demo
+
+__all__ = ["build_demo"]

iac_secfix_space/demo_data.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+DEMO_DIR = Path(__file__).parent.parent / "demo_examples"
+
+DEMO_LABELS: dict[str, str] = {
+    "demo_sg_open.json": "Security Group: Open SSH Ingress (Terraform)",
+    "demo_s3_public.json": "S3 Bucket: Public Access Enabled (Terraform)",
+    "demo_iam_wild.json": "IAM: Wildcard Permissions (Terraform)",
+    "demo_rds_unencr.json": "RDS: Unencrypted Storage (Terraform)",
+    "demo_k8s_root.json": "Kubernetes: Container Running as Root",
+}
+
+
+def load_demos() -> dict[str, dict]:
+    result: dict[str, dict] = {}
+    for fname, label in DEMO_LABELS.items():
+        path = DEMO_DIR / fname
+        if path.exists():
+            result[label] = json.loads(path.read_text())
+    return result

iac_secfix_space/hf_inference.py

@@ -0,0 +1,52 @@
+"""Build a RuntimeConfig that routes to the fine-tuned LoRA via HF inference."""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+LORA_MODEL_ID = "selcuksntrk/iac-secfix-qwen35-9b-lora"
+HF_SERVERLESS_BASE = "https://api-inference.huggingface.co/models"
+
+
+def has_hf_config() -> bool:
+    return bool(
+        os.getenv("HF_TOKEN")
+        or os.getenv("IAC_SECFIX_HF_TOKEN")
+        or os.getenv("IAC_SECFIX_HF_ENDPOINT")
+    )
+
+
+def build_hf_runtime_config():
+    """Return RuntimeConfig for HF inference.
+
+    Priority:
+    1. IAC_SECFIX_HF_ENDPOINT — a dedicated HF Inference Endpoint (most reliable,
+       works even without merging the LoRA into the base model).
+    2. HF serverless via the OpenAI-compatible path — works if the model has been
+       set up for serverless inference on HF Hub.
+    """
+    from iac_secfix_agents.config import RuntimeConfig
+
+    token = os.getenv("HF_TOKEN") or os.getenv("IAC_SECFIX_HF_TOKEN", "")
+    endpoint = os.getenv("IAC_SECFIX_HF_ENDPOINT", "").rstrip("/")
+
+    if endpoint:
+        return RuntimeConfig(
+            base_url=endpoint,
+            api_key=token,
+            model=os.getenv("IAC_SECFIX_HF_MODEL", LORA_MODEL_ID),
+            temperature=0.0,
+            max_tokens=2048,
+        )
+
+    # Fall back to HF serverless (OpenAI-compatible chat completions path)
+    return RuntimeConfig(
+        base_url=f"{HF_SERVERLESS_BASE}/{LORA_MODEL_ID}/v1",
+        api_key=token,
+        model=LORA_MODEL_ID,
+        temperature=0.0,
+        max_tokens=2048,
+    )

iac_secfix_space/rendering.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+
+ACTION_STYLES: dict[str, str] = {
+    "approved": "background:#22c55e;color:white",
+    "needs_human_review": "background:#f97316;color:white",
+    "rejected": "background:#ef4444;color:white",
+    "refused": "background:#dc2626;color:white",
+}
+
+
+def action_badge(action: str) -> str:
+    style = ACTION_STYLES.get(action, "background:#6b7280;color:white")
+    label = action.upper().replace("_", " ")
+    return f"<span style='{style};padding:5px 14px;border-radius:5px;font-weight:bold;font-size:1.1em'>{label}</span>"
+
+
+def render_findings_md(rule_ids: list[str], summary: dict) -> str:
+    failed = summary.get("failed", len(rule_ids))
+    crit = summary.get("CRITICAL", 0)
+    high = summary.get("HIGH", 0)
+    med = summary.get("MEDIUM", 0)
+
+    lines = [f"**{failed} failed checks** (CRITICAL: {crit} | HIGH: {high} | MEDIUM: {med})"]
+    for rid in rule_ids:
+        lines.append(f"- `{rid}`")
+    return "\n".join(lines)
+
+
+def render_result(data: dict) -> tuple[str, str, str, str, str, str]:
+    decision = data.get("decision") or {}
+    action = decision.get("action", "unknown")
+    reason = decision.get("reason", "")
+
+    original = data.get("original_file", "")
+    patch_obj = decision.get("patch") or {}
+    fixed = patch_obj.get("fixed_file") or data.get("fixed_file", "")
+
+    pre_rules: list[str] = data.get("pre_rule_ids") or []
+    post_rules: list[str] = data.get("post_rule_ids") or []
+    pre_summary: dict = data.get("pre_summary") or {}
+    post_summary: dict = data.get("post_summary") or {}
+
+    validation = decision.get("validation") or data.get("validation") or {}
+    resolved: list[str] = validation.get("targeted_resolved") or []
+    unresolved: list[str] = validation.get("targeted_unresolved") or []
+    parse_ok: bool = validation.get("parse_ok", False)
+    changed_ratio: float = validation.get("changed_lines_ratio", 0.0)
+
+    explanation = patch_obj.get("explanation") or reason
+    risk_notes: list[str] = patch_obj.get("risk_notes") or []
+
+    status_html = (
+        f"<div style='margin:12px 0'>"
+        f"{action_badge(action)}"
+        f"<p style='margin-top:8px;color:#374151'>{reason}</p>"
+        f"</div>"
+    )
+
+    details_parts = [
+        "### Validation",
+        f"- Parse OK: {'Yes' if parse_ok else 'No'}",
+        f"- Changed lines: {changed_ratio:.0%}",
+        f"- Resolved: {', '.join(f'`{r}`' for r in resolved) if resolved else 'none'}",
+        f"- Unresolved: {', '.join(f'`{r}`' for r in unresolved) if unresolved else 'none'}",
+        "",
+        "### Explanation",
+        explanation,
+    ]
+    if risk_notes:
+        details_parts += ["", "### Risk Notes"] + [f"- {n}" for n in risk_notes]
+
+    return (
+        original,
+        fixed,
+        status_html,
+        render_findings_md(pre_rules, pre_summary),
+        render_findings_md(post_rules, post_summary),
+        "\n".join(details_parts),
+    )

iac_secfix_space/ui.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import gradio as gr
+
+from .demo_data import load_demos
+from .hf_inference import LORA_MODEL_ID, build_hf_runtime_config, has_hf_config
+from .rendering import render_result
+
+_N = 6  # number of output components
+
+
+def _empty() -> tuple:
+    return ("",) * _N
+
+
+def _demo_outputs(label: str | None, demos: dict) -> tuple:
+    if not label or label not in demos:
+        return _empty()
+    return render_result(demos[label])
+
+
+def _live_outputs(file_content: str, iac_type: str) -> tuple:
+    if not file_content.strip():
+        return _empty()
+    try:
+        from iac_secfix_agents import IngestRequest, RemediationOrchestrator
+
+        decision = RemediationOrchestrator().remediate(
+            IngestRequest(
+                file_name="live_input.tf" if iac_type == "terraform" else "live_input.yaml",
+                file_content=file_content,
+                iac_type=iac_type,  # type: ignore[arg-type]
+            )
+        )
+        val = decision.validation
+        data = {
+            "original_file": file_content,
+            "fixed_file": decision.patch.fixed_file if decision.patch else "",
+            "decision": decision.model_dump(mode="json"),
+            "pre_rule_ids": [],
+            "post_rule_ids": val.targeted_unresolved if val else [],
+            "pre_summary": val.pre_summary if val else {},
+            "post_summary": val.post_summary if val else {},
+        }
+        return render_result(data)
+    except Exception as exc:
+        return (
+            file_content, "",
+            f"<div style='color:red;padding:8px'><b>Error:</b> {exc}</div>",
+            "", "", "",
+        )
+
+
+def _lora_outputs(file_content: str, iac_type: str) -> tuple:
+    if not file_content.strip():
+        return _empty()
+    try:
+        from iac_secfix_agents import IngestRequest, OrchestratorSettings, RemediationOrchestrator
+
+        config = build_hf_runtime_config()
+        decision = RemediationOrchestrator(config=config).remediate(
+            IngestRequest(
+                file_name="lora_input.tf" if iac_type == "terraform" else "lora_input.yaml",
+                file_content=file_content,
+                iac_type=iac_type,  # type: ignore[arg-type]
+            )
+        )
+        val = decision.validation
+        data = {
+            "original_file": file_content,
+            "fixed_file": decision.patch.fixed_file if decision.patch else "",
+            "decision": decision.model_dump(mode="json"),
+            "pre_rule_ids": [],
+            "post_rule_ids": val.targeted_unresolved if val else [],
+            "pre_summary": val.pre_summary if val else {},
+            "post_summary": val.post_summary if val else {},
+        }
+        return render_result(data)
+    except Exception as exc:
+        return (
+            file_content, "",
+            f"<div style='color:red;padding:8px'><b>LoRA inference error:</b> {exc}</div>",
+            "", "", "",
+        )
+
+
+def _file_panels(label_orig: str, label_fixed: str, interactive_orig: bool = False) -> tuple:
+    orig = gr.Code(label=label_orig, language="yaml", interactive=interactive_orig, lines=22)
+    fixed = gr.Code(label=label_fixed, language="yaml", interactive=False, lines=22)
+    return orig, fixed
+
+
+def _result_panels() -> tuple:
+    status = gr.HTML()
+    with gr.Row():
+        before = gr.Markdown(label="Findings Before")
+        after = gr.Markdown(label="Findings After")
+    details = gr.Markdown()
+    return status, before, after, details
+
+
+def build_demo() -> gr.Blocks:
+    demos = load_demos()
+    choices = list(demos.keys())
+    has_live_vllm = bool(os.getenv("IAC_SECFIX_BASE_URL"))
+    has_lora = has_hf_config()
+
+    with gr.Blocks(title="IaC-SecFix", theme=gr.themes.Soft()) as app:
+        gr.Markdown(
+            f"""
+# IaC-SecFix
+**Scanner-verified multi-agent remediation for Terraform and Kubernetes**
+
+Multi-agent loop: **IngestAgent** → **PolicyContextAgent** → **PatchAgent** →
+**ValidationAgent** → **SafetyAgent** → **HumanApprovalGate**
+
+Fine-tuned LoRA: [`{LORA_MODEL_ID}`](https://huggingface.co/{LORA_MODEL_ID})
+| Base model: `Qwen/Qwen3.5-9B` | r=8, alpha=16
+| Built for the **AMD Developer Hackathon 2026**
+"""
+        )
+
+        with gr.Tabs():
+            # ── Tab 1: Demo Playback ──────────────────────────────────────
+            with gr.Tab("Demo Playback"):
+                gr.Markdown(
+                    "Precomputed results from the benchmark run — no GPU required. "
+                    "Select an example to see the full agent trace."
+                )
+                with gr.Row():
+                    demo_dd = gr.Dropdown(choices=choices, value=choices[0] if choices else None,
+                                          label="Example", scale=4)
+                    load_btn = gr.Button("Load", variant="primary", scale=1)
+
+                demo_status, demo_before, demo_after, demo_details = _result_panels()
+                with gr.Row():
+                    demo_orig, demo_fixed = _file_panels("Original File", "Fixed File")
+
+                demo_outs = [demo_orig, demo_fixed, demo_status, demo_before, demo_after, demo_details]
+                load_btn.click(fn=lambda l: _demo_outputs(l, demos), inputs=[demo_dd], outputs=demo_outs)
+                app.load(fn=lambda: _demo_outputs(choices[0] if choices else None, demos), outputs=demo_outs)
+
+            # ── Tab 2: Fine-tuned LoRA ────────────────────────────────────
+            if has_lora:
+                with gr.Tab("Fine-tuned LoRA"):
+                    gr.Markdown(
+                        f"Runs the full multi-agent loop using the fine-tuned LoRA adapter "
+                        f"[`{LORA_MODEL_ID}`](https://huggingface.co/{LORA_MODEL_ID}).\n\n"
+                        "**Space secrets required:** `HF_TOKEN` (serverless) "
+                        "or `IAC_SECFIX_HF_ENDPOINT` + `IAC_SECFIX_HF_TOKEN` (dedicated endpoint)."
+                    )
+                    with gr.Row():
+                        lora_code = gr.Code(label="Paste IaC file here", language="yaml",
+                                            interactive=True, lines=22)
+                        lora_type = gr.Dropdown(choices=["terraform", "kubernetes"],
+                                                value="terraform", label="IaC Type", scale=0)
+                    lora_btn = gr.Button("Run with Fine-tuned LoRA", variant="primary")
+                    lora_status, lora_before, lora_after, lora_details = _result_panels()
+                    with gr.Row():
+                        lora_orig, lora_fixed = _file_panels("Input File", "Fixed File")
+                    lora_btn.click(
+                        fn=_lora_outputs,
+                        inputs=[lora_code, lora_type],
+                        outputs=[lora_orig, lora_fixed, lora_status, lora_before, lora_after, lora_details],
+                    )
+
+            # ── Tab 3: Live vLLM endpoint (optional) ─────────────────────
+            if has_live_vllm:
+                with gr.Tab("Live vLLM Endpoint"):
+                    gr.Markdown(
+                        "Calls the OpenAI-compatible vLLM endpoint. "
+                        "Set `IAC_SECFIX_BASE_URL`, `IAC_SECFIX_API_KEY`, and `IAC_SECFIX_MODEL` in Space secrets."
+                    )
+                    with gr.Row():
+                        live_code = gr.Code(label="Paste IaC file here", language="yaml",
+                                            interactive=True, lines=22)
+                        live_type = gr.Dropdown(choices=["terraform", "kubernetes"],
+                                                value="terraform", label="IaC Type", scale=0)
+                    live_btn = gr.Button("Run Agent Loop", variant="primary")
+                    live_status, live_before, live_after, live_details = _result_panels()
+                    with gr.Row():
+                        live_orig, live_fixed = _file_panels("Input File", "Fixed File")
+                    live_btn.click(
+                        fn=_live_outputs,
+                        inputs=[live_code, live_type],
+                        outputs=[live_orig, live_fixed, live_status, live_before, live_after, live_details],
+                    )
+
+        gr.Markdown(
+            "---\n**IaC-SecFix** | AMD Developer Hackathon 2026 | "
+            "Benchmark B3 (zero-shot+RAG): 50 samples · 32.6% targeted resolution · 0% unsafe actions"
+        )
+
+    return app

requirements.txt

@@ -1,6 +1,7 @@
+gradio>=5.0.0
+openai>=1.40.0
 pydantic>=2.7
 pydantic-ai-slim[openai]>=1.91.0
-openai>=1.40.0
 checkov>=3.2.0
 python-hcl2>=4.3.0
 PyYAML>=6.0.1