clawsec-scanner

ClawSec Scanner

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

• 依赖项扫描：使用 npm audit 和 pip-audit 分析 npm 和 Python 依赖项，并解析结构化 JSON 输出
• CVE 数据库集成：查询 OSV（主要）、NVD 2.0 和 GitHub Advisory Database，以补充漏洞信息
• SAST 分析：使用 Semgrep（JavaScript/TypeScript）和 Bandit（Python）进行静态代码分析，检测硬编码密钥、命令注入、路径遍历和不安全反序列化
• DAST 框架：针对 OpenClaw hook 元数据和处理程序源代码进行 Agent 专用静态分析，不导入或调用目标代码
• 统一报告：汇总漏洞报告，并提供严重性分类和修复建议
• 持续监控：集成 OpenClaw hook，实现自动定期扫描

Vercel Skills 安装

使用 Vercel Skills CLI 为此执行环境安装：

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

功能

多引擎扫描

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

1. 依赖项扫描

   • 通过子进程执行 npm audit --json 和 pip-audit -f json
   • 解析结构化输出，提取 CVE ID、严重性和受影响版本
   • 处理边缘情况：缺少 package-lock.json、漏洞数量为零、JSON 格式错误

2. CVE 数据库查询

   • OSV API（主要）：免费、无需身份验证，支持多种生态系统（npm、PyPI、Go、Maven）
   • NVD 2.0（可选）：需要 API 密钥，以避免 6 秒的速率限制
   • GitHub Advisory Database（可选）：使用 OAuth 令牌的 GraphQL API
   • 将所有 API 响应规范化为统一的 Vulnerability 架构

3. 静态分析（SAST）

   • Semgrep（JavaScript/TypeScript）：使用 --config auto 或 --config p/security-audit 检测安全问题
   • Bandit（Python）：利用现有的 pyproject.toml 配置
   • 可识别：硬编码密钥（API 密钥、令牌）、命令注入（eval、exec）、路径遍历、不安全反序列化

4. 动态分析（DAST）

   • 根据 HOOK.md 元数据发现 OpenClaw hook 处理程序，并进行静态 hook 检查
   • 在不导入、转译或调用目标处理程序的情况下，验证覆盖范围和源代码级风险信号
   • 注意：传统 Web DAST 工具（ZAP、Burp）不适用于 Agent 平台；此功能提供 Agent 专用测试

统一报告

所有扫描类型都会生成一致的 ScanReport JSON 架构：

{
  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;
  }
}

每个 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 集成

通过 hook 实现自动持续监控：

• 按可配置的间隔运行扫描器（默认：86400s / 24 小时）
• 在 agent:bootstrap 和 command:new 事件触发时运行
• 将发现的问题及严重性摘要发布到 event.messages 数组
• 通过 CLAWSEC_SCANNER_INTERVAL 环境变量进行速率限制

安装

先决条件

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

# 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

选项 A：通过 clawhub 安装（推荐）

npx clawhub@latest install clawsec-scanner

选项 B：手动安装并验证

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

用法

按需 CLI 扫描

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

# Scan all skills with JSON output
"$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 标志：

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

OpenClaw Hook 设置（持续监控）

启用自动定期扫描：

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

这会创建一个 Hook，用于：

• 在 agent:bootstrap 和 command:new 事件发生时进行扫描
• 遵循 CLAWSEC_SCANNER_INTERVAL 限流设置（默认值：86400 秒 / 24 小时）
• 将发现的问题及严重程度摘要发送到对话中
• 为高危/严重漏洞提供修复建议

启用 Hook 后，重启 OpenClaw 网关，然后运行 /new 以触发立即扫描。

环境变量

# Optional - NVD API key to avoid rate limiting (6-second delays without key)
export CLAWSEC_NVD_API_KEY="your-nvd-api-key"

# Optional - GitHub OAuth token for Advisory Database queries
export GITHUB_TOKEN="ghp_your_token_here"

# Optional - Scanner hook interval in seconds (default: 86400 / 24 hours)
export CLAWSEC_SCANNER_INTERVAL="86400"

# Optional - Allow unsigned advisory feed during development (from clawsec-suite)
export CLAWSEC_ALLOW_UNSIGNED_FEED="1"

架构

模块化设计

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

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            # Static hook inspection orchestration
└── dast_hook_executor.mjs     # Static hook source inspection helper

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

失败时保持开放的理念

