日々の使い方
Awnexa は AWS を直接ではなく、最後のスキャン結果をもとに答えます。役立つ状態を保つには、システムが変わったら再スキャンし、スキャン同士の比較を Claude Code に任せるのが基本です。
変更があったら再スキャンする
Section titled “変更があったら再スキャンする”設計レビューや調査の前、デプロイの後、または定期的に awnexa scan を実行します。スキャンごとに新しいスナップショットとして保存され、古いものも残ります。最新のスキャンが 7 日以上前になると出力にそのことが入る(staleWarning)ので、Claude Code は回答のデータがどれだけ古いかを伝えます。
awnexa scanawnexa snapshot list --format tableClaude Code(または awnexa status)が、より新しいスキャンが失敗・実行中である旨の warning を示したときは、表示しているデータはそのスキャンより古いものです。頼る前に再スキャンしてください。
定期スキャン
Section titled “定期スキャン”cron や CI のジョブなど、コマンドを実行できるスケジューラーなら何でも使えます。読み取りしかできない認証情報(AWS アクセスを参照)を使い、次の実行からも同じデータディレクトリが見える場所で実行します。
# crontab: 毎週月曜 7:000 7 * * 1 cd /path/to/infra && awnexa scan --log-level error一部のサービスを読めなかったとき awnexa scan は終了コード 4 を返すので、CI で検知できます。
GitHub Actions で毎週スキャンする
Section titled “GitHub Actions で毎週スキャンする”このワークフローは毎週月曜にスキャンし、前回のスキャンから変わったものを Issue にします。データディレクトリは、ワークフローのアーティファクトとして次の実行に引き継ぎます(キャッシュは 7 日間使われないと消えるため、毎週のジョブでは失われることがあります)。.github/workflows/awnexa-weekly.yml として保存します。
name: Awnexa weekly scanon: schedule: - cron: '0 22 * * 0' # 毎週月曜 7:00(日本時間) workflow_dispatch:permissions: contents: read id-token: write # OIDC で AWS にサインインする actions: read # 前回の実行のデータディレクトリを取得する issues: write # 変更を Issue にするconcurrency: awnexa-weeklyjobs: scan: runs-on: ubuntu-latest env: AWNEXA_HOME: ${{ github.workspace }}/awnexa-data GH_TOKEN: ${{ github.token }} steps: - uses: actions/setup-node@v4 with: node-version: 22 - run: npm install -g awnexa@0.2.0 - name: Restore the data directory of the last successful run run: | run_id=$(gh run list -R "$GITHUB_REPOSITORY" --workflow awnexa-weekly.yml --status success \ --limit 1 --json databaseId --jq '.[0].databaseId // empty') if [ -n "$run_id" ]; then gh run download "$run_id" -R "$GITHUB_REPOSITORY" -n awnexa-data -D "$AWNEXA_HOME" fi - uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ vars.AWNEXA_ROLE_ARN }} aws-region: ap-northeast-1 - name: Scan run: | awnexa scan --region ap-northeast-1,us-east-1 --log-level error || { code=$? [ "$code" -eq 4 ] || exit "$code" echo "::warning::Some services could not be read (exit code 4)" } - name: Keep the 3 newest scans run: awnexa snapshot prune --keep 3 --yes - uses: actions/upload-artifact@v4 with: name: awnexa-data path: ${{ env.AWNEXA_HOME }} retention-days: 30 - name: Open an issue when something changed run: | if ! awnexa snapshot diff --no-persist > diff.json 2> error.json; then jq -e '.error.code == "NO_SCAN"' error.json > /dev/null || { cat error.json; exit 1; } echo "First scan: nothing to compare with yet" exit 0 fi changes=$(jq '.summary.created + .summary.modified + .summary.deleted + .summary.unknown' diff.json) if [ "$changes" -gt 0 ]; then awnexa snapshot diff --no-persist --as markdown > diff.md head -c 60000 diff.md > body.md # Issue の本文は 65,536 文字まで gh issue create -R "$GITHUB_REPOSITORY" --title "AWS changes $(date -u +%F)" --body-file body.md fi最初に実行する前に:
- GitHub Actions が OpenID Connect で引き受けられ、AWS 管理ポリシー
ReadOnlyAccessだけを付けた IAM ロールを作り、その ARN をリポジトリの変数AWNEXA_ROLE_ARNに保存します。手順は Configuring OpenID Connect in Amazon Web Services を参照してください。 --regionとaws-regionのリージョンを設定し、確かめた Awnexa のバージョンに固定します。- 非公開のリポジトリを使ってください。アーティファクトにはスキャン結果が、Issue にはリソースの名前と変わった設定が入るため、リポジトリを読める人は誰でも読めます。秘密の値は保存する前に伏せますが、名前・ID・タグは伏せません。
最初の実行には比べる相手がないため、データディレクトリを保存するだけです。Issue は、リソースが作成・変更・削除されたとき、または比べられなかった(unknown)ときだけ作られます。とても長い差分は Issue に収まるように切り詰めます。無料版は最新 3 世代のスキャンを比べるため、ワークフローは 3 世代を残します。30 日間成功した実行がないとアーティファクトが期限切れになり、次の実行は最初のスキャンからやり直します。
何が変わったかを見る
Section titled “何が変わったかを見る”同じアカウントの 2 つのスキャンを比較します。スキャン ID を省くと、最新のスキャンとその前のスキャンを比べます。それ以外のスキャンは awnexa snapshot list で ID を確認します。
awnexa snapshot diff --as markdownawnexa snapshot diff <古いスキャンID> <新しいスキャンID> --as markdownリソースごとに created・modified(変わったプロパティ付き)・deleted を示します。どちらかのスキャンでサービスを完全に読めなかったときは、見つからないリソースを deleted ではなく unknown とします。Claude Code に「前回のスキャンから何が変わった?」と聞くこともできます。
無料版で比較できるのは、アカウントごとに最新 3 世代のスナップショットです。それより古いものもデータベースに残り、読み取れます。
設計書を書く
Section titled “設計書を書く”awnexa report は、スキャン結果から Mermaid の図を含む Markdown の設計書(概要・ネットワーク・セキュリティ・インベントリ・Coverage)を書き出します。コードと一緒にコミットしたり、チームで共有したりできます。
awnexa report --out docs/aws設計書の Coverage の注意書き(⚠)は確認できなかった範囲を示します。編集するときも残してください。
自分のツールでデータを使う
Section titled “自分のツールでデータを使う”awnexa export はスキャン全体を JSON か NDJSON で書き出します。ほかのコマンドも JSON を出力するので、スクリプトや CI で処理できます。
awnexa export --out scan.jsonawnexa export --as ndjson --split --out export/複数の AWS アカウント
Section titled “複数の AWS アカウント”無料版は、データディレクトリごとに 1 つの AWS アカウントを保存します。アカウントごとにディレクトリを分け、--data-dir か環境変数 AWNEXA_HOME で選びます。
awnexa --data-dir ~/awnexa/prod init --profile prod-readonly --region ap-northeast-1awnexa --data-dir ~/awnexa/prod scan./.awnexa 以外のディレクトリを Claude Code に読ませるときは、MCP サーバーも同じ --data-dir で登録します(Claude Code との連携)。
ディスクの空きを作る
Section titled “ディスクの空きを作る”スナップショットと取得根拠のファイルは自動では削除されません。古いものを削除するときは、まず計画を確認してから実行します。
awnexa snapshot prune --keep 3 --dry-runawnexa snapshot prune --keep 3 --vacuum各アカウントの最新の完了(または一部取得)したスキャンは必ず残ります。削除したスナップショットは元に戻せません。
Awnexa を更新する
Section titled “Awnexa を更新する”npm install -g awnexa@latestawnexa skills install --project ~/work/my-infra --force2 つ目のコマンドは、プロジェクトにインストールした Skill を新しいバージョンに合わせて更新します。忘れても、そのプロジェクトで実行した awnexa status が古い Awnexa のインストールした Skill を示し(skillsOutdated)、awnexa skills list でそれぞれの状態を確認できます。変更点は変更履歴にあります。
うまくいかないとき
Section titled “うまくいかないとき”| 表示 | 対処 |
|---|---|
終了コード 3(AWS_AUTH_FAILED) |
AWS CLI でプロファイルを使えるか確認する: aws sts get-caller-identity --profile <名前> |
awnexa coverage に access_denied |
ReadOnlyAccess を付ける。付いている場合は awnexa plugins の requiredIamActions のその操作を許可して再スキャンする |
awnexa coverage に unsupported |
未対応のサービスかリージョン。「確認していない」として扱う |
awnexa scan が ACCOUNT_LIMIT |
データディレクトリに別のアカウントがある。--profile を確認するか、別のディレクトリを使う |
snapshot diff が SNAPSHOT_OUTSIDE_FREE_LIMIT |
アカウントの最新 3 世代の中で比較する |
エラーは stderr に JSON({"error":{"code":…,"message":…}})で出力します。--log-level info(または debug)を付けると、処理の詳細が表示されます。解決しないときはお問い合わせください。
CLI は匿名の利用統計を送信します(既定はオン。AWS の構成データは送りません)。送る内容の確認と無効化はいつでもできます。
awnexa telemetry statusawnexa telemetry showawnexa telemetry disableすべての項目は CLI が送信するデータにあります。