DevOps Agent IAM 設計ガイド — マルチアカウント構成で最小権限を実現する

「DevOps Agent、とりあえず AdministratorAccess で動いてるんですが…問題ありますか？」

PoC を始めたばかりのころは、まず動かすことが最優先です。IAM の権限設計は「後でちゃんとやる」と後回しになりがち。しかし本番導入を検討し始めると、「最小権限って具体的にどこまで絞ればいい？」「マルチアカウントにするとロールが増えて複雑になる」という壁にぶつかります。

この記事では、AWS マネージドポリシーの中身・マルチアカウント構成で必要な3点セット・Permission Guardrail という安全装置の仕組みを、PoC の実体験をもとに整理します。

この記事で分かること

• DevOpsAgentRole と AIDevOpsAgentAccessPolicy の関係
• マルチアカウント構成でセカンダリアカウントに必要な3点セット
• Permission Guardrail が何を保証してくれるか
• Preview（パブリックプレビュー）から GA へ移行したときのポリシー変更点
• エンタープライズ導入前のチェックリスト

DevOps Agent が必要とする IAM の全体像

DevOps Agent の IAM を理解するうえで、最初に押さえておきたいのは「エージェント自身が使うロール」と「管理者・オペレーターが使うポリシー」は別物だという点です。

エージェント実行ロール（DevOpsAgentRole）の役割

Agent Space を作成すると、AWS は自動的に2つの IAM ロールを作成します。

• DevOpsAgentRole-AgentSpace-<suffix>: DevOps Agent 自身が引き受けるロール（調査・分析に使用）
• DevOpsAgentRole-WebappAdmin-<suffix>: オペレーターアプリ（Operator Web App）用のロール

記事内で「DevOpsAgentRole」と表記する場合は、前者の DevOpsAgentRole-AgentSpace-<suffix> を指しています。

このロールには主に2つのポリシーがアタッチされます。

• AIDevOpsAgentAccessPolicy: 調査に必要なリソースへのアクセス権限（AWS マネージドポリシー）
• インラインポリシー: Resource Explorer のサービスリンクロール作成権限など、環境固有の設定

AIDevOpsAgentAccessPolicy（主に読み取りアクセスが基本）

AIDevOpsAgentAccessPolicy は、DevOps Agent が調査を行うために必要なアクセス権限をまとめた AWS マネージドポリシーです。CloudWatch のメトリクス取得、EC2 の状態確認、CloudTrail のログ参照など、調査に必要な Describe* や Get*・List* 系のアクションが中心です。

ただし「完全な読み取り専用」ではなく、Amazon Bedrock の InvokeModel や Amazon CodeWhisperer の一部アクションなど、エージェントの推論・応答生成に必要な呼び出しアクションも含まれています。いずれもリソースの変更・削除は行いません。（変更が必要なら MCP 経由でカスタムスキルに委ねる設計です）

AIDevOpsAgentFullAccess は管理者用（エージェント自体ではない）

AIDevOpsAgentFullAccess は、Agent Space の作成・設定・管理を行うオペレーター向けのポリシーです。DevOps Agent 自身のロールにアタッチするものではありません。

主に aidevops:* のサービスアクションで構成されており、Agent Space 管理に必要な iam:CreateServiceLinkedRole と iam:PassRole も含まれています。（エージェントロールではなくオペレーターに付与するものです）

この2つを混同して「エージェントに FullAccess を付けておけば間違いない」とやってしまうと、必要以上の権限を持ったエージェントが動き続けることになります。要注意です。

関連記事 DevOps Agent カスタムスキル実践ガイド — SKILL.mdの書き方から運用サイクルまで カスタムスキルが追加権限を必要とするケースはこちらで解説しています。

マルチアカウント構成のIAM設計

プライマリアカウントで動く DevOps Agent が、セカンダリアカウントのリソースを調査するためには、クロスアカウントのロール設定が必要です。

セカンダリに必要な3点セット

セカンダリアカウントに作成する IAM ロールには、以下の3点が必要です。

① Trust Policy（信頼ポリシー）

DevOps Agent サービスがこのロールを引き受けられるよう設定します。Principal には IAM ロール ARN ではなく、サービスプリンシパル aidevops.amazonaws.com を指定します。アクセス元の制限は Condition 句の aws:SourceAccount（プライマリアカウント ID）と sts:ExternalId（Agent Space の ARN）で行います。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<プライマリアカウントID>",
          "sts:ExternalId": "<Agent Space の ARN>"
        }
      }
    }
  ]
}

② AIDevOpsAgentAccessPolicy（マネージドポリシー）

プライマリと同様に、セカンダリアカウントのリソース調査に必要な読み取り権限を付与します。AWS マネージドポリシーをアタッチするだけなので、追加の作業は不要です。

③ Inline Policy（環境固有の追加権限）