扫描器优先保障可用性，而非严格传递失败：

• 网络故障 → 输出部分结果，并记录警告
• 缺少工具 → 跳过该扫描类型，继续执行其他扫描
• JSON 格式错误 → 解析有效内容，并记录错误
• API 速率限制 → 实施指数退避，并回退到其他来源
• 未发现漏洞 → 输出包含空数组的成功报告

会立即退出的严重故障：

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

子进程执行模式

所有外部工具均作为子进程运行，并输出结构化 JSON：

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));
  }
});

故障排除

常见问题

“缺少 package-lock.json”警告

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

“超出 NVD API 速率限制”

• 设置 CLAWSEC_NVD_API_KEY 环境变量
• 未设置 API 密钥时：请求之间强制等待 6 秒
• 主要使用 OSV API（没有速率限制）

“找不到 pip-audit”

• 安装：uv pip install pip-audit 或 pip install pip-audit
• 验证：which pip-audit
• 如果安装在非标准位置，请将其添加到 PATH

“缺少 Semgrep 二进制文件”

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

“DAST 静态覆盖发现”

• DAST 测试框架不会执行目标 Hook 处理程序。
• JavaScript 和 TypeScript Hook 文件会作为源代码读取，并报告为 info 级静态覆盖发现。
• 判断 Hook 是否需要进行更深入的沙箱测试时，请手动检查列出的任何静态信号。

“检测到并发扫描”

• 锁文件存在：/tmp/clawsec-scanner.lock
• 等待正在运行的扫描完成，或手动删除锁文件
• 这可防止扫描重叠而产生不一致的结果

验证

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

# 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
python ../../utils/validate_skill.py .

# Scan test fixtures (should detect known vulnerabilities)
./scripts/runner.sh --target test/fixtures/ --format text

开发

运行测试

# All tests (vanilla Node.js, no framework)
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 static hook inspection

代码检查

# JavaScript/TypeScript
npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0

# Python (Bandit already configured in pyproject.toml)
ruff check .
bandit -r . -ll

# Shell scripts
shellcheck scripts/*.sh

添加自定义 Semgrep 规则

在 .semgrep/rules/ 中创建自定义规则：

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

更新 scripts/sast_analyzer.mjs 以包含自定义规则：

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

与 ClawSec Suite 集成

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

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

安装完整的 ClawSec Suite：

npx clawhub@latest install clawsec-suite
# Then use clawsec-suite to discover and install clawsec-scanner

安全注意事项

扫描器安全

• 扫描器代码中不硬编码机密
• API 密钥仅从环境变量读取（绝不记录或提交）
• 子进程参数使用数组，以防止 Shell 注入
• 所有外部工具输出均通过 try/catch 错误处理进行解析

漏洞优先级

严重/高危漏洞发现应立即处理：

• 依赖项中存在已知漏洞利用（CVSS 9.0+）
• 代码中硬编码 API 密钥或凭据
• 命令注入漏洞
• 未经验证的路径遍历

中危/低危漏洞发现可在正常的迭代周期内处理：

• 没有已知漏洞利用的过时依赖项
• 缺少安全标头
• 使用弱加密

信息类发现仅供参考：

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

路线图

v0.0.4（当前版本）

• 依赖项扫描（npm audit、pip-audit）
• CVE 数据库集成（OSV、NVD、GitHub Advisory）
• SAST 分析（Semgrep、Bandit）
• 静态检查 OpenClaw 钩子以执行 DAST，不运行目标代码
• 统一 JSON 报告
• OpenClaw 钩子集成

未来增强

• 自动修复（升级依赖项、修复代码）
• 支持 SARIF 输出格式，以集成 GitHub Code Scanning
• 用于跟踪漏洞变化的 Web 控制面板
• CI/CD GitHub Action，在发现高危问题时阻止 PR
• 容器镜像扫描（Docker、OCI）
• 基础设施即代码扫描（Terraform、CloudFormation）
• 全面的 Agent 工作流 DAST（需要更深入的平台集成）

贡献

发现安全问题？请私下发送报告至 [email protected]。

如需提出功能请求或报告 Bug，请在以下地址创建 issue： https://github.com/prompt-security/clawsec/issues

许可证

AGPL-3.0-or-later

完整文本请参阅仓库根目录中的 LICENSE 文件。

资源

• 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 Registry：https://semgrep.dev/explore
• Bandit 文档：https://bandit.readthedocs.io/