Pr3 extractors ir

ctm-iac/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.coverage
+htmlcov/
+.pytest_cache/
+*.egg-info/
+dist/
+raw_graph.json
+canonical_ir.json

ctm-iac/README.md

@@ -0,0 +1,120 @@
+# ctm-iac — CloudFormation Threat Modeller
+
+Converts a CDK/CloudFormation template into a structured security threat model using a
+4-stage pipeline: **CFN → RawGraph → CanonicalIR → Views → ThreatModel**.
+
+For pipeline internals see [`ctm_iac/README.md`](ctm_iac/README.md).
+For stage-by-stage technical details see [`TECHNICAL_DETAILS.md`](TECHNICAL_DETAILS.md).
+
+---
+
+## Prerequisites
+
+- Python 3.11+
+- [`uv`](https://github.com/astral-sh/uv) (package manager)
+- An [OpenRouter](https://openrouter.ai) API key (for Stage 4 LLM threat generation)
+
+---
+
+## Setup
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Export your OpenRouter key
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+---
+
+## Running the pipeline
+
+### Full pipeline — CFN template → threat model
+
+```bash
+uv run python main.py \
+  --cfn cdk-dataset/simple-image-upload-download-website/cdk/cdk.out/SimpleImageWebAppStack-development.template.json \
+  --raw cdk-dataset/simple-image-upload-download-website/raw_graph.json \
+  --canonical cdk-dataset/simple-image-upload-download-website/canonical_ir.json \
+  --threats cdk-dataset/simple-image-upload-download-website/llm_threat_model.json
+```
+
+### Stages 1+2 only (no LLM call required)
+
+```bash
+uv run python main.py \
+  --cfn path/to/template.json \
+  --canonical canonical_ir.json
+```
+
+### Print CanonicalIR to stdout (default when no output flag is given)
+
+```bash
+uv run python main.py --cfn path/to/template.json
+```
+
+### Use a different LLM model
+
+```bash
+export OPENROUTER_MODEL=openai/gpt-4o
+uv run python main.py --cfn path/to/template.json --threats threats.json
+```
+
+---
+
+## CLI flags
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--cfn PATH` | Yes | Path to the CloudFormation JSON template (`cdk synth` output) |
+| `--raw PATH` | No | Save Stage 1 RawGraph JSON to this file |
+| `--canonical PATH` | No | Save Stage 2 CanonicalIR JSON to this file |
+| `--threats PATH` | No | Run LLM threat generation and save ThreatModel JSON here |
+
+All output flags are optional and independent. When none are given, the CanonicalIR is
+printed to stdout.
+
+---
+
+## Output files
+
+| File | Stage | Description |
+|------|-------|-------------|
+| `raw_graph.json` | 1 | All CFN resources as nodes, all Ref/GetAtt/DependsOn as edges |
+| `canonical_ir.json` | 2 | Architecture-level components with semantic edges (NETWORK_PATH, CAN_DO, PROTECTED_BY, …) |
+| `llm_threat_model.json` | 4 | JSON array of STRIDE threats in ground-truth format |
+
+---
+
+## Running all 6 sample apps
+
+```bash
+APPS=(
+  "automated-security-response:cdk/cdk.out/AutomatedSecurityResponseStack.template.json"
+  "aws-ai-chat-bot:cdk/cdk.out/AiChatbotStack-dev.template.json"
+  "code-execution-platform:cdk/cdk.out/CodeExecutionPlatformStack.template.json"
+  "containerized-microservices:cdk/cdk.out/ContainerizedMicroservicesStack.template.json"
+  "simple-image-upload-download-website:cdk/cdk.out/SimpleImageWebAppStack-development.template.json"
+  "support-ticketing-system:cdk/cdk.out/SupportTicketingStack-dev.template.json"
+)
+
+for entry in "${APPS[@]}"; do
+  APP="${entry%%:*}"
+  TMPL="${entry#*:}"
+  DIR="cdk-dataset/$APP"
+  uv run python main.py \
+    --cfn "$DIR/$TMPL" \
+    --raw "$DIR/raw_graph.json" \
+    --canonical "$DIR/canonical_ir.json" \
+    --threats "$DIR/llm_threat_model.json"
+done
+```
+
+---
+
+## Running tests
+
+```bash
+uv run pytest tests/ -v --cov=ctm_iac
+```