tachi
Threat Modeling and Vulnerability Detection Harness for Claude Code.
AI-Reasoning Scanner — STRIDE + AI + MAESTRO.
Get started: Quick Start | Developer Guide (full walkthrough with worked examples)
OWASP Coverage
50/50 across five frameworks — every catalogued threat in each framework
has a tachi detection agent.
* Web/API combined slot: OWASP Web Top 10:2021 (A01–A10) + OWASP API
Security Top 10:2023 (API1–API10) — 20 items, 20/20.
Canonical matrix: docs/standards/OWASP_COVERAGE.md ·
Byte-deterministic Coverage Attestation: examples/*/sample-report/
What is tachi?
tachi is a threat modeling and AI-reasoning vulnerability detection harness for Claude Code. SAST catches syntax-level bugs; the harness reasons over your architecture description to catch logic-level ones — broken authentication flows, missing privilege boundaries, prompt injection paths, agent autonomy gaps, cross-layer attack chains.
It runs as a new scanning column alongside SAST / SCA / Secrets, with two views of one engine:
- Threat modeling view — structured artifacts:
threats.md, SARIF, narrative report, attack trees, MAESTRO classification.
- Vulnerability scanning view — per-finding logic-level risks surfaced from the architecture, scored, and mapped to OWASP / MITRE ATT&CK / ATLAS / NIST AI RMF / CWE.
One command (/tachi.threat-model) dispatches 14 specialized agents and produces a complete threat model. Five post-pipeline commands enrich the results: /tachi.risk-score for quantitative scoring, /tachi.compensating-controls for codebase control analysis, /tachi.infographic for visual risk diagrams, /tachi.security-report for a professional PDF assessment booklet, and /tachi.architecture for automated architecture description generation.
- 14 threat categories: 6 STRIDE + 5 LLM-specific + 3 Agentic
- OWASP coverage: 50/50 across five frameworks (LLM Top 10:2026, Agentic Top 10:2026, ML Top 10:2023, Mobile Top 10:2024, Web/API Top 10:2021/2023)
- MAESTRO layer mapping: CSA seven-layer taxonomy (L1-L7) for agentic AI threat classification
- 5 input formats: Mermaid, free-text, ASCII, PlantUML, C4
- 6 commands, 20+ artifacts: structured findings, SARIF, narrative report, attack trees, risk scores, compensating controls, 5 infographic templates, PDF security report
- Baseline delta tracking: Compare runs to track new, resolved, and unchanged findings over time
- Works with any stack: the harness analyzes architecture, not code
tachi is built with the Agentic Oriented Development Kit (AOD Kit), a governance framework for AI agent-assisted development.
If you’re new here, start with the Welcome thread for how the board is organized.
Prerequisites
tachi requires two external CLIs for full functionality. Both are required — typst compiles the PDF security report and @mermaid-js/mermaid-cli (mmdc) renders attack path diagrams. See ADR-022 for the rationale.
macOS:
brew install typst
npm install -g @mermaid-js/mermaid-cli
Linux (Debian/Ubuntu):
apt install typst # or: cargo install typst-cli / dnf install typst on Fedora
npm install -g @mermaid-js/mermaid-cli
WSL (use your distro’s package manager, same as Linux):
apt install typst
npm install -g @mermaid-js/mermaid-cli
/tachi.security-report aborts at preflight with a clear install command if either CLI is missing when attack-trees are present.
Quick Start
1. Clone tachi (one-time)
git clone https://github.com/davidmatousek/tachi.git ~/Projects/tachi
2. Add tachi to your project
From your project root:
~/Projects/tachi/scripts/install.sh
To install a specific version:
~/Projects/tachi/scripts/install.sh --version v4.48.1 # x-release-please-version
If tachi is cloned to a non-default location:
~/Projects/tachi/scripts/install.sh --source /path/to/tachi
By default, install.sh refuses to write into a symlinked destination. Pass --follow-symlinks to opt in:
~/Projects/tachi/scripts/install.sh --follow-symlinks
--follow-symlinks Install through symlinked destinations (for example a linked .claude/skills). Without it, install.sh stops before writing anything when a destination is a symlink. With it, install.sh follows links at or above each installed path, names every resolved destination, and only copies: it never deletes through a link. Even with it, install.sh refuses broken, looping or wrong-type links (a file where a folder is needed, or the reverse), links nested inside an installed folder, and destinations inside the tachi source clone.
Manual install (alternative)
Set TACHI to your tachi clone’s path (the default location is shown) and run this from your project root. It copies every path between the BEGIN MANIFEST and END MANIFEST markers of INSTALL_MANIFEST.md, and it is safe to re-run. The manual path does not check for symlinked destinations, so run it only into real directories.
TACHI=~/Projects/tachi
sed -n '/^<!-- BEGIN MANIFEST -->$/,/^<!-- END MANIFEST -->$/p' "$TACHI/INSTALL_MANIFEST.md" |
grep -v -e '^<!--' -e '^#' -e '^$' |
while IFS= read -r p; do
case "$p" in
*/) mkdir -p "$p" && cp -R "$TACHI/$p." "$p" ;;
*) mkdir -p "$(dirname "$p")" && cp "$TACHI/$p" "$p" ;;
esac
done
See INSTALL_MANIFEST.md for the full list of distributable files.
3. Restart Claude Code
After copying the files, restart Claude Code (close and reopen the VS Code window, or start a new CLI session) so it picks up the new agents and commands.
If you want infographic images (.jpg), set the GEMINI_API_KEY environment variable with a key from Google AI Studio. This is optional — all text-based outputs work without it.
4. Create your architecture file (or let Claude Code do it)
Create docs/security/architecture.md describing your system. You can write it yourself or ask Claude Code:
Investigate this repository's architecture -- source code, config files, infrastructure
definitions, READMEs -- and create docs/security/architecture.md as a Mermaid flowchart
with all major components, data flows, protocols, and trust boundaries.
tachi auto-detects the format. Mermaid, free-text, ASCII, PlantUML, and C4 are all supported.
5. Run your first threat model
/tachi.threat-model
That’s it. One command. tachi validates the setup, reads your architecture, dispatches 14 threat agents, and writes everything to a timestamped folder under docs/security/.
6. Review your results
| File |
Source |
What It Contains |
threats.md |
/tachi.threat-model |
Primary threat model – findings, coverage matrix, MAESTRO layers, risk summary |
threats.sarif |
/tachi.threat-model |
SARIF 2.1.0 for GitHub Code Scanning and CI/CD integration |
threat-report.md |
/tachi.threat-model |
Narrative report with executive summary and remediation roadmap |
attack-trees/ |
/tachi.threat-model |
One Mermaid attack tree per Critical/High finding |
risk-scores.md |
/tachi.risk-score |
Quantitative risk scores with CVSS, exploitability, scalability, reachability |
risk-scores.sarif |
/tachi.risk-score |
SARIF 2.1.0 with composite scores as security-severity per finding |
compensating-controls.md |
/tachi.compensating-controls |
Detected codebase controls, residual risk, missing control recommendations |
compensating-controls.sarif |
/tachi.compensating-controls |
SARIF 2.1.0 with residual risk as security-severity per finding |
threat-baseball-card.jpg |
/tachi.infographic |
Baseball Card risk dashboard (requires GEMINI_API_KEY) |
threat-system-architecture.jpg |
/tachi.infographic |
Annotated architecture diagram with finding legend |
threat-risk-funnel.jpg |
/tachi.infographic |
Risk distribution funnel by severity |
threat-maestro-stack.jpg |
/tachi.infographic |
MAESTRO layer stack visualization (agentic systems only) |
threat-maestro-heatmap.jpg |
/tachi.infographic |
MAESTRO layer x severity heat map (agentic systems only) |
security-report.pdf |
/tachi.security-report |
Professional PDF booklet with all artifacts assembled |
Start with threats.md Section 7 – Recommended Actions. Then run /tachi.risk-score for quantitative prioritization, /tachi.compensating-controls to detect existing defenses, /tachi.infographic for visual risk diagrams, and /tachi.security-report to assemble everything into a PDF booklet. Work through Critical findings first, then High.
Full Walkthrough: The Developer Guide covers the complete 5-step risk lifecycle with worked examples, advanced options, and CI/CD integration.
Command Options
/tachi.threat-model
Runs the 5-phase threat modeling pipeline: scope, determine threats, determine countermeasures, assess, and report. Produces threats.md, threats.sarif, threat-report.md, attack-trees/, and attack-chains.md (conditional, when cross-layer chains are detected). Findings include MAESTRO layer classification for agentic AI components. Phase 3.5 cross-layer correlation detects attack chains spanning multiple MAESTRO layers with chain-breaking control recommendations. Automatically detects baseline from previous runs for delta tracking.
# Default -- uses docs/security/architecture.md
/tachi.threat-model
# Specify architecture file
/tachi.threat-model path/to/my-architecture.md
# Custom output directory
/tachi.threat-model docs/security/architecture.md --output-dir reports/security/
# Version-tagged output for a release
/tachi.threat-model docs/security/architecture.md --version v1.0.0
# Explicit baseline for delta comparison
/tachi.threat-model docs/security/architecture.md --baseline docs/security/2026-03-01/threats.md
/tachi.risk-score
Enriches threat model output with four-dimensional quantitative risk scores (CVSS 3.1, exploitability, scalability, reachability) and governance fields (owner, SLA, disposition, review date). Produces risk-scores.md and risk-scores.sarif.
# Score threats in the default location
/tachi.risk-score
# Score threats in a specific directory
/tachi.risk-score docs/security/2026-03-27/
# Custom output directory
/tachi.risk-score docs/security/2026-03-27/ --output-dir reports/risk/
/tachi.compensating-controls
Scans a target codebase against scored threats to detect existing security controls, calculate residual risk, and recommend missing controls. Requires /tachi.risk-score output as input. Produces compensating-controls.md and compensating-controls.sarif.
# Scan current project against risk scores in the default location
/tachi.compensating-controls
# Scan against risk scores in a specific directory
/tachi.compensating-controls docs/security/2026-03-27/
# Scan a different codebase
/tachi.compensating-controls docs/security/2026-03-27/ --target ~/Projects/my-app/
# Custom output directory
/tachi.compensating-controls docs/security/2026-03-27/ --output-dir reports/controls/
/tachi.infographic
Generates visual threat infographic specifications and presentation-ready images. Auto-detects the richest data source in the output directory (prefers compensating-controls.md > risk-scores.md > threats.md). Produces spec markdown and .jpg images (images require GEMINI_API_KEY).
Templates: baseball-card, system-architecture, risk-funnel, maestro-stack, maestro-heatmap, all
# Generate all templates (auto-includes MAESTRO if data present)
/tachi.infographic
# Generate from a specific directory
/tachi.infographic docs/security/2026-03-27/
# Generate a specific template
/tachi.infographic docs/security/2026-03-27/ --template baseball-card
/tachi.infographic docs/security/2026-03-27/ --template risk-funnel
# Generate both MAESTRO templates
/tachi.infographic docs/security/2026-03-27/ --template maestro
/tachi.security-report
Assembles all pipeline artifacts into a professional multi-page PDF security assessment booklet. Auto-detects available artifacts and conditionally includes pages. Requires typst CLI for PDF compilation and mmdc (Mermaid CLI) for attack path and attack chain diagram rendering (hard prerequisite per ADR-022 when diagrams are present).
Page types (conditional, based on available artifacts):
Cover, Disclaimer, Table of Contents, Risk Methodology, Assessment Scope, Executive Summary, Attack Path Analysis, Attack Chain Diagrams, MAESTRO Findings, Infographic pages (full-bleed), Findings Detail, Control Coverage, Remediation Roadmap
# Generate PDF from the default location
/tachi.security-report
# Generate from a specific directory
/tachi.security-report docs/security/2026-03-27/
# Custom output path
/tachi.security-report docs/security/2026-03-27/ --output reports/assessment.pdf
How It Works
tachi uses a multi-agent orchestration pattern. The orchestrator parses your architecture, identifies components and data flows, then dispatches the right combination of 14 threat agents per component:
| Component Type |
STRIDE Agents |
AI Agents |
| External Entity (users, APIs) |
S, R |
– |
| Process (servers, agents) |
S, T, R, I, D, E |
LLM + AG if AI keywords detected |
| Data Store (databases, caches) |
T, I, D |
– |
| Data Flow (API calls, messages) |
T, I, D |
– |
AI agents activate when component names or descriptions contain keywords like “LLM”, “agent”, “orchestrator”, “MCP”, “tool server”, “embedding”, “RAG”, etc.
After all agents report, the orchestrator deduplicates findings, runs cross-agent correlation, computes risk ratings, and generates the output suite.
MAESTRO Layer Classification
For agentic AI systems, tachi maps each finding to the CSA MAESTRO seven-layer taxonomy:
| Layer |
Name |
Scope |
| L1 |
Foundation Model |
Pre-trained LLMs, inference engines |
| L2 |
Data Operations |
Vector stores, RAG pipelines, embeddings |
| L3 |
Agent Framework |
Orchestrators, tool servers, MCP |
| L4 |
Deployment Infrastructure |
API gateways, containers, networking |
| L5 |
Evaluation and Observability |
Audit logging, monitoring, anomaly detection, forensics |
| L6 |
Security and Compliance |
Auth, guardrails, rate limiting, encryption, IAM |
| L7 |
Agent Ecosystem |
Multi-agent coordination, delegation, chat UIs, API endpoints |
MAESTRO layers appear in threats.md, propagate through all downstream commands, and power the maestro-stack and maestro-heatmap infographic templates.
Agentic Pattern Synthesis
For multi-agent architectures, tachi’s Phase 3.6 Pattern Synthesis Engine (per ADR-026) classifies findings into the six canonical CSA MAESTRO cross-cutting agentic patterns:
| Pattern |
Canonical Definition |
agent_collusion |
Multiple compromised agents coordinate to achieve malicious objectives |
emergent_behavior |
Unpredictable behaviors arising from multi-agent interactions (cascades, feedback amplification, drift) |
temporal_attack |
Persistent-state exploits: sleeper agents, gradual corruption, seasonal exploitation |
trust_exploitation |
Inter-agent identity spoofing, reputation manipulation, trust chain attacks |
communication_vulnerability |
Inter-agent message interception, protocol manipulation, routing attacks |
resource_competition |
Resource monopolization, priority manipulation, coordination disruption |
Each finding receives a new agentic_pattern enum field (schema 1.4) during Phase 3.6 — gated by the multi-agent predicate (≥2 agentic/LLM components, inter-agent data flow, or explicit multi-agent keywords in the architecture description). Pattern assignments appear in threats.md Section 7 (Pattern column), Section 4b (Findings by Agentic Pattern), threat-report.md Section 7 (Agentic Pattern Analysis narrative), and SARIF maestro-pattern:<name> tags mirroring the existing maestro-layer:<L#> convention. The deterministic classification rule table and the multi-agent gate predicate live in maestro-agentic-patterns-shared.md.
Previously-uncovered patterns (Agent Collusion, Temporal Attacks, Emergent Behavior) that are not captured by any individual detection agent surface via net-new findings with the AGP-NN id prefix, generated deterministically when the architecture satisfies a rule’s topology preconditions but no existing finding carries the pattern label.
Baseline Delta Tracking
When you run /tachi.threat-model on a system that already has a previous run, tachi automatically detects the baseline and computes a delta: new findings, resolved findings, unchanged findings, and updated findings. This lets you track risk posture changes over time without manual diffing.
Threat Categories
STRIDE (6 categories)
| Category |
Threat |
Example |
| Spoofing |
Identity impersonation |
Stolen API key used to make authenticated requests |
| Tampering |
Unauthorized data modification |
SQL injection modifying database records |
| Repudiation |
Missing accountability |
User denies triggering an expensive operation, no logs exist |
| Information Disclosure |
Data exposure |
Error messages leaking internal architecture details |
| Denial of Service |
Availability attacks |
Request flooding exhausting connection pools |
| Elevation of Privilege |
Unauthorized access |
Regular user accessing admin endpoints |
AI-Specific (8 categories)
| Category |
Threat |
Example |
| Prompt Injection (LLM) |
Adversarial inputs hijacking LLM behavior |
Hidden instructions in a document causing the LLM to leak its system prompt |
| Data Poisoning (LLM) |
Corrupted training/RAG data |
Attacker modifying knowledge base documents to spread misinformation |
| Model Theft (LLM) |
Model extraction or unbounded consumption |
Competitor reverse-engineering your fine-tuned model via API queries; cost-amplification denial-of-wallet |
| Output Integrity (LLM) |
Improper handling of LLM output flowing into execution sinks |
LLM-generated SQL passed to a database client without parameterization; markdown XSS in a rendered chat reply |
| Misinformation (LLM) |
Factually incorrect or fabricated LLM output reaching humans/decisions |
Clinical advisory LLM hallucinating drug dosages without RAG grounding |
| Agent Autonomy (AG) |
Insufficient oversight |
AI agent sending 500 emails without human approval |
| Tool Abuse (AG) |
Tool misuse or manipulation |
Malicious MCP plugin exfiltrating source code when invoked; insecure inter-agent communication |
| Human-Agent Trust Exploitation (AG) |
Communication-axis trust manipulation toward human users |
Wellness chatbot subtly claiming medical authority while concealing AI authorship |
OWASP Coverage
tachi ships at full coverage across five OWASP frameworks (50/50 items covered). Every finding can carry an optional source_attribution field citing OWASP / MITRE ATT&CK / MITRE ATLAS / NIST AI RMF / CWE items, and the tachi.security-report PDF emits a per-architecture Coverage Attestation page aggregating coverage across cited frameworks.
| Framework |
Items Covered |
Detection Surface |
| OWASP Top 10 for LLM Applications 2026 |
10/10 |
LLM agents (prompt-injection, data-poisoning, model-theft, output-integrity, misinformation) |
| OWASP Agentic Top 10 2026 |
10/10 |
Agentic agents (agent-autonomy, tool-abuse, human-trust-exploitation) |
| OWASP ML Top 10 2023 |
10/10 |
tampering + data-poisoning + model-theft enrichment for predictive ML |
| OWASP Mobile Top 10 2024 |
10/10 |
spoofing + tampering + info-disclosure + privilege-escalation + repudiation enrichment for mobile |
| OWASP Top 10:2021 + API Security Top 10:2023 |
10/10 |
STRIDE detection agents with cross-framework source_attribution populator wiring |
See schemas/taxonomy/ for the cross-framework crosswalk catalog (38 ATT&CK + 7 ATLAS + 41 CWE references currently cited, plus NIST AI RMF mappings).
Examples
The examples/ directory contains complete threat models across different input formats and architectures:
The agentic-app example includes a complete sample report showing every artifact the pipeline produces – structured findings, SARIF, narrative report, attack trees, cross-layer attack chains, risk scores, compensating controls, and infographics:
Integration Reference
| Resource |
Location |
Purpose |
| Interface Contract |
docs/INTERFACE-CONTRACT.md |
Input formats, invocation protocol, output structure |
| Output Templates |
templates/tachi/ |
Canonical output structures and Typst PDF templates |
| Schemas |
schemas/ |
Machine-readable contracts (finding.yaml, input.yaml, output.yaml, risk-scoring.yaml) |
| Taxonomy Crosswalk |
schemas/taxonomy/ |
Machine-readable catalog of OWASP/MITRE/NIST/CWE IDs + cross-framework crosswalk (Feature 180 F-A1) |
| Source Attribution |
docs/architecture/02_ADRs/ADR-028-source-attribution-schema-extension.md |
Optional source_attribution finding field (schema 1.5) citing F-A1 framework IDs — contract only (Feature 189 F-A2) |
| Threat Agents |
.claude/agents/tachi/ |
14 detection agents (6 STRIDE + 5 LLM + 3 Agentic) + 7 utility agents (orchestrator, attack-tree-delta, threat-report, threat-infographic, risk-scorer, control-analyzer, report-assembler) |
| Commands |
.claude/commands/ |
6 slash commands: tachi.threat-model, tachi.risk-score, tachi.compensating-controls, tachi.infographic, tachi.security-report, tachi.architecture |
| Developer Guide |
docs/guides/DEVELOPER_GUIDE_TACHI.md |
Full walkthrough with worked examples |
Known Issues
Finding count variance between runs
Successive threat model runs on the same architecture may produce slightly different finding counts (typically +/- 10%). This is expected behavior with LLM-based analysis.
What’s consistent: Core findings across all STRIDE and AI categories. The same high-severity threats will appear in every run.
What varies: Borderline findings in the long tail – a Medium-severity finding like “missing correlation ID on external API calls” may appear in one run but not the next, depending on how the agent reasons through the architecture.
Why this happens: Each of the 14 threat agents makes independent LLM calls. LLM output is non-deterministic by nature, so agents may surface slightly different findings on each invocation.
If you need higher consistency:
- Run twice and diff the results to catch edge cases
- Use a previous run’s
threats.md as a baseline for comparison
- Treat the threat model as a living document that improves with each run
Built with AOD Kit
tachi is built with the Agentic Oriented Development Kit (AOD Kit), a governance framework for AI agent-assisted development. AOD Kit provides the SDLC Triad methodology (PM + Architect + Team Lead sign-offs), quality gates, and structured workflows that govern how tachi itself is developed and maintained.
Releases
Releases are automated via release-please. When conventional commits (feat:, fix:, docs:, etc.) are merged to main, release-please creates a Release PR with auto-generated CHANGELOG entries and the next semantic version. Merging the Release PR creates the git tag and GitHub Release.
To install a specific version: install.sh --version v4.48.1
Running Tests
tachi uses pytest for Python script tests under tests/scripts/. To run the test suite:
pip install -r requirements-dev.txt
make test
This runs pytest tests/scripts/ --cov=scripts --cov-report=term-missing. Tests are required by Constitution Principle VI (Testing Excellence, ≥80% coverage).
Contributing
We welcome contributions. See CONTRIBUTING.md for guidelines.
License
Apache 2.0 License. See LICENSE for details.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
评论