/scan-code

name: scan-code
description: >-
  Scans a Power Pages site project for security issues in source code and
  dependencies. Runs static analysis and dependency scanning, then surfaces
  findings by category (code patterns, vulnerable packages, secrets, license
  issues). Use when the user wants to review code for security problems,
  check for vulnerable packages, find hard-coded secrets, run a code scan,
  or asks "is my code safe?", "check my dependencies", "find security
  issues in my source" — even if they say "audit my code" without
  mentioning specific tools.
user-invocable: true
argument-hint: "[optional: --review <out-dir>]"
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList
model: opus

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

Scan Code

Scan a Power Pages site project's source files and dependencies for security issues. Runs opengrep (static analysis) and trivy (dependency/secret/license scanning), then surfaces findings.

**Initial request:** $ARGUMENTS

> **WARNING:** Before proceeding, inform the user: "This skill uses **opengrep** and **trivy**, only if they are installed on your local machine. These third-party, open-source tools scan your source code and dependencies and might collect or transmit data under their own terms, privacy policies, and data-handling practices. Microsoft does not control these. If you select the AI fallback, the AI service processes your source code. Review your organization's policies and applicable third-party terms before continuing."

Gotchas

• **Both tools must be installed.** Run `check-tools.js` to verify. If either is missing, offer an agent-driven review fallback (see Step 1.2).
• **Opengrep exits 1 when findings exist.** This is normal behavior, not an error — the script handles it.
• **Large output.** Both tools can produce large JSON for big projects. The scripts normalize the output into a flat findings list.
• **Trivy severity flag only affects vulnerability findings.** Secrets and license findings are always returned regardless of the `--severity` flag.
• **Secrets are never shown in full — anywhere.** Whenever **you** read source directly (the agent-driven review) or present a finding, use your judgment to recognize any credential — API keys, tokens, passwords, connection strings, private keys, or any other secret shape (there is no fixed list). Never output its raw value **anywhere** — your context, the session, chat, logs, a summary, the report, or any other output — not even partially; where a value would otherwise be shown, replace it with a mask (e.g. `********`).

Workflow

1. **Prerequisites** — Locate project, check tool availability 2. **Choose scope** — What to scan and at what depth 3. **Run scans** — Execute tools, capture results 4. **Summarize** — Present findings, record usage, offer follow-ups

Task Tracking

Create tasks in three groups. Mark each `in_progress` when starting, `completed` when done.

| Group | When to create | Tasks | |-------|----------------|-------| | 1 | At start | Check prerequisites | | 2 | After prerequisites pass | Choose scope (skip in review mode) | | 3 | After scope is decided (or in review mode) | Run scans · Summarize (always) |

---

1. Prerequisites

1.1 Locate the project, detect review mode

Use `Glob` to find `**/powerpages.config.json`. If `$ARGUMENTS` contains `--review <out-dir>`, remember the output directory — Step 2 is skipped (run all checks at Advanced depth), and Step 4 writes JSON only.

1.2 Check tool availability

node "${PLUGIN_ROOT}/skills/scan-code/scripts/check-tools.js"

If either tool is missing, tell the user which tool is missing. Then offer an agent-driven review as a fallback:

**In review mode (non-interactive), do not offer the agent-driven review.** It needs an interactive opt-in, and the orchestrator expects a JSON file. Write `{ "status": "skipped", "reason": "<which tool> is not installed" }` to `<REVIEW_DIR>/scan-code.json` and stop.

<!-- gate: scan-code:1.agent-review-fallback | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · scan-code:1.agent-review-fallback):** When a scanning tool is missing, offer the agent-driven review as a fallback before doing any work. It reads the source with `Glob`/`Read`/`Grep` and has high token consumption, so the user must opt in. > > **Trigger:** Step 1.2, only when `check-tools.js` reports a missing tool (interactive mode only — review mode never reaches here because it stops when tools are missing). > **Why we ask:** Auto-starting the agent-driven review burns a large amount of tokens without consent; the user may prefer to install the tool and re-run instead. > **Cancel leaves:** Nothing — no files read, no scan run.

**Framing — all user-facing text (the warning, any `AskUserQuestion` option labels, and the summary): MUST NOT call this a "manual review".** It is agent-driven — describe it as *you reviewing the code yourself*, e.g., "I can look through your code directly and flag issues."

Warn the user that this review reads many files and uses a large amount of tokens, then detect the git context:

• **Feature branch** (not `main`, `master`, or equivalent): offer to review only the changes in the current branch (`git diff <main-branch>...HEAD`).
• **Main/master branch or no git repo**: offer to review the entire project source.

If the user accepts, use `Glob` + `Read` + `Grep` to review the relevant files for common security patterns (hard-coded secrets, unsafe API usage, missing input validation, exposed endpoints, etc.) and present findings. **Never surface a secret value anywhere** — never output a credential's raw value in any output (your context, the session, chat, logs, etc.), not even partially; where a value would otherwise be shown, replace it with a mask (e.g. `********`). Do not attempt to install the t