threatsmith 0.2.0__tar.gz

threatsmith-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: "Publish"
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install Python 3.12
+        run: uv python install 3.12
+      - name: Run tests
+        run: uv run pytest
+      - name: Build
+        run: uv build
+      - name: Publish
+        run: uv publish

threatsmith-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+.ruff_cache/
+
+.pytest_cache
+
+.cursor
+
+venv/
+.venv/
+.env

threatsmith-0.2.0/CLAUDE.md

@@ -0,0 +1,70 @@
+## Project Overview
+
+ThreatSmith is an AI-powered PASTA (Process for Attack Simulation and Threat Analysis) threat modeling engine. It wraps AI coding agents (Claude Code, Codex) to orchestrate a 7-stage threat modeling pipeline plus a report consolidation step, producing structured markdown deliverables.
+
+## Technical Stack
+
+- Python 3.12+, src layout with hatchling build backend
+- Typer for CLI, stdlib logging for all output
+- No runtime dependencies beyond typer — engines are invoked via subprocess
+
+## Development Commands
+
+```bash
+uv run pytest                # run all tests
+uv run ruff check --fix      # lint (auto-fix; never manually fix lint issues)
+uv run ruff format           # format (always use this, never manually reformat)
+```
+
+Always run `uv run ruff check --fix` and `uv run ruff format` to let the tools auto-fix issues. Do not run the check-only variants (`ruff check` without `--fix`, `ruff format --check`) and then manually apply fixes.
+
+## Architecture
+
+```
+CLI (main.py)
+  → detect_scanners(), generate_metadata()
+  → Orchestrator.run()
+      → for stage 1–8:
+          assemble_prompt(stage_number, prior_outputs, scanner_info, ...)
+            → selects stage module → builds typed context dataclass → calls build_prompt()
+          engine.execute(prompt, working_directory) → exit_code
+          validate output file exists → read into prior_outputs
+```
+
+### Key interfaces
+
+- **Engine** (`engines/base.py`): ABC with `execute(prompt: str, working_directory: str) -> int`. Engines are thin subprocess wrappers — prompt assembly is the orchestrator's job.
+- **`get_engine(name)`** (`engines/__init__.py`): Factory mapping `"claude-code"` / `"codex"` to engine classes.
+- **`assemble_prompt()`** (`prompts/assembler.py`): Maps stage number to the correct stage module, builds the typed context dataclass, calls `build_prompt()`. Returns a single prompt string.
+- **Stage prompt modules** (`prompts/stage_01_objectives.py` through `stage_08_report.py`): Each exports `STAGE_PROMPT` constant + `build_prompt(context, output_dir="threatmodel") -> str`.
+- **Context dataclasses** (`prompts/contexts.py`): One per stage (e.g. `ObjectivesContext`, `VulnerabilityContext`). Fields are `str | None = None`; `VulnerabilityContext` also has `scanners_available: list[str] | None`.
+- **Orchestrator** (`orchestrator.py`): Dataclass. `run()` iterates stages 1–8, accumulates deliverables in `_prior_outputs` dict keyed as `stage_01_output` through `stage_08_output`. Returns 0 on success, 1 on failure.
+
+### Dynamic injection
+
+- **OWASP references** (Stage 4): Web Top 10 always injected. API/LLM/Mobile Top 10 conditionally injected based on case-insensitive keyword matching against Stage 2 output. Constants in `prompts/owasp_references.py`.
+- **Scanner snippets** (Stage 5): Injected per available scanner from `prompts/scanner_snippets.py` `SCANNER_SNIPPETS` dict. `detect_scanners()` returns `{"available": [...], "unavailable": [...]}`.
+
+### Stage → file mapping
+
+Defined in `orchestrator._STAGE_FILES`:
+- `01-objectives.md` through `07-risk-and-impact-analysis.md` (PASTA stages)
+- `08-report.md` (consolidation, not a PASTA stage — no new analysis)
+
+## Codebase Patterns
+
+- **Prompt placeholders**: Use `.replace("{placeholder}", value)`, not `.format()` — prompt text contains curly braces that break `.format()`.
+- **Prior stage injection**: XML-delimited `<prior_stages><stage_NN_name>...</stage_NN_name></prior_stages>` via `{prior_stages_section}` placeholder. Each stage output is independently optional (only included when present).
+- **`or None` guards**: `context.field or None` treats both missing and empty-string values as absent. Used throughout `build_prompt()` and `assemble_prompt()`.
+- **Logging**: Modules use `logger = logging.getLogger(__name__)`. CLI configures via `configure_logging(verbose)` in `utils/logging.py`. DEBUG = verbose, INFO = operational progress, WARNING/ERROR = failures.
+- **scanner_info keys**: `detect_scanners()` returns `{"available": [...], "unavailable": [...]}`. The assembler maps `scanner_info["available"]` to `VulnerabilityContext.scanners_available`.
+- **metadata.json**: `generate_metadata()` accepts `engine_name` param but writes `"engine"` key. Returns a `Metadata` dataclass. `write_metadata(output_dir, metadata)` serializes to JSON.
+
+## Testing Patterns
+
+- Tests are in `tests/` at root level. Test files mirror source: `test_stage_04.py` tests `stage_04_threat_analysis.py`.
+- Do not write tests for string constants — test logic and behavior only.
+- **Mock engine in E2E tests**: Use a closure over `output_dir` in `execute_side_effect(prompt, working_directory)` to write stage files. Track call count with `{"n": 0}` dict.
+- **Patch location for CLI tests**: Patch `threatsmith.main.get_engine` (not `threatsmith.engines.get_engine`) since the CLI imports into its own namespace.
+- `detect_scanners()` and `generate_metadata()` are safe to use unpatched in tests — scanners uses `shutil.which()`, metadata falls back to `"unknown"` for git failures.
+- Test logging with `caplog.at_level(logging.DEBUG, logger="threatsmith.module_name")`.

