[Extension]: Add ThreatSpec (v0.1.0) #4660

Extension ID

threatspec

Extension Name

ThreatSpec

Version

0.1.0

Description

ThreatSpec is a spec-kit extension that makes threat modeling and security traceability a first-class part of Spec-Driven Development.

Author

hupe1980

Repository URL

https://github.com/hupe1980/spec-kit-threatspec

Download URL

https://github.com/hupe1980/spec-kit-threatspec/archive/refs/tags/v0.1.0.zip

License

MIT

Homepage (optional)

https://github.com/hupe1980/spec-kit-threatspec

Documentation URL (optional)

https://github.com/hupe1980/spec-kit-threatspec/blob/main/README.md

Changelog URL (optional)

https://github.com/hupe1980/spec-kit-threatspec/blob/main/CHANGELOG.md

Required Spec Kit Version

=1.0.0

Required Tools (optional)

- python (>=3.8) - required, with PyYAML; the bash and PowerShell wrappers fall back to `uv run --with pyyaml --with jsonschema` when no local PyYAML is present
- uv - optional, only needed as that fallback
- jsonschema - optional, enables full JSON Schema validation; a built-in structural validator runs without it

Number of Commands

3

Number of Hooks (optional)

7

Tags

security, threat-modeling, llm, agentic, traceability

Key Features

• Generates an Open Threat Model (OTM)-compatible threat-model.yaml from spec.md and plan.md, validated by a bundled JSON Schema
• Publishes testable SR-### security requirements into spec.md between managed markers, so /speckit.plan and /speckit.tasks consume them natively
• Twelve deterministic checks (schema, dangling references, threat→mitigation→requirement→task→verification coverage, risk-decision expiry, spec drift) with md, json, and SARIF output for GitHub code scanning
• Evidence-based security convergence: the agent judges each requirement only from collected evidence, verified requires an inspectable pointer, verification history is append-only, and gaps are appended to tasks.md as traceable tasks
• Threat profiles for STRIDE, OWASP Top 10 for LLM Applications 2026, and OWASP Top 10 for Agentic Applications 2026, with edition-pinned framework mappings and applicability surfaces
• Runs without an agent: the engine is a plain Python script usable in CI, plus a bundled composite GitHub Action
• Seven optional lifecycle hooks (after_specify through before_converge); installing the extension changes nothing until you opt in

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on:

• macOS 15 with Spec Kit CLI v1.0.7 (dev install, archive URL install, and self-hosted catalog install)
• GitHub Actions CI: Ubuntu and Windows, Python 3.11 and 3.13

Test project: an internal link shortener built end to end with the full nine-step workflow, from /speckit.specify through to security convergence.

Test scenarios:

1. Installed the extension three ways: --dev, --from <archive URL>, and by name from a self-hosted catalog; confirmed .extensionignore keeps tests and docs out of the install
2. Ran all three commands as agent skills against real specs; verified each writes only its documented files
3. Ran the full lifecycle on the test project: 20 threats modelled, 16 security requirements, 46 tasks, 106 application tests, final status CONVERGED
4. Verified append-only guarantees: tasks.md unchanged when converged, no duplicate tasks on repeated convergence runs, verification history never rewritten
5. Verified the deterministic engine standalone: valid SARIF 2.1.0 output, exit codes 0/1/2 by severity, CRLF checkouts produce no false drift
6. Extension test suite: 46 passing, including manifest validation against the Spec Kit CLI's own ExtensionManifest

Example Usage

# Install
specify extension add threatspec --from https://github.com/hupe1980/spec-kit-threatspec/archive/refs/tags/v0.1.0.zip

# Model threats from the spec, then check the chain before implementing
/speckit.threatspec.model
/speckit.threatspec.check

# After implementation, verify every security requirement against evidence
/speckit.threatspec.converge

# The same checks run without an agent, for CI
.specify/extensions/threatspec/scripts/bash/threatspec.sh check --format sarif --output threatspec.sarif

Proposed Catalog Entry

{
  "threatspec": {
    "name": "ThreatSpec — Threat Modeling & Security Traceability",
    "id": "threatspec",
    "description": "STRIDE and AI/ML threat modeling with threat-to-test traceability and security convergence",
    "author": "hupe1980",
    "version": "0.1.0",
    "download_url": "https://github.com/hupe1980/spec-kit-threatspec/archive/refs/tags/v0.1.0.zip",
    "repository": "https://github.com/hupe1980/spec-kit-threatspec",
    "homepage": "https://github.com/hupe1980/spec-kit-threatspec",
    "documentation": "https://github.com/hupe1980/spec-kit-threatspec/blob/main/README.md",
    "changelog": "https://github.com/hupe1980/spec-kit-threatspec/blob/main/CHANGELOG.md",
    "license": "MIT",
    "category": "process",
    "effect": "read-write",
    "requires": {
      "speckit_version": ">=1.0.0"
    },
    "provides": {
      "commands": 3,
      "hooks": 7
    },
    "tags": ["security", "threat-modeling", "llm", "agentic", "traceability"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-09-21T00:00:00Z",
    "updated_at": "2026-09-21T00:00:00Z"
  }
}

Additional Context

ThreatSpec is not another one-shot threat-report command. It maintains a machine-readable threat model with typed cross-references across the whole lifecycle, so a threat can be traced to a mitigation, a requirement, a task, a test, and a recorded verdict. Structural work (schema, references, coverage, drift, severity) runs deterministically in scripts; the agent is used only for judgment.

The repository also ships two optional companions that install through their own primitives: a threatspec-sdd preset that appends SR-### awareness to the core tasks, analyze, converge, and checklist commands, and a secure-sdd workflow with review gates.

examples/rag-assistant/ contains a complete first-pass output generated by the model command from a bare spec, including the rendered threat model, check report, and coverage table, kept valid by the test suite.

The extension's own threat model is published at docs/threat-model.md, including the residual risks (indirect prompt injection via artifact content, and the opt-in verification.test_command).