convez.ai
Skill
mannanj

skillguard

mannanj/skillguard

Ver no GitHub
BomPluginScore · de 0 a 100

Scan Claude Code skills for malicious code — before Claude runs them. Multi-engine scanner + PreToolUse hook that blocks unscanned skills.

Instalação

$npx convez-ai mannanj/skillguard

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
9
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

🛡️ SkillGuard

Scan Claude Code skills for malicious code — before Claude runs them.

Four detection engines — zero-dep local patterns, Cisco, Snyk, SkillAudit — orchestrated behind a PreToolUse hook that blocks anything unscanned. Prompt injection, credential theft, reverse shells, data exfiltration: caught at the gate.

CI License: AGPL-3.0 Python 3.10+

skillguard.sh


Why

Community skills are an unaudited supply chain running with your permissions. When researchers audited ClawHub (the OpenClaw skill marketplace) in early 2026, Koi Security found 341 malicious skills — typosquatted lookalikes whose "Prerequisites" step installed an infostealer that harvested crypto wallets, SSH keys, and .env files. Snyk's follow-up study found that 13.4% of all skills on the registry contained at least one critical-level security issue. Claude Code skills share the same trust model: a SKILL.md you probably never read, executing with everything you've allowed.

Every existing scanner checks skills when you remember to run it. SkillGuard is the one that also blocks at runtime: a PreToolUse hook that refuses to let Claude use any skill that hasn't been scanned.

Quick start

# Inside Claude Code — hook auto-registers, no settings.json editing:
/plugin marketplace add mannanj/skillguard
/plugin install skillguard@skillguard

Then scan everything once:

skillguard --engines local        # instant, zero dependencies

Installed as a plugin only? skillguard isn't on your PATH — when the hook first blocks a skill, it prints the exact python3 .../cli.py command to run instead.

From now on, every skill invocation shows a one-line verdict — and unscanned skills are blocked until you scan (or explicitly skip) them.

Install

MethodCommandNotes
Claude Code plugin (recommended)/plugin marketplace add mannanj/skillguard then /plugin install skillguard@skillguardHook auto-registers on enable
pip / pipxpip install -e . from a cloneskillguard + skillguard-hook entry points
curl installercurl -fsSL https://skillguard.sh/install | shCopies files + patches settings.json (backed up first) — read it before piping
Manualclone + add examples/settings-hook-snippet.json to ~/.claude/settings.jsonFull control

Optional engines: pip install "skillguard[cisco]" for the Cisco engine; set SNYK_TOKEN (+ uv) for Snyk; SkillAudit needs nothing but network.

How it works

flowchart LR
    A[Claude invokes a skill] --> B{PreToolUse hook}
    B -->|no scan on record| X[⛔ BLOCK — exit 2]
    B -->|cache corrupted| X
    B -->|skill modified after scan| X
    B -->|scanned clean| C[✅ allow + status line]
    B -->|scanned, findings| D[✅ allow + finding count]
    B -->|explicitly skipped| E[⚠️ allow + reminder]
    X --> F[skillguard --skill NAME] --> G[4 engines scan] --> H[cache verdict]

The scanner walks every .md/.py/.sh/.js/.ts/.yaml/.json file in each skill, runs the selected engines, and caches the verdict at ~/.claude/skillguard-cache/. The hook reads that cache in milliseconds at invocation time.

Detection engines

EngineWhat it bringsRequires
local60+ compiled regex patterns, 12 threat categories. Deterministic, offline, instant.Nothing — stdlib only
ciscoCisco AI Skill Scanner: YARA + YAML rules, AST behavioral analysispip install "skillguard[cisco]"
skillauditSkillAudit REST API: 401 patterns, cross-file analysisNetwork
snykSnyk agent-scan: LLM-powered semantic detectionSNYK_TOKEN + uv
skillguard --engines all                 # everything available
skillguard --engines local,skillaudit    # pick your mix

Engines degrade gracefully — a missing dependency skips that engine with a note, never a crash.

What it catches

