convez.ai
AgenteDevOps & InfraestruturaAvançado
okamyuji

Agente de Resposta a Incidentes AWS com Claude

okamyuji/incident-response-agent

Automação de triagem de incidentes AWS com Claude via Bedrock e Step Functions

Ver no GitHub
InicialPluginScore · de 0 a 100

Implementação de referência de um agente nativo AWS que detecta e investiga automaticamente falhas de aplicação usando Amazon Bedrock (Claude), Step Functions e ECS Fargate. Sistema completo com enmascaramento duplo de dados sensíveis, roteamento inteligente de modelos (Haiku/Sonnet/Opus) e integração com GuardDuty e AWS Config para governança.

Instalação

$npx convez-ai okamyuji/incident-response-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Detecção e triagem automática de falhas em aplicações AWS
  • Investigação assistida de incidentes com mascaramento de PII/PHI
  • Orquestração inteligente de resposta a incidentes com escalação progressiva
  • Conformidade e governança com GuardDuty e AWS Config

Veredito

Solução robusta e production-ready para automação de resposta a incidentes em ambientes AWS. A arquitetura em camadas (CloudWatch Logs + Bedrock Guardrails), roteamento por severidade e suporte a conformidade (GuardDuty/Config) a tornam ideal para equipes de operações em transição para observabilidade automatizada. Requer expertise sólida em AWS, Terraform e integração com Claude API.

README

A tradução para o português deste README ainda está na fila.

インシデント対応サポートエージェント on AWS

本システムの概要

本システムは、AWS環境で発生するアプリケーション障害を自動的に検知し、Amazon Bedrock経由でClaudeに調査とトリアージを行わせる、障害対応支援のためのリファレンス実装です。PagerDutyやZabbixを別途構築・運用しなくても、AWSネイティブサービスとClaudeの組み合わせだけで一次オンコール業務を回せる構成を示します。

システムは二段構えのマスキング機構(CloudWatch Logsのデータ保護機能とBedrock Guardrails)を備え、個人情報や金融情報が推論経路に流れ込む前に除去します。Step Functionsがモデル選択を明示的にルーティングし、Haikuでトリアージ、Sonnetで深堀り、Opusで最重大インシデントの根本原因分析を行います。Haikuへの入力はログprefilterでトークン消費を約7割削減し、severity_hint=P1 のsignalで判断のブレを抑えます。生成された調査結果は日本語でDynamoDBにインシデントレコードとして記録され、[IRA][P1] / [IRA][P2] / [IRA][P3] の件名プレフィックス付きでSNS経由でオンコール担当者にメール通知されます。

企業向けガバナンス層としてGuardDutyとAWS Configを最小構成で組み込んでいます。GuardDutyはアカウント全体の脅威検知、AWS Configは構成ドリフト検知を担当し、少人数検証から社内展開に広げる過程でのリスク管理に使えます。

本リポジトリにはTerraformによるIaC一式と、障害検知の動作検証用に適時障害を発生させるNode.jsサンプルアプリケーションが含まれています。ECR / ECS Fargate上で稼働し、HTTP 5xx、応答遅延、OOM、外部API呼び出し失敗、エラーログ急増の5種類の通常障害に加えて、Opusまでエスカレーションさせるための POST /chaos/p1 エンドポイントも公開しています。

動作検証が完了した段階で scripts/destroy.sh を実行すると、作成したリソース群はすべて削除されます。検証はus-east-1リージョンで行い、個人予算30 USD以内に収まるようAWS Budgetsによるキャップを設定しています。

二段マスキング

ログ層では CloudWatch Logs のデータ保護ポリシーを使います。ロググループ単位またはアカウント単位で managed data identifiers を指定すると、PII / PHI / 金融情報などのプリセットに従ってingest時点で自動的にマスクがかかります。Logs Insightsやメトリックフィルタ、サブスクリプションフィルタといったすべてのegress経路でマスクが有効になるため、Claudeに渡す前段で機密情報を除去できます。ユースケース例は Handling sensitive log data using Amazon CloudWatch に詳説があります。追加コストはスキャンの従量課金のみで発生します。Macie と CloudWatch Logs を組み合わせる公式パターンも存在しますが、運用開始時点では別契約を要するスキャン系サービスは不要です。

推論層では Bedrock Guardrails の Sensitive Information Filters を使います。入力プロンプトと応答の両方に対してマスクおよび拒否を適用できます。managed identifiersで取りこぼす業務固有の識別子については、正規表現ベースのcustom word / regexを Guardrails 側に追加します。AWS内で閉じた構成を保ったまま、推論経路の出入口で機密情報の流出を防ぐ設計です。

