security-scanner – OpenClaw Skill

---

name: security-scanner description: Comprehensive vulnerability and malware scanner for skills and code. Detects code execution vulnerabilities (eval, exec, dynamic require), credential theft patterns, network calls to suspicious domains, obfuscation, and more. Provides risk assessment (SAFE/CAUTION/DANGEROUS) with detailed findings and actionable recommendations. Use before installing untrusted skills or when reviewing code for security issues.

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

Security Scanner Skill for Clawdbot

Comprehensive vulnerability and malware scanner for skills and code.

This skill performs deep static analysis to detect:

• Code execution vulnerabilities (eval, exec, dynamic require)
• Credential theft patterns
• Network calls to suspicious domains
• Obfuscation and hidden code
• Permission misuse

Installation

The skill is already located at:

~/clawd/security-scanner-skill/

Make it globally accessible

# Option 1: Create symlink in /usr/local/bin
sudo ln -s ~/clawd/security-scanner-skill/cli.sh /usr/local/bin/security-scanner

# Option 2: Add to PATH in ~/.zshrc or ~/.bash_profile
export PATH="$PATH:~/clawd/security-scanner-skill"

Then use directly:

security-scanner ./some-skill/

Quick Usage

Scan a skill directory

security-scanner ~/clawd/my-skill/

Scan a single file

security-scanner ~/clawd/my-skill/handler.js

Scan inline code

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

Get JSON output (for parsing)

security-scanner ~/clawd/my-skill/ --output json

See suggested fixes

security-scanner ~/clawd/my-skill/ --fix

Full help

security-scanner --help

Risk Levels

Level	Color	Action	Next Step
🟢 SAFE	Green	Install	Deploy the skill
🟡 CAUTION	Yellow	Quarantine	Review findings before installing
🔴 DANGEROUS	Red	Reject	Do not install, request code review

Exit Codes

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

Use in scripts:

security-scanner ./skill
if [ $? -eq 2 ]; then
  echo "DANGEROUS - Rejecting installation"
  exit 1
elif [ $? -eq 1 ]; then
  echo "CAUTION - Manual review required"
fi

Using with Clawdbot

From Main Session

When reviewing a new skill before installation:

/Users/ericwoodard/clawd/security-scanner-skill/cli.sh ~/clawd/new-skill/

From Sub-Agent

In a sub-agent task (like automated skill vetting):

#!/bin/bash
SKILL_PATH=$1
SCANNER="/Users/ericwoodard/clawd/security-scanner-skill/scripts/scanner.js"

node "$SCANNER" "$SKILL_PATH" --output json > /tmp/scan-report.json

# Check result
RISK_LEVEL=$(jq -r '.riskLevel' /tmp/scan-report.json)

case "$RISK_LEVEL" in
  DANGEROUS)
    echo "❌ REJECT - Dangerous patterns detected"
    exit 2
    ;;
  CAUTION)
    echo "⚠️  QUARANTINE - Manual review required"
    exit 1
    ;;
  SAFE)
    echo "✓ INSTALL - No obvious threats"
    exit 0
    ;;
esac

Integration with Telegram Bot

When someone shares a skill in Telegram:

@clawd scan-skill https://github.com/user/skill-repo

Would run:

git clone https://github.com/user/skill-repo /tmp/skill-scan
security-scanner /tmp/skill-scan --output json
# Send results via Telegram

Examples

Example 1: Scan safe skill

$ security-scanner examples/example-safe.js

=== Security Scanner Report ===

Target: examples/example-safe.js
Files Scanned: 1
Findings: 0

Risk Level: SAFE

✓ No suspicious patterns found!

Recommendation:
  Action: INSTALL
  Reason: No obvious malicious patterns detected
  Details: Code appears safe. Standard security practices still recommended.

Example 2: Scan code with caution flags

$ security-scanner examples/example-caution.js

=== Security Scanner Report ===

Target: examples/example-caution.js
Files Scanned: 1
Findings: 5

Risk Level: CAUTION

Detailed Findings:

  example-caution.js
    Line 7: [CAUTION] child_process allows spawning external commands
      Code: require('child_process')
      Context: const child_process = require('child_process');

    Line 16: [CAUTION] Accessing sensitive environment variables
      Code: process.env.API_KEY
      Context: const apiKey = process.env.API_KEY;

    [... more findings ...]

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

Example 3: Get JSON output

$ security-scanner examples/example-dangerous.js --output json
{
  "target": "examples/example-dangerous.js",
  "timestamp": "2025-01-29T10:30:45.123Z",
  "riskLevel": "DANGEROUS",
  "findings": [
    {
      "type": "eval",
      "risk": "DANGEROUS",
      "description": "eval() allows arbitrary code execution",
      "weight": 10,
      "lineNumber": 6,
      "lineContent": "  const result = eval(userInput);",
      "filename": "example-dangerous.js",
      "matchText": "eval("
    },
    [... more findings ...]
  ],
  "recommendation": {
    "action": "REJECT",
    "reason": "Code contains dangerous patterns that could allow malware or data theft",
    "details": "Do not install. Request source code review from maintainer."
  }
}

Detected Patterns

Code Execution (🔴 DANGEROUS)

• eval() - Executes arbitrary JavaScript
• exec() - Executes arbitrary commands
• Dynamic require('./path' + variable) - Loads arbitrary code

Credential Theft (🟡 CAUTION)

• process.env.API_KEY, process.env.SECRET, etc.
• process.env[variableName] - Dynamic access
• Reading from system files: /etc/passwd, ~/.ssh/

