clawsec-scanner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ClawSec Scanner

ClawSec 扫描器

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 dynamic analysis with real OpenClaw hook execution harness (malicious input, timeout, output bounds, event mutation safety)
Unified Reporting: Consolidated vulnerability reports with severity classification and remediation guidance
Continuous Monitoring: OpenClaw hook integration for automated periodic scanning

面向Agent平台的综合安全扫描器，可从多个维度自动化检测漏洞：

依赖扫描：使用
```
npm audit
```
和
```
pip-audit
```
分析npm和Python依赖，支持结构化JSON输出解析
CVE数据库集成：查询OSV（主数据源）、NVD 2.0和GitHub Advisory数据库以补充漏洞信息
SAST分析：使用Semgrep（针对JavaScript/TypeScript）和Bandit（针对Python）执行静态代码分析，检测硬编码密钥、命令注入、路径遍历和不安全反序列化漏洞
DAST框架：Agent专属动态分析能力，搭载真实OpenClaw钩子执行测试套件（恶意输入、超时、输出边界、事件突变安全性检测）
统一报告：整合漏洞报告，附带 severity 分级和修复指南
持续监控：支持OpenClaw钩子集成，可实现自动化定期扫描

Features

功能特性

Multi-Engine Scanning

多引擎扫描

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

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
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
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
Dynamic Analysis (DAST)
- Real hook execution harness for OpenClaw hook handlers discovered from
```
HOOK.md
```
  metadata
- Verifies: malicious input resilience, timeout behavior, output amplification bounds, and core event mutation safety
- Note: Traditional web DAST tools (ZAP, Burp) do not apply to agent platforms - this provides agent-specific testing

扫描器协调四类互补的扫描类型，实现全面的漏洞覆盖：

依赖扫描
- 以子进程方式执行
```
npm audit --json
```
  和
```
pip-audit -f json
```
- 解析结构化输出，提取CVE ID、严重等级、受影响版本
- 处理边界场景：缺失package-lock.json、零漏洞、JSON格式错误
CVE数据库查询
- OSV API（主数据源）：免费、无需认证，支持广泛生态（npm、PyPI、Go、Maven）
- NVD 2.0（可选）：需要API密钥以避免6秒请求速率限制
- GitHub Advisory Database（可选）：需要OAuth令牌的GraphQL API
- 将所有API响应标准化为统一的
```
Vulnerability
```
  schema
静态分析（SAST）
- 针对JavaScript/TypeScript的Semgrep：使用
```
--config auto
```
  或
```
--config p/security-audit
```
  检测安全问题
- 针对Python的Bandit：复用现有
```
pyproject.toml
```
  配置
- 可识别：硬编码密钥（API密钥、令牌）、命令注入（
```
eval
```
  、
```
exec
```
  ）、路径遍历、不安全反序列化
动态分析（DAST）
- 针对从
```
HOOK.md
```
  元数据中发现的OpenClaw钩子处理程序的真实钩子执行测试套件
- 验证项：恶意输入韧性、超时行为、输出放大边界、核心事件突变安全性
- 注意：传统Web DAST工具（ZAP、Burp）不适用于Agent平台，本工具提供Agent专属测试能力

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

所有扫描类型均输出符合统一

ScanReport

JSON schema的结果：

typescript

{
  scan_id: string;         // UUID
  timestamp: string;       // ISO 8601
  target: string;          // 扫描路径
  vulnerabilities: Vulnerability[];
  summary: {
    critical: number;
    high: number;
    medium: number;
    low: number;
    info: number;
  }
}

每个

Vulnerability

对象包含：

```
id
```
：CVE-2023-12345 或 GHSA-xxxx-yyyy-zzzz
```
source
```
：npm-audit | pip-audit | osv | nvd | github | sast | dast
```
severity
```
：critical | high | medium | low | info
```
package
```
：包名（SAST/DAST场景为'N/A'）
```
version
```
：受影响版本
```
fixed_version
```
：首个包含修复的版本（如有）
```
title
```
：简短描述
```
description
```
：完整公告文本
```
references
```
：更多信息的URL
```
discovered_at
```
：ISO 8601 时间戳

