security-auditor

security-auditor

Audit an untrusted agent or skill (a SKILL.md, AGENTS.md, Cursor .mdc, agent definition, and its bundled scripts/references) for 7 information-security risks before you trust, install, or load it into an AI agent.

Agent-skills are trusted instructions loaded into an agent's context plus attachable executable code — the macro-virus problem, reborn for AI agents. security-auditor is a small, zero-install, cross-platform tool that flags the dangerous patterns before they ever reach your agent.

What it checks — the 7 risks

Code	Risk
R1	Prompt injection / instruction hijacking
R2	Arbitrary code execution
R3	Data exfiltration / credential theft
R4	Persistence / backdoor
R5	Supply-chain (download-and-run, remote installs)
R6	Obfuscation / hidden content (base64, hex, hidden Unicode)
R7	Outward-facing actions / data publication

Full rule list and severities: references/pattern-catalog.md.

How it works — two tiers

• Tier A — deterministic scanner (scripts/scan-patterns.*). Regex + raw-byte hidden-Unicode scan. Language-agnostic, reproducible, injection-proof (regex can't be talked out of its verdict), and runnable with no AI at all — perfect for CI/pre-commit. Returns a verdict + exit code.
• Tier B — LLM semantic pass. Your AI agent reads the Tier A output and the file to catch natural-language / multilingual prompt injection, correlate findings into real attack chains, and confirm or downgrade each hit. Methodology: references/methodology.md.

Why both? If you only ask an LLM to audit a malicious skill, that skill's text enters the very agent doing the audit and can try to subvert the verdict. The deterministic Tier A is the trust anchor that cannot be argued with; Tier B adds judgment on top.

Requirements — zero install

OS	Engine	Preinstalled?
Windows	Windows PowerShell 5.1	✅ ships with Windows
macOS / Linux	bash + grep + find	✅ ships with the OS

No pwsh, no Python, no packages.

Quick start (CLI, no AI needed)

# macOS / Linux
bash scripts/scan-patterns.sh <path-to-.md-or-folder> [--md-only] [--report out.md]

# Windows (no admin, no ExecutionPolicy change to the system)
powershell -ExecutionPolicy Bypass -File scripts\scan-patterns.ps1 <path> [-MdOnly] [-Report out.md]

Point <path> at a single .md, or at a skill's SKILL.md (scans it plus bundled files), or at a whole folder (recursive bundle audit).

Exit codes — gate on these in CI: 0 = PASS · 1 = REVIEW · 2 = BLOCK · 64 = usage · 66 = path not found.

Example:

=== security-auditor :: Tier A (deterministic pattern scan) ===
scope:  md + bundled files
files scanned: 2

SEVERITY  RISK  FILE          LINE  RULE           MATCH
CRITICAL  R5    setup.sh      8     curl-pipe-sh   curl http://… | bash
HIGH      R3    SKILL.md      10    sensitive-cred …read ~/.ssh/id_rsa…

=== SUMMARY ===
CRITICAL: 1   HIGH: 1   MEDIUM: 0   LOW: 0
VERDICT: BLOCK

Use it with an AI agent

This whole folder is the skill. SKILL.md (at the folder root) uses the standard skill format that Claude Code, OpenCode, and Codex all read, with the scanner engine bundled in scripts/. Drop the folder into your tool's skills directory — no renaming, no path edits — then ask "audit this skill" or "is this skill safe?".

Tool	Copy the folder into	Notes
Claude Code	~/.claude/skills/ (user) or <project>/.claude/skills/	cp -R security-auditor ~/.claude/skills/
OpenCode	~/.config/opencode/skills/ (global) or <project>/.opencode/skills/	also auto-discovers ~/.claude/skills/
Codex	~/.agents/skills/ (user) or <repo>/.agents/skills/	reads the same SKILL.md format

# Example — install for Claude Code (available in every project)
cp -R security-auditor ~/.claude/skills/

The agent loads SKILL.md's metadata at startup and runs the skill automatically when your request matches its description. Full methodology and report template: references/methodology.md.

Cursor has no per-skill folder (it uses .cursor/rules/*.mdc or a root AGENTS.md), so it isn't a turnkey folder-drop. You can still point Cursor at SKILL.md / references/methodology.md manually.

Output

• Console: findings table + summary + verdict.
• Report file: Markdown report. When run via an AI agent it is written to ./security-audits/audit_<target>_<timestamp>.md, in the same natural language as the audited file (English in → English out; etc.).

Repo layout

security-auditor/             # copy this whole folder into your tool's skills dir
├── SKILL.md                  # skill entry point (standard format: Claude Code / OpenCode / Codex)
├── README.md                 # this file
├── scripts/
│   ├── scan-patterns.sh      # Tier A — macOS / Linux (bash)
│   └── scan-patterns.ps1     # Tier A — Windows PowerShell 5.1
└── references/
    ├── methodology.md        # full Tier A + Tier B methodology + report template
    └── pattern-catalog.md    # the ~35 rules ↔ R1–R7, severities, limitations

Limitations

• Tier A is intentionally conservative / fail-closed: HIGH/CRITICAL → BLOCK. Tier B clears confirmed-benign hits — don't gate on Tier A alone for nuanced cases.
• Tier A detects code-shaped risks and English R1 markers; non-English natural-language injection is Tier B's job.
• Skips node_modules, .git, .archive, dist, build, vendor, and files > 2 MB.
• Novel custom encodings (XOR/ROT/gzip beyond base64/hex) are out of Tier A scope.

License

MIT.