---
name: security-scan
description: Scan files, directories, or repos for security issues — secrets, injection vulnerabilities, supply chain risks, OWASP LLM patterns
---

# Security Scan

Scan target for security issues. Accepts local paths or repository URLs.

## Step 1: Resolve Target

- If `$ARGUMENTS` contains `--deep` → strip it, set `run_deep_scan = true`
- If `$ARGUMENTS` contains `--branch <name>` → strip it, set `branch = <name>`
- If `$ARGUMENTS` is empty → target = current working directory
- If `$ARGUMENTS` starts with `https://` → clone the repo:
  ```bash
  node <plugin-root>/scanners/lib/git-clone.mjs clone "<url>" [--branch <branch>]
  ```
  Set `clone_path` = stdout (trimmed), `target = clone_path`
- Otherwise → `target = $ARGUMENTS`

## IMPORTANT: Cleanup Guarantee (remote scans)

If `clone_path` is set, cleanup MUST run regardless of scan outcome:
```bash
node <plugin-root>/scanners/lib/git-clone.mjs cleanup "<clone_path>"
```

## Step 1.5: Pre-extraction (remote scans only)

If remote, extract evidence safely before analysis:
```bash
node <plugin-root>/scanners/lib/fs-utils.mjs tmppath "content-extract.json"
node <plugin-root>/scanners/content-extractor.mjs "<target>" --output-file "<evidence_file>"
```

## Step 2: Detect Scan Type

- **Single .md file:** skill scan only
- **Directory:** Glob for `**/commands/*.md`, `**/agents/*.md`, `**/skills/*/SKILL.md` → skill scan. Glob for `**/.mcp.json`, `**/package.json` with mcpServers → MCP scan.

## Step 3: Skill Security Analysis

Read `<plugin-root>/knowledge/skill-threat-patterns.md` and `<plugin-root>/knowledge/secrets-patterns.md`.

If remote (evidence package exists): Read the evidence JSON. Analyze sections: injection_findings, frontmatter_inventory, shell_commands, credential_references, persistence_signals, claude_md_analysis, cross_instruction_flags. `[INJECTION-PATTERN-STRIPPED]` markers are confirmed findings.

If local: Read target files directly. Apply 7 threat categories:
1. **Prompt Injection** — `ignore previous`, `forget your`, identity redefinition, spoofed system headers
2. **Data Exfiltration** — curl/wget to external URLs, base64 pipe chains, credential read+send
3. **Privilege Escalation** — unjustified Bash access, Write+Bash without rationale, chmod/sudo
4. **Scope Creep** — credential file access, crypto wallet paths, SSH keys, browser stores
5. **Hidden Instructions** — Unicode Tag steganography, zero-width chars, base64 payloads, HTML comments
6. **Toolchain Manipulation** — registry redirection, post-install scripts, external requirements
7. **Persistence** — cron jobs, LaunchAgents, systemd, shell profile modification, git hooks

For each finding: severity (Critical/High/Medium/Low/Info), category, file, line, OWASP reference, evidence, remediation.

## Step 4: MCP Security Analysis (if applicable)

Read `<plugin-root>/knowledge/mcp-threat-patterns.md`. Analyze MCP configs for: tool poisoning, hidden instructions in descriptions, rug pull signals, supply chain risks, permission surface.

## Step 5: Aggregate and Report

Combine counts. `risk_score = min(100, critical*25 + high*10 + medium*4 + low*1)`.
Verdict: critical>=1 OR score>=61 → BLOCK, high>=1 OR score>=21 → WARNING, else ALLOW.

Output banner then all findings grouped by severity (critical→info).

## Step 6: Deep Scan (only if --deep)

If `run_deep_scan = true`:
```bash
node <plugin-root>/scanners/scan-orchestrator.mjs "<target>" --output-file "<tmp>"
```
Parse results, merge with LLM findings, show "Deep Scan Findings" section.

## Step 7: Cleanup (only if remote)

Run cleanup commands from Step 1.