⚠️ Beta: not production ready.appsec-advisoris under active development. Interfaces, schemas, and output may change without notice.
appsec-advisor is a Claude Code plugin for automated, code-derived threat modeling. It reconstructs application components, data flows, and trust boundaries from code and configuration, then applies STRIDE to identify threats in the implemented architecture. Findings reference repository evidence and include remediation guidance.
The Threat Analyst covers the design side: on request, it analyzes a planned feature or a selected code change for threats and asks the team for missing design facts. The plugin also includes requirements audits, change reviews, and CI gates.
Why appsec-advisor? · Security · Quick start · Threat Modeler · Threat Analyst · Requirements Audit · Developer tools · Report a failed run · Enterprise rollout · Documentation · Product requirements · What's new in 0.6.0-beta.5 · Contributing
appsec-advisor prepares threat models from code and configuration. It does not replace collaborative threat modeling with the people who own the system. You do not need an existing threat model or a workshop to start.
| Threat Modeler | Collaborative threat modeling | |
|---|---|---|
| Works from | Code, configuration, and supplied context | Design intent, business context, and knowledge of runtime and production controls |
| Delivers | Architecture, trust boundaries, and threats; every finding cites repository evidence | Judgment on which threats matter and which assumptions hold |
| Strength | Covers the whole repository the same way on every run | Sees what the code cannot show |
| Leaves open | Business impact, risk acceptance, and controls outside the repository | Consistent coverage of a large or fast-changing codebase |
Run the Threat Modeler for a first assessment and again when code or configuration changes. Before code exists, the experimental Threat Analyst prepares the team discussion of a planned feature with threat scenarios, protection assumptions, and open questions. It also reviews single changes and reports evidence-backed findings.
The code cannot tell the tool which networks you trust or which data is critical to your business. You add that as business context and trust-boundary declarations, and the analysis then treats them as stated assumptions.
Results come as Markdown and YAML, with optional PDF, HTML, SARIF, Threat Dragon, and pentest-task exports. Organizations can add their own requirements and tools without maintaining a fork of the core analysis pipeline. See Enterprise rollout.
The assessment uses evidence from the analyzed repository and supplied context, including configured related-repository models. It cannot verify runtime behavior or production-only controls. An AppSec engineer or security architect should validate findings before they drive remediation or risk acceptance.
Important
Treat scanned repositories as untrusted input. Repository content enters the LLM context and may attempt prompt injection. Untrusted mode is the default; keep it enabled and use a container or VM for third-party or vendor code. See Security: Untrusted repositories.
Data handling. Source, manifests, and configuration for analyzed components are sent to Anthropic. Surfaced secrets are masked. The plugin requires api.anthropic.com, cannot run air-gapped, and uses provider-side prompt caching.
Python renders reports from validated structured data. If a run artifact contains an unmasked secret, the run fails before its outputs are considered publishable.
Requires Claude Code, Python 3.10+, and git on PATH. Optional Mermaid dependencies provide stricter diagram validation; see the Threat Modeler reference.
For most repositories, run the Claude Code session on Sonnet 4.6. The orchestration session remains active for the full assessment and therefore has the largest effect on cost. Agent models are routed separately: a standard scan uses Sonnet 5.5 for judgment and report authoring, while STRIDE discovery remains on Sonnet 4.6. A multi-repository assessment runs STRIDE on Sonnet 5.5 instead. Very large repositories may require a Sonnet 5.5 session for the larger context window. See when to use the latest Sonnet.
Add the marketplace and install the plugin. This installs the current release from main and needs no checkout. If GitHub SSH access is not configured, run export CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 in your shell before installing or updating to use HTTPS for both the marketplace and plugin downloads:
claude plugin marketplace add appsec-foundry/appsec-advisor
claude plugin install appsec-advisor@appsec-foundryLater releases arrive with claude plugin update appsec-advisor@appsec-foundry, which takes effect after a restart. /appsec-advisor:status --check-updates compares the core version against the release branch.
Then start Claude Code from the repository you want to assess:
cd /path/to/repository-to-assess
claudeTo run the development branch instead of a release, clone the repository and start Claude Code with the checkout:
git clone --branch dev https://github.com/appsec-foundry/appsec-advisor.git /path/to/appsec-advisor
cd /path/to/repository-to-assess
claude --plugin-dir /path/to/appsec-advisorRun the one-time permission setup:
/appsec-advisor:check-permissions --update
The command adds the missing rules, including Bash(*), to this repository's .claude/settings.local.json. Without them the assessment stops before it starts, unless your settings set defaultMode to auto or bypassPermissions.
Restart or reload Claude Code, then create the model:
/appsec-advisor:create-threat-model
The assessment writes threat-model.md and threat-model.yaml to docs/security/.
# Ask about the model in plain language
what are the most critical findings?
how well is authentication protected?
what should I fix first?
# Fix findings, accept their risk, or build a remediation plan
/appsec-advisor:review-threat-model
# Analyze a planned feature or your current changes
/appsec-advisor:analyze-threats Let support staff export customer data as CSV.
/appsec-advisor:analyze-threats --worktree
# Reassess after code changes while preserving history
/appsec-advisor:create-threat-model --full
# Optionally publish a reviewed model to version control
/appsec-advisor:publish-threat-model
Updates preserve finding IDs. Review decisions are stored separately. Run /appsec-advisor:help for the complete command list.
Run /appsec-advisor:create-threat-model to get:
- an architecture model with components, data flows, and trust boundaries;
- findings ordered by risk and tied to repository evidence;
- a Weakness Register for systemic and design patterns;
- abuse cases checked against the code, including your own one-sentence business rules in
docs/security/abuse-cases/; - mitigation guidance and generated diagrams;
threat-model.mdandthreat-model.yaml, with optional PDF, HTML, SARIF, Threat Dragon, and pentest-task exports.
The report links findings to the OWASP Top 10:2025. If the repository contains an LLM or agentic application, it also checks the relevant OWASP LLM and Agentic Applications categories.
The Threat Modeler guide covers depth, focused scans, repository context, exports, costs, and limits.
Example: Read a thorough assessment of OWASP Juice Shop or browse more examples.
Figure 1a shows the runtime components, data flows, and attack paths identified in OWASP Juice Shop.
For repositories with a build pipeline, Figure 1b links build inputs and release artifacts to the most severe supply-chain attacks and the relevant controls.
Figure 2 connects threat actors through example attack routes and the linked weaknesses to the potential business harm.
Assessments consume model tokens and usually take tens of minutes; thorough runs may exceed an hour. See assessment depth and cost control for measured costs.
An abuse case describes something an attacker or a user must not be able to do. The plugin ships two kinds:
- Technical attack chains, for example: inject a script into a page, read the session token, and log in as the victim.
- Business rules, for example: a customer must not see another customer's orders, and a request must not skip its approval.
Each run finds the code behind these operations and checks whether the rule holds. The result changes the findings:
- The code breaks a rule and no finding covers it yet: the run adds one, for example for an order endpoint that loads an order by its ID without checking who owns it.
- A finding already covers it: the case is linked to that finding, and a finding whose evidence was ambiguous is shown as verified.
- Every step of an attack chain holds: its findings can be raised to the impact the case declares, such as Critical for a path to an admin account.
- The code does not settle the question: §9 lists the case as open, not as safe, and it can become a question for your team.
You can add your own cases. For a rule in one repository, put a YAML file into docs/security/abuse-cases/. One sentence and a file-name pattern are enough:
schema_version: 2
abuse_cases:
- id: REPO-AC-001
kind: descriptive
title: Employee approves their own expense report
check: Check whether an employee can approve an expense report they submitted.
scope_qualifier: {path_patterns: ["*expense*"]}The next run checks this rule in files such as ExpenseController.java or below expenses/. Repository abuse cases explains when a case runs and how its result is reported. To apply cases to every repository of your organization, add them to an organization profile. Abuse cases in organization profiles also covers technical attack chains, turning off built-in cases, and failing a CI run on a confirmed case.
/appsec-advisor:abuse-cases lists the defined technical and business abuse cases with their origin: plugin, organization profile, or repository. /appsec-advisor:analyze-threats --abuse-case <ID> checks one case against the code without a full assessment, with the existing threat model as context or, with --isolated, without it. /appsec-advisor:create-threat-model --only-abuse-case <ID> runs a new full assessment that checks only the selected cases; it replaces the existing threat model. /appsec-advisor:ask-threat-model reports how each case turned out.
This mode is experimental: expect rough edges, and review its results more closely than those of a single-repository scan.
To assess several local checkouts as one system, repeat --repo in the headless runner. Every selected repository is scanned freshly, and the run produces one threat model, one report and one Figure 1. Run it from the plugin checkout and replace the example paths with your checkouts and report location:
./scripts/run-headless.sh \
--repo /repos/frontend \
--repo /repos/backend \
--repo /repos/worker \
--output /reports/order-system \
--soft-budget 40A combined run has these requirements:
- Select 2–16 top-level Git checkouts that do not contain each other.
- Choose an
--outputdirectory outside every selected checkout. - Set
--soft-budgetor--hard-budget. The run stops when the budget is exhausted.
A combined run uses Sonnet 5.5 for STRIDE at quick and standard depth instead of Sonnet 4.6, because Sonnet 4.6 returns no STRIDE result in this mode. STRIDE calls therefore cost more than in a single-repository scan. The run prints each role's model at the start and warns about this change. See Assess several repositories as one system.
Components, findings and exports name the repository they come from, for example Order API [backend] and backend/src/orders.ts:42. The order of the --repo flags does not matter, and no repository takes precedence. A connection between repositories appears only when source evidence supports it, and repository membership never creates a trust boundary. The run supports full assessments and --resume of an interrupted run whose sources and settings are unchanged; --incremental, --rerender and --rebuild are not available for combined runs. See non-interactive mode for details and limits.
To keep separate reports instead, run one assessment per repository with its own --output directory. Configure docs/related-repos.yaml in a repository to include existing dependency models as cross-repository context. These imports inform the local analysis; they do not rescan dependency source code.
Run /appsec-advisor:analyze-threats before or while you build a feature. It reports:
- likely threats to the planned feature or the selected change;
- recommended controls or design choices, with their trade-offs;
- the security requirements that apply to it;
- assumptions it made and questions the team needs to answer.
The report is advisory and does not change threat-model.yaml. The Threat Analyst is experimental.
| When | Command |
|---|---|
| Before coding | /appsec-advisor:analyze-threats Let support staff export customer data as CSV. |
| During implementation | /appsec-advisor:analyze-threats --worktree --question "Can a tenant read another tenant's export?" |
| Before merging | /appsec-advisor:analyze-threats --base <target-branch> --head HEAD |
Add --explore when the answer depends on code you cannot name: the analysis then reads a redacted copy of the tracked files, without tools that run commands or write files. The Threat Analyst guide covers exploration, staged changes, saved answers, the advisory CI job, and limitations.
/appsec-advisor:audit-security-requirements checks the repository against an AppSec requirements catalog. It provides a faster control assessment for pull-request gates, compliance dashboards, and audit preparation.
# Use the configured catalog
/appsec-advisor:audit-security-requirements
# Use a catalog URL for this run
/appsec-advisor:audit-security-requirements --requirements https://appsec.int.example.com/appsec-requirements.yaml
If you do not have a catalog, adapt data/appsec-requirements-fallback.yaml or use the requirements harvester. See the Requirements Audit reference for setup and options.
| Tool | Use |
|---|---|
| Secure-coding baseline | Install, update, verify, or remove secure-coding instructions with install-baseline, update-baseline, verify-baseline, and remove-baseline. |
| Security Coach (experimental) | Add security guidance while writing security-sensitive code. |
| appsec-reviewer (experimental) | Embed change review in Claude Code or an Agent SDK workflow. |
| verify-requirements (experimental) | Review an interactive diff against the requirements catalog. |
| appsec-reviewer-cli (experimental) | Run the same change review in CI or other automation. |
See the developer tools guide for commands and configuration.
The security score checks a repository without building a threat model. It returns a score from 0 to 100, undetermined if too few checks apply, or incomplete without a score if a required scanner fails or emits invalid output. Findings and diagnostics remain visible in every verdict. You need Python 3.10+, PyYAML, jsonschema, and git.
/appsec-advisor:security-score
For CI or other automation, run the script from a plugin checkout:
python3 /path/to/appsec-advisor/scripts/analyzers/security_score.py --repo /path/to/projectBoth accept the same options. --repo also accepts an HTTPS GitHub or GitLab Git URL. Use --json or --yaml for structured output validated against schemas/security-score.schema.yaml. Exit codes are 0 for a score, 2 for insufficient coverage, and 1 for incomplete execution or an error. Compare commits only with matching scoring versions, catalog fingerprints, and applicable coverage in comparability. Findings without a scored baseline and findings excluded by severity policy are disclosed separately.
Run the scanner for findings, endpoints, and detected technologies without building a threat model. You need Python 3.10+, PyYAML, jsonschema, and git.
python3 /path/to/appsec-advisor/scripts/analyzers/repo_scan.py --repo /path/to/project--repo accepts a local directory or an HTTPS GitHub or GitLab Git URL. Use --high to show only High and Critical findings, or --json scan.json to save a JSON report. See --help for scan selection.
Investigate a suspected plugin error and prepare a minimal issue draft with:
/appsec-advisor:report-error
The skill checks the plugin cause locally and distinguishes source inspection from an executed neutral reproduction. It shows the complete issue draft before asking for permission to publish it to appsec-foundry/appsec-advisor. Raw logs, project source, findings, and diagnostic attachments are excluded. Review the draft for remaining internal names; your GitHub account remains visible as the issue author. Publication requires an existing GitHub CLI login.
Use /appsec-advisor:report-error --bundle-only for the local diagnostic archive workflow. Log scrubbing is best effort; inspect the entire archive before sharing it manually. Unattended scans never ask questions or publish issues.
AppSec and Platform teams can supply organization-specific requirements, defaults, guardrails, skills, hooks, and MCP servers. The organization packaging template keeps this configuration in a separate internal package built from a pinned upstream release. Core agent definitions remain upstream-owned.
See Internal Plugin Packaging and Organization Profiles.
| Goal | Start here |
|---|---|
| Run or configure a threat model | Threat Modeler |
| Analyze a planned feature or selected code change | Threat Analyst |
| Configure models, cost, or logging | Configuration and Model Selection |
| Configure requirements audits | Requirements Audit |
| Run an existing plugin checkout without interaction | Non-interactive Mode |
Agents inspect the repository and perform the security analysis. Deterministic Python validates structured artifacts, renders reports, generates exports, and enforces release gates. Schemas define the data exchanged between pipeline stages.
The main directories are agents/, skills/, scripts/, schemas/, templates/, and tests/. See the repository layout for the complete map and the tests required for each kind of change.
- appsec-advisor-tools provides a launcher and CI templates for unattended assessments. It provisions the plugin and target, then delegates the assessment to this plugin's headless runner.
- appsec-advisor-packaging-template builds organization-specific plugin packages from pinned upstream releases.
- aiscb contains the secure-coding rules bundled by the plugin.
| Project | Primary scope | Relation to appsec-advisor |
|---|---|---|
| tachi | Multi-agent analysis of an architecture description. | Tachi treats the description as its primary input; appsec-advisor derives the model from code and configuration. |
| stride-gpt | Provider-independent STRIDE analysis from a description or codebase. | stride-gpt supports several model providers; appsec-advisor runs in Claude Code and adds schema validation and stable finding IDs. |
| OWASP pytm | Threat models authored and maintained as Python code. | pytm requires developers to declare the model; appsec-advisor derives it from the implementation. |
| OWASP Threat Dragon | Visual threat modeling and editable data-flow diagrams. | Threat Dragon starts from a modeler-authored diagram; appsec-advisor can generate and export an initial model from a repository. |
| OWASP ThreatAtlas | Collaborative threat-modeling workshops on shared diagrams. | ThreatAtlas records the workshop model; appsec-advisor maintains a code-derived model between sessions. |
| OWASP Precogly | Program-level threat modeling, libraries, and compliance traceability. | Precogly acts as a maintained system of record; appsec-advisor produces a model for an individual repository. |
| Claude Security | Enterprise scanning for exploitable codebase vulnerabilities. | Claude Security focuses on implementation flaws; appsec-advisor also identifies architectural gaps without a single vulnerable line. |
The Threat Dragon export can carry generated models into Threat Dragon and ThreatAtlas.
Highlights from the 0.6.0 beta releases.
- New abuse-case catalog. The built-in catalog now covers business misuse, such as viewing other users' data or skipping an approval, alongside technical attack chains. Runs check both by default, and you can add your own cases as one sentence each. Reworked rules keep unrelated findings from inflating severity and report unchecked cases. See Abuse cases.
- New
/appsec-advisor:abuse-casescommand. It lists all abuse cases with their result and explains each one step by step. - Reworked Threat Analyst. It checks a single abuse case against your code (
--abuse-case <ID>), rates each attack step with evidence, and uses your existing threat model as context. See Threat Analyst. - Several repositories, one threat model. Repeat
--repoin headless mode to assess a system split across repositories in a single report. See Assess multiple repositories. - Report improvements. Critical findings are grouped by root cause with the fix for each group, the diagrams show trust boundaries more clearly, and secrets from your code are masked in every output.
- More accurate analysis. Reworked scanners fix missed detections and false positives, and standard and thorough runs use Sonnet 5.5.
-
Interactive runs propose the application's use case and its worst plausible business impact for confirmation, and save the answers in
docs/security/business-context.mdfor later analyses. The answers keep business-critical assets in scope and inform finding priority.
-
scripts/analyzers/repo_scan.pyruns standalone checks with severity filtering and endpoint and technology inventories; both it and/appsec-advisor:security-scoresupport local repositories and HTTPS GitHub/GitLab URLs, with YAML or JSON exports. -
Architecture and attack-route diagrams show technology, authentication evidence, attacker prerequisites, weaknesses, impact, and linked findings, with detail views for large architectures. Existing models need a new analysis to populate missing authentication evidence.
-
Malicious insiders and attackers holding a user's device now require opt-in through
.appsec/actors.yamlor the organization profile; otherwise, they are listed as not assessed. -
/appsec-advisor:report-errorinvestigates suspected plugin errors and prepares anonymised GitHub issue drafts for review and explicit publication approval;--bundle-onlykeeps diagnostics local. -
Fixes restore Config and IaC findings in reports and improve authentication checks, severity consistency, and run reliability. Security Score withholds a score when a required scanner fails or returns invalid output.
- Redesigned architecture diagrams show actors, services, assets, data flows, trust boundaries, weaknesses, and attack paths while preserving login and privilege requirements. Worst-case scenario tables show attack-path verification status.
- Management and completion summaries highlight up to three open threat-modeling questions, linked to findings, for assumptions the code cannot settle.
- Headless runs show live progress, token use, and cost;
--soft-budgetwarns about projected overruns without stopping an active run. /appsec-advisor:repo-profileinspects repository size, languages, build manifests, and tracked-versus-untracked content without model calls or network access.- Baseline installation and updates verify signed releases and checksums.
- Source scans cover executable NoSQL predicates and input-driven code or template compilation, alongside fixes to run recovery, reports, and cost tracking.
- Findings name violated requirements, mitigations quote the relevant blueprint sections, and the Management Summary states compliance and failed requirements.
/appsec-advisor:security-scoreprovides a scanner-only score from 0 to 100;/appsec-advisor:statusshows installed versions, skills, profile, and configuration, with update checks through--check-updates./appsec-advisor:authnz-reviewexports pentest tasks with discovered routes as the endpoint catalog; source scans flag unchecked LLM output reaching rendering, interpreters, or privileged actions./appsec-advisor:update-baselinerefreshes installed secure-coding baselines, including organization-provided sources.- Fixes improve run recovery, business-context handling, and exports.
- Runs support only full, rebuild, and rerender; use
--fullto reassess changed code while preserving report history. Reference runs reduced analysis costs by 39.8% at quick depth and 26.8% at thorough depth. - Trust boundaries appear in diagrams and link to crossing findings. Optional business context, collected interactively or through
--context, keeps named sensitive assets in scope and informs finding impact and priority. install-baseline,verify-baseline, andremove-baselinemanage the AI Secure Coding Baseline, including CI enforcement;/appsec-advisor:helplists available commands.- Organization profiles can ship custom skills and baselines, configure the session banner, and disable individual skills.
--formats threatdragonadds alpha Threat Dragon v2 exports for Threat Dragon and OWASP ThreatAtlas.- Fixes improve analysis coverage, run recovery, and report consistency.
See the full changelog for all changes.
Development happens on dev. Branch from it and target it with your pull request; main contains tagged releases.
See CONTRIBUTING.md for setup and repository conventions. Read AGENTS.md before changing runtime behavior, schemas, prompts, permissions, cleanup behavior, or report output. Report vulnerabilities through SECURITY.md.