{"id":46478340,"url":"https://github.com/melonattacker/threat-thinker","last_synced_at":"2026-04-02T16:46:04.646Z","repository":{"id":324310841,"uuid":"1066486010","full_name":"melonattacker/threat-thinker","owner":"melonattacker","description":"AI-powered threat modeling that turns architecture diagrams into actionable risks","archived":false,"fork":false,"pushed_at":"2025-12-25T14:07:31.000Z","size":2862,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-27T01:33:52.166Z","etag":null,"topics":["architecture","diagrams","python","risk-analytics","security","security-tools","threat-analysis","threat-modelling"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/melonattacker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-29T14:49:06.000Z","updated_at":"2025-12-25T14:07:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/melonattacker/threat-thinker","commit_stats":null,"previous_names":["melonattacker/threat-thinker"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/melonattacker/threat-thinker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melonattacker%2Fthreat-thinker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melonattacker%2Fthreat-thinker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melonattacker%2Fthreat-thinker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melonattacker%2Fthreat-thinker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/melonattacker","download_url":"https://codeload.github.com/melonattacker/threat-thinker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melonattacker%2Fthreat-thinker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30165627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T04:43:31.446Z","status":"ssl_error","status_checked_at":"2026-03-06T04:40:30.133Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","diagrams","python","risk-analytics","security","security-tools","threat-analysis","threat-modelling"],"created_at":"2026-03-06T07:32:29.700Z","updated_at":"2026-04-02T16:46:04.505Z","avatar_url":"https://github.com/melonattacker.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Threat Thinker\nAI-powered threat modeling that turns architecture diagrams into actionable risks.\n\n**Public Demo**: [https://threat-thinker.melonattacker.com](https://threat-thinker.melonattacker.com/)\n\n\u003e [!IMPORTANT]\n\u003e This is a public demo environment. Please do not upload sensitive or confidential architecture diagrams.\n\u003e For sensitive use cases, use the local CLI or Web UI.\n\n\u003cimg width=\"360\" alt=\"threat-thinker-logo\" src=\"./docs/images/threat-thinker-logo.png\" /\u003e\n\n\n## What is Threat Thinker?\nThreat Thinker is an open-source tool that turns architecture diagrams into threat models automatically. It keeps models current with minimal manual work by pairing deterministic parsing with LLM reasoning.\n\nKey Features:\n- **Diagram coverage**: Ingests Mermaid, draw.io, Threat Dragon JSON, native Graph IR JSON, and images.\n- **Attribute inference**: Uses LLMs to enrich components, data flows, and trust boundaries.\n- **RAG boost**: Strengthens threat reasoning with local docs/KBs (e.g., OWASP/MITRE/internal).\n- **Threat Dragon**: Imports Threat Dragon diagrams and can export findings back in Threat Dragon format.\n- **Reports**: Exports Markdown, JSON, and HTML for reviews and automation.\n\n## Key Features\n### Diagram-to-threat reasoning\n- Drop in a diagram via CLI (`--diagram` or format-specific flags) or Web UI and get threats without manual modeling.\n- Supports Mermaid, draw.io, Threat Dragon JSON, native Graph IR JSON, and image-based diagrams.\n- Deterministic parsing plus LLM reasoning fills missing labels, trust boundaries, and protocols.\n- Outputs prioritized threats with short rationales and OWASP ASVS/CWE references for quick review.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg width=\"500\" alt=\"diagram-to-threats\" src=\"./docs/images/diagram-to-threats.png\" /\u003e \n    \u003cbr\u003e\n    \u003cem\u003eInput diagram and get prioritized threats automatically\u003c/em\u003e\n\u003c/p\u003e\n\n### Local RAG to boost accuracy\n- Build on-disk knowledge bases from PDFs/Markdown/HTML with `threat-thinker kb build` under `~/.threat-thinker/kb/\u003cname\u003e`.\n- Enable `--rag` in CLI or the “Use Knowledge Base” toggle in Web UI to ground LLM answers in security guidelines and your org's guidance.\n- Retrieval stays local; only the final prompts go to your chosen LLM provider.\n- Tune top-k per run and swap KBs per project to balance depth, speed, and relevance.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg width=\"500\" alt=\"knowledge-base\" src=\"./docs/images/knowledge-base.png\" /\u003e \n    \u003cbr\u003e\n    \u003cem\u003eBuild local knowledge bases and use them to strengthen threat reasoning\u003c/em\u003e\n\u003c/p\u003e\n\n### Threat Dragon round-trip\n- Import [Threat Dragon](https://owasp.org/www-project-threat-dragon/) v2 JSON with `--threat-dragon`, preserving layout and cell metadata.\n- Export a Threat Dragon-compatible JSON that embeds detected threats without regenerating positions.\n- Re-open the exported JSON in Threat Dragon to review or adjust cells with the added findings.\n- Markdown/JSON/HTML reports stay available alongside Threat Dragon output for broader sharing.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg width=\"500\" alt=\"threat-dragon-output\" src=\"./docs/images/threat-dragon.png\" /\u003e \n    \u003cbr\u003e\n    \u003cem\u003eImport and export Threat Dragon diagrams with embedded threat findings\u003c/em\u003e\n\u003c/p\u003e\n\n## Getting Started\n### Set Up API Keys\nThreat Thinker uses LLM for extracting diagrams from images, extracting components, data flows, and trust boundaries from architecture diagrams, and for inferring threats. Threat Thinker supports OpenAI, Anthropic Claude, AWS Bedrock (Claude v3+ models), and local Ollama APIs (for text-only flows).\n\nYou must set at least one of the following environment variables before use:\n\n```bash\n# For OpenAI API (e.g., gpt-4.1)\nexport OPENAI_API_KEY=...\n\n# For Claude API (e.g., claude-sonnet-4-5)\nexport ANTHROPIC_API_KEY=...\n\n# For Bedrock API (e.g., anthropic.claude-sonnet-4-5-20250929-v1:0)\n# Option 1: Use AWS Profile (recommended)\naws configure --profile my-profile\n# Then use --aws-profile my-profile in the command\n\n# Option 2: Use environment variables\nexport AWS_ACCESS_KEY_ID=...\nexport AWS_SECRET_ACCESS_KEY=...\nexport AWS_SESSION_TOKEN=...\n```\n\n### Local Ollama (no API key)\n- Start Ollama locally (default host `http://localhost:11434`) and pull a model (e.g., `ollama pull llama3.1`).\n- Run Threat Thinker with `--llm-api ollama --llm-model \u003cmodel\u003e [--ollama-host http://localhost:11434]` for Mermaid/Draw.io/Threat Dragon inputs.\n- Image extraction is not supported with the Ollama backend; use text-based diagram inputs instead.\n\n### Installation\n\nChoose one of the following methods:\n\n#### Using [pipx](https://pipx.pypa.io/) \n```bash\npipx install https://github.com/melonattacker/threat-thinker/releases/download/v0.6.1/threat_thinker-0.6.1-py3-none-any.whl\n```\n\n#### Using [uv](https://docs.astral.sh/uv/)\n```bash\nuv tool install https://github.com/melonattacker/threat-thinker/releases/download/v0.6.1/threat_thinker-0.6.1-py3-none-any.whl\n```\n\n#### Using pip\n```bash\npip install https://github.com/melonattacker/threat-thinker/releases/download/v0.6.1/threat_thinker-0.6.1-py3-none-any.whl\n\n# Or install latest from main\npip install git+https://github.com/melonattacker/threat-thinker.git\n```\n\n\u003e **Note**: If you see `externally-managed-environment` error,\n\u003e use `pipx` or `uv` instead, or create a virtual environment first.\n\n#### For development\n```bash\ngit clone https://github.com/melonattacker/threat-thinker.git\ncd threat-thinker\nuv sync --extra dev --frozen\n\n# Fallback if uv is unavailable\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .[dev]\n```\n\n#### Verify installation\n```bash\nthreat-thinker --help\n```\n### CLI Usage\nHere is an example of command using CLI mode.\n\n\n```bash\n# Think: Analyze a diagram\nthreat-thinker think \\\n    --diagram examples/web/system.mmd \\\n    --infer-hints \\\n    --topn 5 \\\n    --llm-api openai \\\n    --llm-model gpt-4.1 \\\n    --out-dir reports/\n\n# Diff: Compare two threat reports and analyze changes\nthreat-thinker diff \\\n    --after reports/new-report.json \\\n    --before reports/old-report.json \\\n    --llm-api openai \\\n    --llm-model gpt-4.1 \\\n    --out-dir reports/ \\\n    --lang en\n\n# Run threat analysis with local Ollama (text-only diagrams)\nthreat-thinker think \\\n    --mermaid examples/web/system.mmd \\\n    --llm-api ollama \\\n    --llm-model llama3.1 \\\n    --ollama-host http://localhost:11434 \\\n    --out-dir reports/\n\n# Serve: Launch API server\nthreat-thinker serve --config examples/demo-app/serve.example.yaml\n\n# Worker: Start background processor for queued jobs\nthreat-thinker worker --config examples/demo-app/serve.example.yaml\n```\n\n### Web UI\n\n```bash\n# Launch Web UI\nthreat-thinker webui\n```\n\nThen visit http://localhost:7860 to use Threat Thinker interactively.\n\n## Documentation\n- [docs/tutorials.md](./docs/tutorials.md) — Guided runs for web, AWS, and diff scenarios.\n- [docs/cli.md](./docs/cli.md) — Flag reference and examples for think/diff/kb commands.\n- [docs/design.md](./docs/design.md) — Architecture and processing flow across the five layers.\n- [docs/rag.md](./docs/rag.md) — Building and using local knowledge bases to strengthen threat reasoning.\n- [docs/reports.md](./docs/reports.md) - Report formats and contents for Markdown, JSON, HTML, Threat Dragon and diff outputs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelonattacker%2Fthreat-thinker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmelonattacker%2Fthreat-thinker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelonattacker%2Fthreat-thinker/lists"}