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
- 其他.gitignore191 B
- 参考文档enhancement_plan.md7.4 KB
- 许可证LICENSE1.0 KB
- 参考文档prompts.md1.5 KB
- 其他pytest.ini737 B
- 参考文档README_VALIDATION_REPORT.md6.0 KB
- 参考文档README.md5.4 KB
- 参考文档references/security_patterns.md2.1 KB
- 脚本scripts/batch_scan.py7.8 KB
- 脚本scripts/scan_skill.py536 B
- 脚本scripts/scan_skill.sh246 B
- 参考文档security_categories/command_injection.txt—
- 参考文档security_categories/credential_access.txt—
- 参考文档security_categories/data_exfiltration.txt—
- 参考文档security_categories/file_deletion.txt—
- 参考文档security_categories/hardcoded_secrets.txt—
- 其他security_categories/hh1132 B
- 参考文档security_categories/sensitive_file_access.txt—
- 脚本security_scan_results/aggregate_results.py10.3 KB
- 参考文档security_scan_results/AGGREGATED_REPORT.md11.9 KB
- 脚本security_scan_results/comparison_report.py4.3 KB
- 参考文档security_scan_results/SECURITY_AUDIT_REPORT.md12.2 KB
- 参考文档SKILL.md_UPDATE_PLAN.md2.4 KB
- 参考文档SKILL.md_VALIDATION_REPORT.md5.2 KB
- 脚本src/__init__.py1.2 KB
- 脚本src/analyzers/ast_analyzer.py10.0 KB
- 脚本src/analyzers/base.py919 B
- 脚本src/analyzers/dependency_analyzer.py8.9 KB
- 脚本src/analyzers/regex_analyzer.py10.0 KB
- 脚本src/analyzers/secret_analyzer.py11.0 KB
- 脚本src/analyzers/taint_analyzer.py7.0 KB
- 脚本src/cli.py4.9 KB
- 脚本src/config/__init__.py319 B
- 脚本src/config/loader.py9.1 KB
- 脚本src/config/validator.py9.1 KB
- 脚本src/formatters/base.py644 B
- 脚本src/formatters/json_formatter.py553 B
- 脚本src/formatters/markdown_formatter.py2.7 KB
- 脚本src/formatters/text_formatter.py5.1 KB
- 脚本src/rules.py8.2 KB
- 脚本src/scanner.py5.3 KB
- 脚本src/types.py2.9 KB
- 脚本src/utils/__init__.py124 B
- 脚本src/utils/entropy.py2.7 KB
- 参考文档status.md20.6 KB
- 脚本tests/__init__.py668 B
- 脚本tests/conftest.py7.8 KB
- 脚本tests/integration/__init__.py50 B
- 脚本tests/integration/test_cli.py10.6 KB
- 脚本tests/integration/test_scanner.py11.7 KB
- 脚本tests/run_tests.py2.2 KB
- 脚本tests/test_v31_enhancements.py9.6 KB
- 脚本tests/unit/__init__.py41 B
- 脚本tests/unit/test_analyzers.py17.6 KB
- 脚本tests/unit/test_config.py10.6 KB
- 脚本tests/unit/test_formatters.py16.9 KB
- 脚本tests/unit/test_rules.py15.5 KB
- 脚本tests/unit/test_secret_detection.py13.8 KB
- 脚本tests/unit/test_types.py13.7 KB
- 参考文档TRUSTSKILL_V3_VALIDATION_REPORT.md8.8 KB
- 参考文档V3_ENHANCEMENT_PLAN.md9.9 KB
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
deepfor untrusted skills,standardfor quick checks - [ ] Output format is set - Use
jsonfor automation,textfor 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:
-
Data Exfiltration Patterns
- Sending files to unknown servers
- POST requests with system information
- Uploading
.ssh,.env, or credential files
-
Backdoor Patterns
- Hidden network listeners
- Encoded/obfuscated malicious code
- Scheduled tasks creating persistence
-
Destructive Operations
rm -rf /or equivalentshutil.rmtreeon user directories- Mass file deletion patterns
-
Credential Harvesting
- Reading
/etc/passwd,/etc/shadow - Accessing browser credential stores
- Extracting SSH private keys
- Reading
Action: Delete the skill immediately and report to security team.
What It Detects
High Risk 🔴
- Tainted Command Injection: User input flowing to
eval(),exec(), oros.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__orimportlibwith 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
- Before installing untrusted skills - Always scan skills from unknown sources
- Periodic audits - Regular security checks of installed skills
- Pre-execution validation - Before running skill scripts that modify system
- Publishing validation - Before publishing skills to ClawHub
- CI/CD integration - Use
--format jsonfor 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 fileyarn.lock- Yarn lock filepnpm-lock.yaml- pnpm lock filecomposer.lock- PHP Composer lock filepoetry.lock- Python Poetry lock fileCargo.lock- Rust Cargo lock fileGemfile.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.pywith_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_heresk-...,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
-
Integrity Hashes in Lock Files (v3.1+ handles automatically)
"integrity": "sha512-P33hHGdldxGabLFjPPpaTxVolMrzrcegejx..."→ These are SRI hashes, not secrets
-
Documentation Placeholders (v3.1+ handles automatically)
export API_KEY="your_api_key_here"→ This is documentation, not a real secret
-
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:
- Multiple HIGH findings in the same skill
- Findings involve external network communication
- Code appears intentionally obfuscated
- Files accessed outside workspace without clear reason
- 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 found1: High-risk issues detected (useful for CI/CD pipelines)
License
MIT License - See the LICENSE file for details.
04 同仓库更多 Skills
webapp-testing
Web application testing principles. E2E, Playwright, deep audit strategies.
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.
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.
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.
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.
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.