OpenClaw Integration

OpenClaw 集成

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

通过钩子实现自动化持续监控：

可配置扫描间隔（默认：86400秒 / 24小时）
在
```
agent:bootstrap
```
和
```
command:new
```
事件触发扫描
将结果发布到
```
event.messages
```
数组，附带严重等级汇总
可通过
```
CLAWSEC_SCANNER_INTERVAL
```
环境变量配置速率限制

Installation

安装

Prerequisites

前置依赖

Verify required binaries are available:

bash

undefined

确认所需二进制文件可用：

bash

undefined

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

pip-audit --version # 安装命令：uv pip install pip-audit semgrep --version # 安装命令：pip install semgrep 或 brew install semgrep bandit --version # 安装命令：uv pip install bandit

Utilities

工具集

jq --version curl --version

undefined

jq --version curl --version

undefined

Option A: Via clawhub (recommended)

方案A：通过clawhub安装（推荐）

bash

npx clawhub@latest install clawsec-scanner

bash

npx clawhub@latest install clawsec-scanner

Option B: Manual installation with verification

方案B：手动安装+校验

bash

set -euo pipefail

VERSION="${SKILL_VERSION:?Set SKILL_VERSION (e.g. 0.1.0)}"
INSTALL_ROOT="${INSTALL_ROOT:-$HOME/.openclaw/skills}"
DEST="$INSTALL_ROOT/clawsec-scanner"
BASE="https://github.com/prompt-security/clawsec/releases/download/clawsec-scanner-v${VERSION}"

TEMP_DIR="$(mktemp -d)"
trap 'rm -rf "$TEMP_DIR"' EXIT

bash

set -euo pipefail

VERSION="${SKILL_VERSION:?Set SKILL_VERSION (e.g. 0.1.0)}"
INSTALL_ROOT="${INSTALL_ROOT:-$HOME/.openclaw/skills}"
DEST="$INSTALL_ROOT/clawsec-scanner"
BASE="https://github.com/prompt-security/clawsec/releases/download/clawsec-scanner-v${VERSION}"

TEMP_DIR="$(mktemp -d)"
trap 'rm -rf "$TEMP_DIR"' EXIT

Pinned release-signing public key

固定的发布签名公钥

Fingerprint (SHA-256 of SPKI DER): 711424e4535f84093fefb024cd1ca4ec87439e53907b305b79a631d5befba9c8

指纹（SPKI DER的SHA-256）：711424e4535f84093fefb024cd1ca4ec87439e53907b305b79a631d5befba9c8

cat > "$TEMP_DIR/release-signing-public.pem" <<'PEM' -----BEGIN PUBLIC KEY----- MCowBQYDK2VwAyEAS7nijfMcUoOBCj4yOXJX+GYGv2pFl2Yaha1P4v5Cm6A= -----END PUBLIC KEY----- PEM

ZIP_NAME="clawsec-scanner-v${VERSION}.zip"

cat > "$TEMP_DIR/release-signing-public.pem" <<'PEM' -----BEGIN PUBLIC KEY----- MCowBQYDK2VwAyEAS7nijfMcUoOBCj4yOXJX+GYGv2pFl2Yaha1P4v5Cm6A= -----END PUBLIC KEY----- PEM

ZIP_NAME="clawsec-scanner-v${VERSION}.zip"

Download release archive + signed checksums

下载发布包+签名校验和

curl -fsSL "$BASE/$ZIP_NAME" -o "$TEMP_DIR/$ZIP_NAME" curl -fsSL "$BASE/checksums.json" -o "$TEMP_DIR/checksums.json" curl -fsSL "$BASE/checksums.sig" -o "$TEMP_DIR/checksums.sig"

Verify checksums manifest signature

校验校验和清单签名

