Agentive
AIエージェント活用

AIエージェントの権限設計 — settings.jsonで安全な自動実行を実現

約6分で読めます

AIエージェントの自動実行において、権限設計は安全性と生産性のバランスを決定する最も重要な要素である。Claude Codeのsettings.jsonによるallow/deny設定、.claude/settings.localでの環境別カスタマイズ、Hooksとの連携による動的な権限制御まで、実践的な権限設計を体系的に解説する。

settings.jsonの基本構造

Claude Codeの権限設定は、プロジェクトレベルとユーザーレベルの2階層で管理される。プロジェクトレベルの設定はリポジトリにコミットでき、チーム全体で共有できる。

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)"
    ]
  }
}

パーミッション評価の優先順位

  1. denyリストが最優先で評価される
  2. allowリストに含まれるコマンドは自動承認される
  3. どちらにも含まれないコマンドはユーザー確認が求められる
// パーミッション評価のロジック
interface PermissionRule {
  pattern: string;
  type: "allow" | "deny";
}

function evaluatePermission(
  command: string,
  rules: PermissionRule[]
): "allowed" | "denied" | "ask" {
  // denyルールを先に評価
  for (const rule of rules.filter((r) => r.type === "deny")) {
    if (matchGlob(command, rule.pattern)) {
      return "denied";
    }
  }

  // allowルールを評価
  for (const rule of rules.filter((r) => r.type === "allow")) {
    if (matchGlob(command, rule.pattern)) {
      return "allowed";
    }
  }

  return "ask";
}

ユースケース別の権限テンプレート

開発環境（最小権限）

開発初期段階では、読み取り操作のみを許可し、書き込み操作は個別に承認する。

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(git reset --hard *)",
      "Bash(rm *)",
      "Write"
    ]
  }
}

CI/CD環境（自動実行）

CI環境ではテストとビルドの自動実行を許可しつつ、デプロイ操作は制限する。

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test *)",
      "Bash(npm run build)",
      "Bash(npm run lint)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Edit",
      "Write"
    ],
    "deny": [
      "Bash(npm publish *)",
      "Bash(git push --force *)",
      "Bash(docker push *)"
    ]
  }
}

本番運用（フルオート）

信頼性が確認された環境では、広範な操作を許可しつつ破壊的操作のみを禁止する。

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Write",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(node *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo *)",
      "Bash(curl * | *sh)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)"
    ]
  }
}

Hooksによる動的な権限制御

Claude Code Hooksを使うことで、特定の条件下でのみ権限を変更する動的な制御が可能になる。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "node hooks/check-command.js \"$TOOL_INPUT\""
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "node hooks/validate-output.js \"$TOOL_INPUT\""
      }
    ]
  }
}

フック実装例

// hooks/check-command.js
// Bashコマンドの実行前に安全性をチェック
const input = JSON.parse(process.argv[2]);
const command = input.command || "";

// 危険なパターンの検出
const dangerousPatterns = [
  /rm\s+-rf\s+\//,
  />\s*\/dev\/sd/,
  /mkfs\./,
  /dd\s+if=/,
  /:(){ :|:& };:/,
];

for (const pattern of dangerousPatterns) {
  if (pattern.test(command)) {
    console.error(JSON.stringify({
      error: "Dangerous command detected: " + command,
    }));
    process.exit(1);
  }
}

// 安全なコマンドとして承認
process.exit(0);

サンドボックス環境の構築

完全に安全な実行環境を構築するために、Dockerコンテナ内でエージェントを実行する方法を解説する。

FROM node:20-slim

# 非rootユーザーを作成
RUN groupadd -r agent && useradd -r -g agent agent

# 作業ディレクトリを設定
WORKDIR /workspace

# 必要なツールのみインストール
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    && rm -rf /var/lib/apt/lists/*

# Claude Codeをインストール
RUN npm install -g @anthropic-ai/claude-code

# 権限設定ファイルをコピー
COPY settings.json /workspace/.claude/settings.json

# 非rootユーザーに切り替え
USER agent

CMD ["claude", "--auto-mode"]

権限設計の比較

設計パターン安全性自動化度運用コスト適用場面
最小権限（読取のみ）最高低低初期導入・検証
タスク限定高中中定型業務の自動化
フルオート+deny中高中信頼済み環境
Hooks付きフルオート高高高本番運用
サンドボックス最高最高高CI/CD環境

権限監査のチェックリスト

定期的に以下の項目を確認し、権限設定が適切に維持されているか監査する。

  1. allow/denyの網羅性: 新しく追加したツールやコマンドがルールに含まれているか
  2. 最小権限の原則: 不要に広いパターンマッチが設定されていないか
  3. deny優先の確認: 危険なコマンドがdenyリストに含まれているか
  4. 環境差分の確認: 開発・ステージング・本番で適切に権限が分離されているか

ベストプラクティス

  1. 段階的に権限を開放する: まず読み取りのみ許可し、安定性を確認しながら書き込み権限を追加する
  2. deny-firstで設計する: まず全て拒否し、必要なものだけ許可するアプローチ
  3. Hooksで監視する: 権限内であっても、重要な操作はHooksでログを取る
  4. 定期的な棚卸し: 使用されていない許可ルールを定期的に削除する

関連記事

A

Agentive 編集部

AIエージェントを実際に使い倒す個人開発者。サイト制作の自動化を実践しながら、その知見を発信しています。