isnad-scan

# isnad-scan — Security Scanner for AI Agent Skills

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

## Quick Scan

```bash
isnad-scan <path>
```

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

## Options

```bash
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:
```bash
isnad-scan ./skills/some-new-skill/
```

Full audit with CVE checking:
```bash
isnad-scan ./skills/some-new-skill/ --cve -v
```

JSON output for automation:
```bash
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

```python
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](https://isnad.md), bringing trust verification to the AI agent skill ecosystem.

**PyPI:** `pip install isnad-scan`
**GitHub:** [counterspec/isnad](https://github.com/counterspec/isnad)
**Protocol:** [isnad.md](https://isnad.md)