openssl base64 -d -A -in "$TEMP_DIR/checksums.sig" -out "$TEMP_DIR/checksums.sig.bin" if ! openssl pkeyutl -verify
-pubin
-inkey "$TEMP_DIR/release-signing-public.pem"
-sigfile "$TEMP_DIR/checksums.sig.bin"
-rawin
-in "$TEMP_DIR/checksums.json" >/dev/null 2>&1; then echo "ERROR: checksums.json signature verification failed" >&2 exit 1 fi

EXPECTED_SHA="$(jq -r '.archive.sha256 // empty' "$TEMP_DIR/checksums.json")" if [ -z "$EXPECTED_SHA" ]; then echo "ERROR: checksums.json missing archive.sha256" >&2 exit 1 fi

ACTUAL_SHA="$(shasum -a 256 "$TEMP_DIR/$ZIP_NAME" | awk '{print $1}')" if [ "$EXPECTED_SHA" != "$ACTUAL_SHA" ]; then echo "ERROR: Archive checksum mismatch" >&2 exit 1 fi

echo "Checksums verified. Installing..."

mkdir -p "$INSTALL_ROOT" rm -rf "$DEST" unzip -q "$TEMP_DIR/$ZIP_NAME" -d "$INSTALL_ROOT"

chmod 600 "$DEST/skill.json" find "$DEST" -type f ! -name "skill.json" -exec chmod 644 {} ;

echo "Installed clawsec-scanner v${VERSION} to: $DEST" echo "Next step: Run a scan or set up continuous monitoring"

undefined

EXPECTED_SHA="$(jq -r '.archive.sha256 // empty' "$TEMP_DIR/checksums.json")" if [ -z "$EXPECTED_SHA" ]; then echo "ERROR: checksums.json 缺失 archive.sha256 字段" >&2 exit 1 fi

ACTUAL_SHA="$(shasum -a 256 "$TEMP_DIR/$ZIP_NAME" | awk '{print $1}')" if [ "$EXPECTED_SHA" != "$ACTUAL_SHA" ]; then echo "ERROR: 安装包校验和不匹配" >&2 exit 1 fi

echo "校验和验证通过，正在安装..."

mkdir -p "$INSTALL_ROOT" rm -rf "$DEST" unzip -q "$TEMP_DIR/$ZIP_NAME" -d "$INSTALL_ROOT"

chmod 600 "$DEST/skill.json" find "$DEST" -type f ! -name "skill.json" -exec chmod 644 {} ;

echo "已安装 clawsec-scanner v${VERSION} 到路径：$DEST" echo "下一步：执行扫描或配置持续监控"

undefined

Usage

使用说明

On-Demand CLI Scanning

按需CLI扫描

bash

SCANNER_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-scanner"

bash

SCANNER_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-scanner"

Scan all skills with JSON output

扫描所有skill，输出JSON格式结果

"$SCANNER_DIR/scripts/runner.sh" --target ./skills/ --output report.json --format json

Scan specific directory with human-readable output

扫描指定目录，输出人类可读格式结果

"$SCANNER_DIR/scripts/runner.sh" --target ./my-skill/ --format text

Check available flags

查看可用参数

"$SCANNER_DIR/scripts/runner.sh" --help


**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

"$SCANNER_DIR/scripts/runner.sh" --help


**CLI参数：**
- `--target <path>`：要扫描的目录（必填）
- `--output <file>`：将结果写入文件（可选，默认输出到stdout）
- `--format <json|text>`：输出格式（默认：json）
- `--check`：验证所有所需二进制文件是否已安装

OpenClaw Hook Setup (Continuous Monitoring)

OpenClaw钩子配置（持续监控）

Enable automated periodic scanning:

bash

SCANNER_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-scanner"
node "$SCANNER_DIR/scripts/setup_scanner_hook.mjs"

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.

启用自动化定期扫描：

bash

SCANNER_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-scanner"
node "$SCANNER_DIR/scripts/setup_scanner_hook.mjs"

该操作会创建一个钩子，具备以下能力：

