@gustavobrunodev/skill-scanner

Security scanner for AI agent skill packages — detect prompt injection, data exfiltration, command injection, and more.

Installation

npm install @gustavobrunodev/skill-scanner

CLI Usage

Scan a skill directory

skill-scanner scan /path/to/skill

Scan with a specific policy

skill-scanner scan /path/to/skill --policy strict

Scan all skills in a directory

skill-scanner scan-all /path/to/skills --recursive

Available options

skill-scanner scan --help

Output formats

skill-scanner scan /path/to/skill --format json
skill-scanner scan /path/to/skill --format markdown
skill-scanner scan /path/to/skill --format sarif
skill-scanner scan /path/to/skill --format html
skill-scanner scan /path/to/skill --format table

List analyzers

skill-scanner list-analyzers

Validate custom rules

skill-scanner validate-rules /path/to/rules.yaml

Generate a policy file

skill-scanner generate-policy --preset balanced --output policy.yaml

Library Usage

import { SkillScanner, ScanPolicy, buildAnalyzers, Severity } from '@gustavobrunodev/skill-scanner';

const policy = ScanPolicy.default();
const analyzers = buildAnalyzers({ policy });
const scanner = new SkillScanner({ analyzers, policy });

const result = await scanner.scanSkill('/path/to/skill');

console.log(`Safe: ${result.isSafe}`);
console.log(`Findings: ${result.findings.length}`);
console.log(`Max severity: ${result.maxSeverity}`);

for (const finding of result.findings) {
  console.log(`[${finding.severity}] ${finding.title}`);
}

API Server

Start the HTTP API server:

skill-scanner-api
# or with custom port
PORT=9000 HOST=127.0.0.1 skill-scanner-api

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | / | Service info | | GET | /health | Health check | | GET | /analyzers | List available analyzers | | POST | /scan | Scan a skill directory | | POST | /scan-upload | Upload and scan a ZIP file | | POST | /scan-batch | Start an async batch scan | | GET | /scan-batch/:scanId | Poll batch scan results |

Scan request

curl -X POST http://localhost:8000/scan \
  -H 'Content-Type: application/json' \
  -d '{"skillDirectory": "/path/to/skill"}'

Pre-commit Hook

Install as a git pre-commit hook to scan staged skill packages:

skill-scanner-pre-commit

Configure via .skill_scannerrc in your repo root:

{
  "severity_threshold": "high",
  "skills_path": ".claude/skills",
  "fail_fast": true
}

License

Apache-2.0