isnad-scan — Security Scanner for AI Agent Skills

Scan any skill, package, or directory for security threats before installing or running it.

Quick Scan

isnad-scan <path>

Scans a directory and reports findings by severity (CRITICAL, HIGH, MEDIUM, LOW).

Options

isnad-scan <path> --cve          # Also check dependencies for known CVEs (via OSV.dev)
isnad-scan <path> -v             # Verbose output (show matched lines)
isnad-scan <path> --json         # Machine-readable JSON output
isnad-scan <path> --cve -v       # Full audit: CVEs + verbose findings

What It Detects (69+ patterns)

Code Injection — shell execution, eval, exec, subprocess, os.system, dynamic imports

Prompt Injection — role override attempts, instruction hijacking, jailbreak patterns

Credential Exfiltration — env var harvesting, keychain access, token theft, file reads of sensitive paths

Network Threats — reverse shells, DNS exfiltration, unauthorized outbound connections, webhook data leaks

Filesystem Attacks — path traversal, symlink attacks, /etc/passwd reads, SSH key access

Supply Chain — typosquatting detection, minified JS analysis, binary file scanning, hidden files

Crypto Risks — weak algorithms, hardcoded keys, wallet seed extraction

When to Use

1. Before installing a new skill — scan the skill directory first
2. Auditing existing skills — periodic security review
3. Reviewing PRs/contributions — catch malicious code in submissions
4. Pre-publish validation — ensure your own skills are clean before sharing
5. CI/CD integration — isnad-scan . --json for automated checks

Interpreting Results

🔴 CRITICAL  — Immediate threat. Do not install/run.
🟠 HIGH      — Likely malicious or dangerous. Review carefully.
🟡 MEDIUM    — Suspicious pattern. May be legitimate, verify intent.
🔵 LOW       — Informational. Common in legitimate code but worth noting.

Examples

Scan a ClawHub skill before installing:

isnad-scan ./skills/some-new-skill/

Full audit with CVE checking:

isnad-scan ./skills/some-new-skill/ --cve -v

JSON output for automation:

isnad-scan . --json | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'{d[\"summary\"][\"critical\"]} critical, {d[\"summary\"][\"high\"]} high')"

Python API

from isnad_scan import scan_directory

results = scan_directory("/path/to/skill")
for finding in results.findings:
    print(f"[{finding.severity}] {finding.category}: {finding.description}")
    print(f"  File: {finding.file}:{finding.line}")

About ISNAD

ISNAD (إسناد) means "chain of transmission" — a method for verifying the authenticity of transmitted knowledge. isnad-scan is the security layer of the ISNAD Protocol, bringing trust verification to the AI agent skill ecosystem.

PyPI: pip install isnad-scan

GitHub: counterspec/isnad

Protocol: isnad.md