在
```
agent:bootstrap
```
和
```
command:new
```
事件触发扫描
遵守
```
CLAWSEC_SCANNER_INTERVAL
```
速率限制（默认：86400秒 / 24小时）
将扫描结果和严重等级汇总发布到会话中
为高危/严重漏洞提供修复建议

启用钩子后重启OpenClaw网关，然后执行

/new

即可触发立即扫描。

Environment Variables

环境变量

bash

undefined

bash

undefined

Optional - NVD API key to avoid rate limiting (6-second delays without key)

可选 - NVD API密钥，用于避免速率限制（无密钥时会有6秒延迟）

export CLAWSEC_NVD_API_KEY="your-nvd-api-key"

Optional - GitHub OAuth token for Advisory Database queries

可选 - 用于查询Advisory Database的GitHub OAuth令牌

export GITHUB_TOKEN="ghp_your_token_here"

Optional - Scanner hook interval in seconds (default: 86400 / 24 hours)

可选 - 扫描钩子执行间隔，单位秒（默认：86400 / 24小时）

export CLAWSEC_SCANNER_INTERVAL="86400"

Optional - Allow unsigned advisory feed during development (from clawsec-suite)

可选 - 开发环境下允许未签名的公告源（来自clawsec-suite）

export CLAWSEC_ALLOW_UNSIGNED_FEED="1"

undefined

export CLAWSEC_ALLOW_UNSIGNED_FEED="1"

undefined

Architecture

架构设计

Modular Design

模块化设计

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

scripts/runner.sh              # Orchestration layer
├── scan_dependencies.mjs      # npm audit + pip-audit
├── query_cve_databases.mjs    # OSV/NVD/GitHub API queries
├── sast_analyzer.mjs          # Semgrep + Bandit static analysis
├── dast_runner.mjs            # Dynamic security testing orchestration
└── dast_hook_executor.mjs     # Isolated real hook execution harness

lib/
├── report.mjs                 # Result aggregation and formatting
├── utils.mjs                  # Subprocess exec, JSON parsing, error handling
└── types.ts                   # TypeScript schema definitions

hooks/clawsec-scanner-hook/
├── HOOK.md                    # OpenClaw hook metadata
└── handler.ts                 # Periodic scan trigger

每类扫描都是独立模块，可单独运行或作为统一扫描的一部分执行：

scripts/runner.sh              # 编排层
├── scan_dependencies.mjs      # npm audit + pip-audit
├── query_cve_databases.mjs    # OSV/NVD/GitHub API查询
├── sast_analyzer.mjs          # Semgrep + Bandit 静态分析
├── dast_runner.mjs            # 动态安全测试编排
└── dast_hook_executor.mjs     # 隔离的真实钩子执行测试套件

lib/
├── report.mjs                 # 结果聚合和格式化
├── utils.mjs                  # 子进程执行、JSON解析、错误处理
└── types.ts                   # TypeScript schema定义

hooks/clawsec-scanner-hook/
├── HOOK.md                    # OpenClaw钩子元数据
└── handler.ts                 # 定期扫描触发器

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)

扫描器优先保障可用性，而非严格的故障传播：

网络故障 → 输出部分结果，记录警告日志
工具缺失 → 跳过对应扫描类型，继续执行其他扫描
JSON格式错误 → 解析有效部分，记录错误日志
API速率限制 → 实现指数退避，回退到其他数据源
零漏洞 → 输出空数组的成功报告

会直接退出的严重故障：

目标路径不存在
无可用扫描工具（所有二进制文件缺失）
检测到并发扫描（存在锁文件）

Subprocess Execution Pattern

子进程执行模式

All external tools run as subprocesses with structured JSON output:

javascript

import { spawn } from 'node:child_process';

// Example: npm audit execution
const proc = spawn('npm', ['audit', '--json'], {
  cwd: targetPath,
  stdio: ['ignore', 'pipe', 'pipe']
});

