はじめかた
インストールから 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 だけでも使えます)
1. インストールする
Section titled “1. インストールする”npm install -g awnexaawnexa versionパッケージは npm の awnexa です。最新の版とこれまでに公開した版を確認できます。
-g を付けると awnexa コマンドが PATH に入ります。Claude Code も MCP サーバーと Skill で同じコマンドを実行するので、プロジェクトではなくグローバルにインストールしてください。
Awnexa は better-sqlite3 を使います。主な OS と Node.js のバージョンにはビルド済みのバイナリがあります。それ以外の環境では npm がビルドするため、Python と C++ コンパイラが必要です(Windows は「C++ によるデスクトップ開発」)。
まず AWS なしで試す
Section titled “まず AWS なしで試す”awnexa init --sample を実行すると、架空のシステム(使い方の例と同じもの)の 2 回分のスキャンを入れた別のデータディレクトリ(./.awnexa-sample)ができます。AWS は呼ばず、認証情報も使いません。出力には sample: true が付きます。--data-dir で指定して使います。
awnexa init --sampleawnexa --data-dir ./.awnexa-sample status --compactawnexa --data-dir ./.awnexa-sample impact sg-0a1b2c3d4e5f60718 --depth 2 --compactClaude 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 に入ります)。
2. AWS アクセスを設定する
Section titled “2. AWS アクセスを設定する”必要なのは読み取りの権限だけです。スキャンに使うロールまたはユーザーに、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)。
3. データディレクトリを作る
Section titled “3. データディレクトリを作る”スキャン結果を置きたいディレクトリ(インフラのリポジトリなど)で実行します。設定ファイル(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 の順に探します。
4. スキャンする
Section titled “4. スキャンする”awnexa scanほかのリージョンは --region(繰り返すかカンマ区切り)、アカウントで有効なすべてのリージョンは --all-regions で指定できます。
すべて取得できたときは終了コード 0、権限不足などで一部のサービスを読めなかったときは 4 で終わります。どちらの場合も、読み取れた分は保存されます。
5. 取得できたものを確認する
Section titled “5. 取得できたものを確認する”awnexa statusawnexa coverage --status partial,failed,access_denied,unsupported,unknownstatus はスキャンと件数を、このステータスを指定した coverage は完全には読めなかったものだけを表示します。不足を埋めるには、足りない権限を追加して再スキャンします。
中身を見てみます。
awnexa overviewawnexa resources list --type AWS::EC2::Subnet --limit 20 --format tableawnexa resources show <resource-id>awnexa impact <security-group-id> --depth 3コマンドは既定で JSON を出力します(Claude Code やスクリプト向け)。resources list・coverage・snapshot list などの一覧系のコマンドは --format table も使え、ターミナルで読みやすくなります。すべてのコマンドとオプションは CLI リファレンスにあります。
次のステップ
Section titled “次のステップ”Awnexa を Claude Code につなぐと、システムのことをふだんの言葉で質問できます。取得網羅性・取得根拠・確度の意味はしくみで説明しています。