{"id":"c2d71db9-bfe1-4772-a623-64a7c699c5ee","slug":"llm-threat-modeling-agents","kind":"mcp","name":"llm-threat-modeling-agents","summary":"Multi-agent LLM threat modeling framework using MAESTRO and OWASP COMPASS, with modular agents for security risk analysis, CVE mapping, and remediation recommendations.","owner":"emmanuelgjr","repoUrl":"https://github.com/emmanuelgjr/llm-threat-modeling-agents","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-05-20T02:21:59.000Z","addedAt":"2026-10-21T15:13:56.416Z","logoUrl":"https://avatars.githubusercontent.com/u/129134995?u=e7a7106f4605f448ebdd3844451dc81acbd5586e&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T04:08:18.195Z","sample":false,"url":"https://conduits.dev/tools/llm-threat-modeling-agents","language":"Python","transports":["stdio"],"install":{"pypi":"llm-threat-modeling-agents"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"![MIT License](https://img.shields.io/badge/license-MIT-green.svg)\n![Python](https://img.shields.io/badge/python-3.9%2B-blue)\n[![Open Issues](https://img.shields.io/github/issues/emmanuelgjr/llm-threat-modeling-agents.svg)](https://github.com/emmanuelgjr/llm-threat-modeling-agents/issues)\n\n# LLM Threat Modeling Agents\n\n> Multi-agent threat modeling framework for LLM / GenAI systems, grounded in the **MAESTRO** layered framework and the **OWASP COMPASS** GenAI threat taxonomy. Produces scored risks, CWE mappings and remediation recommendations from a plain-English scenario description.\n\n## What it does\n\nGiven a JSON scenario like:\n\n```json\n{\n  \"name\": \"Customer Service GenAI Bot\",\n  \"description\": \"A customer support chatbot that can access sensitive customer data via tool calls.\",\n  \"environment\": \"SaaS, Cloud\"\n}\n```\n\nThe pipeline runs five cooperating agents:\n\n| # | Agent | Responsibility |\n|---|-------|----------------|\n| 1 | `MaestroAgent` | Maps the scenario onto the seven MAESTRO layers (Memory, Agent, Environment, System, Tools, Resources, Objectives) using keyword indicators. |\n| 2 | `CompassAgent` | Identifies which of the 16 OWASP COMPASS threats apply, with a per-threat likelihood. |\n| 3 | `RiskAnalyzer` | Scores each threat as `likelihood × impact` (1-25) and assigns a Low/Medium/High/Critical severity, boosted for regulated environments (healthcare, banking, SOC, legal). |\n| 4 | `CVEAgent` | Attaches the CWE weakness IDs declared per threat. Pluggable `lookup_cves` hook for live NVD integration. |\n| 5 | `RecommendationAgent` | Emits the canonical mitigation for each threat, tagged with severity and CWEs. |\n\nResults are written to `output/results.json` and rendered as colour-coded tables plus a run summary (severity breakdown and top threats).\n\n## Quickstart\n\n```bash\ngit clone https://github.com/emmanuelgjr/llm-threat-modeling-agents.git\ncd llm-threat-modeling-agents\npython -m venv venv\n# Windows\n.\\venv\\Scripts\\activate\n# macOS / Linux\nsource venv/bin/activate\n\n# Install as a package (preferred)\npip install -e .                # core\npip install -e \".[llm]\"         # + Anthropic SDK for LLM-backed agents\npip install -e \".[dev]\"         # + pytest\n\n# Run via the installed console script...\nthreat-model\n# ...or directly\npython main.py\n```\n\n### CLI options\n\n```bash\npython main.py --input data/sample_inputs.json \\\n               --output output/results.json \\\n               --markdown output/report.md \\\n               --html output/report.html \\\n               --log-level INFO\npython main.py --quiet                  # only print the run summary\npython main.py --fail-on critical       # CI gate: exit 2 if any Critical risk\npython main.py --fail-on high           # CI gate: exit 2 on High or Critical\npython main.py --nvd                    # enrich CWEs with live CVEs from NVD (cached)\npython main.py --sarif output/results.sarif    # SARIF 2.1.0 for GitHub code scanning\npython main.py --diff output/baseline.json     # compare against a previous run\npython main.py --diff baseline.json --fail-on-diff   # exit 3 on new risks / regressions\npython main.py --llm                                 # use Claude for MAESTRO + COMPASS analysis\npython main.py --llm --llm-model claude-opus-4-6     # override the model\npython main.py --plugins data/plugins                # load custom threats/layers\npython main.py --history output/history.jsonl --history-label \"$(git rev-parse --short HEAD)\"\npython main.py --csv output/risks.csv                # flat risk register\npython main.py --pdf output/report.pdf               # requires the [pdf] extra\npython main.py --cache                               # skip pipeline if input unchanged\npython main.py --webhook https://hooks.slack.com/... --webhook-on Critical\nthreat-model --init my-project                       # scaffold a fresh project\n```\n\n### Project layout & subcommands\n\n- **`threat-model --init DIR`** scaffolds a new project (`data/sample_inputs.json`, `data/plugins/example.json`, `threat-model.toml`).\n- **`threat-model.toml`** can pin defaults so CI invocations stay short:\n  ```toml\n  [defaults]\n  input = \"data/sample_inputs.json\"\n  output = \"output/results.json\"\n  markdown = \"output/report.md\"\n  html = \"output/report.html\"\n  sarif = \"output/results.sarif\"\n  history = \"output/history.jsonl\"\n  plugins = [\"data/plugins\"]\n  fail_on = \"high\"\n  ```\n- **`--cache`** hashes the input + plugin files and reuses the previous run when nothing has changed (cache lives in `.cache/runs/`).\n\n### Extra outputs\n\n- `--csv PATH` writes a flat risk register (one row per `(scenario, threat)`) — drop straight into a spreadsheet.\n- `--pdf PATH` writes a PDF rendered from the HTML report. Requires the optional extra: `pip install -e \".[pdf]\"`.\n- `--webhook URL [--webhook-on Critical|High|Medium|Low]` posts a JSON summary to a Slack-compatible webhook when the threshold is met.\n\n### Custom scoring plugins\n\nIn addition to threats and layers, plugin files may declare environment-based likelihood boosts that feed `RiskAnalyzer`:\n\n```json\n{\n  \"scoring\": {\n    \"environment_boost\": {\n      \"iot\": 1,\n      \"industrial\": 2,\n      \"production\": 1\n    }\n  }\n}\n```\n\nBoosts are merged with the built-in defaults (healthcare/banking/SOC/legal) and applied to any scenario whose `environment` string matches the key.\n\n### Web UI\n\nA tiny FastAPI app lets you upload a scenarios JSON and view the rendered HTML report in a browser:\n\n```bash\npip install -e \".[web]\"\nuvicorn web.app:app --reload\n```\n\n### MCP server\n\nThe pipeline is exposed as Model Context Protocol tools so other LLM agents (Claude Desktop, Claude Code, custom MCP clients) can call it directly:\n\n```bash\npip install -e \".[mcp]\"\nthreat-model-mcp        # stdio transport\n```\n\nTools: `analyze_scenario` (single scenario) and `analyze_scenarios` (batch).\n\n### Trend tracking\n\nPass `--history PATH` (typically `output/history.jsonl`) and the run summary — scenarios, total risks, average and max score, severity counts and per-scenario max — is appended as one JSON line. The file is append-only and safe to commit; CI runs can attach a `--history-label` (commit SHA, branch, build number).\n\nWhen both `--history` and `--html` are set, the HTML report embeds an inline-SVG line chart of average and max risk score across every recorded run, so you can see your threat posture trend at a glance.\n\n### Mermaid diagrams in Markdown\n\nEach scenario in the Markdown report now includes a `mermaid` flowchart of `Scenario → MAESTRO Layer → Threat`, with threat nodes colour-coded by severity. GitHub renders these natively, so the diagrams appear inline in any rendered Markdown report.\n\n### Custom threats and layers (plugins)\n\nDrop a JSON file in any directory and pass it (or its parent) to `--plugins`. Plugins can extend the MAESTRO layer set, add COMPASS threats, or both — the new entries flow through risk scoring, CVE mapping, recommendations, reports, SARIF and diff with no code changes. See `data/plugins/example_network_layer.json` for the format. Pass `--plugins` multiple times to layer them.\n\n### NVD API key & concurrency\n\nSet `NVD_API_KEY` to lift the public NVD rate limit (5 → 50 req / 30s) and unlock concurrent CWE fetching:\n\n```bash\nexport NVD_API_KEY=your-key\nthreat-model --nvd\n```\n\nWithout a key the client falls back to single-threaded polite mode. Responses are cached in `.cache/nvd/` either way.\n\n### HTML charts\n\nThe HTML report now includes inline-SVG charts (no JS dependencies) for the run-wide severity breakdown and per-scenario risk scores, in addition to the existing tables and traceability matrix.\n\n### LLM-backed analysis (optional)\n\nInstall the optional extra and set your API key:\n\n```bash\npip install -e \".[llm]\"\nexport ANTHROPIC_API_KEY=sk-ant-...\nthreat-model --llm\n```\n\nWhen `--llm` is set the pipeline calls Claude (default `claude-sonnet-4-6`) to map each scenario onto MAESTRO layers and COMPASS threats. The output schema is identical to the keyword agents, so risk scoring, CVE mapping, recommendations and reports work unchanged. If the `anthropic` package isn't installed, `ANTHROPIC_API_KEY` is missing, or the API call fails, the agents **transparently fall back** to the keyword analysis — `--llm` is always safe to pass in CI.\n\n### SARIF export & GitHub code scanning\n\n`--sarif PATH` writes a SARIF 2.1.0 file. The bundled CI workflow uploads it via `github/codeql-action/upload-sarif`, so every threat appears in your repository's **Security → Code scanning** tab. Each COMPASS threat is registered as a SARIF rule with its CWEs, MAESTRO layers and canonical mitigation; severities map to `error` (Critical/High), `warning` (Medium) and `note` (Low).\n\n### Diff mode (CI regression gate)\n\n`--diff PATH` compares the current run against a saved baseline `results.json`. The output lists:\n\n- **New risks** introduced since the baseline\n- **Resolved risks** (present in baseline, gone now)\n- **Severity changes** (worse / better) per risk\n\nCombine with `--fail-on-diff` to exit `3` whenever a CI run introduces new risks or worsens existing ones — perfect for blocking PRs that regress your threat posture.\n\n### Live CVE enrichment (NVD)\n\nPass `--nvd` to query the public [NVD 2.0 API](https://nvd.nist.gov/developers/vulnerabilities) for real CVEs that match each threat's CWE list. Responses are cached under `.cache/nvd/` so re-runs are instant. Rate limiting is built in; for heavy use you may want to add an NVD API key.\n\n### Input validation\n\nScenario files are validated before the pipeline runs (`utils/schema.py`). Missing fields, wrong types, empty `scenarios` arrays and duplicate scenario names produce a clear error and exit code `1` — no half-completed runs.\n\n### Traceability matrix\n\nEvery run prints (and writes into both reports) a **Threat → MAESTRO layers** traceability matrix that aggregates risks across all analysed scenarios: which threats hit which layers, in how many scenarios, with the maximum observed score and severity.\n\n### Reports\n\n- `--markdown PATH` writes a share-ready Markdown report (run summary, per-scenario risks and recommendations).\n- `--html PATH` writes a standalone HTML report with severity badges.\n- The terminal summary now ranks scenarios by their **max risk score** so you can see the riskiest systems at a glance.\n\n### Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). The repo ships with a `.pre-commit-config.yaml` (ruff + ruff-format + standard hygiene hooks); install with `pip install -e \".[dev]\"` and `pre-commit install`.\n\n### Continuous integration\n\nA GitHub Actions workflow (`.github/workflows/ci.yml`) runs `pytest` on Python 3.9–3.12 and smoke-runs the pipeline, uploading the generated JSON / Markdown / HTML reports as build artifacts.\n\n## Project layout\n\n```\nllm-threat-modeling-agents/\n├── main.py                 # CLI entry point + pipeline orchestrator\n├── agents/\n│   ├── maestro_agent.py    # MAESTRO layer mapping\n│   ├── compass_agent.py    # COMPASS threat assessment\n│   ├── risk_analyzer.py    # likelihood × impact scoring\n│   ├── cve_agent.py        # CWE / CVE mapping\n│   └── recommendation_agent.py\n├── utils/\n│   ├── maestro_layers.py   # layer metadata + indicators\n│   ├── compass_threats.py  # threat metadata, CWEs, mitigations\n│   └── output.py           # JSON + colour table rendering, summary\n├── data/sample_inputs.json # 10 example scenarios\n├── tests/test_pipeline.py  # pytest smoke + unit tests\n└── output/results.json     # latest run results\n```\n\n## Extending\n\n- **Add a scenario** — append an entry to `data/sample_inputs.json` (or pass `--input` to your own file).\n- **Add a threat** — add an entry to `COMPASS_THREATS` in `utils/compass_threats.py`. The new threat will automatically flow through risk scoring, CWE mapping and recommendations.\n- **Plug a real CVE feed** — subclass `CVEAgent` and override `lookup_cves(threat, cwes)` to call NVD or your internal vulnerability database.\n- **Swap to LLM-driven analysis** — replace the keyword matching in `MaestroAgent` / `CompassAgent` with calls to an LLM SDK. The downstream pipeline only needs the same output schema.\n\n## Tests\n\n```bash\npytest -v\n```\n\nThe tests cover MAESTRO mapping, COMPASS detection, risk scoring bounds, CVE/recommendation alignment, and an end-to-end pipeline run.\n\n## Frameworks\n\n- **MAESTRO** — Multi-layer threat modelling for autonomous agents.\n- **OWASP COMPASS** — Comprehensive Pattern Library for GenAI Security.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n"}