// Handle non-zero exit codes gracefully
// npm audit exits 1 when vulnerabilities found (not an error!)
proc.on('close', code => {
  if (code !== 0 && stderr.includes('ERR!')) {
    // Actual error
    reject(new Error(stderr));
  } else {
    // Vulnerabilities found or success
    resolve(JSON.parse(stdout));
  }
});

所有外部工具均以子进程方式运行，输出结构化JSON：

javascript

import { spawn } from 'node:child_process';

// 示例：执行npm audit
const proc = spawn('npm', ['audit', '--json'], {
  cwd: targetPath,
  stdio: ['ignore', 'pipe', 'pipe']
});

// 优雅处理非零退出码
// 当发现漏洞时npm audit会返回退出码1（并非错误！）
proc.on('close', code => {
  if (code !== 0 && stderr.includes('ERR!')) {
    // 真实错误
    reject(new Error(stderr));
  } else {
    // 发现漏洞或执行成功
    resolve(JSON.parse(stdout));
  }
});

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

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

"TypeScript hook not executable in DAST harness"

The DAST harness executes real hook handlers and transpiles
```
handler.ts
```
files when a TypeScript compiler is available
Install TypeScript in the scanner environment:
```
npm install -D typescript
```
(or provide
```
handler.js
```
/
```
handler.mjs
```
)
Without a compiler, scanner reports an
```
info
```
-level coverage finding instead of a high-severity vulnerability

"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

"Missing package-lock.json"警告

```
npm audit
```
需要锁文件才能运行
在目标目录执行
```
npm install
```
生成锁文件
如果npm audit执行失败，扫描器会继续执行其他扫描类型

"NVD API rate limit exceeded"

设置
```
CLAWSEC_NVD_API_KEY
```
环境变量
无API密钥时：请求之间会强制增加6秒延迟
OSV API作为主数据源（无速率限制）

"pip-audit not found"

安装：

uv pip install pip-audit

或

pip install pip-audit

验证：
```
which pip-audit
```
如果安装在非标准路径，将其添加到PATH中

"Semgrep binary missing"

安装：
```
pip install semgrep
```
或
```
brew install semgrep
```
需要Python 3.8+运行时
替代方案：使用Docker镜像
```
returntocorp/semgrep
```

"TypeScript hook not executable in DAST harness"

DAST测试套件会执行真实的钩子处理程序，当TypeScript编译器可用时会转译
```
handler.ts
```
文件
在扫描器环境中安装TypeScript：
```
npm install -D typescript
```
（或提供
```
handler.js
```
/
```
handler.mjs
```
）
无编译器时，扫描器会报告
```
info
```
级别的覆盖提示，而非高危漏洞

"Concurrent scan detected"

存在锁文件：
```
/tmp/clawsec-scanner.lock
```
等待运行中的扫描完成，或手动删除锁文件
该机制用于避免扫描重叠导致结果不一致

Verification

功能验证

Check scanner is working correctly:

bash

undefined

检查扫描器是否正常工作：

bash

undefined

Verify required binaries

验证所需二进制文件

./scripts/runner.sh --check

Run unit tests

运行单元测试

node test/dependency_scanner.test.mjs node test/cve_integration.test.mjs node test/sast_engine.test.mjs node test/dast_harness.test.mjs

Validate skill structure

验证skill结构

python ../../utils/validate_skill.py .

Scan test fixtures (should detect known vulnerabilities)

扫描测试用例（应检测到已知漏洞）

./scripts/runner.sh --target test/fixtures/ --format text

undefined

./scripts/runner.sh --target test/fixtures/ --format text

undefined

Development

开发指南

Running Tests

运行测试

bash

undefined

bash

undefined

All tests (vanilla Node.js, no framework)

所有测试（原生Node.js，无框架依赖）

