clawsec-scanner

ClawSec Scanner

Comprehensive security scanner for agent platforms that automates vulnerability detection across multiple dimensions:

• Dependency Scanning: Analyzes npm and Python dependencies using npm audit and pip-audit with structured JSON output parsing
• CVE Database Integration: Queries OSV (primary), NVD 2.0, and GitHub Advisory Database for vulnerability enrichment
• SAST Analysis: Static code analysis using Semgrep (JavaScript/TypeScript) and Bandit (Python) to detect hardcoded secrets, command injection, path traversal, and unsafe deserialization
• DAST Framework: Agent-specific static analysis of OpenClaw hook metadata and handler source without importing or invoking target code
• Unified Reporting: Consolidated vulnerability reports with severity classification and remediation guidance
• Continuous Monitoring: OpenClaw hook integration for automated periodic scanning

Vercel Skills Installation

Install with the Vercel Skills CLI for this harness:

npx skills add prompt-security/clawsec --skill clawsec-scanner -a openclaw -y

Features

Multi-Engine Scanning

The scanner orchestrates four complementary scan types to provide comprehensive vulnerability coverage:

1. Dependency Scanning

   • Executes npm audit --json and pip-audit -f json as subprocesses
   • Parses structured output to extract CVE IDs, severity, affected versions
   • Handles edge cases: missing package-lock.json, zero vulnerabilities, malformed JSON

2. CVE Database Queries

   • OSV API (primary): Free, no authentication, broad ecosystem support (npm, PyPI, Go, Maven)
   • NVD 2.0 (optional): Requires API key to avoid 6-second rate limiting
   • GitHub Advisory Database (optional): GraphQL API with OAuth token
   • Normalizes all API responses to unified Vulnerability schema

3. Static Analysis (SAST)

   • Semgrep for JavaScript/TypeScript: Detects security issues using --config auto or --config p/security-audit
   • Bandit for Python: Leverages existing pyproject.toml configuration
   • Identifies: hardcoded secrets (API keys, tokens), command injection (eval, exec), path traversal, unsafe deserialization

4. Dynamic Analysis (DAST)

   • Static hook inspection for OpenClaw hook handlers discovered from HOOK.md metadata
   • Verifies coverage and source-level risk signals without importing, transpiling, or invoking target handlers
   • Note: Traditional web DAST tools (ZAP, Burp) do not apply to agent platforms - this provides agent-specific testing

Unified Reporting

All scan types emit a consistent ScanReport JSON schema:

