skill-scan

Skill-Scan — エージェントスキル向けセキュリティ監査ツール

OpenClaw スキルパッケージ向けの多層セキュリティスキャナーです。静的解析と、オプションの LLM による詳細検査を通じて、悪意のあるコード、検知回避技術、プロンプトインジェクション、不整合な動作を検出します。信頼できないスキルをインストールまたは有効化する前に、必ず実行してください。

機能

• 6 つの分析レイヤー — パターンマッチング、AST／検知回避、プロンプトインジェクション、LLM 詳細分析、アラインメント検証、メタ分析
• 60 以上の検出ルール — 実行に関する脅威、認証情報の窃取、データ流出、難読化、動作シグネチャ
• コンテキストを考慮したスコアリング — 正当な API スキルに対する誤検知を減らします
• ClawHub 連携 — スラッグを指定して、レジストリからスキルを直接スキャンできます
• 複数の出力モード — テキストレポート（デフォルト）、--json、--compact、--quiet
• 終了コード — 安全なら 0、リスクありなら 1（スクリプトと簡単に連携できます）

使用するタイミング

インストールまたは有効化する前に、必ず実行してください：

• ClawHub のスキル（自分が作成したものではないすべてのスキル）
• 他のユーザーやチームが共有したスキル
• 公開リポジトリのスキル
• 自分で内容を確認していないスキルパッケージ

インストール済みのスキルについても、定期的な監査を推奨します。

クイックスタート

# Scan a local skill directory
skill-scan scan /path/to/skill

# Scan a skill from ClawHub before installing it
skill-scan scan-hub some-skill-slug

# Batch scan all installed skills
skill-scan batch /path/to/skills-directory

# JSON output for programmatic use
skill-scan scan-hub some-skill-slug --json

# Quiet mode (just score + verdict)
skill-scan scan-hub some-skill-slug --quiet

リスクスコア

リスク	スコア	対応
低	80-100	安全にインストールできます
中	50-79	インストール前に検出結果を確認してください
高	20-49	インストールしないでください — 重大な脅威が検出されました
重大	0-19	インストールしないでください — 複数の重大な脅威が検出されました

終了コード

• 0 — リスクが低い（続行しても安全です）
• 1 — リスクが中以上（インストールをブロックします）

LLM オプション

skill-scan scan-hub slug --llm        # Always run deep analysis (layers 4-5)
skill-scan scan-hub slug --llm-auto   # LLM only if pattern scan finds MEDIUM+
skill-scan scan-hub slug --llm-only   # Skip patterns, LLM analysis only

プロバイダーは環境から自動検出されます：

• OPENAI_API_KEY -> gpt-4o-mini
• ANTHROPIC_API_KEY -> claude-sonnet-4-5

エージェント向け

ユーザーから ClawHub のスキルのインストールを依頼された場合は、次のワークフローに従ってください：

1. まずスキャンする — インストールする前に、skill-scan scan-hub <slug> を実行します
2. 結果を確認する：
   • リスクが低い場合（終了コード 0）：インストールを続行します
   • リスクが中程度の場合：検出結果をユーザーに示し、続行するか確認します
   • リスクが高または重大の場合：インストールをブロックし、レポートを表示します
3. 報告する — スキャンの概要（スコア、リスクレベル、検出件数）を必ずユーザーに示します

アラート形式

スキャンでリスクが中以上と判定された場合：

🛡️ Skill-Scan Alert: {RISK_LEVEL} ({SCORE}/100)
Skill: {slug}
Findings: {count} issue(s) detected
Top threat: {highest severity finding title}
Action: Installation blocked pending review.

AGENTS.md との連携

skill-scan をエージェントのワークフローに組み込むには、次のテンプレートのいずれか 1 つを AGENTS.md（または同等のエージェント指示ファイル）に追加します。

オプション A：自動スキャン（推奨）

