Security Scanner

Security Scanner Skill

Comprehensive static analysis tool for detecting vulnerabilities, malware patterns, and security issues in code and skills.

Overview

Security Scanner performs deep static analysis on:

• Code files (.js, .ts, .jsx, .tsx, .py, .go, .java, .rb, .php, .sh)
• Skill directories (recursively scans all code)
• Inline code snippets

It flags dangerous patterns, suspicious behaviors, and obfuscation, then provides actionable recommendations.

Quick Start

# Scan a skill directory
security-scanner ./my-skill/

# Scan a single file
security-scanner ./package.js

# Scan code snippet
security-scanner --code "eval(userInput)"

# Get JSON output
security-scanner ./skill --output json

# See suggested fixes
security-scanner ./skill --fix

Risk Levels & Recommendations

🔴 DANGEROUS → REJECT

Verdict: Do not install this code.

Detected patterns:

• eval() - Arbitrary code execution
• exec() - Command execution
• Dynamic require() with variable paths
• Evidence of code injection vulnerabilities

Action: Request source code review from maintainer or reject entirely.

🟡 CAUTION → QUARANTINE

Verdict: Review before installation.

Detected patterns:

• child_process calls (spawning external commands)
• Environment variable access (potential secret theft)
• Network calls to unknown domains
• Obfuscated/minified code
• Low-level socket access (net, dgram)
• Encoded strings (hex/Unicode escapes)

Action: Examine findings, ask maintainer about suspicious patterns, install with caution.

🟢 SAFE → INSTALL

Verdict: No obvious malicious patterns detected.

Action: Safe to install. Standard security practices still recommended (keep updated, monitor permissions).

What It Detects

Code Execution (Highest Risk)

• ✗ eval()
• ✗ exec()
• ✗ Dynamic require() with variable paths
• ⚠ child_process module imports

Credential Theft

• ✗ process.env.SECRET, process.env.API_KEY, etc.
• ⚠ Dynamic environment variable access process.env[varName]
• ⚠ fs.readFileSync() on sensitive system files (/etc/, ~/)

Network/Data Exfiltration

• ⚠ Network calls to unknown external domains (via fetch, http.get, etc.)
• ⚠ HTTP/HTTPS module imports (potential network calls)
• ⚠ Low-level socket access (net, dgram)

Obfuscation (Red Flag)

• ⚠ Minified code (unusually high symbol density, very short lines)
• ⚠ Hex-encoded strings (\x41\x42\x43)
• ⚠ Unicode-encoded strings (\u0041\u0042)

Why it matters: Obfuscated code hides malicious logic. Legitimate libraries don't need to be obfuscated.

Output Formats

Text (Human-Readable, Default)

=== Security Scanner Report ===

Target: ./my-skill
Files Scanned: 5
Findings: 2

Risk Level: CAUTION

Detailed Findings:

  scripts/handler.js
    Line 42: [CAUTION] child_process allows spawning external commands
      Code: require('child_process')
      Context: const spawn = require('child_process').spawn;

  src/api.js
    Line 18: [CAUTION] Network call to external domain
      Code: fetch('https://api.example.com/verify')
      Context: return fetch('https://api.example.com/verify', {...})

Recommendation:
  Action: QUARANTINE
  Reason: Code contains potentially suspicious patterns requiring review
  Details: Review findings before installation. Consider asking maintainer about specific suspicious patterns.

Suggested Fixes:
  • Replace dynamic require with static import
    File: scripts/handler.js:42
    Suggestion: Use static imports or a whitelist of allowed modules
    Difficulty: MEDIUM

JSON (Programmatic)

scanner --output json

Returns structured JSON with:

• target: Path/name scanned
• timestamp: ISO timestamp
• riskLevel: SAFE | CAUTION | DANGEROUS
• findings[]: Array of detected issues with line numbers
• scannedFiles[]: List of files analyzed
• recommendation: Action and reasoning
• fixes[]: (if --fix used) Suggested code changes

Using It in Your Workflow

Pre-Installation Check

# Before installing a new skill
security-scanner ~/downloads/mystery-skill/

# If DANGEROUS → Don't install
# If CAUTION → Review output, ask author
# If SAFE → Good to go

Code Review

# Check your own skill for issues
security-scanner ./my-skill/ --output json > security-report.json

# Fix issues
security-scanner ./my-skill/ --fix

Automated CI/CD

