Trustskill

TrustSkill v3.1 - Advanced Skill Security Scanner

A comprehensive security scanner for OpenClaw skills that detects:

• Malicious code and backdoors
• Hardcoded secrets (API keys, passwords, tokens via entropy analysis)
• Vulnerable dependencies (known CVEs via OSV database)
• Tainted data flows (user input to dangerous functions)
• Credential theft (SSH keys, passwords, API keys)
• Privacy file access (Memory files, configs)
• Command injection (eval, exec, os.system)
• Data uploads (suspicious POST/PUT requests)
• File system risks (destructive operations)
• Network security issues

What's New in v3.1

🔒 NPM Integrity Hash Whitelist

Automatically recognizes and skips npm/pnpm/yarn integrity hashes (sha512-xxx) in lock files, eliminating 99% of false positive HIGH findings from package-lock.json, yarn.lock, and pnpm-lock.yaml.

📊 Smart Data Flow Detection

Distinguishes between data uploads (HIGH risk) and data downloads (MEDIUM risk):

• requests.post(), requests.put() → data_upload (HIGH)
• urllib.request.urlretrieve(), requests.get(stream=True) → data_download (MEDIUM)

📝 Context-Aware Documentation Scanning

Recognizes placeholder patterns and documentation examples:

• Placeholder patterns: your_api_key_here, sk-..., <API_KEY>, ${VARIABLE}
• i18n patterns: 配置, 设置, 示例, 请将, 填入
• Markdown code blocks in documentation files

🌐 Enhanced Whitelist System

Built-in whitelists for known safe patterns:

• Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml, composer.lock, poetry.lock, Cargo.lock
• Documentation files: SKILL.md, README.md, AGENTS.md, CHANGELOG.md
• Testing utilities: test_*.py, conftest.py, with_server.py

What's New in v3.0

• 🔐 Secret Detection Engine: Hybrid entropy + pattern-based detection for AWS, GitHub, OpenAI, and generic API keys
• 📦 Dependency Vulnerability Scanner: Checks against OSV (Open Source Vulnerabilities) database
• 🌊 Taint Analysis: Tracks data flow from user input to dangerous functions (deep mode)
• ⚙️ Configuration System: YAML/JSON-based custom rules, severity overrides, and whitelisting

Prerequisites

Source the venv environment first before running the python scripts:

source /opt/venv/bin/activate && pip -V
# pip 26.0.1 from /opt/venv/lib/python3.12/site-packages/pip (python 3.12)

Quick Start

Scan a skill directory:

python src/cli.py /path/to/skill-folder

Scanning Modes

Note: Secret and Dependency analyzers run in all modes because they provide critical security checks with minimal performance overhead.

Usage Examples

Basic scan

python src/cli.py ~/.openclaw/skills/some-skill

Deep scan with JSON output

python src/cli.py ~/.openclaw/skills/some-skill --mode deep --format json

Export for manual review

python src/cli.py ~/.openclaw/skills/some-skill --export-for-llm

Use custom configuration

python src/cli.py ~/.openclaw/skills/some-skill --config trustskill.yaml

Batch scan multiple skills