Network/Data Exfiltration (🟡 CAUTION)

• fetch() to unknown external domains
• HTTP requests via http.get(), http.post()
• Low-level socket access (net, dgram)

Obfuscation (🟡 CAUTION)

• Minified code (unusual density of symbols)
• Hex-encoded strings: \x41\x42\x43
• Unicode escapes: \u0041\u0042

What It CAN'T Detect

⚠️ Limitations of static analysis:

• Runtime tricks (code decoded at runtime)
• Complex control flow analysis
• Supply chain attacks (compromised dependencies)
• Behavioral patterns (requires execution)

Still safe: If Security Scanner says SAFE, you're good. It's conservative and flags edge cases.

Common Findings Explained

"child_process allows spawning external commands"

Issue: Code can run system commands.

Severity: CAUTION (legitimate use cases exist)

How to evaluate:

• Is it spawning hardcoded commands? → Usually safe
• Is it spawning user input? → DANGEROUS
• Does it have proper input validation? → Review carefully

Example of dangerous use:

// DON'T DO THIS
spawn(userInput);  // User can run ANY command

Example of safe use:

// BETTER
spawn('npm', ['install']);  // Hardcoded command and args

"Accessing sensitive environment variables"

Issue: Code reads API keys or secrets from environment.

Severity: CAUTION (depends on usage)

How to evaluate:

• Is it documented? (should explain which env vars it needs)
• Where does it send the secret? (to official API? or unknown domain?)
• Is it properly protected? (not logged, not sent to analytics)

"Network call to external domain"

Issue: Code makes HTTP requests to some domain.

Severity: CAUTION (depends on the domain)

Legitimate domains:

• ✅ api.github.com
• ✅ api.weather.gov
• ✅ Known services (Stripe, AWS, etc.)

Suspicious domains:

• ❌ malware-site.ru
• ❌ random-analytics.xyz
• ❌ Domains in unexpected countries

"Code appears to be minified or obfuscated"

Issue: Source code is intentionally hidden.

Severity: CAUTION (big red flag for single-file skills)

When it's normal:

• Node modules with both source and .min.js version
• Production builds (dist/, build/)

When it's suspicious:

• Single-file skill that's completely minified
• No source code available
• Unusual variable names after minification

Workflow Examples

Installing a New Skill

# 1. Download the skill
git clone https://github.com/unknown-author/mystery-skill.git

# 2. Scan it
security-scanner ./mystery-skill/

# 3. Check the result
# - DANGEROUS → Don't install
# - CAUTION → Review the findings, ask the author
# - SAFE → Good to go

# 4. If CAUTION, see suggested fixes
security-scanner ./mystery-skill/ --fix

# 5. Install only after review
cp -r ./mystery-skill ~/clawd/

Reviewing Your Own Skill Before Release

# 1. Scan your skill
security-scanner ~/clawd/my-awesome-skill/

# 2. Address findings
security-scanner ~/clawd/my-awesome-skill/ --fix

# 3. If you have legitimate uses for flagged code, document them
# Add comments explaining why eval() or child_process is needed

# 4. Re-scan to verify
security-scanner ~/clawd/my-awesome-skill/

# 5. Publish (you should see SAFE or explained CAUTION)

CI/CD Integration

In your GitHub Actions workflow:

- name: Security Scan
  run: |
    npm install -g security-scanner
    security-scanner ./src/ --output json > security-report.json
    RISK=$(jq -r '.riskLevel' security-report.json)
    
    if [ "$RISK" = "DANGEROUS" ]; then
      echo "Build failed: Dangerous patterns detected"
      exit 1
    fi
    
    if [ "$RISK" = "CAUTION" ]; then
      echo "⚠️  Warning: Suspicious patterns found - manual review recommended"
      jq '.findings[]' security-report.json
    fi

- name: Upload Report
  uses: actions/upload-artifact@v2
  with:
    name: security-report
    path: security-report.json

Advanced Usage

Parse JSON output programmatically

# Get risk level
RISK=$(security-scanner ./skill --output json | jq -r '.riskLevel')

# Get all findings for a specific type
security-scanner ./skill --output json | jq '.findings[] | select(.type == "eval")'

# Count findings by risk level
security-scanner ./skill --output json | jq '.findings | group_by(.risk) | map({risk: .[0].risk, count: length})'

Filter to specific file types

# Scan only JavaScript files
find ./skill -name "*.js" -exec security-scanner {} \;

# Scan and show only DANGEROUS findings
security-scanner ./skill --output json | jq '.findings[] | select(.risk == "DANGEROUS")'

Performance

• Time: <1 second for typical skill (1-10 files)
• Memory: Minimal (loaded files only)
• Scalability: Tested up to 10,000 lines per file

Troubleshooting

"Command not found: security-scanner"

Make sure the symlink is created:

ln -s ~/clawd/security-scanner-skill/cli.sh /usr/local/bin/security-scanner

"No findings detected" but I expected some

Check if the pattern is exact:

• evalFunction() won't match eval()
• process . env (with spaces) won't match process.env

You can run with --output json and manually verify the code contains the pattern.

False positives

Some legitimate uses are flagged:

• Comments mentioning eval()
• String literals containing "API_KEY"

Review the specific lines to verify they're actual issues.

Contributing

Found a pattern that isn't detected? Found a false positive?

Create an issue with:

1. Example code
2. Current behavior
3. Expected behavior

License

MIT - Feel free to use and modify

---

Skill Version: 1.0.0
Last Updated: 2025-01-29
Status: Production Ready