{
  scan_id: string;         

Each Vulnerability object includes:

• id: CVE-2023-12345 or GHSA-xxxx-yyyy-zzzz
• source: npm-audit | pip-audit | osv | nvd | github | sast | dast
• severity: critical | high | medium | low | info
• package: Package name (or 'N/A' for SAST/DAST)
• version: Affected version
• fixed_version: First version with fix (if available)
• title: Short description
• description: Full advisory text
• references: URLs for more info
• discovered_at: ISO 8601 timestamp

OpenClaw Integration

Automated continuous monitoring via hook:

• Runs scanner on configurable interval (default: 86400s / 24 hours)
• Triggers on agent:bootstrap and command:new events
• Posts findings to event.messages array with severity summary
• Rate-limited by CLAWSEC_SCANNER_INTERVAL environment variable

Installation

Prerequisites

Verify required binaries are available:

Option A: Via clawhub (recommended)

Option B: Manual installation with verification

Usage

On-Demand CLI Scanning

CLI Flags:

• --target <path>: Directory to scan (required)
• --output <file>: Write results to file (optional, defaults to stdout)
• --format <json|text>: Output format (default: json)
• --check: Verify all required binaries are installed

OpenClaw Hook Setup (Continuous Monitoring)

Enable automated periodic scanning:

This creates a hook that:

• Scans on agent:bootstrap and command:new events
• Respects CLAWSEC_SCANNER_INTERVAL rate limiting (default: 86400 seconds / 24 hours)
• Posts findings to conversation with severity summary
• Recommends remediation for high/critical vulnerabilities

Restart the OpenClaw gateway after enabling the hook, then run /new to trigger an immediate scan.

Environment Variables

Architecture

Modular Design

Each scan type is an independent module that can run standalone or as part of unified scan:

Fail-Open Philosophy

The scanner prioritizes availability over strict failure propagation:

• Network failures → emit partial results, log warnings
• Missing tools → skip that scan type, continue with others
• Malformed JSON → parse what's valid, log errors
• API rate limits → implement exponential backoff, fallback to other sources
• Zero vulnerabilities → emit success report with empty array

Critical failures that exit immediately:

• Target path does not exist
• No scanning tools available (all bins missing)
• Concurrent scan detected (lockfile present)

Subprocess Execution Pattern

All external tools run as subprocesses with structured JSON output:

Troubleshooting

Common Issues

"Missing package-lock.json" warning

• npm audit requires lockfile to run
• Run npm install in target directory to generate
• Scanner continues with other scan types if npm audit fails

"NVD API rate limit exceeded"

• Set CLAWSEC_NVD_API_KEY environment variable
• Without API key: 6-second delays enforced between requests
• OSV API used as primary source (no rate limits)

"pip-audit not found"

• Install: uv pip install pip-audit or pip install pip-audit
• Verify: which pip-audit
• Add to PATH if installed in non-standard location

"Semgrep binary missing"

• Install: pip install semgrep OR brew install semgrep
• Requires Python 3.8+ runtime
• Alternative: use Docker image returntocorp/semgrep

"DAST static coverage finding"

• The DAST harness does not execute target hook handlers.
• JavaScript and TypeScript hook files are read as source and reported with info-level static coverage findings.
• Review any listed static signals manually when deciding whether a hook needs deeper sandboxed testing.

"Concurrent scan detected"

• Lockfile exists: /tmp/clawsec-scanner.lock
• Wait for running scan to complete or manually remove lockfile
• Prevents overlapping scans that could produce inconsistent results

Verification

Check scanner is working correctly:

Development

Running Tests

Linting

Adding Custom Semgrep Rules

Create custom rules in .semgrep/rules/:

Update scripts/sast_analyzer.mjs to include custom rules:

Integration with ClawSec Suite

The scanner works standalone or as part of the ClawSec ecosystem:

• clawsec-suite: Meta-skill that can install and manage clawsec-scanner
• clawsec-feed: Advisory feed for malicious skill detection (complementary)
• openclaw-audit-watchdog: Cron-based audit automation (similar pattern)

Install the full ClawSec suite:

Security Considerations

Scanner Security

• No hardcoded secrets in scanner code
• API keys read from environment variables only (never logged or committed)
• Subprocess arguments use arrays to prevent shell injection
• All external tool output parsed with try/catch error handling

Vulnerability Prioritization

Critical/High severity findings should be addressed immediately:

• Known exploits in dependencies (CVSS 9.0+)
• Hardcoded API keys or credentials in code
• Command injection vulnerabilities
• Path traversal without validation

Medium/Low severity findings can be addressed in normal sprint cycles:

• Outdated dependencies without known exploits
• Missing security headers
• Weak cryptography usage

Info findings are advisory only:

• Deprecated API usage
• Code quality issues flagged by linters

Roadmap

v0.0.4 (Current)

• Dependency scanning (npm audit, pip-audit)
• CVE database integration (OSV, NVD, GitHub Advisory)
• SAST analysis (Semgrep, Bandit)
• Static OpenClaw hook inspection for DAST without target code execution
• Unified JSON reporting
• OpenClaw hook integration

Future Enhancements

• Automatic remediation (dependency upgrades, code fixes)
• SARIF output format for GitHub Code Scanning integration
• Web dashboard for vulnerability tracking over time
• CI/CD GitHub Action for PR blocking on high-severity findings
• Container image scanning (Docker, OCI)
• Infrastructure-as-Code scanning (Terraform, CloudFormation)
• Comprehensive agent workflow DAST (requires deeper platform integration)

Contributing

Found a security issue? Please report privately to security@prompt.security.

For feature requests and bug reports, open an issue at: https://github.com/prompt-security/clawsec/issues

License

AGPL-3.0-or-later

See LICENSE file in repository root for full text.

Resources

• ClawSec Homepage: https://clawsec.prompt.security
• Documentation: https://clawsec.prompt.security/scanner
• GitHub Repository: https://github.com/prompt-security/clawsec
• OSV API Docs: https://osv.dev/docs/
• NVD API Docs: https://nvd.nist.gov/developers/vulnerabilities
• Semgrep Registry: https://semgrep.dev/explore
• Bandit Documentation: https://bandit.readthedocs.io/