Resource Explorer のサービスリンクロール作成権限など、Agent Space の設定に応じた追加権限をインラインポリシーで付与します。CloudFormation テンプレートや CLI のオンボーディングガイドに具体例が記載されています。

プライマリロールへの sts:AssumeRole 付与

プライマリアカウントの DevOpsAgentRole にも、セカンダリのロールを引き受けるためのインラインポリシーが必要です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::<セカンダリアカウントID>:role/<CrossAccountRole名>"
    }
  ]
}

セカンダリアカウントを複数追加する場合は、Resource を配列にして対象 ARN を列挙するか、OU 単位で条件を絞るアプローチが取れます。

PoC実体験（設定手順と詰まりポイント）

弊社の PoC では、プライマリアカウントで Agent Space を作成し、セカンダリアカウントの EC2 や CloudWatch Logs を調査対象に追加しました。設定自体は AWS コンソールの Agent Space 設定画面から「アカウントを追加」で完結します。

ただし、詰まりやすいポイントが2つありました。

詰まりポイント① Trust Policy のプリンシパルはサービスプリンシパルで指定する

Principal に IAM ロール ARN を直接書くのは誤りです（実際にやってしまいました）。正しくは "Service": "aidevops.amazonaws.com" を Principal に指定し、Condition の aws:SourceAccount と sts:ExternalId（Agent Space ARN）でアクセス元を絞ります。ARN は Agent Space 作成後にコンソールまたは CLI で確認できます。

詰まりポイント② Resource Explorer のサービスリンクロールが各アカウントに必要

DevOps Agent はリソース検索に Resource Explorer を使います。セカンダリアカウントでも Resource Explorer が有効化されていないと、調査の精度が下がります。（インラインポリシーで resource-explorer-2:CreateIndex 等を付与しておくと自動作成されます）

Permission Guardrail を理解する

Permission Guardrail は、DevOps Agent を安全に運用するうえで非常に重要な仕組みです。しかし、あまり知られていません。

Guardrail とは何か（セッションポリシーとしての上限）

DevOps Agent はセッションを作成するたびに、AWS が定義した「Permission Guardrail（許可ガードレール）」をセッションポリシーとして自動的に適用します。

仕組みとしては IAM の AssumeRole 時にセッションポリシーを渡すのと同じ。エージェントが引き受けたロールに対し、Guardrail がセッション単位でさらに権限を絞り込むイメージです。

実効権限は「2つの層の重複部分」だけ

3つの層の関係を整理するとこうなります。

層	誰が設定	役割
IAMロールの権限	あなた（運用チーム）	付与したい権限の範囲
Permission Guardrail	AWS	エージェントが使える権限の上限
実効権限	両方の重複部分	エージェントが実際に使える権限

IAM ロールの権限が広くても、Guardrail がカバーしていないアクションは実行できません。逆に Guardrail がカバーしているアクションでも、IAM ロールに権限がなければ実行できません。両方の層に含まれているものだけが、実際に使える権限です。

Guardrail があるからこそ広めに設定しても安全側に倒せる

この仕組みがあることで、IAM ロールの権限設計に一定の余裕が生まれます。たとえば AIDevOpsAgentAccessPolicy に含まれていない新しいサービスへのアクセスをロールに追加しても、Guardrail がカバーしていなければ実際には使われません。

極端な例を言うと、エージェントのロールに AdministratorAccess を付けても、Guardrail の外にある ec2:TerminateInstances などは実行できません。冒頭の「とりあえず AdministratorAccess で動かしてる」という状態は、Guardrail が安全網として機能しているため実害は起きにくい構造です。ただし IAM のベストプラクティスとして、不要な権限は絞るべきなのは変わりません。

なお、Guardrail はエージェントの調査セッション（DevOpsAgentRole の assume）にのみ適用されます。オペレーターがコンソールで使う AIDevOpsAgentFullAccess は Guardrail の対象外です。

関連記事 CloudWatchアラームから3分で自動調査開始 — DevOps Agent × EventBridge構成パターン DevOps Agent の基本構成と CloudWatch 連携はこちらで解説しています。

カスタムスキルが権限を拡張するとき

カスタムスキルの操作もすべて Permission Guardrail を通過します。そのため、ロールに権限を追加しても、Guardrail の curated list に含まれていないアクションは実行できません。

Guardrail がサポートする追加権限（curated list）

AWS の公式ドキュメントが定義する、インラインポリシーで有効化できる追加権限は以下のとおりです。

サービス	アクション	用途
Amazon Athena	GetQuery*、StartQueryExecution、StopQueryExecution	データカタログへのクエリ実行
Amazon S3	s3:GetObject、s3:ListBucket	アプリケーションデータ・ログの読み取り
AWS Direct Connect	DescribeConnections、DescribeDirectConnectGatewayAssociations、DescribeDirectConnectGateways、DescribeLags、DescribeVirtualInterfaces	ネットワーク接続の調査
AWS Glue	glue:GetPartitions	Athena クエリ用パーティションメタデータ
AWS KMS	kms:Decrypt	暗号化された S3 オブジェクトの復号

