[{"url":"https://hupe1980.github.io/spec-kit-attacktree/","title":"AttackTree for Spec Kit: attack trees for Spec-Driven Development","description":"Open-source Spec Kit extension that turns specs into attack trees: model attacker goals and AND/OR paths, simulate which security controls cut them, and verify every control with evidence.","body":""},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/","title":"Documentation","description":"Documentation for AttackTree, the Spec Kit extension for attack trees: installation, quickstart, concepts, guides, and the full reference for commands, CLI, file format, checks, and configuration.","body":"AttackTree adds attack trees to Spec Kit’s Spec-Driven Development workflow. New here? Read What is AttackTree?, then follow the quickstart. The rest is organised by what you need: concepts explain how and why it works, guides solve a task, and the reference lists every command, field, and setting."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/agentic-systems/","title":"Agentic and LLM systems","description":"Model attack trees for LLM applications and AI agents: the five attack-surface zones, prompt injection and tool-misuse paths, probabilistic guardrails, and bypass-rate measurement.","body":"LLM applications and agents are where path-based reasoning pays off most. A prompt injection is rarely the goal. It is the first step of a path that continues through planning, tool use, and egress, and the defences along that path are often probabilistic. Enable the agentic profile next to default:\n#\nFive zones\nThe profile tags nodes with the zone of the agent they target, following Christian Schneider’s scenario-driven approach:\nZoneWhere the step happensTypical attacks\ninputevery channel into the context: prompts, retrieval, email, tool output, tool descriptionsdirect and indirect prompt injection, tool description poisoning\nreasoningplanning and goal interpretationgoal hijack, sensitive context leakage\ntoolstool execution with the agent’s privilegestool misuse, delegated credential abuse, egress\nmemorycontext, working memory, long-term storagememory poisoning that persists across sessions\ninter-agentmessages between agentsspoofed or tampered messages, cascading compromise\nWalking a goal zone by zone is a reliable way to find the paths. A typical exfiltration path needs a step in input (instructions reach the agent), reasoning (the plan shifts), tools (a data-reading tool runs), and tools again (data leaves). That is an AND of four steps, and every one of them is a place for a control.\n#\nVectors and references\nThe profile proposes 15 attack vectors with references to the OWASP Top 10 for LLM Applications 2026 (owasp-llm-2026), the OWASP Top 10 for Agentic Applications 2026 (owasp-asi-2026), MITRE ATLAS (mitre-atlas), and MAESTRO layers. Proposals are a checklist, not a template: the model records a vector only when the spec makes it possible.\n#\nProbabilistic controls\nGuardrails, injection classifiers, goal-lock checks, output filters, and human approval reduce attacks without blocking them. Mark them probabilistic: true:\nThe effect is an assumption until a micro attack simulation measures it. Converge then records the measured bypass_rate, and the tree uses it. In Monte Carlo runs, probabilistic controls are sampled as well, so goals that depend on them show a wider spread.\nTwo rules from practice:\nLayer different failure modes. Two classifiers that both fail on the same payload family are one control, not two. Pair a probabilistic control with a deterministic one, such as a tool allowlist, an egress allowlist, or scoped credentials, on the same path.\nGive humans the context. Human approval that shows “Send email? Yes/No” without the reasoning chain approves the attack. Write a validation step that checks what the approver sees.\n#\nThe same example, zone by zone\nThe shipped example is an agentic assistant with a retrieval path and a ticket tool. Its goal goal.abuse-ticket-credential combines an injection (input) with a call beyond scope (tools). Its most likely path, however, is an operator reading the credential from configuration. Path-based ranking surfaces exactly this kind of finding: the AI-specific path is real, but not the cheapest."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/attack-tree-format/","title":"attack-tree.yaml format","description":"Complete reference for attack-tree.yaml: actors, assets, goals, AND/OR nodes, attack vectors, controls, CR requirements, verification, decisions, reference rules, baselines, and drift hashes.","body":"attack-tree.yaml lives next to spec.md in each feature directory and is the single source of truth: attack-tree.md and the CR-### block in spec.md are rendered from it. The JSON Schema describes its shape; the engine validates against the schema, the reference rules below, and the tree structure on every write. An annotated skeleton and a complete example are in the repository.\n#\nTop level\nKeyPurpose\nattacktreeversion, generated, profiles, extends, sources, exclusions\nprojectid, name, optional description, owner\nactorswho attacks, with capabilities\nassetswhat the goals hit (optional, OTM-compatible ids)\ngoalsroots: attacker outcomes with impact\nnodesthe tree, as a flat list with parent; leaves carry attack\ncontrolssafeguards attached to nodes or goals\nrequirementsCR-### control requirements\nverificationappend-only evidence history\ndecisionsaccepted or transferred risks\n#\nIdentifiers\nEntityPatternExample\nactoractor.&lt;slug&gt;actor.content-author\nassetasset.&lt;slug&gt;asset.document\ngoalgoal.&lt;slug&gt;goal.read-restricted-documents\nnodenode.&lt;slug&gt;node.rrd-inject-document\ncontrolcontrol.&lt;slug&gt;control.ticket-confirmation\nrequirementCR-###CR-003\nverificationverification.&lt;slug&gt;verification.cr-003.2026-09-25\ndecisiondecision.&lt;slug&gt;decision.deny-service\nIds are immutable. A goal or node the model command no longer produces keeps its entry with status: retired and a retired_reason; retiring a goal or an interior node by hand retires its whole subtree. Asset ids follow the OTM convention (asset.&lt;slug&gt;) so seed and links line up with an OTM file.\n#\nActors\nLeave out occurrence unless you have a reason; it defaults to 100. A capability an actor does not state never limits it, so an unrated or partially rated actor can run more than it should (check A15 names the missing keys). occurrence scales every path that actor can run: a path’s reported likelihood is its raw likelihood times the occurrence of the most active actor able to run it, so a trivial attack that only a rare actor attempts ranks below a harder one that a common actor attempts. Schneier lists “likelihood that an attacker will try a given attack” as its own node value; attacktree.online calls it the actor’s occurrence.\n#\nGoals\nimpact may also be a single level (impact: high). status is human- and engine-owned: the model command never changes it on an existing goal; converge sets mitigated when the goal has feasible paths, every one carries a verified control, the residual risk is below risk.block_on, and the goal is not unknown; accepted and transferred follow an unexpired decision and fall back to open when it expires.\n#\nNodes\nA node with children is a subgoal and must not carry attack; a node without children is a leaf and should (check A4). A node with status: needs-clarification is a question: give it a name starting with [NEEDS CLARIFICATION: …], place it under an OR node next to a rated sibling, and the engine evaluates the tree without it (an interior node in that state hides its whole subtree), lists it as an assumption in the simulation, and reports it as check A14. A goal whose every path runs through open questions is reported as unknown, not as low risk, and converge never marks it mitigated.\n#\nControls\nstatus is human-owned for proposed, planned, and rejected; converge sets implemented (from evidence of code at the touchpoint) and verified, and demotes a verified claim without evidence to implemented. The model command never changes the status of an existing control, whatever its incoming file says. evidence follows the verification method: tests, scans, and simulations give lab-validated, reviews design-reviewed, manual drills end-to-end-validated; regression-tested is set by hand once the check runs in CI.\n#\nRequirements\n#\nVerification\nAppended by converge and never rewritten.\n#\nDecisions\n#\nReference rules (check A2)\nnodes[].parent → a goal or node; parent chains must end at a goal without cycles\na node with children must not have attack\nnodes[].attack.actors → actors[]; attack.requires tags → the profile’s scales.requires\ngoals[].assets → assets[]\ncontrols[].nodes → goals or nodes; controls[].effects keys → attached nodes; controls[].requirements → requirements[]\nrequirements[].controls → controls[]\nverification[].requirement → requirements[]; decisions[].target → goals or nodes (a decision on a node accepts every path through it: those paths count in the goal’s likelihood but not in blocking or check A6)\nLinks into an OTM file (links.threats, links.mitigations) carry the ids exactly as the OTM file spells them and are checked only when model.otm is configured and the file exists (check A13).\n#\nExclusions\n#\nBaseline inheritance\nattacktree.extends may point at a project-level tree (by convention .specify/memory/attack-tree.yaml) that holds shared actors, assets, controls, and decisions. Entities from the baseline are visible for reference resolution, simulation, and rendering; the feature tree wins on id clashes. The baseline is never written by feature commands.\n#\nDrift hashes\nattacktree.sources[] records a SHA-256 per source file (spec.md, plan.md, and the configured OTM file). The hash is computed on universal-newline text with trailing newlines trimmed, so a CRLF checkout produces the same digest as an LF one. For Markdown sources every extension-managed block (&lt;!-- attacktree:begin --&gt; … &lt;!-- attacktree:end --&gt;, and any other extension’s &lt;!-- &lt;id&gt;:begin --&gt; … &lt;!-- &lt;id&gt;:end --&gt;) is removed first, so rendering never counts as drift; any edit outside the markers does.\n#\nDeterminism\nThe engine writes entities sorted by id with a fixed key order, so regenerating an unchanged tree yields a byte-identical file, and the rendered attack-tree.md is identical for an identical tree and configuration. Monte Carlo results are reproducible for a given seed."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/attack-trees/","title":"Attack trees explained","description":"What an attack tree is, where the method comes from, how AND and OR nodes and leaf values work, and why attack trees rank threats better than a list.","body":"An attack tree describes how an attacker can reach a goal. The goal is the root, the ways to reach it are its children, and the children are refined until each leaf is a concrete attack. Bruce Schneier popularised the method in his 1999 article Attack Trees. It borrows its logic from fault tree analysis, which engineers have used since the 1960s to reason about how systems fail.\n#\nNodes: goals, AND, OR, leaves\nSchneier’s first example is a safe. The attacker’s goal is to open it:\nTwo kinds of node connect children to their parent:\nOR nodes are alternatives. The parent succeeds if any child succeeds: the safe opens if the lock is picked, or the combination is learnt, or the safe is cut open.\nAND nodes are steps. The parent succeeds only if every child succeeds: eavesdropping needs the conversation and the target stating the combination.\nLeaves are attack vectors, the concrete things an attacker does. Everything above a leaf is a subgoal.\n#\nValues propagate upwards\nOnce leaves carry values, the tree computes the values of every subgoal and of the goal:\nValue on the leavesOR node takesAND node takes\npossible / impossiblepossible if any child ispossible only if all children are\ncostthe cheapest childthe sum of the children\nprobability of successthe most likely childthe product of the children\nThe result answers questions a list of threats cannot: what is the cheapest attack? What is the most likely one? Which attacks need no special equipment? In Schneier’s safe, cutting the safe open costs little but needs a torch. Bribing someone who knows the combination costs more but needs no equipment. Which one matters depends on who attacks.\n#\nAttackers decide which leaves count\n“Different attackers have different levels of skill, access, risk aversion, money, and so on,” Schneier wrote. A bored student will not bribe anyone; organised crime will. So the same tree has different answers for different attackers.\nAttackTree makes this explicit. Every threat actor has four capabilities: skill, resources, access, and risk_appetite. Every leaf states what it takes: a complexity that sets the skill needed, a cost that sets the resources needed, and requires tags such as insider-access or illegal. A leaf only counts for actors who can do it, and an AND path only counts if one actor can do every step. The simulation then reports the answer per actor.\n#\nControls prune the tree\nA control, or countermeasure, makes a node harder. Schneier’s what-if is simple: raise the cost of bribery, recompute, and see what the cheapest attack becomes. AttackTree attaches controls to nodes with an effect, from 25 % to eliminating the step outright. Where you attach them matters:\nNear the root, a control is generic and protects everything below it.\nNear a leaf, a control is specific and protects one attack.\nOn a node every path crosses, a choke point, one control protects every path to the goal.\nThe simulation finds choke points, measures each unbuilt control’s effect, and shows which controls your defence depends on alone.\n#\nWhy trees beat lists\nA threat list says what can go wrong. A tree says how an attacker gets from where they start to what they want, and that difference changes what you build:\nIt ranks by the path, not the finding. An attacker takes the easiest route. A severe but unreachable vulnerability ranks below a mundane one on the main path.\nIt shows leverage. Paths converge. One control at a convergence point can do more than five on the leaves.\nIt exposes false comfort. Schneier found that PGP’s key length hardly mattered, because keyloggers and trojans were far cheaper routes to the same plaintext. “The areas people think of as vulnerable usually aren’t.”\nIt is reusable. A subtree for “obtain a valid session” applies to every feature behind the same login.\nTrees and lists complement each other. A STRIDE-style list is a good source of leaves; the tree puts them in order. AttackTree can seed goals from an Open Threat Model file produced by such tools.\n#\nFrom method to practice\nSchneier’s paper leaves open how to rate leaves consistently and how to carry the analysis into delivery. Christian Schneider’s Attack Tree platform (attacktree.online) closed that gap for workshops. Leaves get an actor and a complexity, and likelihood is derived from the two. Goals get impact per class, such as business, data, and compliance. Controls get an effect, a cost, a status, and validation steps. What-if and Monte Carlo simulations turn the tree into a prioritised roadmap. AttackTree follows the same vocabulary and adds the parts a repository needs: requirements in the spec, tasks, checks, and verification.\n#\nFurther reading\nBruce Schneier, Attack Trees, Dr. Dobb’s Journal, 1999.\nChristian Schneider, Threat modeling agentic AI: a scenario-driven approach, 2026.\nChristian Schneider, Verifying agentic AI controls with attack tree micro simulations, 2026.\nKordy, Kordy, Mauw, and Schweitzer, ADTool: Security Analysis with Attack–Defense Trees, 2013. It covers attack–defence trees, which model defences as nodes.\nNext: how AttackTree turns ratings into risk."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/checks/","title":"Checks","description":"Reference for AttackTree's sixteen deterministic checks A1 to A16 with severities and fixes, and the ten semantic passes the check command adds.","body":"attacktree.sh check runs sixteen deterministic checks over the tree, tasks.md, the sources, and the configured OTM file. /speckit-attacktree-check prints them and adds ten semantic passes that need judgement. Findings cite a location, such as attack-tree.yaml#goal.forge-ticket or spec.md, and a recommendation.\n#\nDeterministic checks\nIDFindsSeverityFix\nA1Schema violations, or a missing attack-tree.yamlCRITICALCorrect the field the message names.\nA2Dangling references, parent cycles, an attack block on a node with children, effects for a node the control is not attached to, unknown requires tagsCRITICALPoint the reference at an existing id, or add the entity.\nA3A goal without any nodeMEDIUMModel its paths, or retire it.\nA4A leaf without attack, actors, or complexityHIGHRate the attack vector.\nA5An AND or OR node, or an AND goal, with a single childLOWAdd the missing alternative or step, or merge the node into its child.\nA6A feasible path to a goal with no control on any of its nodes and no decisionHIGH, CRITICAL for critical-impact goalsAttach a control on the path (a choke point covers every path), or record a decision.\nA7A control without a CR-### requirementHIGHDerive a requirement with acceptance scenarios.\nA8A requirement without a task in tasks.mdHIGHAdd a task tagged [CR-###].\nA9A requirement without verificationLOW before implementation, MEDIUM in progress, MEDIUM or HIGH once its tasks are doneRun converge after implementation.\nA10A decision missing owner, rationale, or expiry, or already expired (HIGH); an expiry beyond max_duration_days (MEDIUM)HIGH or MEDIUMComplete, renew, or shorten the decision.\nA11spec.md, plan.md, or the OTM file changed since the tree was generated (MEDIUM), or was never hashed (LOW)MEDIUM or LOWRe-run the model command.\nA12A control marked verified without a passing verification for all its requirementsHIGHRun converge; statuses follow evidence.\nA13A link to a threat or mitigation that is not in the OTM fileMEDIUMFix the link, or refresh the tree after the OTM file changed.\nA14A node that needs clarificationMEDIUMAnswer the question with /speckit-clarify, then re-run the model command.\nA15An actor without some of skill, resources, access, or risk appetiteMEDIUMRate the missing capabilities.\nA16Path enumeration truncated at risk.max_pathsLOWRaise the limit, or split the goal.\nExpired decisions protect nothing: A6 and the simulation ignore them. More than three pre-implementation A9 findings are aggregated into one line.\n#\nExit codes and enforcement\nWorst findingwarnstrict\nCRITICAL22\nHIGH11\nMEDIUM01\nLOW or none00\nSet enforcement in the configuration, or pass --strict for one run. Under strict, the agent also refuses to proceed to /speckit-implement while a CRITICAL finding is open.\n#\nOutput formats\nmd (the default) is the report table. json contains findings, metrics, the worst severity, and the effective enforcement. sarif is SARIF 2.1.0 for GitHub code scanning, with one rule per check ID.\n#\nSemantic passes\nThe check command’s agent adds these after reading the tree, the spec, the plan, the tasks, the OTM file, the profiles, and the constitution:\nPassLooks for\nS1 Drift contentwhat changed in the sources that the tree does not reflect yet\nS2 Missing pathsentry points, goals, or actors the artifacts imply but the tree lacks\nS3 Duplicatesnodes or controls that describe the same step or safeguard\nS4 Control fitcontrols that do not address their node, controls far from a choke point, single points of failure on critical goals\nS5 Rating plausibilityratings the artifacts contradict, missing requires tags\nS6 Requirement and task fituntestable requirements, acceptance that skips the validation steps, tasks that cannot implement the control\nS7 ConstitutionMUST principles about security without a goal or control\nS8 Decisionsdecisions whose rationale no longer holds\nS9 Probabilistic controlsguardrails not marked probabilistic, human approval without context\nS10 Wordinggoals phrased as weaknesses, controls without touchpoints or validation steps"},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/ci/","title":"Continuous integration","description":"Run AttackTree's checks and simulation in CI without an agent, upload findings to GitHub code scanning as SARIF, and gate pull requests on residual risk.","body":"The engine needs no LLM, so every check and the simulation run in CI. This guide covers the bundled GitHub Action and the plain command line.\n#\nGitHub Action\nThe action runs the checks, uploads the findings to code scanning under the attacktree category, runs the simulation, and fails the job on HIGH or CRITICAL findings.\nInputDefaultEffect\nfeature-dirauto-detectFeature directory; otherwise SPECIFY_FEATURE, the branch name, or the newest spec.\nformatmdCheck report format in the log: md or json.\nstrictfalseAlso fail on MEDIUM findings.\nscenariocurrentControl statuses the simulation counts: none, current, verified, planned, or all.\nfail-on-blocking-goalsfalseFail while a goal is at risk.block_on residual risk without a decision.\nupload-sariftrueUpload findings to code scanning.\nfail-on-findingstrueFail on the check’s exit code.\nOutputs: exit-code (check), simulate-exit-code, and sarif (the file path).\n#\nWhich gate to use\nEvery pull request: the default. Structural errors and missing links fail the build; verification gaps before implementation stay LOW, so they don’t.\nBefore merging to main: add fail-on-blocking-goals: \"true\" with scenario: planned. The agreed roadmap must bring every goal below the blocking level.\nAfter implementation: scenario: verified counts only controls with evidence.\n#\nCommand line\nThe same engine runs anywhere Python and PyYAML are available:\nCommandExit 0Exit 1Exit 2\nchecknothing above MEDIUMHIGH, or MEDIUM with --strictCRITICAL\nsimulateno blocking goala goal at risk.block_on—\nconverge-applyconvergednot converged—\n#\nPhase-aware verification findings\nCheck A9, a requirement without verification, follows implementation progress. It is LOW while no task for the requirement is done, MEDIUM while some are, and MEDIUM or HIGH once all are done but nothing verifies it. HIGH applies when the control guards a high or critical goal. A pull request that only changes the spec therefore does not fail for missing evidence.\n#\nCode scanning\nWith upload-sarif, findings appear in the repository’s Security → Code scanning tab and as annotations on the pull request, with rule IDs A1 to A16, the file, and a recommendation."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/cli/","title":"Engine CLI","description":"Reference for attacktree.sh, the deterministic AttackTree engine: global options, feature resolution, every subcommand with its flags, and exit codes.","body":"The engine is scripts/python/attacktree.py. Call it through the wrappers scripts/bash/attacktree.sh or scripts/powershell/attacktree.ps1, which find a Python with PyYAML or fall back to uv. In an installed project the path is .specify/extensions/attacktree/scripts/bash/attacktree.sh.\n#\nGlobal options\nOptionDefault\n--repo PATHThe nearest parent directory containing .specify/ or .git.\n--feature-dir PATHSPECIFY_FEATURE, then the directory under specs/ named like the current git branch, then the newest specs/*/spec.md.\nGlobal options come before the subcommand.\n#\nSubcommands\n#\npaths\nPrints the resolved repository, feature, and artifact paths, whether each artifact exists, and how the feature was found. --json for machine-readable output. Exit code 1 if no feature is found.\n#\ninit\nCreates an empty attack-tree.yaml with source hashes and the configured baseline. --project-id, --name, and --force to overwrite an existing tree.\n#\nseed\nDerives assets and candidate goals from an Open Threat Model file. --otm FILE (default: model.otm from the configuration) and --output FILE.\n#\nvalidate FILE\nValidates a tree against the JSON Schema, the reference rules, and the tree structure. --json for machine-readable output. Exit code 1 on errors.\n#\nmerge --incoming FILE\nMerges an agent-written tree into attack-tree.yaml: it keeps ids and human-owned fields, retires what disappeared, records source hashes, sorts deterministically, and validates. --dry-run prints the result without writing. --allow-invalid writes despite errors; avoid it.\n#\nrender\nWrites attack-tree.md and the CR-### block in spec.md. --no-markdown and --no-spec skip either for one run.\n#\ncheck\nRuns checks A1 to A16. --format md|json|sarif, --output FILE, --persist (writes security/attacktree-check-report.md), --strict, --enforcement warn|strict. Exit code 0 when nothing is above MEDIUM, 1 for HIGH (or MEDIUM in strict mode), 2 for CRITICAL.\n#\nsimulate\nEvaluates the tree. --format md|json, --output FILE, --persist (writes security/attacktree-simulation.{md,json}), --scenario none|current|verified|planned|all, --apply IDS and --remove IDS (comma-separated control ids, what-if only), --iterations N, --seed N, --no-monte-carlo. Refuses to run on an invalid tree. Exit code 1 while a goal is at risk.block_on residual risk without a decision.\n#\nconverge-scan\nCollects evidence facts per requirement as JSON: tasks, test files, touchpoints, validation steps, residual risk with verified controls, and check findings. --output FILE.\n#\nconverge-apply --verdicts FILE\nRecords verdicts, rolls statuses up, writes the convergence report, and appends remediation tasks. --only CR-001,CR-002 judges only those requirements; the others keep their last verdict. --commit SHA overrides the detected commit. --no-render skips re-rendering attack-tree.md. Exit code 0 when converged, 1 otherwise.\n#\nEnvironment\nVariableEffect\nSPECIFY_FEATUREFeature directory name under specs/.\nSPECKIT_ATTACKTREE_ENFORCEMENTOverrides enforcement.\nSPECKIT_ATTACKTREE_PROFILESOverrides profiles (comma-separated).\nSPECKIT_ATTACKTREE_SCENARIOOverrides risk.scenario."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/commands/","title":"Commands","description":"Reference for the four AttackTree agent commands: model, simulate, check, and converge. Arguments, what each command reads and writes, and when to run it.","body":"Spec Kit renders each command for your agent. Claude Code, Copilot, Cursor, and most others use the hyphenated form, as in /speckit-attacktree-model. opencode, Gemini, and Qwen use the dotted form, as in /speckit.attacktree.model. Arguments are free text after the command. They only narrow scope and are never executed.\nEvery command resolves the feature directory the same way: from --feature-dir specs/&lt;name&gt; if given, then SPECIFY_FEATURE, the current git branch, and finally the newest specs/*/spec.md. Every command also treats the content of the spec, plan, OTM file, code, and tests as untrusted data. Instruction-like text found there is quoted under Unverified and never followed.\n#\n/speckit-attacktree-model\nBuilds or incrementally updates the attack tree.\nRun after/speckit-specify, /speckit-clarify, and /speckit-plan (with --from-plan)\nArguments--feature-dir, --from-plan, --profiles default,agentic, --goal &lt;text&gt;, --focus &lt;text&gt;\nReadsspec.md, plan.md, the constitution, the configured OTM file, the existing tree, the profiles\nWritesattack-tree.yaml, attack-tree.md, the CR-### block in spec.md, working files in security/\nThe agent defines actors, goals, paths, controls, and requirements, and writes the whole tree to security/incoming-attack-tree.yaml. The engine then merges it into attack-tree.yaml: it validates the tree, keeps ids and human-owned fields, retires what disappeared, and records source hashes. Where the spec is silent, the agent adds a needs-clarification node instead of inventing architecture. The report lists open questions, proposed risk decisions, and the structural simulation.\n#\n/speckit-attacktree-simulate\nEvaluates the tree and interprets the result for the team.\nRun afterthe model pass over the plan, before /speckit-tasks; also as the before_implement hook\nArguments--feature-dir, --scenario none|current|verified|planned|all, --apply ids, --remove ids, --iterations N, --seed N, --goal &lt;id&gt; (focuses the report)\nWritessecurity/attacktree-simulation.{md,json}\nThe command runs the configured scenario and the planned scenario, then answers six questions: where are we exposed, where is the leverage, what are we betting on, what should we build first, how sure are we, and what does the model not know. It changes no statuses. See Simulation.\n#\n/speckit-attacktree-check\nFinds gaps in the chain from goal to verified control.\nRun after/speckit-tasks, and before /speckit-implement\nArguments--feature-dir, --strict, --format md|json|sarif\nWritessecurity/attacktree-check-report.md\nThe engine runs the sixteen deterministic checks. The agent then adds ten semantic passes: drift content, missing paths, duplicates, control fit, rating plausibility, requirement and task fit, constitution, decisions, probabilistic controls, and wording. Under enforcement: strict, a CRITICAL finding means /speckit-implement must not run.\n#\n/speckit-attacktree-converge\nVerifies control requirements with evidence after implementation.\nRun after/speckit-implement; also as the before_converge hook\nArguments--feature-dir, --only CR-003,CR-007, --run-tests\nWritesattack-tree.yaml (verification, statuses, bypass rates), attack-tree.md, security/attacktree-*, an appended phase in tasks.md\nThe engine collects facts per requirement: tasks, test files that mention the ID, touchpoints, and validation steps. The agent judges each requirement from evidence it opened. The engine records the verdicts, rolls statuses up, recomputes residual risk with verified controls only, and appends remediation tasks. --run-tests runs verification.test_command once, if one is configured. See Verification and convergence."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/configuration/","title":"Configuration","description":"Every AttackTree configuration key with its default and effect: profiles, enforcement, risk scenario and blocking levels, simulation, risk acceptance, model rendering and OTM, and verification.","body":"AttackTree reads one configuration per repository. Every key is optional, and each has a documented default.\n#\nWhere the file lives\nspecify extension add attacktree writes .specify/extensions/attacktree/attacktree-config.yml with every key at its default. Edit and commit it. Put machine-specific values in attacktree-config.local.yml next to it, which Spec Kit gitignores. The annotated source of the file is config-template.yml.\n#\nPrecedence\nload_config() merges four layers, each overriding the one above it:\n#LayerSource\n1Extension defaultsconfig.defaults in extension.yml\n2Project config.specify/extensions/attacktree/attacktree-config.yml\n3Local overrides.specify/extensions/attacktree/attacktree-config.local.yml\n4EnvironmentSPECKIT_ATTACKTREE_*\nMerging is recursive: a mapping in a later layer is merged key by key into the earlier one. A scalar or a list is replaced outright: setting profiles: [agentic] discards the default [default] instead of appending to it. The default profile’s scales still apply in that case; only its proposal libraries are lost.\n#\nEnvironment variables\nExactly three are recognised:\nVariableEffect\nSPECKIT_ATTACKTREE_ENFORCEMENTReplaces enforcement.\nSPECKIT_ATTACKTREE_PROFILESReplaces profiles; comma-separated, whitespace trimmed.\nSPECKIT_ATTACKTREE_SCENARIOReplaces risk.scenario.\nOther nested keys cannot be set from the environment; use the local override file.\n#\nKeys\n#\nprofiles\nSee Profiles. Profiles supply the scales and the proposal libraries. Default [default]. Each name resolves to profiles/&lt;name&gt;.yaml. The default profile’s scales are always the base; the first active profile that declares scales overlays them, and every profile adds archetypes, vector and control proposals, and zones. A feature’s own attack-tree.yaml wins over this setting: the engine reads attacktree.profiles from the tree first.\nProfileSupplies\ndefaultscales, 8 actor archetypes, 20 attack vector proposals with CAPEC references, 16 control proposals with ASVS 4.0.3 or NIST CSF references\nagentic5 attack-surface zones, 4 agentic archetypes, 15 vectors with OWASP LLM and Agentic 2026, ATLAS, and MAESTRO references, 16 controls of which 5 are probabilistic\n#\nenforcement\nControls the exit code of the check command and the advice the agent gives. Default warn.\nWorst findingwarnstrict\ncritical22\nhigh11\nmedium01\nlow or none00\nUnder strict the check and simulate commands also state that implementation must not proceed while a CRITICAL finding or a blocking goal is open.\n#\nrisk\nKeyDefaultEffect\nblock_on[critical]Residual risk levels that make a goal “blocking”: simulate exits 1, converge does not converge, unless an unexpired decision targets the goal.\nscenariocurrentWhich control statuses count as active in simulate, render, and check metrics: none (no control, the baseline), current (implemented, verified), verified, planned (planned, implemented, verified), all (everything not rejected). Converge always uses verified; check A6 always uses all.\nmax_paths200Cap on enumerated paths per node, kept per actor so every actor’s most likely paths survive. Larger trees are flagged truncated (check A16) and choke points are computed on the sample.\n#\nsimulation\nKeyDefaultEffect\niterations2000Monte Carlo iterations; 0 disables the section.\nseed42Random seed; identical inputs give identical results.\nlikelihood_spread15Points added and subtracted around each leaf likelihood when no likelihood_range is set. Probabilistic controls are always jittered by ± 0.15 of their surviving fraction.\nsimulate --iterations N --seed N overrides both for one run.\n#\nrisk_acceptance\nGoverns check A10 over decisions[]. A decision must carry owner, rationale, and expires; anything missing is a high finding. require_owner: false drops owner from that set. max_duration_days caps how far ahead expires may sit; exceeding it is a medium finding. An expiry in the past, or one that is not YYYY-MM-DD, is high.\n#\nmodel\nKeyDefaultEffect\nbaseline.specify/memory/attack-tree.yamlProject-level tree inherited by each new feature tree for shared actors, assets, controls, and decisions. Read at init only, silently skipped when absent.\notm\"\" (off)Path, relative to the feature directory or the repository, of an Open Threat Model file that seed reads, A13 links against, and A11 hashes. Empty disables OTM interop.\nwrite_requirements_to_spectruePublishes the CR-### block into spec.md between the attacktree markers. render --no-spec overrides it for one run.\nrender_markdowntrueWrites attack-tree.md. render --no-markdown overrides it for one run.\ndiagrammermaidmermaid embeds one flowchart per goal in attack-tree.md; none omits them.\n#\nverification\nKeyDefaultConsumed byEffect\ntest_dirs[tests, test, spec, __tests__]engineDirectories walked when collecting evidence.\nevidence_markers[\"CR-\"]engineSubstrings searched in those files to tie a test to a requirement (CR-001, CR_001, CR001 all match).\ntest_command\"\"agentThe command converge runs, once, when it is invoked with --run-tests. Without the flag nothing is executed even if a command is configured.\nscanners[]agentScanner or micro-simulation outputs converge may cite as evidence, recorded with method: scan or simulation. Never as a verdict on its own.\nThe engine never executes test_command or scanners; converge-scan echoes them under config.verification, and the converge command prompt decides what to run. Running anything is opt-in: without --run-tests, converge reads artifacts and runs nothing."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/design/","title":"Design and roadmap","description":"Why AttackTree is built the way it is: positioning next to threat lists and attacktree.online, design decisions, what is out of scope, and the roadmap.","body":"#\nPositioning\nPer-element threat enumeration, such as STRIDE and its descendants, lists what can go wrong. Attack trees answer a different question: given a concrete adversary, how would they reach the outcome they want, which step is the bottleneck, and which control buys the most for the least. Christian Schneider’s Attack Tree platform made that a practical workshop method. AttackTree brings the method into Spec-Driven Development as an artifact that lives next to the spec, changes with it, and can be simulated, checked, and verified without an LLM.\nQuestionSpec KitAttackTree\nWhat are we working on?spec.md, plan.mdactors, assets, goals\nWhat can go wrong?—goals reached through AND/OR paths\nWhat are we going to do about it?tasks.mdcontrols ranked by simulation, CR-###, tasks\nDid we do a good job?/speckit-convergeevidence per requirement, residual risk from verified controls\n#\nDesign decisions\nDecisionReason\nTree as a flat list of nodes with parentsIds stay stable across regenerations, merges work per entity, and diffs stay readable. The rendered outline and diagrams restore the shape.\nSchneier’s rules, literallyOR takes the best child, AND multiplies likelihoods and adds costs, controls scale the subtree. One documented risk matrix, no hidden arithmetic.\nAttacker profiles are dataCapabilities and requires tags live in profiles, so a team can redefine “insider” without touching code.\nDeterministic core, semantic edgeThe engine does feasibility, propagation, paths, choke points, what-if, Monte Carlo, checks, and evidence collection. The agent reads specs, proposes, and judges evidence it opened.\nScenarios, not statusesRisk is always computed for a stated set of control statuses. Convergence believes only verified.\nMeasure probabilistic controlsGuardrails get a measured bypass rate from a micro attack simulation, and the tree uses the measurement from then on.\nHuman-owned fields are stickyStatuses, evidence levels, bypass rates, decisions, and notes survive any regeneration by the agent.\nUnknowns stay unknownAn open question is not a zero; goals that depend on one report unknown and are never marked mitigated.\nNative idsCR-### sits next to FR-### and SC-### in spec.md, so core commands can treat control requirements like any requirement.\nOpen formats onlyJSON Schema for the tree, OTM for import, SARIF for findings. AttackTree writes no format it cannot validate.\nDeliberate limits:\nAttack trees, not attack–defence trees. Controls are attributes of nodes, not nodes, which keeps the YAML flat and the simulation simple. A control on an inner node still defends its whole subtree.\nNo coalitions. An AND path counts only if one actor can perform every step.\nCoarse costs. Attack cost maps to four resource tiers, and control cost to three levels. The tree prioritises; it does not budget.\nBounded enumeration. Paths are capped per node, and each actor’s best paths are kept. Truncation is reported, never silent.\n#\nattacktree.online files\nattacktree.online saves trees as .json or .json.gz, but it publishes no schema for them. A tree exported by the app is a Version: 1 document with a NodeMap (nodes with AndOperator, Parent, Children, Impact, ThreatActor, Complexity, and Controls as effect percentages), a ControlMap, an AssetMap, Actors, and report settings. Impact, complexity, actor, and status are numeric codes whose meaning is only visible in the app. The mapping from AttackTree would be direct, but without a specification the codes are guesses that a release of the tool could invalidate silently. An exporter therefore waits until the format is published.\n#\nRoadmap\nNext: sequential AND gates with ordering; detectability on leaves feeding detective controls; coalition paths; a semantic diff of two trees for review; a cross-feature risk report; exporters for ADTool and, once specified, attacktree.online; adversarial test fixtures with injected instructions; pinned versions for the uv fallback; rejecting extends paths outside the repository.\nLater: a fault-tree view; OSCAL control mapping; the convergence report as an in-toto attestation.\nOut of scope: penetration testing, scanners, hosting, and dashboards. Scanner and simulation results are consumed as evidence; AttackTree does not produce them.\n#\nRelated work\nToolRelation\nAttack Tree by Christian SchneiderThe reference practice: visual editor, actor profiles, what-if, choke points, Monte Carlo, reports, API. AttackTree follows its vocabulary and brings the analyses that matter in a repository into the Spec Kit workflow.\nADToolAttack–defence trees with quantitative attribute domains; prior art for the propagation rules.\nIriusRisk, Threat Dragon, pytm, ThreagileThreat models as diagrams or code. Anything that produces OTM can seed an attack tree."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/evidence/","title":"Verification and convergence","description":"How AttackTree verifies security controls with evidence: verdicts, evidence levels, micro attack simulations and bypass rates, status roll-up, and the definition of converged.","body":"A control in a tree is a claim until something proves it works. /speckit-attacktree-converge turns claims into evidence after implementation and recomputes risk from what was proven.\n#\nClaims are not evidence\nA checked task, a comment saying “input is validated”, or status: implemented in the tree proves nothing. A test that only mentions the requirement ID, or asserts a constant, proves nothing either. Evidence is one of these:\na test whose assertions exercise the requirement’s Given/When/Then scenario;\na micro attack simulation record that executed the control’s validation steps against the running system;\na review of the code at the control’s touchpoint, showing the control is wired into the path the attack takes;\na scan result that covers the requirement.\n#\nVerdicts\nThe agent judges each CR-### requirement from evidence it opened, stopping at the first verdict it can justify:\nVerdictMeansRecorded result\nverifiedevery acceptance scenario is exercised and passespass\nimplemented-unverifiedthe control is present and wired, but nothing tests itinconclusive\npartiala scenario, a path, or the wiring is missingpartial\nmissingno implementation foundfail\nThe engine rejects verified without an evidence pointer, such as path::test_name, path:line, or a record file. Every verdict is appended to verification[] with a timestamp and a commit. History is never rewritten.\n#\nRoll-up\nAfter recording, the engine updates the tree:\nA control becomes verified when all its requirements are verified. Its evidence level follows the method: lab-validated for tests, scans, and simulations, design-reviewed for reviews, and end-to-end-validated for manual drills.\nA proposed or planned control becomes implemented when any of its requirements shows code at the touchpoint.\nA verified claim without a passing verification falls back to implemented.\nA goal becomes mitigated when it has feasible paths, every one carries a verified control, its residual risk with verified controls is below risk.block_on, and it is not unknown. accepted and transferred follow an unexpired decision.\nResidual risk is then recomputed with the verified scenario: only proven controls count.\n#\nProbabilistic controls and bypass rates\nGuardrails, classifiers, and human approval do not block; they reduce. Mark them probabilistic: true. Their real effect is a bypass rate, the share of attacks that get through, and only a measurement can establish it. A micro attack simulation is a small, targeted exercise that runs a control’s validation steps with enough probes to state a rate. Christian Schneider suggests 30 or more probes for a leaf-level control, and hundreds, with a confidence interval, for a control on a critical goal’s choke point.\nRecord the rate with the verdict. The engine stores it on the requirement’s probabilistic controls, and from then on the simulation uses the measured value instead of the effect level. A goal-lock classifier assumed at “medium” (50 %) but measured at 15 % bypass lowers risk more than assumed; one measured at 60 % raises it. Either way, the tree now reports what the control does.\n#\nRemediation tasks\nEvery requirement that is not verified becomes a task in a ## Phase N: Control Convergence section appended to tasks.md. The task is tagged [CR-###], names the touchpoints, and states the verdict and why. So does every goal still at blocking risk. Existing tasks are never changed. A gap that already has an open task is not duplicated, and a converged run leaves tasks.md byte-for-byte unchanged.\n#\nDefinition of converged\nA feature is converged when all four hold:\nNo goal is at or above risk.block_on residual risk with verified controls only, unless an unexpired decision covers it.\nEvery CR-### is verified, or all its controls are rejected.\nNo risk decision has expired.\nspec.md, plan.md, and the configured OTM file have not changed since the tree was generated.\nThe converge command exits with code 0 when converged and 1 otherwise, so it can run in CI after implementation."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/glossary/","title":"Glossary","description":"Definitions of the terms used by AttackTree: attack tree, goal, node, leaf, AND and OR gates, path, choke point, control, bypass rate, residual risk, scenario, and more.","body":"Achilles heel. A leaf that many paths to a goal share, weighted by those paths’ likelihood.\nActor, threat actor. Someone who attacks the system, described by skill, resources, access, risk appetite, and optionally occurrence.\nAND node. A node whose children are steps that must all succeed. Likelihoods multiply and costs add.\nAttack tree. A tree whose root is an attacker’s goal, whose inner nodes are subgoals, and whose leaves are concrete attacks.\nAttack vector. A leaf: a concrete action with a complexity, a likelihood, and optionally a cost and requirements.\nBypass rate. The measured share of attacks that get through a probabilistic control. Once recorded, it replaces the control’s assumed effect.\nChoke point. A node that every feasible path to a goal crosses. A control there covers every path.\nComplexity. How hard a leaf is to execute, from trivial to extreme. It sets the skill an actor needs and the default likelihood.\nControl. A security measure attached to one or more nodes. It reduces the likelihood of everything below them.\nControl requirement (CR-###). A testable obligation derived from one or more controls, with Given/When/Then acceptance scenarios, published into spec.md.\nConverged. No goal at blocking residual risk with verified controls only, every requirement verified, no expired decision, no drift. See Verification.\nDecision. An owner’s acceptance or transfer of a goal’s risk, or of every path through a node, until an expiry date.\nDefence in depth. In the what-if table, a control that lowers no goal’s best path today but cuts alternative paths.\nDrift. A change to spec.md, plan.md, or the OTM file since the tree was generated, detected by content hashes.\nEffect. How much a control reduces the likelihood below its node: low (25 %), medium (50 %), high (80 %), or eliminates (100 %).\nEvidence level. How a control’s verification was established: assumed, design-reviewed, lab-validated, end-to-end-validated, or regression-tested.\nFeasible. A leaf or path that at least one modelled actor can perform.\nGoal. The root of a tree: an outcome an attacker wants, with an impact rating per class.\nImpact. The damage if a goal is reached, rated per class (business, customer, data, compliance, safety) from low to critical.\nMicro attack simulation. A small, targeted exercise that runs a control’s validation steps against the real system to measure whether and how often it works.\nMonte Carlo. Repeated evaluation of the tree with ratings sampled around their estimates, to show how sensitive each goal is to them.\nNeeds clarification. A node the spec does not settle. It is left out of the evaluation until the question is answered.\nOccurrence. How likely an actor is to target the system at all, from 1 to 100. It scales every path the actor can run.\nOR node. A node whose children are alternatives. The best one counts.\nPath. A set of leaves that together achieve a goal: one choice at every OR node on the way.\nProbabilistic control. A control that reduces rather than blocks, such as a classifier, guardrail, or human approval. Its effect needs measuring.\nResidual risk. A goal’s risk level after the controls of a scenario, from its likelihood level and impact level.\nScenario. The set of control statuses counted by a simulation: none, current, planned, verified, or all.\nSingle point of failure. An active control whose removal alone raises a goal’s risk level.\nTouchpoint. The file or component where a control is implemented.\nZone. In the agentic profile, the part of an AI agent a node targets: input, reasoning, tools, memory, or inter-agent."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/installation/","title":"Installation","description":"Install the AttackTree extension into a Spec Kit project from a release archive, a catalog, or a local checkout, plus the optional preset and workflow.","body":"#\nRequirements\nSpec Kit 1.0 or later, with a project initialised by specify init.\nPython 3.11 or later with PyYAML. If PyYAML is missing, the wrapper scripts fall back to uv, which fetches PyYAML and jsonschema on the fly.\nAny coding agent that Spec Kit supports: Claude Code, GitHub Copilot, Cursor, Gemini CLI, opencode, Codex, and others.\n#\nInstall the extension\nPick one of three sources. All three install the same files into .specify/extensions/attacktree/ and register the four commands with your agent.\nFrom a release archive. The CLI asks you to confirm the URL because it is not in a catalog you trust yet.\nFrom this project’s catalog. Register the catalog once, then install and update by name.\nFrom a local checkout, for development:\n#\nVerify\nThe list shows AttackTree — Attack Tree Modeling &amp; Control Simulation with 4 commands and 7 hooks. If your agent was already running, restart it so it picks up the new commands. Depending on the agent, they appear as /speckit-attacktree-model (Claude Code, Copilot, Cursor, and most others) or /speckit.attacktree.model (opencode, Gemini, Qwen).\nThe install also scaffolds .specify/extensions/attacktree/attacktree-config.yml. The defaults work; see Configuration before you change them.\n#\nOptional companions\nThe repository ships two optional add-ons. They are not part of the extension archive, so install them from a checkout.\nAdd-onWhat it doesInstall\nPreset attacktree-sddAppends a short section to the core tasks, analyze, converge, and checklist commands so they tag, inventory, and check CR-### requirements nativelyspecify preset add --dev ./spec-kit-attacktree/preset/attacktree-sdd\nWorkflow attacktree-sddRuns the whole cycle from specify to converge with review gates after the tree, the simulation, and the gap checkspecify workflow add --dev ./spec-kit-attacktree/workflow/attacktree-sdd\n#\nHooks\nAll seven hooks are optional: after /speckit-specify, /speckit-plan, /speckit-tasks, and the other core commands, the agent asks whether to run the matching AttackTree command. Nothing runs without your confirmation. To make a hook automatic, set optional: false for it in .specify/extensions.yml. The workflow guide lists every hook.\n#\nUpdate and remove\nRemoving the extension leaves your feature artifacts (attack-tree.yaml, the CR-### block in spec.md) untouched."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/introduction/","title":"What is AttackTree?","description":"AttackTree is an open-source Spec Kit extension that builds attack trees from your spec, simulates which security controls cut the attack paths, and verifies each control with evidence.","body":"AttackTree is an extension for GitHub Spec Kit. It adds threat modelling with attack trees to Spec-Driven Development: from the specification of a feature, your coding agent builds a tree of what an attacker wants and every way to get there. A deterministic engine then simulates the tree and tells you which security controls matter. Those controls become requirements in the spec and, after implementation, are verified with evidence.\n#\nThe problem it solves\nSecurity reviews of a spec usually produce a list: “prompt injection”, “missing authorization”, “credential theft”. A list does not say which item an attacker would actually use, which one control would stop the most attacks, or whether the controls that were built work. So teams spend effort evenly, or on whatever sounds most dangerous.\nAn attack tree answers those questions. It describes attacks as paths from an attacker’s starting point to a goal, so it can rank them by likelihood and cost for a given attacker. It also shows where paths converge on a single step. Bruce Schneier introduced the method in 1999; Christian Schneider’s Attack Tree platform turned it into a practical workshop method with actors, controls, and simulation. AttackTree brings that practice into your repository and your agent’s workflow.\n#\nWhat you get\nAn attack tree per feature, as attack-tree.yaml next to spec.md: threat actors with capabilities, attacker goals with business impact, AND/OR paths, rated attack vectors, and controls. It is versioned, diffable, and validated by a schema.\nA simulation of that tree: the most likely and cheapest path per attacker, residual risk per goal, choke points, single points of failure, a what-if ranking of every control not yet built, a roadmap ordered by risk reduction per cost, and a Monte Carlo run over the uncertainty in the ratings.\nControl requirements (CR-001, CR-002, …) with Given/When/Then acceptance criteria, published into spec.md so that planning and task generation treat them like functional requirements.\nSixteen deterministic checks that keep the chain from goal to verified control complete, with Markdown, JSON, and SARIF output for code scanning.\nEvidence-based convergence: after implementation, each requirement is judged from tests, reviews, or micro attack simulations. Verified controls, measured bypass rates, and gaps flow back into the tree and into tasks.md.\n#\nHow it fits Spec Kit\nAttackTree adds four commands. Each runs at a natural point of the Spec Kit lifecycle, and optional hooks can prompt for them automatically.\nAfterRunResult\n/speckit-specify/speckit-attacktree-modelthe attack tree and the CR-### block in spec.md\n/speckit-plan/speckit-attacktree-model --from-plan, then /speckit-attacktree-simulateconcrete attack vectors and a control roadmap\n/speckit-tasks/speckit-attacktree-checka gap report from goals to tasks\n/speckit-implement/speckit-attacktree-convergeverified controls, residual risk, remediation tasks\nThe agent does what needs judgement: reading the spec, proposing attacks and controls, and judging evidence. The engine, a single Python script, does all the arithmetic and bookkeeping. It needs no LLM, so the same checks and simulation run in CI.\n#\nWho it is for\nTeams using Spec Kit who want security designed in at the spec stage, not bolted on at review.\nSecurity architects who already run attack tree or threat modelling workshops and want the result to live in the repository, stay current as the spec changes, and connect to tasks and tests.\nBuilders of LLM and agentic features, where prompt injection, tool misuse, and probabilistic guardrails make path-based reasoning essential. See Agentic and LLM systems.\n#\nNext steps\nInstall the extension.\nRun the quickstart on the shipped example in five minutes.\nLearn how attack trees work if the method is new to you."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/otm/","title":"Open Threat Model interop","description":"Seed AttackTree goals and assets from an Open Threat Model (OTM) file exported by other threat modelling tools, link goals back to threats, and track drift.","body":"The Open Threat Model (OTM) is a tool-neutral format for threat models. IriusRisk created it, and its open-source StartLeft converter produces OTM from Terraform, CloudFormation, and diagram formats. If your team already keeps a threat model in OTM, AttackTree can start from it instead of from a blank page. OTM interop is off by default.\n#\nEnable it\nPoint model.otm at the file, relative to the feature directory or the repository:\n#\nWhat it does\nSeeding. The model command calls attacktree.sh seed, which reads the OTM file and proposes:\none asset per OTM asset, with ids normalised to asset.&lt;slug&gt;;\none candidate goal per rated, non-retired threat, with impact derived from the threat’s impact score and links.threats pointing back to it.\nThe agent then merges candidates that describe the same attacker outcome, drops threats that are weaknesses rather than goals (recording them under attacktree.exclusions with a reason), defines the actors (OTM has no actor entity), and builds the paths.\nLinks. Goals and nodes may carry links: { threats: […], mitigations: […] } with ids exactly as the OTM file spells them. Check A13 reports links to entities that no longer exist.\nDrift. The OTM file is hashed with spec.md and plan.md. When it changes, check A11 asks you to refresh the tree.\n#\nSeed by hand\nseed never writes attack-tree.yaml; it prints or saves a starting point for the model command."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/profiles/","title":"Profiles","description":"AttackTree profiles supply the scales the engine computes with and libraries of actor archetypes, attack vectors, and controls: the default and agentic profiles, and how to write your own.","body":"A profile is a YAML file in profiles/. It supplies two things:\nScales the engine computes with: capability levels, complexity, cost tiers, requires tags, control effect and cost levels, impact classes, likelihood levels, and the risk matrix.\nLibraries the model command draws on: actor archetypes, attack vector proposals, control proposals, and, for agentic systems, zones. Proposals are a checklist for the agent, never inserted automatically.\nActivate profiles with profiles in the configuration. A tree records the profiles it was built with in attacktree.profiles, and that list wins over the configuration. The default profile’s scales always apply; other profiles add libraries on top.\n#\ndefault\nPartContents\nScalesthe values documented in Risk model\nrequires tagsauthenticated, insider-access, privileged-access, special-equipment, long-duration, illegal, physical-presence, violence\nActor archetypes8, following Christian Schneider’s scenario-driven set: script kiddie, hacktivist, outside and inside attacker groups, social engineer, compromised employee, malicious administrator, state-sponsored group\nVector proposals20 common attacks, from credential stuffing and SQL injection to dependency compromise and bribery, with MITRE CAPEC, CWE, and ATT&amp;CK references\nControl proposals16 safeguards with default kind and effect and OWASP ASVS 4.0.3 references (one, immutable backups, cites NIST CSF)\nThe ASVS references use the key asvs-4.0 because ASVS 5.0 renumbered every chapter. Edition-pinned keys keep references meaningful when standards move.\n#\nagentic\nPartContents\nZonesinput, reasoning, tools, memory, inter-agent\nActor archetypes4: author of content the agent reads, publisher of a malicious tool or MCP server, model-assisted adversary, compromised peer agent\nVector proposals15, with OWASP Top 10 for LLM Applications 2026, OWASP Top 10 for Agentic Applications 2026, MITRE ATLAS, and MAESTRO references\nControl proposals16: 11 deterministic (tool pinning, allowlists, credential isolation, sandboxing, recursion caps, …) and 5 probabilistic (injection classifier, goal-lock check, human-in-the-loop, output guardrail, behaviour monitoring)\nSee Agentic and LLM systems for how to use it.\n#\nWrite your own\nAdd profiles/&lt;id&gt;.yaml to the extension, in an installed project .specify/extensions/attacktree/profiles/. Give it a unique profile.id and add the id to profiles. Keep the file under version control elsewhere too: specify extension update replaces the extension directory. To change the arithmetic, declare only the scales keys you change; everything else comes from default:\nKeep it consistent: every complexity maps to a defined skill, every requires tag names defined capability levels, and every risk-matrix row covers every impact level. attacktree.sh validate rejects trees that use a requires tag no active profile defines."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/quickstart/","title":"Quickstart","description":"Run AttackTree on the shipped example in five minutes, then build your first attack tree for your own feature with a coding agent.","body":"This quickstart has two parts. First, run the engine on the example that ships with the repository to see what an attack tree produces, with no agent needed. Then build one for your own feature.\n#\nPart 1: explore the example\nThe example is an internal assistant that answers employee questions from a knowledge base and can open support tickets. Its attack-tree.yaml is a realistic first pass: four actors, six goals, 23 attack vectors, and 14 proposed controls.\nIf python3 -c \"import yaml\" fails, use uv run --with pyyaml python instead of python3 in the alias.\n#\nSimulate the tree as it stands\nNo control is built yet, so this is the undefended picture. Four of six goals are at critical risk. Look at goal.read-restricted-documents: its most likely path is an employee who asks a question that only a restricted document answers, with the assistant quoting that document. The path has a likelihood of 70 % × 85 % = 59.5 %. The report also lists node.rrd-reach as an uncovered choke point: every path to that goal crosses it, and no control sits there yet.\n#\nAsk a what-if question\nThe what-if table ranks control.visibility-filtered-retrieval first. It is attached to that choke point. Check what building it would change:\nThe critical goal drops to likelihood 0: one control cut every path. Compare --scenario all, which counts every proposed control. Two goals stay high even then, which means the tree needs more controls on those goals. That is exactly the conversation a simulation should start.\n#\nRun the checks\nThe report has two findings. One node needs clarification, because the spec does not say whether administrators can export the knowledge base. Fourteen requirements have no verification yet, which is expected before implementation. Try --format sarif to see the output code scanning consumes.\n#\nRead the rendered tree\nOpen examples/agent-assistant/specs/001-agent-assistant/attack-tree.md. Each goal has an outline, a Mermaid diagram with its controls, and its paths. GitHub renders the diagrams inline.\n#\nPart 2: your own feature\nIn a Spec Kit project with the extension installed:\nSpecify the feature as usual with /speckit-specify.\nModel it: run /speckit-attacktree-model. The agent reads spec.md, defines actors, goals, paths, and controls, and validates the tree through the engine. It then writes attack-tree.yaml and attack-tree.md and inserts the CR-### block into spec.md. Answer its open questions with /speckit-clarify.\nPlan with /speckit-plan, then run /speckit-attacktree-model --from-plan. The second pass attaches attacks and controls to the files and components in the plan.\nSimulate with /speckit-attacktree-simulate. Decide which controls to build and set them to status: planned in attack-tree.yaml.\nGenerate tasks with /speckit-tasks, then run /speckit-attacktree-check to confirm every control requirement has a task.\nImplement with /speckit-implement, then run /speckit-attacktree-converge. The agent judges each requirement from the evidence and records the verdicts. Gaps become new tasks in tasks.md.\nRepeat steps 5 and 6 until converge reports CONVERGED.\nWant every step prompted automatically? Enable the hooks, or install the attacktree-sdd workflow, which runs the whole cycle with review gates.\n#\nWhere to go next\nAttack trees explains the method behind the numbers.\nSimulation explains every section of the simulation report.\nCI shows how to gate pull requests on residual risk."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/releasing/","title":"Releasing","description":"Maintainer checklist for releasing AttackTree: version bumps, the release workflow, install verification, and submission to the Spec Kit community catalog.","body":"For maintainers. The checklist follows Spec Kit’s publishing guide and its Extension Submission issue template.\n#\nBefore tagging\nGuide requirementWhere it is satisfied\nextension.yml with valid id, semver, short description, public repository URL, 2–5 lowercase tagsextension.yml; enforced by tests/test_manifest.py\nREADME.md with overview, installation, configuration, usage, troubleshooting, contributingREADME.md, with details on this site\nLICENSE (permissive) and CHANGELOG.mdboth at the root\nCommand files exist for every declared command and reference siblings only through __SPECKIT_COMMAND_*__ tokenscommands/; enforced by tests\nConfig template with documented options and defaultsconfig-template.yml, config.defaults in the manifest; the tests check the two agree\nNo hardcoded secrets, validated inputs, trusted dependenciesPyYAML only; jsonschema optional; $ARGUMENTS never reaches a shell\nVersion bumped on every content changeRelease workflow refuses a tag whose version differs from the manifest\n#\nRelease\nThe site deploys itself from main through the Pages workflow; a release needs no extra step for it.\nBump extension.version in extension.yml, update CHANGELOG.md, and update version and download_url in catalog.json (the test suite checks they agree).\nTag and push:\nThe Release workflow runs the tests, builds attacktree-v0.1.0.zip, smoke-installs it with the Spec Kit CLI, and publishes a GitHub Release whose notes include the archive’s SHA-256.\nVerify the two install paths the guide expects:\n#\nSubmit to the community catalog\nFile an issue with the Extension Submission template. Do not open a pull request against catalog.community.json. Field values:\nFieldValue\nExtension IDattacktree\nExtension NameAttackTree — Attack Tree Modeling &amp; Control Simulation\nVersionfrom extension.yml\nDescriptionAttack trees with attacker profiles, AND/OR path simulation, control roadmaps, and control-to-test traceability\nAuthorhupe1980\nRepository URLhttps://github.com/hupe1980/spec-kit-attacktree\nDownload URLhttps://github.com/hupe1980/spec-kit-attacktree/archive/refs/tags/vX.Y.Z.zip\nLicenseMIT\nDocumentation URLhttps://hupe1980.github.io/spec-kit-attacktree/\nChangelog URLhttps://github.com/hupe1980/spec-kit-attacktree/blob/main/CHANGELOG.md\nRequired Spec Kit Version&gt;=1.0.0\nRequired ToolsPython 3 with PyYAML, or uv\nNumber of Commands4\nNumber of Hooks7\nTagssecurity, attack-trees, threat-modeling, risk-simulation, traceability\nKey Featuresattack-tree.yaml with actors, goals, AND/OR paths, controls; Schneier propagation with attacker profiles; choke points, single points of failure, what-if roadmap, seeded Monte Carlo; CR-### requirements published into spec.md; deterministic checks A1–A16 with SARIF; evidence-based convergence with measured bypass rates; seeds from and links to Open Threat Model files\nTesting checklistinstalls from the download URL (release workflow smoke test); commands executed on real projects; docs complete; no known vulnerabilities (see the security page)\nThe community catalog is discovery-only. Users either copy the entry into a catalog they trust or use the --from URL. The ready-made entry in catalog.json at the repository root is what a maintainer would paste.\n#\nSelf-hosted catalog\ncatalog.json is also a complete installable catalog. Teams can register it and install by name:\nSpec Kit ≥ 1.0.7 requires tag-pinned download URLs in catalogs, which is why download_url names a release tag rather than main."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/risk-model/","title":"Risk model","description":"How AttackTree computes likelihood, feasibility, control effects, actor occurrence, and residual risk, with a worked example and the full risk matrix.","body":"Every number in the simulation comes from a few documented rules. This page explains them with one path from the shipped example. The scales live in the default profile, so a team can change them without touching the engine.\n#\nLeaves: likelihood per attempt\nEach leaf states the probability that one attempt succeeds before any control, as an integer from 0 to 100. If likelihood is omitted, the leaf’s complexity supplies a default:\nComplexitySkill neededDefault likelihood\ntrivialnovice90\nlownovice75\nmediumintermediate50\nhighadvanced30\nextremeexpert10\n#\nFeasibility: who can run the leaf\nA leaf counts for an actor only when all three conditions hold:\nThe actor’s skill is at least the skill its complexity needs.\nThe actor’s resources cover the tier of its cost: up to 1,000 is minimal, up to 25,000 moderate, up to 250,000 substantial, and anything above extensive.\nThe actor satisfies each requires tag. For example, authenticated needs access: user or more, and illegal needs risk_appetite: medium or more.\nA capability an actor does not state never limits it. Check A15 reports incompletely rated actors.\n#\nGates: OR and AND\nAn OR node takes the best child path.\nAn AND node multiplies the likelihoods of its children, adds their costs, and is feasible only if a single actor can perform every step. Coalitions of actors are out of scope.\nEvery combination of choices through the OR nodes is a path, a set of leaves that together achieve the goal. The engine enumerates paths per goal, up to risk.max_paths per node. It keeps each actor’s most likely paths when it truncates and reports truncation as check A16.\n#\nControls: scaling the subtree\nA control attached to a node multiplies the likelihood of everything below that node by what survives it:\nEffectReductionSurvives\nlow25 %0.75\nmedium50 %0.50\nhigh80 %0.20\neliminates100 %0\nA control can state a different level per attached node with effects. Once a micro attack simulation has measured it, bypass_rate replaces the level: a 12 % bypass rate means 0.12 survives.\nWhich controls count depends on the scenario:\nScenarioActive controlsUsed for\nnoneno controlthe undefended baseline\ncurrentimplemented and verifiedtoday’s risk; the default\nplannedplanned, implemented, and verifiedthe risk after the agreed roadmap\nverifiedverified onlyconvergence: evidence, not claims\nallevery control not rejectedstructure: is any path uncovered?\n#\nActors: occurrence\nSome actors can run an attack but rarely target the system. An actor’s optional occurrence, from 1 to 100, scales every path that actor can run. A path’s likelihood is its raw likelihood times the occurrence of the most active actor able to run it. Schneier lists “likelihood that an attacker will try” as a value of its own. Leave occurrence at 100 unless you have a reason.\n#\nGoals: impact and residual risk\nA goal rates its impact per class: business, customer, data, compliance, and safety. The highest rating is the goal’s impact level. The goal’s likelihood is the likelihood of its best feasible path, which maps to a level:\nLevelLikelihood\nlowbelow 15\nmedium15 to below 40\nhigh40 to below 70\nvery-high70 and above\nLikelihood level and impact level give the residual risk:\nLikelihood ↓ / impact →lowmediumhighcritical\nvery-highmediumhighcriticalcritical\nhighlowmediumhighcritical\nmediumlowmediummediumhigh\nlowlowlowmediumhigh\nA goal no path can reach, with likelihood exactly 0, is low risk whatever its impact. A goal whose every path runs through an open question is unknown; see Unknowns.\n#\nWorked example\nGoal goal.read-restricted-documents in the example is an AND of two subgoals, getting restricted content into the model’s context and getting it out. Its impact is data: critical and compliance: high, so its level is critical.\nThe best way in is node.rrd-ask-directly: a curious employee asks a question only a restricted document answers. Complexity trivial, likelihood 70.\nThe best way out is node.rrd-answer-quotes: the assistant quotes the document. Likelihood 85.\nThe employee can do both, so the AND is feasible: 70 % × 85 % = 59.5, which is high.\nHigh likelihood × critical impact = critical residual risk.\nNow add control.visibility-filtered-retrieval (effect eliminates) on the choke point node.rrd-reach. Every way in is multiplied by 0, the goal’s likelihood becomes 0, and its risk becomes low. With a medium effect instead, the best path would be 70 × 0.5 × 85 % = 29.75, which is medium likelihood and high residual risk.\n#\nUnknowns\nA node with status: needs-clarification is a question the spec does not answer, such as “can administrators export the knowledge base?” It is not a rated step. The engine leaves it out of the evaluation, lists it as an assumption in the simulation, and reports it as check A14. A goal that can only be reached through open questions reports risk unknown: never low, never mitigated.\n#\nWhat the numbers are not\nThe ratings are informed estimates, and the arithmetic makes them consistent and comparable, not precise. Read likelihoods as levels and rankings. The Monte Carlo run shows how sensitive each goal is to the ratings, so you know which ones deserve a second opinion or a measurement."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/security/","title":"Security","description":"AttackTree's own threat model: prompt injection through artifacts, overwriting human content, command execution, manipulated simulations, and how each is controlled.","body":"AttackTree runs inside a coding agent with read and write access to your repository. This is its own threat model, in the shape it asks of others: goals, paths, controls, and status. Report a vulnerability through GitHub’s private vulnerability reporting.\n#\nActors and goals\nActors: the developer (privileged, trusted), other contributors to the repository (insider), authors of content the spec, plan, threat model, or code quotes (external, untrusted), package registries (external, semi-trusted).\nGoalImpactPathsControlsStatus\nG1 Make the agent record controls as verified, or goals as mitigated, that are notdata high, compliance high(a) instruction-like text in spec.md, plan.md, an OTM file, code, tests, or fetched pages steers the agent (indirect prompt injection); (b) $ARGUMENTS carries instructions; (c) a hand-edited attack-tree.yaml sets status: verifiedevery command treats artifact content as data and quotes suspicious text under “Unverified”; arguments only select scope and never reach a shell; verified needs an evidence pointer the engine checks; control and goal status are computed by converge-apply, never asserted; check A12 flags a verified claim without a passing verification entry(a) mitigated by prompt discipline, residual risk remains because LLM adherence is probabilistic; (b), (c) mitigated\nG2 Overwrite human-authored content in spec.md or tasks.mdbusiness mediumthe CR block insertion or the appended convergence phase touches text outside its scopewrites are confined to the &lt;!-- attacktree:begin/end --&gt; markers, first insertion goes before ## Success Criteria; tasks.md is append-only and byte-for-byte unchanged when converged; both covered by testsmitigated\nG3 Run arbitrary commands through the extensionbusiness highverification.test_command in the config executes; the uv run --with pyyaml --with jsonschema fallback pulls packages from PyPI at first useempty by default; runs only when converge is invoked with --run-tests, only the configured command, once; the engine itself never executes it; the config is versioned and reviewable; the wrapper uses uv only when no local Python with PyYAML existsaccepted: the config is developer-owned, same trust as any project script; version pins for the fallback are on the roadmap\nG4 Make the simulation liebusiness mediuma tree whose ratings or control effects were chosen to pass; a bypass_rate recorded without a real measurementthe numbers are only as good as the ratings, and the commands say so; the check command’s S5 pass questions implausible ratings; bypass_rate is written only by converge-apply from a verdict that carries an evidence pointer; history is append-only and reviewable in diffspartially mitigated: the engine does not open the evidence\nG5 Read files outside the repositorydata mediumattacktree.extends or --otm points outside the repositorythe engine only reads YAML at those paths; rejection of paths outside the repo root is on the roadmapopen, low\nG6 Leak secrets or instruction blocks into rendered artifactsdata mediumthe model command copies a secret or a system prompt into attack-tree.yaml or attack-tree.mdcommands forbid verbatim reproduction; the renderer only emits tree fieldsmitigated by prompt discipline\nG7 Run AttackTree without the developer noticingbusiness lowa project makes a hook mandatoryall hooks ship optional: true; changing that is an explicit, versioned edit of .specify/extensions.ymlmitigated\n#\nVerification\nTests cover G1(c) (A12, verified without evidence rejected, status roll-up), G2 (marker confinement, append-only tasks), and G4’s write path (bypass rates only through verdicts). G1(a) and G6 rely on prompt discipline and should be exercised with adversarial fixtures (a spec containing injected instructions) as part of the v0.2 test suite. G3 and G5 are tracked for v0.2."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/simulation/","title":"Simulation","description":"What the AttackTree simulation reports: most likely and cheapest paths, choke points, Achilles heels, single points of failure, what-if and defence in depth, the roadmap, and Monte Carlo.","body":"/speckit-attacktree-simulate, or attacktree.sh simulate in CI, evaluates the tree for a scenario and writes one report. This page explains each section and what to do with it.\n#\nGoals\nOne row per goal: impact, the likelihood and level of its best path, residual risk, the strongest actor, the number of paths, how many of them have no control, the choke points, and the most likely path.\nAct on: goals at a risk level listed in risk.block_on (default: critical). The simulation exits with code 1 while any of them lacks an unexpired decision.\n#\nPaths\nUp to ten paths per goal, ordered by likelihood. Each shows its leaves, likelihood, cost, the actors who can run it, and the controls on it. (accepted) marks paths through a node covered by a risk decision.\nRead for: the story. “An employee asks directly and the assistant quotes the document” is the sentence to put in front of the team.\n#\nChoke points and uncovered choke points\nA choke point is a node that every feasible path to a goal crosses. A control there covers every path at once. An uncovered choke point has no active control, and it is usually the single best place to invest.\n#\nAchilles heels\nLeaves ranked by the share of paths that use them, weighted by those paths’ likelihood. A leaf used by most paths is worth a specific control even when it is not a choke point.\n#\nSingle points of failure\nActive controls whose removal alone raises a goal’s risk level. They are what your defence rests on. Christian Schneider’s rule of thumb is that every high-priority node should have at least two independent controls. A probabilistic control that is a single point of failure on a critical goal deserves both a second control and a measurement.\n#\nWhat-if\nEvery control that is not active in the scenario, applied one at a time:\nColumnMeaning\nRisk reductionImpact-weighted drop of the goals’ best-path likelihoods.\nDepth reductionImpact-weighted drop of the sum of all path likelihoods, including alternative paths.\nEfficiencyRisk reduction divided by the control’s cost weight: low 1, medium 3, high 9.\nClassQuick win, strategic, fill-in, deprioritize, defence in depth, or no effect.\nQuick wins reduce at least the median risk at low or medium cost, strategic controls do so at high cost; fill-ins and deprioritized controls are their below-median counterparts. Defence in depth marks a control that lowers no goal today, because the attacker’s best path goes elsewhere, but cuts alternative paths. It is worth nothing until the best path is closed, and exactly what closes the next one.\n#\nRoadmap\nA greedy order: repeatedly add the control with the most risk reduction per cost, and show every goal’s residual risk after each step. Use it to agree which controls to set to planned, then re-run with --scenario planned to confirm the result.\n#\nMonte Carlo\nRatings are estimates, so the simulation also samples them. Each leaf’s likelihood is drawn from a triangular distribution around its rating, bounded by its likelihood_range or by ± simulation.likelihood_spread points. Each probabilistic control’s surviving fraction is jittered by ± 0.15. The report gives the mean, the median (P50), the 90th percentile (P90), the probability of at least a high likelihood, and the drivers: the leaves whose sampled values correlate most with the goal’s outcome.\nAct on: goals whose P90 lies a level above their mean, and their drivers. Those ratings decide the outcome and deserve a second opinion or a measurement. Runs are reproducible for a given simulation.seed.\n#\nWhat-if from the command line\nNone of these changes attack-tree.yaml. The CLI reference lists every flag."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/troubleshooting/","title":"Troubleshooting","description":"Fixes for common AttackTree problems: missing Python runtime, feature detection, YAML parse errors, rejected merges, infeasible or unknown goals, truncation, and drift.","body":"SymptomCause and fix\nattacktree: no Python runtime with PyYAML foundInstall PyYAML (pip install pyyaml) or uv. The wrappers try python3, then python, then uv run --with pyyaml --with jsonschema.\nattacktree: no feature directory foundPass --feature-dir specs/&lt;feature&gt; before the subcommand, or set SPECIFY_FEATURE. The engine tries the flag, then SPECIFY_FEATURE, then the git branch name, then the newest specs/*/spec.md.\nYAML parse error … quote any scalarA value containing : , #, or starting with [ is unquoted, typically a [NEEDS CLARIFICATION: …] name. Quote it and re-run merge.\nmerge rejected, N validation error(s)The incoming tree references an id that does not exist, has a parent cycle, or puts an attack block on a node with children. The errors name the entity; fix the file rather than bypassing validation.\ncannot simulate, N validation error(s)Same cause; the simulation refuses to run on a broken tree. Run attacktree.sh validate attack-tree.yaml.\nA goal has no feasible path although it has leavesNo modelled actor can perform the steps: skill, resources, and requires tags rule them out, or an AND needs steps that no single actor can do. The rendered outline shows each leaf’s actors and requirements.\nA goal’s risk is unknownEvery path to it runs through a needs-clarification node. Answer the question with /speckit-clarify and re-run the model command.\ntruncated in the simulation, or check A16A subtree has more paths than risk.max_paths. Raise the limit, or split the goal into smaller goals. The best paths per actor are always kept.\nCommands do not appear in the agentRun specify extension list. If the extension is listed, restart the agent so it reloads its commands or skills.\nA11 drift right after editing spec.mdExpected: re-run the model command so the hashes match. Rendering the CR-### block, or another extension’s managed block, never counts as drift.\nConverge reports never hashedThe tree predates source hashing. Run the model command once.\nA control keeps falling back from verified to implementedCheck A12: a control counts as verified only while all its requirements have a passing verification. Run converge with evidence for the missing requirement."},{"url":"https://hupe1980.github.io/spec-kit-attacktree/docs/workflow/","title":"Workflow","description":"Use AttackTree across the Spec Kit lifecycle: two modelling passes, simulation before tasks, checks before implementation, convergence after, plus hooks, the companion preset, and the workflow.","body":"AttackTree adds four commands to Spec Kit. Nothing changes until you run one or enable a hook.\n#\nTwo modelling passes\nAfter /speckit-specify, the tree captures who wants what: actors, goals, and the paths visible from user stories and requirements. Control touchpoints still name components. After /speckit-plan, the second pass (--from-plan) ties attacks to where they land, such as endpoints, tools, and stores, and turns touchpoints into file paths.\nBoth passes are incremental. Ids stay stable. The status, evidence, bypass rate, and notes of existing entities, decisions, and verification history are owned by humans and by converge, so the merge keeps them whatever the agent writes. Goals and nodes that disappear are retired, not deleted.\n#\nChoosing controls\nThe model proposes controls with status: proposed. People decide what gets built. Read the simulation, agree on a roadmap, and set the chosen controls to planned (or rejected) in attack-tree.yaml. simulate --scenario planned then shows the risk the roadmap leaves. Converge moves controls to implemented and verified from evidence; nobody edits those statuses by hand.\n#\nAccepting risk\nNot every path gets a control. A decisions[] entry accepts or transfers the risk of a goal, or of every path through a node, with an owner, a rationale, and an expiry date. An unexpired decision stops a goal from blocking. An expired one protects nothing, and check A10 reports it. The agent never creates decisions on its own; it proposes them.\n#\nHooks\nSpec Kit lists installed hooks in .specify/extensions.yml. All ship with optional: true: the core command asks whether to run the AttackTree command, and you decide. Set optional: false to make one automatic.\nEventRunsWhy\nafter_specifymodelfirst pass\nafter_clarifymodelrefresh after the spec changed\nafter_planmodelpass over the plan\nafter_taskscheckevery requirement has a task\nbefore_implementsimulatecurrent and planned risk; blocks on blocking goals under enforcement: strict\nafter_implementconvergeevidence-based verification\nbefore_convergeconvergehands remediation tasks to core convergence\nEach AttackTree command also dispatches its own hook points, before_attacktree_&lt;command&gt; and after_attacktree_&lt;command&gt;, so other extensions can chain onto it.\n#\nCompanion preset\nThe attacktree-sdd preset appends one section to four core commands:\ntasks creates an implementation task and a test task per CR-###, tagged [CR-###], ordered by the roadmap.\nanalyze inventories CR-### next to FR-### and SC-###, reports requirements without tasks, and flags statements without a testable acceptance scenario.\nconverge takes requirement verdicts from AttackTree’s convergence report instead of judging from checkboxes.\nchecklist offers a security-controls checklist built from acceptance scenarios and validation steps.\nWithout the preset, AttackTree’s check and converge commands are still the authoritative passes; the core commands simply do not know about CR-###.\n#\nLinking tasks\nA task counts for a requirement only when it carries the bracket tag, as in - [ ] T031 [US1] [CR-002] Filter retrieval by visibility, or a comma list such as [CR-001, CR-003]. A prose mention like “CR-001 to CR-014” links nothing, so ranges cannot fake coverage.\n#\nFiles written\nCommandWrites\nmodelattack-tree.yaml, attack-tree.md, the CR-### block in spec.md, working files in security/\nchecksecurity/attacktree-check-report.md with --persist\nsimulatesecurity/attacktree-simulation.{md,json} with --persist\nconvergeattack-tree.yaml (verification, statuses, bypass rates), attack-tree.md, security/attacktree-*, an appended phase in tasks.md\nplan.md and OTM files are never written, and tasks.md is append-only. Inside spec.md, only the block between &lt;!-- attacktree:begin --&gt; and &lt;!-- attacktree:end --&gt; changes.\n#\nRunning the whole cycle\nThe optional attacktree-sdd workflow runs specify, model, plan, model from plan, simulate, tasks, check, implement, converge, and core converge in order. It pauses for review after the tree, after the simulation (so the team picks the controls), and after the gap check:"}]