この二段構えにより、CloudWatch Logsのデータ保護機能でログを予防的に汚さない状態に保ちつつ、Guardrailsで推論経路も縛ります。管理対象のデータ領域を増やさずにマスキングを完結させられます。

Agent Governance Toolkit

Agent Governance Toolkit はMITライセンスのモノレポ構成で、Python / .NET / TypeScript SDKを備えたstatelessなポリシーエンジンです。LangChainやCrewAI、Google ADK、Microsoft Agent Frameworkのnative hookに差し込むことができ、p99レイテンシ0.1ms未満を謳っています。本システムではECS Fargate上にサイドカーとして配置し、Bedrock Agent呼び出しの出口プロキシとして使います。OWASP Agentic Top 10の全項目をカバーし、v3.1ではagt CLIとGovernance Dashboard、shadow AI discoveryまで同梱されています。

ただしpublic preview段階のため破壊的変更が入りやすく、運用投入時にはバージョン固定とリグレッションテストの枠を必ず用意します。Bedrockは CloudTrail が API 呼び出しを自動記録して CloudWatch に流す仕組みを持っています。Toolkit側で落としたeventをCloudWatch Logsに流し込み、CloudTrailと突き合わせることで、誰が何を呼び出してポリシーで何が止まったかをIAMユーザ単位で再現できます。

ガバナンス層(GuardDuty / AWS Config)

社内向けに展開する場合、一次トリアージの自動化だけでは不十分です。少人数の検証から全社展開へ広げる途中で、構成の手動変更と脅威検知の2方向からリスクが顕在化します。本システムでは次の2サービスを最小構成で組み込んでいます。

  • GuardDuty: detectorを有効化し、既存のVPC Flow LogsとCloudTrail管理イベントをsourceとして取り込みます。finding_publishing_frequency を FIFTEEN_MINUTES に設定し、severity 7.0以上のfindingsをEventBridge経由で既存のインシデント用SNSに流し込みます。
  • AWS Config: configuration_recorder と delivery_channel を有効化し、managed rulesを4個登録します。IAM_PASSWORD_POLICY、INCOMING_SSH_DISABLED、S3_BUCKET_PUBLIC_READ_PROHIBITED、EC2_SECURITY_GROUP_ATTACHED_TO_ENI の4本で、Terraformで宣言した「あるべき状態」からのドリフトを検知します。

両方とも enable_guardduty / enable_config の変数で有効/無効を切り替えられるため、既にアカウントで別プロジェクトが有効化している場合は false に設定します。

aws_config_delivery_channel に sns_topic_arn を付けるとmanaged rule初回評価でNON_COMPLIANTリソース数だけメールが飛ぶため、本実装では付けていません。コンプライアンス状態はAWSコンソールのダッシュボードで確認します。

コスト制御

PagerDutyやZabbixのような監視スタックを別途立ち上げなくても、CloudWatch Alarms、EventBridge、Step Functions、Bedrock(Haiku → Sonnet → Opusのエスカレーション)、DynamoDB(インシデントおよびバグのDB)というAWSネイティブ構成でオンコール業務を回せます。

Bedrock Agentは1クエリで内部5コールを踏むケースが発生しやすく、エージェント課金が積み上がります。Budgetsでサービス別キャップを設定し、Bedrock の料金体系を踏まえてCloudTrailのinvocation数からper-incidentコストを可視化します。Haikuでトリアージ、Sonnetで深堀り、OpusはP1のみに限定する運用ルールを、IAMポリシーとモデルID制限によって強制することで暴発を防ぎます。Opus呼び出しはPrompt Cachingを効かせる前提にしておくと、同一障害の再掘り下げで70〜90パーセントのコスト削減が見込めます。

さらにHaikuに渡すログは事前圧縮(prefilter)でsignalフィールドのみを抽出し、stackは先頭3行、msgは240文字で切り詰めています。同じログ件数でもトークン消費を約7割削減できます。

詳細な課金試算は docs/cost-estimate.md に記載しています。

段階移行の設計

段階1ではCloudWatchデータ保護ポリシーを有効化し、既存ログのマスク状況を可視化します。これだけで監査対応の地盤が整います。段階2ではBedrockと Guardrails を組み合わせ、手動Q&Aエージェントを構築し、HaikuによるトリアージとSonnetによる深堀りの二段階を動かします。段階3ではCloudTrailとAgentCoreで行動監査を取る土台が整った時点で、Agent Governance Toolkitを出口に挟み、OWASP Agenticのリスクをカバーします。段階4では重大インシデント系のみOpusとPrompt Cacheに昇格させます。段階5としてGuardDutyとAWS Configを有効化し、脅威検知と構成ドリフト検知を加えます。