# In your build pipeline - fail if DANGEROUS detected
security-scanner ./src/ --output json
if [ $? -eq 2 ]; then
  echo "Security violations found"
  exit 1
fi

Sub-Agent Invocation

# From a sub-agent or CLI
/Users/ericwoodard/clawd/security-scanner-skill/scripts/scanner.js ~/clawd/some-skill/

Common Findings & How to Interpret

eval() / exec()

Finding: "eval() allows arbitrary code execution"

Interpretation: Code can run any arbitrary JavaScript at runtime. Extremely dangerous.

Response:

• ❌ If malicious: REJECT
• ⚠️ If legitimate: Ask author why eval is needed (usually there's a safer way)

child_process Import

Finding: "child_process allows spawning external commands"

Interpretation: Code can run system commands. Used legitimately by build tools, but also by malware.

Response:

• Check where it's used
• Does it run user input? → DANGEROUS
• Does it run hardcoded commands? → Probably safe, but review

process.env.API_KEY

Finding: "Accessing sensitive environment variables"

Interpretation: Code reads secret keys from environment. This is standard, but verify:

• Is it documented?
• Is the key actually used for intended purpose?
• Could it be exfiltrated?

Response:

• Normal for legitimate skills that need API keys
• Check if the API call goes to the expected domain

Minified Code

Finding: "Code appears to be minified or obfuscated"

Interpretation: Source code is intentionally hidden. Why?

Response:

• ❌ Single-file skill that's minified → Suspicious, ask for source
• ✅ Node module with both .js and .min.js → Standard practice
• ⚠️ Hex-encoded strings → Request deobfuscation

Fetch to Unknown Domain

Finding: "Network call to external domain"

Interpretation: Code calls some external API. Is it expected?

Response:

• ✅ fetch('https://api.github.com/...') → Normal
• ❌ fetch('https://malware-collection.ru/...') → Dangerous
• ⚠️ fetch(userProvidedUrl) → Dangerous (open redirect)

How to Use with Sub-Agents

From a sub-agent, invoke the scanner:

# Run scan
/Users/ericwoodard/clawd/security-scanner-skill/scripts/scanner.js <skill-path>

# Check exit code
if [ $? -eq 2 ]; then
  # DANGEROUS - handle rejection
elif [ $? -eq 1 ]; then
  # CAUTION - handle quarantine
else
  # SAFE
fi

# Or parse JSON output
result=$(/Users/ericwoodard/clawd/security-scanner-skill/scripts/scanner.js <path> --output json)
riskLevel=$(echo "$result" | jq -r '.riskLevel')

Limitations

⚠️ Static analysis only - Does not execute code, so:

• Runtime tricks might not be detected
• Obfuscated strings that are decoded at runtime won't be flagged
• Complex control flow analysis not performed

Still safe: Unless the scanner says DANGEROUS, you should be fine. CAUTION requires manual review but many are false positives.

Commands

security-scanner <path>

Scan a file or directory.

security-scanner ./my-skill/
security-scanner ./code.js

security-scanner --code "<snippet>"

Scan inline code without creating a file.

security-scanner --code "eval(userInput)"

security-scanner <path> --output json

Output results as JSON for programmatic parsing.

security-scanner ./skill --output json > report.json

security-scanner <path> --output text

Output as human-readable text (default).

security-scanner <path> --fix

Show suggested code fixes and mitigation strategies.

security-scanner ./skill --fix

security-scanner --help

Show usage information.

Exit Codes

• 0 - SAFE (no dangerous patterns)
• 1 - CAUTION (suspicious patterns found, manual review needed)
• 2 - DANGEROUS (malicious patterns detected, do not install)

Implementation Notes

• Pattern matching via regular expressions
• Obfuscation detection via heuristics (symbol density, encoding)
• Line-accurate reporting (can pinpoint exact locations)
• Multi-language support (.js, .ts, .py, .go, .java, .rb, .php, .sh)
• Automatic filtering of non-code directories (node_modules, .git, dist, etc.)

Future Enhancements

Potential additions:

• Semantic analysis (understand variable data flow)
• Signature-based detection (known malware patterns)
• Configuration audit (unusual permissions, suspicious settings)
• Quarantine mode (automatically remove/comment suspicious code)
• Integration with malware databases
• Supply chain attack detection (pinning specific versions, checksum verification)

Last Updated: 2025-01-29 Status: Production Ready