コンテンツにスキップ

Claude Code 完全ガイド

Serena MCP セキュリティ実践ガイド — ツール権限管理と段階的開放戦略

この記事は朝の記事のフォローアップです

基本的なSerena MCPのセットアップ手順については、Serena MCP実装ガイドをご覧ください。

ゴール

  • Serenaのread_onlyモードから段階的にツールを開放する具体手順を習得
  • プロジェクト種別（OSS/Enterprise/PoC）ごとの推奨セキュリティ設定を理解
  • 実行ログの監査方法と異常検知パターンを実装

なぜセキュリティ管理が重要か

Serena MCPは強力なツールセットを提供しますが、特にexecute_shell_commandのような機能は任意のシェルコマンドを実行できるため、適切な権限管理なしでは以下のリスクがあります:

  • 意図しないファイル削除・上書き
  • 機密情報の漏洩（環境変数、認証トークン）
  • システム設定の破壊的変更

実務投入では「動けばいい」ではなく、「安全に動く」状態を最初から設計する必要があります。

アーキテクチャ: 3層セキュリティモデル

┌─────────────────────────────────────┐
│  Layer 1: プロジェクトレベル設定    │
│  (.serena/project.yml)              │
│  - read_only フラグ                 │
│  - 許可ツールリスト                 │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│  Layer 2: ユーザーレベル設定        │
│  (~/.serena/serena_config.yml)      │
│  - 使用統計記録                     │
│  - グローバル除外設定               │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│  Layer 3: ログ監査                  │
│  (mcp.log, dashboard)               │
│  - 実行コマンド記録                 │
│  - エラー追跡                       │
└─────────────────────────────────────┘

実装ステップ

ステップ1: 初期設定（完全読取り専用）

プロジェクトに初めてSerenaを導入する際は、必ずread_only: trueから開始します。

# <project>/.serena/project.yml
read_only: true
project_name: my_secure_project

この状態では、Serenaは以下の操作のみ実行可能です:

  • ファイル内容の読取り
  • コード構造の解析
  • セマンティック検索
  • プロジェクトインデックスの作成

書込み系の操作は一切実行されません。

ステップ2: ダッシュボードで実行内容を確認

まず1日間、read_only: trueで運用し、ダッシュボード (http://localhost:24282/dashboard/index.html) でSerenaが何を試みているかを観察します。

確認ポイント:

  • どのファイルにアクセスしているか
  • どのツールが呼び出されているか
  • エラーが発生していないか

ステップ3: 段階的ツール開放

実際の作業で必要なツールを1つずつ有効化します。全て一度に開放するのは危険です。

# <project>/.serena/project.yml
read_only: false  # 書込みモード有効化
project_name: my_secure_project

# 有効化するツールを明示的に指定
included_optional_tools:
  - edit_file          # ファイル編集（最初に必要になる）
  - create_directory   # ディレクトリ作成（次に必要）
  # execute_shell_command は最後まで保留

プロジェクト種別ごとの推奨設定

OSS開発プロジェクト（公開リポジトリ）

# .serena/project.yml
read_only: false
project_name: oss_project
included_optional_tools:
  - edit_file
  - create_directory
  - delete_file
  # execute_shell_command: 許可しない（CIで実行）
設定項目推奨値理由
read_onlyfalse開発効率重視
execute_shell_command無効CI/CDに委譲、ローカルで実行不要
ログ記録有効問題追跡用

Enterprise開発（機密情報含む）

# .serena/project.yml
read_only: true  # デフォルト読取り専用
project_name: enterprise_app

# ホワイトリスト方式: 必要最小限のみ許可
included_optional_tools:
  - edit_file  # レビュー後のみ有効化
設定項目推奨値理由
read_onlytrue（デフォルト）機密保護最優先
execute_shell_command絶対に無効監査ログでも不十分なリスク
環境変数アクセス制限.envファイルを.gitignore+Serena除外

PoC/実験プロジェクト

# .serena/project.yml
read_only: false
project_name: poc_experiment
included_optional_tools:
  - edit_file
  - create_directory
  - delete_file
  - execute_shell_command  # PoC完了後は削除
設定項目推奨値理由
read_onlyfalse実験速度重視
execute_shell_command一時的に許可PoC完了後に無効化
バックアップ必須git commit毎に確認

実行ログ監査の実践

ログファイルの場所

クライアント別のログ保存場所:

クライアントログパス
Claude Desktop~/Library/Application Support/Claude/mcp.log (macOS)
Claude Desktop%APPDATA%\Claude\mcp.log (Windows)
Claude Codeプロジェクトディレクトリ内の.claude/mcp-*.log

監査すべき項目

定期的に以下をチェックします:

# 実行されたコマンドを抽出
grep "execute_shell_command" mcp.log

# エラーのみ抽出
grep "ERROR" mcp.log

# ファイル変更の履歴
grep "edit_file\|delete_file" mcp.log | head -20

異常検知パターン

以下の兆候が見られた場合は即座にread_only: trueに戻します:

症状考えられる原因対処
予期しないファイル削除delete_fileの誤実行ツール無効化、git復元
大量のシェルコマンド実行無限ループ、設定ミスexecute_shell_command無効化
環境変数アクセスログ認証情報読取り試行.envを除外設定に追加

失敗パターンと回避策

失敗1: 初回からread_only: falseで開始

症状原因回避策
意図しないファイル上書きSerenaの動作理解不足必ずread_only: trueで1日運用

失敗2: execute_shell_commandを安易に有効化

症状原因回避策
rm -rf等の危険コマンド実行ツール権限過剰CI/CDで実行、ローカルは無効化

失敗3: ログ監査を怠る

症状原因回避策
問題発生時に原因特定不能ログ未確認週次でmcp.logをレビュー

失敗4: 全プロジェクトで同一設定

症状原因回避策
機密PJで過剰権限プロジェクト種別無視上記の推奨設定表を適用

自動化・拡張案

実践的なセキュリティ運用を自動化する方法:

  1. ログローテーション: 週次でログをアーカイブし、異常パターンを自動検知
  2. pre-commit hook: .serena/project.yml変更時に危険設定を警告
  3. ダッシュボード拡張: Prometheusでメトリクス収集、Grafanaで可視化
  4. 定期監査レポート: 月次でツール使用統計をチーム共有
  5. 権限申請フロー: Enterprise環境でツール有効化にレビュープロセスを導入

次のステップ

セキュリティ基盤が整ったら、以下の高度な活用に進めます:

まとめ

Serena MCPのセキュリティ実践では以下が重要です:

  • 必ずread_only: trueから開始し、ダッシュボードで1日観察
  • プロジェクト種別に応じた設定を適用（OSS/Enterprise/PoCで異なる）
  • execute_shell_commandは最後の手段、基本はCI/CDに委譲
  • 週次でログ監査を実施し、異常パターンを早期検知
  • ツールは1つずつ有効化、全開放は絶対に避ける

安全な運用基盤があってこそ、Serenaの強力な機能を最大限活用できます。

関連記事

参考リンク