Claude Code Mods Security Scanning Methodology & Heuristics Rubric

1. Overview & Transparency Mandate

Because Claude Code CLI runs with ambient user permissions inside developer workstations, installing third-party lifecycle mods, hooks, or MCP bridges introduces supply-chain risk.

At Claude Code Mods Hub (https://claudecodemods.net), our goal is to provide developers with clear, deterministic visibility into what a mod actually does before they install it.

Important Disclosure: Our security ratings and badges (such as AST Scan: 0 Critical Findings) represent automated static heuristic analysis. They do not constitute a formal commercial security certification, accreditation, warranty, or proof of absolute safety. Developers are always advised to inspect open-source repositories and test in sandboxed environments.

---

2. The 6-Point Static Analysis Heuristic Rubric

Our scanner parses TypeScript/JavaScript source trees and plugin.json manifests using Tree-sitter AST nodes and regular expression heuristics to check for six primary threat categories:

Rule 1: Subprocess & Host Binary Execution

• Detection Pattern: child_process.exec(), execSync(), spawn(), spawnSync(), fork(), or execution of unverified shell commands.
• Risk Evaluation: HIGH / CRITICAL. Interceptor hooks should generally inspect or reject events rather than spawning background host processes.
• Permitted Exception: Security mods specifically designed to sandbox shell execution (such as blast-radius), provided the execution target is the inspected command itself and requires developer confirmation.

Rule 2: Destructive Filesystem Operations

• Detection Pattern: Recursive deletions targeting root or parent directories (rm -rf /, rmdirSync('/', { recursive: true })), unconstrained path traversals (../..), or mass file modifications.
• Risk Evaluation: CRITICAL. Mods must restrict filesystem mutations to declared workspace paths or local session log directories (.claude/).

Rule 3: Dynamic Code Injection & Obfuscation

• Detection Pattern: eval(), new Function(), vm.runInThisContext(), vm.runInNewContext(), or encoded payloads (Buffer.from('...', 'base64') executed directly).
• Risk Evaluation: CRITICAL. Dynamic evaluation bypasses static review and violates our directory listing policy.

Rule 4: Credential & Environment Variable Harvesting

• Detection Pattern: Wildcard iteration over process.env (e.g. Object.keys(process.env), JSON.stringify(process.env)), or targeted reads of sensitive stores (~/.ssh/, ~/.aws/credentials, ~/.config/claude/config.json, .env.production).
• Risk Evaluation: CRITICAL. If a mod requires configuration, it must declare specific keys in its plugin.json configSchema or permissions.env.read list.

Rule 5: Outbound Network Sockets & Data Exfiltration

• Detection Pattern: fetch(), http.request(), https.request(), net.connect(), dgram, or WebSocket connections to undeclared remote endpoints.
• Risk Evaluation: HIGH. Mods with zero-egress declarations must not initialize external sockets. Telemetry or AI-bridge mods must explicitly declare hostnames in their permissions manifest.

Rule 6: Manifest & Hook Permission Consistency

• Detection Pattern: Discrepancies between declared plugin.json permissions (permissions.fs.write, permissions.network) and the actual AST calls found in entrypoint scripts.
• Risk Evaluation: MEDIUM / HIGH. Undeclared capabilities are flagged for manual review.

---

3. How We Target Releases & Commit Hashes

To prevent supply-chain drift where a verified package is replaced by an unverified upstream update:

1. Commit Pinning: We link and analyze specific public Git commit SHAs (e.g., e4b91f2).
2. Public Source Requirement: All listed mods must provide a public GitHub or GitLab repository with an OSI-approved open-source license.
3. Change Detection: When upstream repositories release new tags, re-scans are triggered to detect newly added dependencies, altered permissions, or new hook interceptors.

---

4. Limitations of Automated Static Analysis

Static analysis is an automated filter, not an infallible defense:

• Obfuscation: Sophisticated adversarial evasion (such as runtime string assembly or multi-stage network fetch) cannot be guaranteed to be caught by static heuristics alone.
• External Dependencies: While top-level source code is inspected, nested transitive npm dependencies are subject to ecosystem-wide vulnerability audits (npm audit / Snyk).
• Runtime Environment Differences: Behavior that depends on OS-specific edge cases or dynamic system configurations cannot be fully evaluated prior to execution.

---

5. Recommended Safe Installation Workflow for Developers

Before running any third-party mod on your primary development machine:

1. Test in a Container or Isolated Directory:

# Run inside an isolated Docker container or disposable directory
docker run -it -v $(pwd):/workspace node:22-alpine sh

2. Inspect the Local Code:

# Clone the repo locally and run our in-browser validator
git clone https://github.com/example/claude-mod
cat plugin.json

3. Check the Uninstallation Path: Verify that you can uninstall the mod cleanly:

claude plugin uninstall blast-radius@marketplace
# Or inside a Claude session:
/plugin remove blast-radius

---

6. Submitting a Correction or Requesting a Re-Scan

If you are a mod author and believe your package was flagged in error (false positive) or you have released a new security-hardened commit, please submit an update via our Submit Mod portal or open an issue on our community tracker.