ClawHub のスキルは、インストール前にすべて自動でスキャンされます。手動での操作は不要です。

## Skill-Scan — Automatic Pre-Install Security Scanning

BEFORE installing any skill from ClawHub, you MUST scan it with skill-scan first. This is non-negotiable — never skip the scan.

### Workflow

1. When the user asks to install a skill (e.g. `clawhub install <slug>`), run the scan FIRST:
   ```bash
   skill-scan scan-hub <slug>

2. 終了コードと出力を確認する：
   • 終了コード 0（リスクが低い） — clawhub install <slug> を実行して続行します
   • 終了コード 1（リスクが中程度） — 検出結果をユーザーに示し、続行するか確認します
   • 終了コード 1（リスクが高／重大） — インストールをブロックし、レポート全体を表示します
3. ユーザーから明示的な上書き指示がない限り、リスクが高または重大なスキルは決してインストールしないでください
4. インストールを続行する前に、必ずスキャンの概要をユーザーに示してください

定期監査

インストール済みのスキルの監査を依頼された場合は、スキルディレクトリを一括スキャンします：

skill-scan batch {skillsDir}

LLM による詳細分析

重要度の高いインストールの場合や、パターンスキャンでリスクが中程度と判定された場合は、LLM 分析に進みます：

skill-scan scan-hub <slug> --llm-auto

### Option B: Manual On-Demand Scanning

Skills are only scanned when the user explicitly asks. Installation proceeds without automatic checks.

```markdown
## Skill-Scan — On-Demand Skill Security Scanning

skill-scan is available to audit skill packages for security threats. Use it when the user requests a security scan.

### Commands

- **Scan a ClawHub skill**: `skill-scan scan-hub <slug>`
- **Scan a local skill**: `skill-scan scan /path/to/skill`
- **Batch scan installed skills**: `skill-scan batch {skillsDir}`
- **Deep analysis with LLM**: add `--llm` or `--llm-auto` to any scan command

### Risk Levels

- **LOW (80-100)** — safe, no significant threats
- **MEDIUM (50-79)** — review findings, use caution
- **HIGH (20-49)** — serious threats, do not install
- **CRITICAL (0-19)** — multiple critical threats, do not install

### When the User Asks to Scan

1. Run the appropriate scan command
2. Show the scan summary (score, risk level, finding count)
3. If MEDIUM+, list the top findings with severity and description
4. Let the user decide what to do

インストール時の設定

このスキルを初めてインストールするときに、ユーザーに次の質問をします：

skill-scan をワークフローにどのように組み込みますか？

1. 自動（推奨）— すべての clawhub install の前にスキャンします。リスクが高または重大なインストールは自動的にブロックされます。
2. 手動 — 明示的に依頼された場合にのみスキャンします。

ユーザーの選択に基づき、対応するテンプレート（上記のオプション A またはオプション B）をプロジェクトの AGENTS.md に追加します。

検出カテゴリ

実行上の脅威 — eval()、exec()、child_process、動的インポート

認証情報の窃取 — .env へのアクセス、API キー、トークン、秘密鍵、ウォレットファイル

データの持ち出し — fetch()、axios、requests、ソケット、Webhook

ファイルシステムの操作 — 書き込み／削除／名前変更操作

難読化 — Base64、16 進数、Unicode エンコーディング、文字列の構築

プロンプトインジェクション — 脱獄、不可視文字、同形異字、ロールプレイの枠付け、エンコードされた指示

振る舞いのシグネチャ — 複合パターン：データの持ち出し、トロイの木馬型スキル、検出を回避するマルウェア、永続的なバックドア

要件

• Python 3.10+
• httpx>=0.27（LLM API 呼び出しにのみ使用）
• API キーが必要なのは --llm モードのみです（静的解析は単独で実行できます）

関連スキル

• input-guard — 外部入力のスキャン
• memory-scan — エージェントメモリのセキュリティ
• guardrails — セキュリティポリシーの設定