コンテンツにスキップ

はじめかた

インストールから Claude Code が答えられるようになるまでは、インストール、AWS アクセスの設定、データディレクトリの作成とスキャン、Claude Code との連携の順に進めます。その後のデータの保ち方は日々の使い方を参照してください。

  • Node.js 22.12 以上
  • Windows 11 / macOS / Linux
  • AWS CLI で使える認証情報(プロファイル、IAM Identity Center、aws login、環境変数、インスタンスロールなど)。Awnexa は認証情報を AWS SDK に渡すだけで、保存しません。
  • Claude Code(システムのことをふだんの言葉で質問するため。CLI だけでも使えます)
ターミナルウィンドウ
npm install -g awnexa
awnexa version

パッケージは npm の awnexa です。最新の版とこれまでに公開した版を確認できます。

-g を付けると awnexa コマンドが PATH に入ります。Claude Code も MCP サーバーと Skill で同じコマンドを実行するので、プロジェクトではなくグローバルにインストールしてください。

Awnexa は better-sqlite3 を使います。主な OS と Node.js のバージョンにはビルド済みのバイナリがあります。それ以外の環境では npm がビルドするため、Python と C++ コンパイラが必要です(Windows は「C++ によるデスクトップ開発」)。

awnexa init --sample を実行すると、架空のシステム(使い方の例と同じもの)の 2 回分のスキャンを入れた別のデータディレクトリ(./.awnexa-sample)ができます。AWS は呼ばず、認証情報も使いません。出力には sample: true が付きます。--data-dir で指定して使います。

ターミナルウィンドウ
awnexa init --sample
awnexa --data-dir ./.awnexa-sample status --compact
awnexa --data-dir ./.awnexa-sample impact sg-0a1b2c3d4e5f60718 --depth 2 --compact

Claude Code から使うときは、サンプルを専用の MCP サーバーとして登録し(awnexa init --sample の出力の最後に、フルパスを入れたこのコマンドがあります)、同じディレクトリで Claude Code を起動して、サンプルのシステムについて質問します。

ターミナルウィンドウ
claude mcp add awnexa-sample -- awnexa --data-dir "$PWD/.awnexa-sample" mcp

準備ができたら claude mcp remove awnexa-sample で登録を外し、下の手順で自分のアカウントをスキャンします(サンプルとは別の ./.awnexa に入ります)。

必要なのは読み取りの権限だけです。スキャンに使うロールまたはユーザーに、AWS 管理ポリシー ReadOnlyAccess を付けてください。このポリシー 1 つで足ります。AWS を変更する権限は含まず、Awnexa 自身も awnexa plugins に出る読み取り専用の API しか呼びません。

ReadOnlyAccess は、Awnexa が読まないデータ(S3 のオブジェクト、シークレットの値、ログのイベントなど)の読み取りも許可します。同じ認証情報をほかのツールでも使う場合や、認証情報が漏れたときに読まれる範囲を狭めたい場合は、同じロールに次のインラインポリシーを追加してください。これらのデータの読み取りだけを拒否し、Awnexa の動作には影響しません。

任意: データの読み取りを拒否する
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyDataReads",
"Effect": "Deny",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion",
"s3express:CreateSession",
"secretsmanager:GetSecretValue",
"secretsmanager:BatchGetSecretValue",
"ssm:GetParameter",
"ssm:GetParameters",
"ssm:GetParametersByPath",
"ssm:GetParameterHistory",
"kms:Decrypt",
"dynamodb:GetItem",
"dynamodb:BatchGetItem",
"dynamodb:Query",
"dynamodb:Scan",
"dynamodb:PartiQLSelect",
"dynamodb:GetRecords",
"logs:GetLogEvents",
"logs:FilterLogEvents",
"logs:GetLogRecord",
"logs:StartQuery",
"logs:GetQueryResults",
"logs:StartLiveTail",
"lambda:GetFunction",
"lambda:GetLayerVersion",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"rds:DownloadDBLogFilePortion",
"rds:DownloadCompleteDBLogFile",
"sqs:ReceiveMessage",
"kinesis:GetRecords",
"athena:GetQueryResults",
"cloudfront-keyvaluestore:GetKey",
"cloudfront-keyvaluestore:ListKeys"
],
"Resource": "*"
},
{
"Sid": "DenyApiKeyValues",
"Effect": "Deny",
"Action": "apigateway:GET",
"Resource": "arn:aws:apigateway:*::/apikeys*"
}
]
}

それでも awnexa coverage に access_denied が出る場合(AWS が新しい API の操作を ReadOnlyAccess に加えるのが遅れることがあります)は、awnexa plugins の出力の requiredIamActions にあるその操作を許可してください。

スキャンの前に、AWS CLI でそのプロファイルを使えることを確かめてください(例: aws sts get-caller-identity --profile readonly)。

スキャン結果を置きたいディレクトリ(インフラのリポジトリなど)で実行します。設定ファイル(config.json)とデータベース(awnexa.db)を含む ./.awnexa を作ります。readonly はお使いの AWS CLI のプロファイル名に置き換えてください。

ターミナルウィンドウ
awnexa init --profile readonly --region ap-northeast-1

プロファイル名とリージョンは既定値として保存されるので、以後のコマンドではオプションを省略できます。保存するのはプロファイルの名前だけで、認証情報は保存しません。変えるときは --profile や --region を付けてもう一度 awnexa init を実行します(ほかの設定は残ります)。出力には次に実行するコマンド(next)が入り、リージョンが保存されておらずプロファイルにも既定のリージョンが無いときは warning が付きます。

データディレクトリは --data-dir、環境変数 AWNEXA_HOME、最も近い ./.awnexa(このディレクトリか親ディレクトリ)、~/.awnexa の順に探します。

ターミナルウィンドウ
awnexa scan

ほかのリージョンは --region(繰り返すかカンマ区切り)、アカウントで有効なすべてのリージョンは --all-regions で指定できます。

すべて取得できたときは終了コード 0、権限不足などで一部のサービスを読めなかったときは 4 で終わります。どちらの場合も、読み取れた分は保存されます。

ターミナルウィンドウ
awnexa status
awnexa coverage --status partial,failed,access_denied,unsupported,unknown

status はスキャンと件数を、このステータスを指定した coverage は完全には読めなかったものだけを表示します。不足を埋めるには、足りない権限を追加して再スキャンします。

中身を見てみます。

ターミナルウィンドウ
awnexa overview
awnexa resources list --type AWS::EC2::Subnet --limit 20 --format table
awnexa resources show <resource-id>
awnexa impact <security-group-id> --depth 3

コマンドは既定で JSON を出力します(Claude Code やスクリプト向け)。resources list・coverage・snapshot list などの一覧系のコマンドは --format table も使え、ターミナルで読みやすくなります。すべてのコマンドとオプションは CLI リファレンスにあります。

Awnexa を Claude Code につなぐと、システムのことをふだんの言葉で質問できます。取得網羅性・取得根拠・確度の意味はしくみで説明しています。