clawsec-scanner

Files (26)

• CHANGELOG.md
• README.md
• SKILL.md
• .gitkeep · hooks/
• HOOK.md · hooks/clawsec-scanner-hook/
• handler.ts · hooks/clawsec-scanner-hook/
• .gitkeep · lib/
• report.mjs · lib/
• types.ts · lib/
• utils.mjs · lib/
• .gitkeep · scripts/
• dast_hook_executor.mjs · scripts/
• dast_runner.mjs · scripts/
• query_cve_databases.mjs · scripts/
• runner.sh · scripts/
• sast_analyzer.mjs · scripts/
• scan_dependencies.mjs · scripts/
• setup_scanner_hook.mjs · scripts/
• skill.json
• .gitkeep · test/
• cve_integration.test.mjs · test/
• dast_harness.test.mjs · test/
• dependency_scanner.test.mjs · test/
• test_harness.mjs · test/lib/
• reviewer_regressions.test.mjs · test/
• sast_engine.test.mjs · test/

SKILL.md (first lines)

# 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:

```bash
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:

```typescript
{
  scan_id: string;         // UUID
  timestamp: string;       // ISO 8601
  target: string;          // Scanned path
  vulnerabilities: Vulnerability[];
  summary: {
    critical: number;
    high: number;
    medium: number;
    low: number;
    info: number;
  }
}
```

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:

```bash
# Core runtimes
node --version  # v20+
npm --version
python3 --version  # 3.10+

# Scanning tools
pip-audit --version  # Install: uv pip install pip-audit
semgrep --version    # Install: pip install semgrep OR brew install semgrep
bandit --version     # Install: uv pip install bandit

# Utilities
jq --version
curl --version
```

### Option A: Via clawhub (recommended)

```bash
npx clawhub@latest install clawsec-scanner
```

### Option B: Manual installation with verification

```bash
set -euo pipefail

From prompt-security/clawsec, AGPL-3.0.

More from prompt-security/clawsec