---
name: security-plugin-audit
description: Audit a plugin for security risks, permission analysis, and trust assessment before installation
---

# Plugin Audit

Dedicated plugin security audit with trust verdict. Accepts local paths or repository URLs.

## Step 1: Resolve Target

- If `$ARGUMENTS` starts with `https://` → clone the repo:
  ```bash
  node <plugin-root>/scanners/lib/git-clone.mjs clone "<url>" [--branch <branch>]
  ```
  Set `clone_path` and `target`.
- Otherwise → `target = $ARGUMENTS` or current directory

## IMPORTANT: Cleanup Guarantee (remote)

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

## Step 2: Pre-extraction (remote only)

```bash
node <plugin-root>/scanners/lib/fs-utils.mjs tmppath "plugin-extract.json"
node <plugin-root>/scanners/content-extractor.mjs "<target>" --output-file "<evidence_file>"
```

## Step 3: Inventory

Read plugin manifest (plugin.json). Glob for all components: commands, agents, hooks, skills, MCP configs. Build permission matrix: what tools each component can access.

## Step 4: Security Analysis

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

Analyze all files for 7 threat categories. If remote, analyze from evidence package (never read untrusted files directly). Check hook registration vs scripts (ghost hooks). Cross-reference description vs tools permissions.

## Step 5: Report

Output: Plugin metadata, component inventory, permission matrix, hook analysis, all findings by severity.

**Trust Verdict:**
- **Install** — No critical or high findings, permissions appropriate
- **Review** — High findings present but potentially justified, manual review recommended
- **Do Not Install** — Critical findings, active exfiltration, or injection detected

## Step 6: Cleanup

```bash
node <plugin-root>/scanners/lib/git-clone.mjs cleanup "<clone_path>"
node <plugin-root>/scanners/lib/fs-utils.mjs cleanup "<evidence_file>"
```