for test in test/*.test.mjs; do node "$test" || exit 1 done

Individual test suites

单个测试套件

node test/dependency_scanner.test.mjs # Dependency scanning node test/cve_integration.test.mjs # CVE database APIs node test/sast_engine.test.mjs # Static analysis node test/dast_harness.test.mjs # DAST harness execution

undefined

node test/dependency_scanner.test.mjs # 依赖扫描 node test/cve_integration.test.mjs # CVE数据库API node test/sast_engine.test.mjs # 静态分析 node test/dast_harness.test.mjs # DAST测试套件执行

undefined

Linting

代码检查

bash

undefined

bash

undefined

JavaScript/TypeScript

npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0

Python (Bandit already configured in pyproject.toml)

Python（pyproject.toml中已配置Bandit）

ruff check . bandit -r . -ll

Shell scripts

Shell脚本

shellcheck scripts/*.sh

undefined

shellcheck scripts/*.sh

undefined

Adding Custom Semgrep Rules

添加自定义Semgrep规则

Create custom rules in

.semgrep/rules/

yaml

rules:
  - id: custom-security-rule
    pattern: dangerous_function($ARG)
    message: Avoid dangerous_function - use safe_alternative instead
    severity: WARNING
    languages: [javascript, typescript]

Update

scripts/sast_analyzer.mjs

to include custom rules:

javascript

const proc = spawn('semgrep', [
  'scan',
  '--config', 'auto',
  '--config', '.semgrep/rules/',  // Add custom rules
  '--json',
  targetPath
]);

在

.semgrep/rules/

目录下创建自定义规则：

yaml

rules:
  - id: custom-security-rule
    pattern: dangerous_function($ARG)
    message: 避免使用dangerous_function，请改用safe_alternative
    severity: WARNING
    languages: [javascript, typescript]

更新

scripts/sast_analyzer.mjs

引入自定义规则：

javascript

const proc = spawn('semgrep', [
  'scan',
  '--config', 'auto',
  '--config', '.semgrep/rules/',  // 引入自定义规则
  '--json',
  targetPath
]);

Integration with ClawSec Suite

与ClawSec套件集成

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:

bash

npx clawhub@latest install clawsec-suite

扫描器可单独运行，也可作为ClawSec生态的一部分使用：

clawsec-suite：可安装和管理clawsec-scanner的元skill
clawsec-feed：用于恶意skill检测的公告源（补充能力）
openclaw-audit-watchdog：基于Cron的审计自动化工具（类似模式）

安装完整ClawSec套件：

bash

npx clawhub@latest install clawsec-suite

Then use clawsec-suite to discover and install clawsec-scanner

然后使用clawsec-suite发现并安装clawsec-scanner

undefined

undefined

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

扫描器代码中无硬编码密钥
API密钥仅从环境变量读取（绝不会被日志记录或提交）
子进程参数使用数组形式，避免Shell注入
所有外部工具输出均通过try/catch错误处理逻辑解析

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

严重/高危漏洞应立即修复：

依赖中存在已知EXP（CVSS 9.0+）
代码中存在硬编码API密钥或凭证
命令注入漏洞
无校验的路径遍历漏洞

中危/低危漏洞可在正常迭代周期内修复：

无已知EXP的过时依赖
缺失安全头
弱加密算法使用

提示类发现仅为参考建议：

废弃API使用
代码检查工具标记的代码质量问题

Roadmap

路线图

v0.0.2 (Current)

v0.0.2（当前版本）

Future Enhancements

未来功能增强

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

发现安全问题？请私下发送邮件到security@prompt.security报告。

如需提交功能请求和Bug报告，请在以下地址提交Issue： https://github.com/prompt-security/clawsec/issues

License

许可证

AGPL-3.0-or-later

See LICENSE file in repository root for full text.

AGPL-3.0-or-later

完整文本请查看仓库根目录的LICENSE文件。

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/

ClawSec主页：https://clawsec.prompt.security
文档：https://clawsec.prompt.security/scanner
GitHub仓库：https://github.com/prompt-security/clawsec
OSV API文档：https://osv.dev/docs/
NVD API文档：https://nvd.nist.gov/developers/vulnerabilities
Semgrep规则市场：https://semgrep.dev/explore
Bandit文档：https://bandit.readthedocs.io/