threatsmith-0.2.0/LICENSE

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

threatsmith-0.2.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: threatsmith
+Version: 0.2.0
+Summary: AI-powered secure code review and threat analysis engine
+Project-URL: Homepage, https://github.com/yogur/threatsmith
+Project-URL: Repository, https://github.com/yogur/threatsmith
+Project-URL: Issues, https://github.com/yogur/threatsmith/issues
+Author: Abdul Rahman Al-Kibbe
+License-File: LICENSE
+Keywords: ai,code-review,owasp,pasta,security,threat-modeling
+Requires-Python: >=3.12
+Requires-Dist: structlog>=24.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+```
+ ████████╗ ██╗  ██╗ ██████╗  ███████╗  █████╗  ████████╗ ███████╗ ███╗   ███╗ ██╗ ████████╗ ██╗  ██╗
+ ╚══██╔══╝ ██║  ██║ ██╔══██╗ ██╔════╝ ██╔══██╗ ╚══██╔══╝ ██╔════╝ ████╗ ████║ ██║ ╚══██╔══╝ ██║  ██║
+    ██║    ███████║ ██████╔╝ █████╗   ███████║    ██║    ███████╗ ██╔████╔██║ ██║    ██║    ███████║
+    ██║    ██╔══██║ ██╔══██╗ ██╔══╝   ██╔══██║    ██║    ╚════██║ ██║╚██╔╝██║ ██║    ██║    ██╔══██║
+    ██║    ██║  ██║ ██║  ██║ ███████╗ ██║  ██║    ██║    ███████║ ██║ ╚═╝ ██║ ██║    ██║    ██║  ██║
+    ╚═╝    ╚═╝  ╚═╝ ╚═╝  ╚═╝ ╚══════╝ ╚═╝  ╚═╝    ╚═╝    ╚══════╝ ╚═╝     ╚═╝ ╚═╝    ╚═╝    ╚═╝  ╚═╝
+```
+
+# ThreatSmith 🔒🤖
+
+ThreatSmith is an AI-powered PASTA threat modeling engine that automates the entire PASTA pipeline. It runs each stage as a fresh AI coding agent session, assembles prompts with accumulated context from prior stages, auto-detects available security scanners, and validates that each stage produces its expected deliverable. The result is a complete, structured threat model generated directly from your codebase.
+
+**No API keys. No separate billing. No token budgets to manage.** If you have a `Claude Code` or `Codex` subscription, you already have everything you need. Point ThreatSmith at a repository and get a full threat model.
+
+### What is PASTA?
+
+[PASTA (Process for Attack Simulation and Threat Analysis)](https://handbook.gitlab.com/handbook/security/product-security/security-platforms-architecture/application-security/threat-modeling/#pasta-stages) is a 7-stage, risk-centric methodology that produces structured security artifacts: data flow diagrams, threat inventories, vulnerability assessments, attack trees, and prioritized remediation roadmaps. It is thorough, but the manual effort involved makes full adoption rare.
+
+## Use Cases
+
+- **Persist threat models in Git as context for AI-powered secure code review.** Commit the `threatmodel/` directory to your repository. When AI coding agents review PRs or audit code, they can reference the threat model for context on trust boundaries, known vulnerabilities, and attack surfaces.
+- **Give AI coding agents security context to write secure code.** With the threat model in the repo, agents writing new features can consult it to understand data sensitivity classifications, required security controls, and known attack vectors before producing code.
+- **Onboard security engineers to unfamiliar codebases.** The 7-stage output provides a structured, security-focused overview of architecture, data flows, threats, and vulnerabilities without manually reading the entire codebase.
+- **Triage and prioritize remediation.** Stage 7 produces a P0-P3 remediation roadmap ranked by risk reduction vs. implementation effort, giving engineering teams a ready-made security backlog.
+
+## How It Works
+
+```
+┌────────────────┐     ┌──────────────────────┐     ┌──────────────────┐
+│  CLI           │────>│  Orchestrator        │────>│  AI Coding Agent │
+│                │     │                      │     │                  │
+│  threatsmith   │     │  - Stage sequencing  │     │  Claude Code /   │
+│  /path/to/repo │     │  - Prompt assembly   │     │  Codex           │
+│  --engine      │     │  - Context passing   │     │                  │
+│                │     │  - Scanner detection │     │  - Code nav      │
+│                │     │  - Output validation │     │  - File I/O      │
+└────────────────┘     └──────────────────────┘     │  - Shell exec    │
+                                                    │  - Reasoning     │
+                                                    └──────────────────┘
+```
+
+ThreatSmith runs a sequential pipeline of 7 PASTA stages plus a report consolidation step. Each stage executes as a fresh agent session but receives all prior stage outputs as structured context. This mirrors how a security engineer works through PASTA: read the prior findings, then produce the next deliverable.
+
+Currently supports Claude Code (`--engine claude-code`) and Codex (`--engine codex`). Adding a new engine requires implementing a single method: `execute(prompt, working_directory) -> exit_code`.
+
+| Stage | Name | Output |
+|-------|------|--------|
+| 1 | Define Objectives | Business objectives, data sensitivity, compliance requirements |
+| 2 | Define Technical Scope | Technology stack, dependencies, supply chain, deployment |
+| 3 | Application Decomposition | Architecture, data flow diagrams (Mermaid), trust boundaries |
+| 4 | Threat Analysis | STRIDE analysis, attack scenarios, OWASP cross-referencing |
+| 5 | Vulnerability Analysis | Scanner results, CVSS scoring, CWE/CVE enumeration |
+| 6 | Attack Modeling | Attack trees (Mermaid), MITRE ATT&CK mapping, exploit paths |
+| 7 | Risk and Impact Analysis | Risk qualification, countermeasures, P0-P3 remediation roadmap |
+| | | |
+| 8 | Report Consolidation | Executive summary combining all stage outputs (not a PASTA stage) |
+
+### Context Accumulation
+
+Each stage builds on all prior stages. Stage N receives the outputs of stages 1 through N-1, injected as structured XML-delimited sections in the prompt. This accumulated context directs the agent's analysis, reducing blind codebase exploration and improving output quality.
+
+## Installation
+
+### Prerequisites
+
+- Python 3.12+
+- One of the supported AI coding agents installed and authenticated:
+  - `Claude Code` for the claude-code engine
+  - `Codex` for the codex engine
+
+### Install
+
+```bash
+# With pip
+pip install threatsmith
+
+# With uv
+uv tool install threatsmith
+
+# With pipx (no virtual environment needed)
+pipx install threatsmith
+
+# With uvx (no virtual environment needed)
+uvx install threatsmith
+```
+
+## Quick Start
+
+```bash
+threatsmith /path/to/your/repo
+```
+
+This runs the full 7-stage PASTA pipeline using Claude Code (the default engine) and writes all deliverables to `threatmodel/` inside the target repository.
+
+To use a different engine or provide objectives to guide the analysis:
+
+```bash
+threatsmith /path/to/your/repo \
+  --engine codex \
+  --business-objectives "Protect user PII, meet GDPR requirements" \
+  --security-objectives "Prevent data exfiltration" \
+  -v
+```
+
+## Scanner Integration
+
+ThreatSmith automatically detects security scanners on your system before running the pipeline. When a scanner is found, stage-specific instructions are injected into the Stage 5 (Vulnerability Analysis) prompt so the agent knows to run it and incorporate the results.
+
+| Scanner | Purpose | Detection |
+|---------|---------|-----------|
+| Semgrep | Static analysis patterns | `which semgrep` |
+| Trivy | Dependency CVE scanning | `which trivy` |
+| Gitleaks | Secret/credential detection | `which gitleaks` |
+
+Scanners that are not detected are omitted from the prompt entirely. Scanner availability is recorded in `metadata.json` for traceability.
+
+## Output Structure
+
+All deliverables are written to a `threatmodel/` directory (configurable via `--output-dir`) at the target repository root:
+
+```
+threatmodel/
+  metadata.json                    # Run metadata (engine, commit, scanners, timestamp)
+  01-objectives.md                 # Stage 1: Business objectives and data sensitivity
+  02-technical-scope.md            # Stage 2: Technology stack and dependencies
+  03-application-decomposition.md  # Stage 3: Architecture, DFDs, trust boundaries
+  04-threat-analysis.md            # Stage 4: Threat identification and attack scenarios
+  05-vulnerability-analysis.md     # Stage 5: Vulnerability findings and CVSS scoring
+  06-attack-modeling.md            # Stage 6: Attack trees and exploitation paths
+  07-risk-and-impact-analysis.md   # Stage 7: Risk qualification and remediation roadmap
+  08-report.md                     # Consolidated executive report
+```
+
+Individual stage files are preserved alongside the consolidated report. This supports selective consumption (a developer fixing an auth issue only needs stages 4-5), debuggability (re-examine a single stage's output), and granular review by security teams.
+
+## CLI Reference
+
+```
+threatsmith <path> [OPTIONS]
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `path` | positional | required | Path to the target repository |
+| `--engine` | string | `claude-code` | AI engine to use (`claude-code` or `codex`) |
+| `--business-objectives` | string | — | Business objectives to guide the analysis |
+| `--security-objectives` | string | — | Security objectives to guide the analysis |
+| `--output-dir` | string | `threatmodel/` | Output directory for deliverables (relative to target repo) |
+| `-v` / `--verbose` | flag | off | Enable verbose (debug-level) logging |
+
+## Roadmap
+
+- **Batch mode.** Process multiple repositories from a file list (`--repos repos.txt`) with configurable parallelism (`--parallel N`).
+- **Auto-PR creation.** Automatically commit the `threatmodel/` directory, push a branch, and open a pull request via `gh` CLI after analysis completes.
+- **Incremental updates.** Use `git diff` against the commit hash in `metadata.json` to selectively re-run only the stages affected by code changes.
+- **Stage re-run.** Re-run a specific stage (e.g., `--rerun-stage 5`) using existing prior stage outputs without re-running the entire pipeline.
+- **Resume from stage.** Resume a failed or interrupted pipeline run from the stage where it stopped.
+- **CI/CD integration.** GitHub Action and GitLab CI templates for automated threat modeling on pull requests.
+- **Threat model diff.** Compare two threat model runs and surface what changed between them.
+
+## License
+
+MIT License.

threatsmith-0.2.0/README.md

@@ -0,0 +1,164 @@
+```
+ ████████╗ ██╗  ██╗ ██████╗  ███████╗  █████╗  ████████╗ ███████╗ ███╗   ███╗ ██╗ ████████╗ ██╗  ██╗
+ ╚══██╔══╝ ██║  ██║ ██╔══██╗ ██╔════╝ ██╔══██╗ ╚══██╔══╝ ██╔════╝ ████╗ ████║ ██║ ╚══██╔══╝ ██║  ██║
+    ██║    ███████║ ██████╔╝ █████╗   ███████║    ██║    ███████╗ ██╔████╔██║ ██║    ██║    ███████║
+    ██║    ██╔══██║ ██╔══██╗ ██╔══╝   ██╔══██║    ██║    ╚════██║ ██║╚██╔╝██║ ██║    ██║    ██╔══██║
+    ██║    ██║  ██║ ██║  ██║ ███████╗ ██║  ██║    ██║    ███████║ ██║ ╚═╝ ██║ ██║    ██║    ██║  ██║
+    ╚═╝    ╚═╝  ╚═╝ ╚═╝  ╚═╝ ╚══════╝ ╚═╝  ╚═╝    ╚═╝    ╚══════╝ ╚═╝     ╚═╝ ╚═╝    ╚═╝    ╚═╝  ╚═╝
+```
+
+# ThreatSmith 🔒🤖
+
+ThreatSmith is an AI-powered PASTA threat modeling engine that automates the entire PASTA pipeline. It runs each stage as a fresh AI coding agent session, assembles prompts with accumulated context from prior stages, auto-detects available security scanners, and validates that each stage produces its expected deliverable. The result is a complete, structured threat model generated directly from your codebase.
+
+**No API keys. No separate billing. No token budgets to manage.** If you have a `Claude Code` or `Codex` subscription, you already have everything you need. Point ThreatSmith at a repository and get a full threat model.
+
+### What is PASTA?
+
+[PASTA (Process for Attack Simulation and Threat Analysis)](https://handbook.gitlab.com/handbook/security/product-security/security-platforms-architecture/application-security/threat-modeling/#pasta-stages) is a 7-stage, risk-centric methodology that produces structured security artifacts: data flow diagrams, threat inventories, vulnerability assessments, attack trees, and prioritized remediation roadmaps. It is thorough, but the manual effort involved makes full adoption rare.
+
+## Use Cases
+
+- **Persist threat models in Git as context for AI-powered secure code review.** Commit the `threatmodel/` directory to your repository. When AI coding agents review PRs or audit code, they can reference the threat model for context on trust boundaries, known vulnerabilities, and attack surfaces.
+- **Give AI coding agents security context to write secure code.** With the threat model in the repo, agents writing new features can consult it to understand data sensitivity classifications, required security controls, and known attack vectors before producing code.
+- **Onboard security engineers to unfamiliar codebases.** The 7-stage output provides a structured, security-focused overview of architecture, data flows, threats, and vulnerabilities without manually reading the entire codebase.
+- **Triage and prioritize remediation.** Stage 7 produces a P0-P3 remediation roadmap ranked by risk reduction vs. implementation effort, giving engineering teams a ready-made security backlog.
+
+## How It Works
+
+```
+┌────────────────┐     ┌──────────────────────┐     ┌──────────────────┐
+│  CLI           │────>│  Orchestrator        │────>│  AI Coding Agent │
+│                │     │                      │     │                  │
+│  threatsmith   │     │  - Stage sequencing  │     │  Claude Code /   │
+│  /path/to/repo │     │  - Prompt assembly   │     │  Codex           │
+│  --engine      │     │  - Context passing   │     │                  │
+│                │     │  - Scanner detection │     │  - Code nav      │
+│                │     │  - Output validation │     │  - File I/O      │
+└────────────────┘     └──────────────────────┘     │  - Shell exec    │
+                                                    │  - Reasoning     │
+                                                    └──────────────────┘
+```
+
+ThreatSmith runs a sequential pipeline of 7 PASTA stages plus a report consolidation step. Each stage executes as a fresh agent session but receives all prior stage outputs as structured context. This mirrors how a security engineer works through PASTA: read the prior findings, then produce the next deliverable.
+
+Currently supports Claude Code (`--engine claude-code`) and Codex (`--engine codex`). Adding a new engine requires implementing a single method: `execute(prompt, working_directory) -> exit_code`.
+
+| Stage | Name | Output |
+|-------|------|--------|
+| 1 | Define Objectives | Business objectives, data sensitivity, compliance requirements |
+| 2 | Define Technical Scope | Technology stack, dependencies, supply chain, deployment |
+| 3 | Application Decomposition | Architecture, data flow diagrams (Mermaid), trust boundaries |
+| 4 | Threat Analysis | STRIDE analysis, attack scenarios, OWASP cross-referencing |
+| 5 | Vulnerability Analysis | Scanner results, CVSS scoring, CWE/CVE enumeration |
+| 6 | Attack Modeling | Attack trees (Mermaid), MITRE ATT&CK mapping, exploit paths |
+| 7 | Risk and Impact Analysis | Risk qualification, countermeasures, P0-P3 remediation roadmap |
+| | | |
+| 8 | Report Consolidation | Executive summary combining all stage outputs (not a PASTA stage) |
+
+### Context Accumulation
+
+Each stage builds on all prior stages. Stage N receives the outputs of stages 1 through N-1, injected as structured XML-delimited sections in the prompt. This accumulated context directs the agent's analysis, reducing blind codebase exploration and improving output quality.
+
+## Installation
+
+### Prerequisites
+
+- Python 3.12+
+- One of the supported AI coding agents installed and authenticated:
+  - `Claude Code` for the claude-code engine
+  - `Codex` for the codex engine
+
+### Install
+
+```bash
+# With pip
+pip install threatsmith
+
+# With uv
+uv tool install threatsmith
+
+# With pipx (no virtual environment needed)
+pipx install threatsmith
+
+# With uvx (no virtual environment needed)
+uvx install threatsmith
+```
+
+## Quick Start
+
+```bash
+threatsmith /path/to/your/repo
+```
+
+This runs the full 7-stage PASTA pipeline using Claude Code (the default engine) and writes all deliverables to `threatmodel/` inside the target repository.
+
+To use a different engine or provide objectives to guide the analysis:
+
+```bash
+threatsmith /path/to/your/repo \
+  --engine codex \
+  --business-objectives "Protect user PII, meet GDPR requirements" \
+  --security-objectives "Prevent data exfiltration" \
+  -v
+```
+
+## Scanner Integration
+
+ThreatSmith automatically detects security scanners on your system before running the pipeline. When a scanner is found, stage-specific instructions are injected into the Stage 5 (Vulnerability Analysis) prompt so the agent knows to run it and incorporate the results.
+
+| Scanner | Purpose | Detection |
+|---------|---------|-----------|
+| Semgrep | Static analysis patterns | `which semgrep` |
+| Trivy | Dependency CVE scanning | `which trivy` |
+| Gitleaks | Secret/credential detection | `which gitleaks` |
+
+Scanners that are not detected are omitted from the prompt entirely. Scanner availability is recorded in `metadata.json` for traceability.
+
+## Output Structure
+
+All deliverables are written to a `threatmodel/` directory (configurable via `--output-dir`) at the target repository root:
+
+```
+threatmodel/
+  metadata.json                    # Run metadata (engine, commit, scanners, timestamp)
+  01-objectives.md                 # Stage 1: Business objectives and data sensitivity
+  02-technical-scope.md            # Stage 2: Technology stack and dependencies
+  03-application-decomposition.md  # Stage 3: Architecture, DFDs, trust boundaries
+  04-threat-analysis.md            # Stage 4: Threat identification and attack scenarios
+  05-vulnerability-analysis.md     # Stage 5: Vulnerability findings and CVSS scoring
+  06-attack-modeling.md            # Stage 6: Attack trees and exploitation paths
+  07-risk-and-impact-analysis.md   # Stage 7: Risk qualification and remediation roadmap
+  08-report.md                     # Consolidated executive report
+```
+
+Individual stage files are preserved alongside the consolidated report. This supports selective consumption (a developer fixing an auth issue only needs stages 4-5), debuggability (re-examine a single stage's output), and granular review by security teams.
+
+## CLI Reference
+
+```
+threatsmith <path> [OPTIONS]
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `path` | positional | required | Path to the target repository |
+| `--engine` | string | `claude-code` | AI engine to use (`claude-code` or `codex`) |
+| `--business-objectives` | string | — | Business objectives to guide the analysis |
+| `--security-objectives` | string | — | Security objectives to guide the analysis |
+| `--output-dir` | string | `threatmodel/` | Output directory for deliverables (relative to target repo) |
+| `-v` / `--verbose` | flag | off | Enable verbose (debug-level) logging |
+
+## Roadmap
+
+- **Batch mode.** Process multiple repositories from a file list (`--repos repos.txt`) with configurable parallelism (`--parallel N`).
+- **Auto-PR creation.** Automatically commit the `threatmodel/` directory, push a branch, and open a pull request via `gh` CLI after analysis completes.
+- **Incremental updates.** Use `git diff` against the commit hash in `metadata.json` to selectively re-run only the stages affected by code changes.
+- **Stage re-run.** Re-run a specific stage (e.g., `--rerun-stage 5`) using existing prior stage outputs without re-running the entire pipeline.
+- **Resume from stage.** Resume a failed or interrupted pipeline run from the stage where it stopped.
+- **CI/CD integration.** GitHub Action and GitLab CI templates for automated threat modeling on pull requests.
+- **Threat model diff.** Compare two threat model runs and surface what changed between them.
+
+## License
+
+MIT License.

threatsmith-0.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "threatsmith"
+version = "0.2.0"
+description = "AI-powered secure code review and threat analysis engine"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    {name = "Abdul Rahman Al-Kibbe"}
+]
+keywords = ["security", "code-review", "ai", "pasta", "owasp", "threat-modeling"]
+dependencies = [
+    "typer>=0.12",
+    "structlog>=24.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.15.2"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threatsmith"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+src = ["src"]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]
+
+[project.scripts]
+threatsmith = "threatsmith.main:app"
+
+[project.urls]
+Homepage = "https://github.com/yogur/threatsmith"
+Repository = "https://github.com/yogur/threatsmith"
+Issues = "https://github.com/yogur/threatsmith/issues"

threatsmith-0.2.0/src/threatsmith/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("threatsmith")

threatsmith-0.2.0/src/threatsmith/engines/__init__.py

@@ -0,0 +1,19 @@
+from threatsmith.engines.base import Engine
+from threatsmith.engines.claude_code import ClaudeCodeEngine
+from threatsmith.engines.codex import CodexEngine
+
+
+def get_engine(engine_name: str) -> Engine:
+    """Return the correct engine instance for the given engine name."""
+    engines = {
+        "claude-code": ClaudeCodeEngine,
+        "codex": CodexEngine,
+    }
+    if engine_name not in engines:
+        raise ValueError(
+            f"Unknown engine: {engine_name!r}. Choose from: {list(engines)}"
+        )
+    return engines[engine_name]()
+
+
+__all__ = ["Engine", "ClaudeCodeEngine", "CodexEngine", "get_engine"]

threatsmith-0.2.0/src/threatsmith/engines/base.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+
+class Engine(ABC):
+    @abstractmethod
+    def execute(
+        self,
+        prompt: str,
+        working_directory: str,
+        output_dir: str,
+    ) -> int:
+        """Execute the engine with the assembled prompt and return an exit code."""
+        ...

threatsmith-0.2.0/src/threatsmith/engines/claude_code.py

@@ -0,0 +1,37 @@
+import logging
+import subprocess
+
+from threatsmith.engines.base import Engine
+
+logger = logging.getLogger(__name__)
+
+
+class ClaudeCodeEngine(Engine):
+    def execute(
+        self,
+        prompt: str,
+        working_directory: str,
+        output_dir: str,
+    ) -> int:
+        """Invoke claude CLI in non-interactive prompt mode and return its exit code."""
+        safe_dir = output_dir.rstrip("/")
+        cmd = [
+            "claude",
+            "-p",
+            prompt,
+            "--allowedTools",
+            f"Write({safe_dir}/**)",
+            f"Edit({safe_dir}/**)",
+        ]
+        logger.debug("Running: claude -p <prompt> in %s", working_directory)
+        try:
+            result = subprocess.run(cmd, cwd=working_directory)
+            return result.returncode
+        except FileNotFoundError:
+            logger.error(
+                "Claude CLI not found. Ensure 'claude' is installed and in your PATH."
+            )
+            return 1
+        except Exception as e:
+            logger.error("Error executing claude: %s", str(e))
+            return 1

threatsmith-0.2.0/src/threatsmith/engines/codex.py

@@ -0,0 +1,29 @@
+import logging
+import subprocess
+
+from threatsmith.engines.base import Engine
+
+logger = logging.getLogger(__name__)
+
+
+class CodexEngine(Engine):
+    def execute(
+        self,
+        prompt: str,
+        working_directory: str,
+        output_dir: str,
+    ) -> int:
+        """Invoke codex CLI in non-interactive exec mode and return its exit code."""
+        cmd = ["codex", "exec", prompt]
+        logger.debug("Running: codex exec <prompt> in %s", working_directory)
+        try:
+            result = subprocess.run(cmd, cwd=working_directory)
+            return result.returncode
+        except FileNotFoundError:
+            logger.error(
+                "Codex CLI not found. Ensure 'codex' is installed and in your PATH."
+            )
+            return 1
+        except Exception as e:
+            logger.error("Error executing codex: %s", str(e))
+            return 1