コンテンツにスキップ

日々の使い方

Awnexa は AWS を直接ではなく、最後のスキャン結果をもとに答えます。役立つ状態を保つには、システムが変わったら再スキャンし、スキャン同士の比較を Claude Code に任せるのが基本です。

変更があったら再スキャンする

Section titled “変更があったら再スキャンする”

設計レビューや調査の前、デプロイの後、または定期的に awnexa scan を実行します。スキャンごとに新しいスナップショットとして保存され、古いものも残ります。最新のスキャンが 7 日以上前になると出力にそのことが入る(staleWarning)ので、Claude Code は回答のデータがどれだけ古いかを伝えます。

ターミナルウィンドウ
awnexa scan
awnexa snapshot list --format table

Claude Code(または awnexa status)が、より新しいスキャンが失敗・実行中である旨の warning を示したときは、表示しているデータはそのスキャンより古いものです。頼る前に再スキャンしてください。

cron や CI のジョブなど、コマンドを実行できるスケジューラーなら何でも使えます。読み取りしかできない認証情報(AWS アクセスを参照)を使い、次の実行からも同じデータディレクトリが見える場所で実行します。

ターミナルウィンドウ
# crontab: 毎週月曜 7:00
0 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 scan
on:
schedule:
- cron: '0 22 * * 0' # 毎週月曜 7:00(日本時間)
workflow_dispatch:
permissions:
contents: read
id-token: write # OIDC で AWS にサインインする
actions: read # 前回の実行のデータディレクトリを取得する
issues: write # 変更を Issue にする
concurrency: awnexa-weekly
jobs:
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 日間成功した実行がないとアーティファクトが期限切れになり、次の実行は最初のスキャンからやり直します。

同じアカウントの 2 つのスキャンを比較します。スキャン ID を省くと、最新のスキャンとその前のスキャンを比べます。それ以外のスキャンは awnexa snapshot list で ID を確認します。

ターミナルウィンドウ
awnexa snapshot diff --as markdown
awnexa snapshot diff <古いスキャンID> <新しいスキャンID> --as markdown

リソースごとに created・modified(変わったプロパティ付き)・deleted を示します。どちらかのスキャンでサービスを完全に読めなかったときは、見つからないリソースを deleted ではなく unknown とします。Claude Code に「前回のスキャンから何が変わった?」と聞くこともできます。

無料版で比較できるのは、アカウントごとに最新 3 世代のスナップショットです。それより古いものもデータベースに残り、読み取れます。

awnexa report は、スキャン結果から Mermaid の図を含む Markdown の設計書(概要・ネットワーク・セキュリティ・インベントリ・Coverage)を書き出します。コードと一緒にコミットしたり、チームで共有したりできます。

ターミナルウィンドウ
awnexa report --out docs/aws

設計書の Coverage の注意書き(⚠)は確認できなかった範囲を示します。編集するときも残してください。

awnexa export はスキャン全体を JSON か NDJSON で書き出します。ほかのコマンドも JSON を出力するので、スクリプトや CI で処理できます。

ターミナルウィンドウ
awnexa export --out scan.json
awnexa export --as ndjson --split --out export/

無料版は、データディレクトリごとに 1 つの AWS アカウントを保存します。アカウントごとにディレクトリを分け、--data-dir か環境変数 AWNEXA_HOME で選びます。

ターミナルウィンドウ
awnexa --data-dir ~/awnexa/prod init --profile prod-readonly --region ap-northeast-1
awnexa --data-dir ~/awnexa/prod scan

./.awnexa 以外のディレクトリを Claude Code に読ませるときは、MCP サーバーも同じ --data-dir で登録します(Claude Code との連携)。

スナップショットと取得根拠のファイルは自動では削除されません。古いものを削除するときは、まず計画を確認してから実行します。

ターミナルウィンドウ
awnexa snapshot prune --keep 3 --dry-run
awnexa snapshot prune --keep 3 --vacuum

各アカウントの最新の完了(または一部取得)したスキャンは必ず残ります。削除したスナップショットは元に戻せません。

ターミナルウィンドウ
npm install -g awnexa@latest
awnexa skills install --project ~/work/my-infra --force

2 つ目のコマンドは、プロジェクトにインストールした Skill を新しいバージョンに合わせて更新します。忘れても、そのプロジェクトで実行した awnexa status が古い Awnexa のインストールした Skill を示し(skillsOutdated)、awnexa skills list でそれぞれの状態を確認できます。変更点は変更履歴にあります。

表示 対処
終了コード 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 status
awnexa telemetry show
awnexa telemetry disable

すべての項目は CLI が送信するデータにあります。