clawsec-scanner

ClawSec Scanner

エージェントプラットフォーム向けの包括的なセキュリティスキャナーです。複数の側面にわたる脆弱性検出を自動化します。

• 依存関係スキャン：npm audit と pip-audit を使用し、構造化 JSON 出力を解析して npm および Python の依存関係を分析します
• CVE データベースとの統合：OSV（優先）、NVD 2.0、GitHub Advisory Database に問い合わせ、脆弱性情報を拡充します
• SAST 分析：Semgrep（JavaScript/TypeScript）と Bandit（Python）を使用した静的コード分析により、ハードコードされたシークレット、コマンドインジェクション、パストラバーサル、安全でないデシリアライゼーションを検出します
• DAST フレームワーク：OpenClaw フックのメタデータとハンドラーのソースを対象に、エージェント固有の静的分析を実行します。対象コードのインポートや呼び出しは行いません
• 統合レポート：重大度の分類と修正ガイダンスを含む、統合された脆弱性レポートを作成します
• 継続的な監視：OpenClaw フックと統合し、定期的なスキャンを自動化します

Vercel Skills のインストール

このハーネスには Vercel Skills CLI を使用してインストールします。

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

機能

マルチエンジンスキャン

このスキャナーは、包括的に脆弱性を検出するため、相互に補完する 4 種類のスキャンを実行します。

1. 依存関係スキャン

   • サブプロセスとして npm audit --json と pip-audit -f json を実行します
   • 構造化出力を解析し、CVE ID、重大度、影響を受けるバージョンを抽出します
   • package-lock.json がない場合、脆弱性が 0 件の場合、JSON の形式が不正な場合などの例外ケースに対応します

2. CVE データベースへの問い合わせ

   • OSV API（優先）：無料で認証不要。幅広いエコシステム（npm、PyPI、Go、Maven）に対応します
   • NVD 2.0（任意）：6 秒のレート制限を回避するには API キーが必要です
   • 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 フックハンドラーを静的に検査します
   • 対象ハンドラーのインポート、トランスパイル、呼び出しを行わずに、カバレッジとソースレベルのリスク要因を確認します
   • 注：従来の Web DAST ツール（ZAP、Burp）はエージェントプラットフォームには適用できません。この機能ではエージェント固有のテストを実行します

統合レポート

すべてのスキャンで、一貫した 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 との統合

フックを介して継続的な監視を自動化します。

• 設定可能な間隔（デフォルト：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 フックの設定（継続的な監視）

自動の定期スキャンを有効にします。

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 を実行してスキャンをすぐに開始します。

環境変数

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

トラブルシューティング

よくある問題

「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 を使用します

「DAST static coverage finding」

• DAST ハーネスは、対象のフックハンドラーを実行しません。
• JavaScript と TypeScript のフックファイルはソースとして読み込まれ、info レベルの静的カバレッジ検出結果として報告されます。
• フックに対してサンドボックスでの詳細なテストが必要かどうかを判断する際は、一覧に表示された静的な兆候を手動で確認してください。

「Concurrent scan detected」

• ロックファイルが存在します：/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 キーは環境変数からのみ読み込まれます（ログへの記録やコミットは行われません）
• サブプロセスの引数には配列を使用し、シェルインジェクションを防ぎます
• すべての外部ツールの出力は、try/catch によるエラー処理で解析されます

脆弱性の優先順位付け

重大度がクリティカルまたは高の検出結果には、直ちに対処してください。

• 依存関係における既知のエクスプロイト（CVSS 9.0 以上）
• コード内にハードコードされた API キーや認証情報
• コマンドインジェクションの脆弱性
• 検証を行わないパストラバーサル

重大度が中または低の検出結果は、通常のスプリントサイクルで対処できます。

• 既知のエクスプロイトがない古い依存関係
• セキュリティヘッダーの不足
• 弱い暗号化方式の使用

情報レベルの検出結果は、助言のみを目的としています。

• 非推奨の API の使用
• リンターで指摘されたコード品質の問題

ロードマップ

v0.0.4（現在）

• 依存関係のスキャン（npm audit、pip-audit）
• CVE データベースとの統合（OSV、NVD、GitHub Advisory）
• SAST 解析（Semgrep、Bandit）
• 対象コードを実行せずに DAST を行うための、OpenClaw フックの静的検査
• 統合 JSON レポート
• OpenClaw フックとの統合

今後の機能強化

• 自動修正（依存関係のアップグレード、コードの修正）
• GitHub Code Scanning との統合に対応した SARIF 出力形式
• 脆弱性を経時的に追跡する Web ダッシュボード
• 重大度の高い検出結果で PR をブロックする CI/CD GitHub Action
• コンテナーイメージのスキャン（Docker、OCI）
• Infrastructure-as-Code のスキャン（Terraform、CloudFormation）
• エージェントのワークフローを包括的に対象とする DAST（より深いプラットフォーム統合が必要）

コントリビューション

セキュリティ上の問題を発見しましたか？[email protected] まで非公開で報告してください。

機能のリクエストやバグ報告は、次の URL で 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 レジストリ：https://semgrep.dev/explore
• Bandit ドキュメント：https://bandit.readthedocs.io/