CategorySeverityExamples
Reverse shellscritical/dev/tcp/, nc -e, socat exec, named-pipe shells
Data exfiltrationcriticalwebhook.site, requestbin, ngrok, Burp Collaborator endpoints
Prompt injectionhigh"ignore all previous instructions", role reassignment, system-prompt override
Credential thefthigh~/.ssh/id_rsa, ~/.aws/credentials, keychain, wallet/seed-phrase access
Env-var exfiltrationhighenv | curl, piping $*KEY*/$*SECRET*/$*TOKEN*
Piped executionhighcurl … | sh, wget … | bash
Obfuscationhighbase64-decode-exec, hex/unicode escapes, zero-width characters
Persistencemediumcrontab, LaunchAgents, systemd, shell-profile edits
Container escapemediumdocker.sock, nsenter, LD_PRELOAD
Recon, network ops, dangerous file opsmedium/lownmap, tcpdump, rm -rf /, fork bombs, whoami/uname

Output

SkillGuard Scan Results — 2026-06-03 16:20:11 UTC
============================================================
Engines: local
Scope:   global (42 skills), local (3 skills)

SUMMARY
  SEVERITY       LOCAL     TOTAL
  ──────────────────────────────
  critical           2         2
  high               5         5
  medium             1         1

FINDINGS (HIGH+)
  CRITICAL  pretty-formatter (global) — [local] Reverse shell via /dev/tcp
           scripts/setup.sh:14
  HIGH      pretty-formatter (global) — [local] curl piped to shell execution
           SKILL.md:23

Formats: --format table (default, colored), --format json, --format markdown, --quiet.

Exit codes

CodeCLIHook
0scan completed (findings or not)allow — status line on stdout
1usage error / no skills found / no engines—
2—block — unscanned, corrupted cache, or modified-since-scan

Configuration

VariableDefaultPurpose
SKILLGUARD_SKILLAUDIT_BASEhttps://skillaudit.vercel.appSkillAudit endpoint override
SKILLGUARD_SKILLAUDIT_DELAY2.1Seconds between SkillAudit calls (30 req/min limit)
SNYK_TOKEN—Enables the Snyk engine

To stop the hook blocking a skill you've decided to trust without scanning: skillguard --skip NAME — it allows the skill but shows a reminder on every use.

Triaging false positives

Skills that document attack patterns (security guides, prompt-engineering references, vendor docs full of curl | sh examples) light up scanners without being malicious. After you've reviewed a skill's findings and judged them benign:

skillguard --mark-fp NAME      # suppress all of the skill's current non-info findings
skillguard --unmark-fp NAME    # undo — restores the original verdict

Marks live in ~/.claude/skillguard-cache/_triage.json and persist across re-scans: the skill's cache verdict becomes clean (N triaged FP) and stays that way until a scan surfaces something new. A finding's identity is its engine + category + file + message — line numbers are ignored (doc edits shift lines), but any genuinely new finding, or a changed message, escapes the suppression and counts again. info-level advisories (engine errors, policy notes) are never suppressed.

Security considerations

SkillGuard audits its own attack surface — see SECURITY.md for the full threat model and private disclosure process. The short version:

  • The hook fails closed: missing, corrupted, or unreadable cache → block, never silent allow.
  • TOCTOU guard: a skill modified after its last scan is blocked until re-scanned. Known limitation: only enforced for skills in ~/.claude/skills/; plugin-namespaced skills aren't yet located for the mtime check.
  • The scanner never executes skill code — it only reads files.
  • An attacker with arbitrary write access to your home directory is out of scope (they could remove the hook itself).

False positives

Pattern scanning flags appearances, and security documentation legitimately contains attack strings. The local engine suppresses comment lines explaining detections and markdown table rows, but expect occasional flags on security-related skills — that's the trade for catching real ones. Findings show exact file:line context so you can judge in seconds. If a pattern fires wrongly on something common, open an issue with the sample.

Contributing

The highest-value contribution is a new detection pattern with a malicious fixture and a false-positive guard test — see CONTRIBUTING.md. Engine adapters, hook hardening, and docs welcome too.

Related projects

Cisco AI Skill Scanner · Snyk agent-scan · SkillAudit · claude-skill-antivirus · skillcop — all excellent scanners. SkillGuard's difference: it orchestrates them and enforces at runtime.

License

Copyright (C) 2026 Mannan Javid. SkillGuard is dual-licensed:

  • AGPL-3.0-only — free for everyone, including commercial use. Any work based on SkillGuard (including software that exposes it over a network) must be released under the AGPL with full source, and must retain the NOTICE attribution to SkillGuard and this repository.
  • Commercial license — for building on SkillGuard without AGPL obligations. Contact hello@mannan.is.

Just running the unmodified scanner — personally or at work — never requires the commercial license.

Ver o original no GitHub

Bom para

Relacionados