このリスト以外の権限（s3:PutObject・ec2:TerminateInstances 等の書き込み系）は、ロールに付与しても Guardrail にブロックされます。（SSM セッション開始や Run Command 実行もこのリストに含まれないため使用できません）

スキルが実行するアクションに応じた追加権限の考え方

curated list を踏まえたうえで、カスタムスキルで追加権限が役立つのは主に以下のケースです。

• 調査中に Athena クエリを実行してアクセスログを分析したい（athena:StartQueryExecution をインラインポリシーで追加）
• アプリケーションデータが S3 に格納されており、調査時に参照したい（s3:GetObject を特定バケット ARN に限定して追加）
• 暗号化された設定ファイルを復号して内容を確認したい（kms:Decrypt を特定キー ARN に限定して追加）

追加権限は DevOpsAgentRole のインラインポリシーとして付与します。Resource を特定のリソース ARN に限定することで最小権限の原則を維持できます。

CloudTrail で操作を監査し権限を継続レビュー

DevOps Agent の操作は CloudTrail に記録されます。userIdentity.sessionContext.sessionIssuer フィールドで DevOpsAgentRole のセッションを特定できるため、実際に使われているアクションをフィルタリングして「本当に必要な権限」を把握できます。

権限を追加したあとは、定期的に CloudTrail のログを確認して「使われていない権限を剥奪する」サイクルを回すことを推奨します。

エンタープライズ導入チェックリスト

本番導入前に確認しておきたい項目をまとめました。

① IAM ロール設定確認

• AIDevOpsAgentAccessPolicy が DevOpsAgentRole にアタッチされているか
• プレビュー時代の AIOpsAssistantPolicy が残っていないか（GA 移行済みか）
• エージェントロールに書き込み・削除系の権限が付いていないか

② Permission Guardrail の把握

• Guardrail の仕組みを理解した上で IAM 設計しているか
• IAM ロールの権限 × Guardrail の積集合が意図した範囲か確認できているか

③ マルチアカウント3点セット確認

• セカンダリの Trust Policy の Principal が aidevops.amazonaws.com（サービスプリンシパル）になっているか
• Trust Policy の Condition に aws:SourceAccount と sts:ExternalId（Agent Space ARN）が設定されているか
• セカンダリに AIDevOpsAgentAccessPolicy がアタッチされているか
• プライマリロールに sts:AssumeRole（対象: セカンダリロール ARN）が付いているか

④ Agent Space の境界設計

• 本番環境と開発環境で Agent Space を分けているか
• Agent Space にアクセスできるオペレーターを IAM Identity Center などで絞っているか

⑤ 監査ログの整備

• CloudTrail でエージェントのセッション操作を記録できているか
• カスタムスキルを追加するたびに権限レビューのプロセスがあるか

まとめ — IAM設計は「育てる」もの

DevOps Agent の IAM 設計は、最初から完璧にする必要はありません。AIDevOpsAgentAccessPolicy を基本に、Permission Guardrail というセーフティネットを理解した上で運用を始め、CloudTrail のログを見ながら「実際に使っている権限」に絞り込んでいく。それが現実的なアプローチです。

マルチアカウント構成も、Trust Policy + AIDevOpsAgentAccessPolicy + Inline Policy の3点セットさえ押さえれば、構造はシンプルです。複雑に見えるのはドキュメントが分散しているからで、実際の設定項目は多くありません。

IAM 設計を「一度決めたら終わり」ではなく、スキルが増えるたびに見直す生きた設計として育てていくこと。それが DevOps Agent を長く安全に使い続けるコツだと、PoC を通じて実感しています。

まずは aws iam list-roles --query "Roles[?contains(RoleName, 'DevOpsAgentRole-AgentSpace')]" でエージェントロールを特定し、アタッチ済みポリシーを確認するところから始めてみてください。

参考文献

• DevOps Agent IAM permissions — AWS DevOps Agent ユーザーガイド — エージェントロールと管理者ポリシーの解説
• Connecting multiple AWS Accounts — AWS DevOps Agent ユーザーガイド — マルチアカウント構成の公式手順
• Limiting Agent Access in an AWS Account — AWS DevOps Agent ユーザーガイド — Permission Guardrail の説明
• AIDevOpsAgentFullAccess — AWS Managed Policy Reference — 管理者向けポリシーの詳細
• Migrating from public preview to GA — AWS DevOps Agent ユーザーガイド — AIOpsAssistantPolicy から AIDevOpsAgentAccessPolicy への移行手順