本リファレンス実装は、段階1から5までを一括でTerraform化しています。検証段階ではOpus呼び出しを最小化する運用ルールをIAMで強制し、Budgetsで30 USDの上限を設定しています。

構成図

AWS上の最終構成図は docs/architecture.drawio に保存しています。draw.io またはVS CodeのDraw.io Integration拡張で開けます。オンラインで閲覧する場合は、draw.ioの「File → Open From → Device」からローカルの architecture.drawio を読み込んでください。

ディレクトリ構成

incident-response-agent/
├── README.md                  本ファイル
├── .githooks/
│   └── pre-commit             全 workspace を format/lint/test/build で検証する厳密版フック
├── docs/
│   ├── architecture.md        アーキテクチャ詳細
│   ├── architecture.drawio    構成図
│   ├── cost-estimate.md       課金試算(us-east-1 および東京リージョン参考値)
│   └── runbook.md             デプロイと破棄の手順
├── terraform/                 IaC
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── providers.tf
│   ├── modules/               ネットワーク / chaos-app / agt-sidecar / 観測 / パイプライン / 保存 / 通知 / 予算 / guardduty / config_governance
│   └── envs/dev/
├── apps/
│   ├── chaos-app/             Node.js 障害サンプルアプリ(P1 誘発エンドポイント含む)
│   └── agt-sidecar/           Agent Governance Toolkit 出口プロキシ
├── lambda/                    Bedrock 呼び出し Lambda (Haiku / Sonnet / Opus、日本語prompt + prefilter)
│   └── src/shared/prefilter.ts  Haiku 入力のトークン圧縮
└── scripts/
    ├── install-hooks.sh       pre-commit フック有効化(クローン直後に1回実行)
    ├── deploy.sh              一括デプロイ
    ├── verify.sh              動作検証
    ├── trigger-chaos.sh       手動障害発生
    └── destroy.sh             一括削除(Lambda zip 自動再生成付き)

クイックスタート

前提としてAWS CLI、Terraform 1.14+、Docker、Node.js 22+がインストールされていて、us-east-1のBedrockでClaude Haiku / Sonnet / Opusのモデルアクセスが許可されている必要があります。

# 初回のみ: pre-commit フック有効化
./scripts/install-hooks.sh

# 一括デプロイ(Lambdaビルド、ECRへのpush、全Terraform apply)
./scripts/deploy.sh

# 動作検証
./scripts/verify.sh

# 手動で障害を発生させて通知を確認
./scripts/trigger-chaos.sh oom

# Opusまでエスカレーションする P1 誘発
ALB=$(cd terraform/envs/dev && terraform output -raw alb_dns_name)
curl -X POST "http://$ALB/chaos/p1"

# 動作確認後は全リソースを削除
./scripts/destroy.sh

初回の scripts/deploy.sh 実行後、terraform.tfvars に指定したメールアドレスへSNS購読確認メールが届きます。本文のリンクを踏んで購読を確定させないと後続のインシデント通知が受信できません。

詳細な手順は docs/runbook.md を参照してください。

開発環境セットアップ

リポジトリをクローンした直後に下記スクリプトを 1 回だけ実行して pre-commit フックを有効化します。

./scripts/install-hooks.sh

このフックはcommit時に全workspace(apps/chaos-app / apps/agt-sidecar / lambda)で format:check、lint、test、build を完全実行します。遅さより完全性を優先する厳密版のため、ローカルでも実行に数十秒〜 1 分程度かかります。

既知の制約と留意点

  • Agent Governance Toolkitはpublic preview段階であり、破壊的変更のリスクがあります。本実装ではバージョンをピン止めし、アップデート時はリグレッションテストを通す運用を前提としています。
  • 本システムはus-east-1に配置されるため、データレジデンシ要件がある環境では構成の見直しが必要です。東京リージョン配置時の課金試算は docs/cost-estimate.md を参照してください。
  • Bedrock呼び出しはパブリックAPI経由のため、完全な閉域構成にはなりません。閉域化するにはBedrockのPrivateLinkエンドポイントに切り替えてください。
  • AWS Budgetsはソフトリミットです。上限超過時に自動停止は行われないため、通知を受け取り次第 scripts/destroy.sh を実行します。
  • AWS Configは region あたり1つしかrecorderを持てません。既に別プロジェクトで有効化済みの場合は enable_config = false に設定してください。GuardDutyも同様に enable_guardduty で制御できます。
  • terraform destroy は aws_lambda_function.source_code_hash = filebase64sha256(...) を評価するため、lambda/dist/*.zip がローカルに無いと止まります。scripts/destroy.sh は冒頭でzip存在を確認し、無ければ自動再生成します。
Ver o original no GitHub

Bom para

Relacionados