appsec-advisor

appsec-advisor

⚠️ Beta: not production ready. appsec-advisor is 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

Why appsec-advisor?

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.

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.

Scope and limitations

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.

Security notes

[!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.

Output safety

Python renders reports from validated structured data. If a run artifact contains an unmasked secret, the run fails before its outputs are considered publishable.

Quick start

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.

1. Install the plugin

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-foundry

Later 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
claude

To 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-advisor

2. Configure permissions and create the model

Run 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/.

3. Work with the model

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

Threat Modeler

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.md and threat-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.

<img src="docs/images/figure1-example.svg" alt="Figure 1a of the Juice Shop threat model">

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.

<img src="docs/images/figure1b-example.svg" alt="Figure 1b of the Juice Shop threat model">

Figure 2 connects threat actors through example attack routes and the linked weaknesses to the potential business harm.

<img src="docs/images/figure2-example.svg" alt="Figure 2 of the Juice Shop threat model">

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.

Abuse cases

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.

Assess multiple repositories

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 40

A combined run has these requirements:

• Select 2–16 top-level Git checkouts that do not contain each other.
• Choose an --output directory outside every selected checkout.
• Set --soft-budget or --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.

Threat Analyst

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.

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.

Requirements Audit

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

Additional developer tools

See the developer tools guide for commands and configuration.

Security score

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/project

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

Deterministic scan script

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.

Report a failed run

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.

Enterprise rollout

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.

<img src="docs/images/orgpackaging.svg" alt="Example rollout from an upstream release to an Acme-branded plugin">

See Internal Plugin Packaging and Organization Profiles.

Documentation

Project structure

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.

Related projects

Companion repositories

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

Comparable tools

| OWASP pytm | Threat models authored and maintained as Python code. | pytm requires developers to declare the model; appsec-advisor derives it from the