AGENT SKILL

trustskill

TrustSkill v3.1 - Advanced security scanner for OpenClaw skills with 99% false positive reduction. Detects malicious code, hardcoded secrets, vulnerable dependencies, tainted data flows, backdoors, credential theft, privacy file access, command injection, file system risks, network exfiltration, and sensitive data leaks. Features entropy-based secret detection, OSV vulnerability database integration, taint analysis, smart data flow detection, context-aware documentation scanning, and flexible YAML configuration.

License 许可
MIT
最近更新
2026-09-29
Stars
★ 0
Forks
0

01 前言 Front Matter

name
trustskill
version
3.1.0
description
TrustSkill v3.1 - Advanced security scanner for OpenClaw skills with 99% false positive reduction. Detects malicious code, hardcoded secrets, vulnerable dependencies, tainted data flows, backdoors, credential theft, privacy file access, command injection, file system risks, network exfiltration, and sensitive data leaks. Features entropy-based secret detection, OSV vulnerability database integration, taint analysis, smart data flow detection, context-aware documentation scanning, and flexible YAML configuration.

02 资源文件 61

03 SKILL.md 正文

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

Mode Description Speed Accuracy Use Case
fast Regex + Secrets + Dependencies ⚡ Fast ⭐⭐⭐ Quick initial scan
standard Regex + AST + Secrets + Dependencies ⚡ Balanced ⭐⭐⭐⭐ Default, recommended
deep Full analysis + Taint Analysis 🐢 Thorough ⭐⭐⭐⭐⭐ Comprehensive audit

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

Level Icon Meaning Action
HIGH 🔴 Confirmed security risk Stop and investigate immediately
MEDIUM 🟡 Potential risk requiring review Investigate before proceeding
LOW 🟢 Informational, low risk Document and proceed with caution

Finding Categories

Category Risk Description Typical Action
command_injection HIGH User input to dangerous functions Critical - Review code flow
data_upload HIGH POST/PUT to external servers Investigate destination and data
hardcoded_secret HIGH Real API keys/passwords found Remove and rotate credentials
data_download MEDIUM File downloads from internet Verify source is legitimate
api_key_usage MEDIUM API key references (docs) Usually safe if placeholder
network_request MEDIUM HTTP requests Verify endpoints are legitimate
vulnerable_dependency MEDIUM CVE in dependencies Update to patched version
environment_access LOW Reading env variables Normal for configuration
file_operation LOW Standard file I/O Verify paths are safe

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

Score Range Interpretation
0.9 - 1.0 Very high confidence - likely a real issue
0.7 - 0.9 High confidence - investigate thoroughly
0.5 - 0.7 Medium confidence - review context
< 0.5 Low confidence - may be false positive

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

Feature v1.x v2.0 v3.0 v3.1
Regex Analysis ✅ ✅ ✅ ✅
AST Analysis ❌ ✅ ✅ ✅
Secret Detection ❌ ❌ ✅ ✅
Dependency Scanning ❌ ❌ ✅ ✅
Taint Analysis ❌ ❌ ✅ ✅
YAML Configuration ❌ ❌ ✅ ✅
Progress Tracking ❌ ✅ ✅ ✅
Confidence Scoring ❌ ✅ ✅ ✅
Lock File Whitelist ❌ ❌ ❌ ✅
Smart Data Flow ❌ ❌ ❌ ✅
Context-Aware Docs ❌ ❌ ❌ ✅
i18n Placeholder Support ❌ ❌ ❌ ✅
False Positive Reduction ~50% ~70% ~85% ~99%

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.

04 同仓库更多 Skills

nordeim
nordeim/activity-map

webapp-testing

Web application testing principles. E2E, Playwright, deep audit strategies.

★ 0
nordeim
nordeim/activity-map

web-search

Implement web search capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to search for real-time information from the web, retrieve up-to-date content beyond the knowledge cutoff, or find the latest news and data. Returns structured search results with URLs, snippets, and metadata.

★ 0
nordeim
nordeim/activity-map

web-reader

Implement web page content extraction capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to scrape web pages, extract article content, retrieve page metadata, or build applications that process web content. Supports automatic content extraction with title, HTML, and publication time retrieval.

★ 0
nordeim
nordeim/activity-map

web-frameworks

Build modern full-stack web applications with Next.js 16 + React 19 (App Router, Server Components, RSC, PPR, cacheComponents, async params, SSR, SSG, ISR, standalone output), Turborepo (monorepo, task pipelines, remote caching, parallel execution), and RemixIcon (3100+ SVG icons). Use when creating React applications, implementing server-side rendering, setting up monorepos, optimizing build performance and caching, or working with TypeScript full-stack projects.

★ 0
nordeim
nordeim/activity-map

video-understand

Implement specialized video understanding capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze video content, understand motion and temporal sequences, extract information from video frames, describe video scenes, or perform video-based AI analysis. Optimized for MP4, AVI, MOV, and other common video formats.

★ 0
nordeim
nordeim/activity-map

video-generation

Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.

★ 0