for skill in ~/.openclaw/skills/*/; do
  echo "Scanning: $skill"
  python src/cli.py "$skill" --mode deep --format json > "results/$(basename $skill).json"
done

Comprehensive Skill Scanning Guidance

Pre-Scan Checklist

Before scanning a skill, verify:

• Skill source is known - Where did this skill come from? (official repo, trusted source, unknown)
• Virtual environment is active - Run source /opt/venv/bin/activate
• Scan mode is appropriate - Use deep for untrusted skills, standard for quick checks
• Output format is set - Use json for automation, text for manual review

Step-by-Step Scanning Workflow

Phase 1: Initial Assessment

# Step 1: Quick scan to identify obvious issues
python src/cli.py /path/to/skill --mode fast

# Step 2: If any HIGH issues found, proceed to deep scan
python src/cli.py /path/to/skill --mode deep --format json > scan_result.json

Phase 2: Detailed Analysis

# Step 3: Export markdown report for thorough review
python src/cli.py /path/to/skill --mode deep --export-for-llm > scan_report.md

# Step 4: Review specific file types manually
find /path/to/skill -name "*.py" -exec grep -l "eval\|exec\|os.system" {} \;

Phase 3: Validation

# Step 5: Check for actual malicious patterns
grep -r "base64.b64decode" /path/to/skill --include="*.py"
grep -r "requests.post" /path/to/skill --include="*.py"
grep -r "subprocess.*shell=True" /path/to/skill --include="*.py"

Result Interpretation Guide

Severity Levels

Finding Categories

Validation Techniques

1. Verify Hardcoded Secrets

# Check if the "secret" is actually a placeholder
grep -B2 -A2 "your_api_key" /path/to/skill/SKILL.md

# Real secrets are usually in code files, not documentation
grep -r "api_key\s*=\s*['\"]sk-" /path/to/skill --include="*.py"

2. Verify Network Requests

# Check what data is being sent
grep -B5 -A5 "requests.post" /path/to/skill/scripts/*.py

# Verify the destination URL
grep -r "https://" /path/to/skill --include="*.py" | grep -v "example.com"

3. Verify Command Injection

# Check if user input reaches dangerous functions
grep -B10 "eval\|exec\|os.system" /path/to/skill/scripts/*.py

Red Flags Requiring Immediate Action

🚨 STOP IMMEDIATELY if you find:

1. Data Exfiltration Patterns

   • Sending files to unknown servers
   • POST requests with system information
   • Uploading .ssh, .env, or credential files

2. Backdoor Patterns

   • Hidden network listeners
   • Encoded/obfuscated malicious code
   • Scheduled tasks creating persistence

3. Destructive Operations

   • rm -rf / or equivalent
   • shutil.rmtree on user directories
   • Mass file deletion patterns

4. Credential Harvesting

   • Reading /etc/passwd, /etc/shadow
   • Accessing browser credential stores
   • Extracting SSH private keys

Action: Delete the skill immediately and report to security team.

What It Detects

High Risk 🔴

• Tainted Command Injection: User input flowing to eval(), exec(), or os.system()
• Hardcoded Secrets: Real API keys, passwords, tokens (not placeholders)
• Data Upload: HTTP POST/PUT to external servers with sensitive data
• Destructive Operations: Recursive file/directory deletion (rm -rf, shutil.rmtree)
• Credential Harvesting: Password/key extraction attempts

Medium Risk 🟡

• Data Download: File downloads from internet (verify source legitimacy)
• Vulnerable Dependencies: Packages with known CVEs (via OSV database)
• Out-of-bounds File Access: Accessing /etc/passwd, SSH keys, or sensitive configs
• Code Obfuscation: Base64, ROT13, or packed code (may be legitimate)
• Dynamic Imports: Use of __import__ or importlib with variables
• Network Requests: HTTP calls to unknown domains

Low Risk 🟢

• Static Shell Commands: Commands using only string literals
• Standard File Operations: Regular file read/write within the workspace
• Environment Access: Reading environment variables (normal for config)
• Documentation References: API key placeholders in SKILL.md, README.md

When to Use This Skill

1. Before installing untrusted skills - Always scan skills from unknown sources
2. Periodic audits - Regular security checks of installed skills
3. Pre-execution validation - Before running skill scripts that modify system
4. Publishing validation - Before publishing skills to ClawHub
5. CI/CD integration - Use --format json for automated security gates

Security Patterns

See security_patterns.md for detailed patterns and detection rules.

Whitelist System

TrustSkill v3.1+ includes comprehensive whitelists for known safe patterns:

Lock Files (Automatically Skipped)

Files containing integrity hashes that are safe by design:

• package-lock.json - npm lock file
• yarn.lock - Yarn lock file
• pnpm-lock.yaml - pnpm lock file
• composer.lock - PHP Composer lock file
• poetry.lock - Python Poetry lock file
• Cargo.lock - Rust Cargo lock file
• Gemfile.lock - Ruby Bundler lock file

Documentation Files

Files where placeholder references are expected:

• SKILL.md, README.md, AGENTS.md, CHANGELOG.md, LICENSE

Testing Utility Files

Files where shell=True is expected for legitimate testing:

• test_*.py, *_test.py, conftest.py
• with_server.py, test_server.py, test_helpers.py

Placeholder Patterns

Automatically recognized as safe documentation examples:

• your_api_key_here, your_secret_here, your_token_here
• sk-..., sk_... (truncated examples)
• <API_KEY>, <YOUR_TOKEN>, <SECRET>
• ${VARIABLE}, {{VARIABLE}} (template patterns)
• i18n patterns: 配置, 设置, 示例, 请将, 填入

Custom Whitelist

Add custom whitelist patterns via YAML configuration:

rules:
  whitelist:
    files:
      - "test_*.py"
      - "my_server.py"
    patterns:
      - "eval\\(\\s*['\"]1\\+1['\"]\\s*\\)"

Best Practices for Interpreting Results

Understanding Confidence Scores

Common False Positive Patterns

1. Integrity Hashes in Lock Files (v3.1+ handles automatically)

   "integrity": "sha512-P33hHGdldxGabLFjPPpaTxVolMrzrcegejx..."
   

   → These are SRI hashes, not secrets

2. Documentation Placeholders (v3.1+ handles automatically)

   export API_KEY="your_api_key_here"
   

   → This is documentation, not a real secret

3. Environment Variable References

   API_KEY = os.environ.get("MY_API_KEY")
   

   → This reads from environment, not hardcoded

When to Escalate

Escalate to security review if:

1. Multiple HIGH findings in the same skill
2. Findings involve external network communication
3. Code appears intentionally obfuscated
4. Files accessed outside workspace without clear reason
5. Pattern suggests credential exfiltration

Response to Findings

Critical (Stop immediately)

• Confirmed backdoor or data exfiltration
• Hardcoded production credentials
• System-level destructive operations
• Action: Delete skill, report to security, rotate any exposed credentials

High Risk (Manual review required)

• Suspicious network requests
• Tainted data reaching dangerous functions
• Command injection patterns
• Action: Full code review, understand intent, proceed only if confident

Medium Risk (Investigate before proceeding)

• Unknown network endpoints
• Dependency vulnerabilities
• File access outside workspace
• Action: Verify legitimacy, document findings, proceed with caution

Low Risk (Document and proceed)

• Environment variable access
• Standard file operations
• Documentation placeholders
• Action: Note findings, proceed normally

Comparison with Previous Versions

Output Formats

• text (default): Colorized terminal output with progress bar
• json: Machine-readable JSON for CI/CD integration
• markdown: Formatted report for LLM review or documentation

Exit Codes

• 0: No high-risk issues found
• 1: High-risk issues detected (useful for CI/CD pipelines)

License

MIT License - See the LICENSE file for details.