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.

Community

• Questions, ideas, and feature requests → GitHub Discussions
• Reproducible bugs → GitHub Issues
• Security vulnerabilities → private advisory (do not post publicly)
• Full security policy → SECURITY.md (supported versions, response SLA, scope)
• Pre-commit secret-scanning → docs/standards/PRECOMMIT_HOOKS.md (gitleaks default-secure hook; existing adopters opt-in via pre-commit install; starter config: .gitleaks.toml.adopter-template, see PRECOMMIT_HOOKS.md §9.5)
• Real-world usage → In the Wild or the adopters index — tell me how you're using tachi, anonymized is fine

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.0 # x-release-please-version

If tachi is cloned to a non-default location:

~/Projects/tachi/scripts/install.sh --source /path/to/tachi

# Agents (threat analysis engine)
cp -r ~/Projects/tachi/.claude/agents/tachi/ .claude/agents/tachi/

# Commands (6 slash commands)
mkdir -p .claude/commands
for cmd in tachi.threat-model tachi.risk-score tachi.compensating-controls tachi.infographic tachi.security-report tachi.architecture; do
  cp ~/Projects/tachi/.claude/commands/$cmd.md .claude/commands/
done

# Schemas, templates, references, and brand assets
cp -r ~/Projects/tachi/schemas/ schemas/
cp -r ~/Projects/tachi/templates/ templates/
mkdir -p adapters/claude-code/agents
cp -r ~/Projects/tachi/adapters/claude-code/agents/references/ adapters/claude-code/agents/references/
cp -r ~/Projects/tachi/brand/ brand/

# Developer guide
mkdir -p docs/guides
cp ~/Projects/tachi/docs/guides/DEVELOPER_GUIDE_TACHI.md docs/guides/

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

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:

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:

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:

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)

AI-Specific (8 categories)

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.

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

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.0

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.