AIエージェントコーディングのチェックツール4つ:gitleaksとzizmorから

 ・ 10分

photo by John Lee(https://unsplash.com/@john_artifexfilm?utm_source=templater_proxy&utm_medium=referral) on Unsplash

AIエージェントにコーディングを任せると、コミットも、GitHub Actionsのワークフローも、シェルスクリプトもエージェントが書くようになりますよね。この記事では、そういう環境で私が使っているAIエージェントコーディングのチェックツール4つ(gitleaks、zizmor、actionlint、ShellCheck)について、それぞれ何を検出するのか、どう設定したのか、導入中にあった失敗までまとめました。

私は複数のエージェントが同時にPRを出す環境で作業しています。目標だけ渡してエージェントに任せるようになってから、人がすべての行を読んでプッシュしていた頃とは事情が変わりました。人の目の代わりに、毎回同じ基準で動く検査が必要になったんです。

エージェントコーディングにチェックツールが必要な理由#

4つのツールは検出する対象がそれぞれ違います。重なる部分がほとんどないので、1つで残りを代用することはできません。

ツール 検出するもの 動かしている場所
gitleaks コミットに入ったキーやトークンなどのシークレット プッシュ前のフック、PR、毎日
zizmor GitHub Actionsワークフローのセキュリティ問題 ワークフローリポジトリのPR
actionlint ワークフローの構文と式のエラー ワークフローリポジトリのPR
ShellCheck シェルスクリプトのクォートや変数のミス PRで変更されたスクリプトだけ

4つとも自分のマシンで動くコマンドラインツールです。ログインもAPIキーも要らず、呼び出し回数の制限もありません。これがなぜ大事なのかは、gitleaksの話で出てきます。

インストールはHomebrewでまとめてできます。この記事はgitleaks 8.30.1、zizmor 1.32.0、actionlint 1.7.12、ShellCheck 0.11.0を前提にしています。

brew install gitleaks zizmor actionlint shellcheck

gitleaks:プッシュ前とCIでシークレットスキャン#

gitleaksはgitのコミットを調べて、APIキーやトークンのように見える文字列を探します。私は2か所で動かしています。プッシュ直前のpre-pushフックとCIです。

pre-pushフックでプッシュ前に止める#

グローバルのpre-pushフックが、今回プッシュするコミットだけを検査します。中心になるのはこの1行です。

# origin/mainにないコミットだけを検査し、値は伏せて出力します
gitleaks git --log-opts="origin/main..HEAD" --redact --verbose --exit-code 42 .
  • --redactは見つけた値を伏せます。ターミナルのログにシークレットがもう一度出てはいけないからです。
  • --exit-code 42は「シークレットを見つけた」ときの終了コードを別に決めます。既定値は1ですが、gitleaksが単に異常終了したときも1なので、区別できないんです。

フックはシークレットを見つけたときだけプッシュを止めます。gitleaksがインストールされていない、または異常終了した場合は、警告だけ出して通します。ツールの問題でプッシュ全体が止まるよりは良いと判断しました。

その代わり、限界は知ったうえで使う必要があります。

  • git push --no-verifyを使うとフックは実行されません。
  • リポジトリが独自のcore.hooksPathを使っていると(huskyなど)、グローバルフックはまったく動きません。
  • ツールが落ちて通ったプッシュは、検査されていないプッシュです。

つまりフックはうっかりミスを拾う安全網であって、保証ではありません。そのためCIでもう一度検査します。

ggshieldからgitleaksに変えた理由#

最初はフックがGitGuardianのggshieldを先に呼び、応答がないときだけgitleaksを使っていました。ところがGitGuardianの無料枠は30日で10,000回の呼び出しです。この枠を使い切ったあとは、プッシュのたびにこのメッセージだけが出ていました。

no more API calls available

どのみち毎回gitleaksが代わりに検査していたわけです。そこでフックからggshieldの呼び出しを外し、gitleaksだけを残しました。ローカルで動くgitleaksには、ログインも呼び出し上限もありません。

CIではPRのコミットと全履歴を分けて検査する#

CIでは検査範囲を2つに分けました。

  1. PR:PRに含まれるコミット(base..HEAD)を検査します。コミット単位で見るので、PRの中で追加して削除したシークレットも検出されます。
  2. 1日1回:デフォルトブランチとタグの全履歴を検査します。

フックとは逆に、CIは失敗側に倒します。シークレットが出た、gitleaksのバージョンが違う、ツールが落ちた、結果ファイルがない、どれも失敗です。「検査できなかった」が「問題なし」と読まれてはいけないからです。

誤検知は1行のフィンガープリント(fingerprint)だけで例外にします。パスやルールを丸ごと外すことはしません。

# 形式:<コミット>:<ファイル>:<ルール>:<行>
echo '<commit>:<file>:<rule>:<line>' >> .gitleaksignore

ここで一度つまずきました。squash mergeをすると、行はそのままでコミットSHAが変わります。PRで登録したフィンガープリントはデフォルトブランチのコミットには合わないので、同じ誤検知を2回登録する必要がありました。

本物のシークレットが見つかったとき#

エージェントに決めているルールは3つです。

  • 値をPR、Issue、ログのどこにも貼りません。キーの名前だけを伝えます。
  • ファイルから消しても終わりではありません。履歴に残ったキーはまだ有効です。
  • キーの交換(rotation)と履歴の書き換えは人が行います。エージェントは行いません。

zizmor:GitHub Actionsワークフローのセキュリティチェック#

zizmorは、GitHub Actionsのワークフローファイルを読んでセキュリティ問題を見つける静的解析ツールです。

このブログのリポジトリで実行すると、こういう結果になります。一番多かった指摘は、アクションをタグで参照していることです。

zizmor --offline .github/workflows
error[unpinned-uses]: unpinned action reference
  --> .github/workflows/ci.yml:19:15
   |
19 |         uses: pnpm/action-setup@v6
   |               ^^^^^^^^^^^^^^^^^^^^ action is not pinned to a hash (required by blanket policy)
 
...
 
28 findings (9 suppressed, 1 safe fixes, 2 unsafe fixes): 0 informational, 2 low, 0 medium, 17 high

ワークフロー3つでhighが17件です。unpinned-usesのほかにも、pull_request_targetのような危険なトリガー(dangerous-triggers)や、checkoutが残す認証情報(artipacked)を指摘してくれます。--offlineを付けると、ネットワークもトークンも使わずローカルのファイルだけを見ます。

サードパーティのアクションをコミットSHAで固定する理由#

@v6のようなタグは、あとで別のコミットに付け替えられる可能性があります。私の場合はCIランナーが開発マシンでもあるので、汚染されたアクションが実行されると、そのマシンの認証情報に届いてしまいます。そこで最近、ワークフローリポジトリのチェックにzizmorを入れ、ポリシーをこう決めました。

# .github/zizmor.yml
rules:
  unpinned-uses:
    config:
      policies:
        '*': hash-pin # サードパーティのアクションは40文字のコミットSHAで固定
        actions/*: ref-pin # GitHub所有のアクションはタグを許可(Dependabotが更新)

固定したアクションはこう書きます。後ろのコメントでどのバージョンかを残しておきます。

- uses: subosito/flutter-action@1a449444c387b1966244ae4d4f8c696479add0b2 # v2.23.0

既存の指摘はベースラインにして、新しいファイルから止める#

最初に実行すると指摘が大量に出ます。全部直すまで待っていたら、いつまでも有効にできません。そこでCIではmedium以上だけを失敗にし、すでにあった指摘はファイル単位のignoreに書いておきました。

zizmor --offline --no-progress --min-severity medium --config .github/zizmor.yml .github

ignoreに書いたファイルは、直したときにその行を消します。新しく作ったファイルは例外なく検査されます。

actionlint:ワークフローの構文と式のエラーを見つける#

actionlintは、ワークフローYAMLの構文、式、ランナーラベルのエラーを見つけます。zizmorが「危険かどうか」を見るなら、actionlintは「そもそも動くかどうか」を見ます。

引数なしで実行すると、一番近い.github/workflowsを探してすべて検査します。ShellCheckがインストールされていれば、run:の中のシェルスクリプトも一緒に見てくれます。このブログのリポジトリではこれが出ました。

.github/workflows/next.yml:47:9: shellcheck reported issue in this script: SC2086:info:1:41: Double quote to prevent globbing and word splitting [shellcheck]
   |
47 |         run: echo "store-path=$(pnpm store path)" >> $GITHUB_OUTPUT

$GITHUB_OUTPUTにクォートがないという指摘です。

設定するときに知っておくべきことが2つありました。

  • self-hostedランナーのラベル:自分で付けたラベルはactionlintが知らないので、エラーとして扱われます。.github/actionlint.yamlで教える必要があります。
  • ShellCheckのスタイル指摘:既存のワークフローにSC2086のような指摘が多いと、有効にした瞬間にすべて失敗します。私はCIでactionlint -shellcheck=としてShellCheck連携を切り、ワークフローのエラーだけを止めています。
# .github/actionlint.yaml
self-hosted-runner:
  labels:
    - my-runner

それから、actionlintが通ったからといってワークフローが正しく動くわけではありません。構文が正しくても実行時にしか現れないエラーは、actionlintもShellCheckも検出できません。そういう部分には別にテストを置いています。

ShellCheck:変更されたシェルスクリプトだけを厳しく検査する#

ShellCheckは、クォートの抜けや使っていない変数など、シェルスクリプトのミスを見つけます。エージェントは自動化スクリプトをたくさん書くので、効果が大きいです。

ここではactionlintと逆の方針にしました。全体をゆるく見る代わりに、PRで変更されたファイルだけを見て、警告が1つでもあれば失敗です。例外リストもベースラインもありません。警告があるファイルに触ったら、その警告を直さないと通りません。

# ファイルごとに別々に実行します
shellcheck --norc --format=json -- scripts/deploy.sh

導入しながら学んだことです。

  • ファイルは1つずつ渡します。 複数のスクリプトを一度に渡すと、ほかの入力によってsourceや未使用変数の診断が抜けることがあります。
  • 拡張子のないファイルも見ます。 .sh、.bashだけでなく、シバン(shebang)がシェルのファイルも対象です。
  • zshは明示的に外します。 ShellCheckはzshに対応していないので、パスと理由を書いた除外リストを別に置いています。
  • 対象の一覧はgit ls-filesで作ります。 標準的な検索ツールはignoreルールに当たったファイルを隠すので、追跡中のファイルが一覧から抜けることがあります。

チェックツールの導入で経験した失敗3つ#

検査が「通過」に見えるのに、実際には動いていなかったケースが一番危険でした。

gitignoreのsecret*パターンでスキャナーのファイルが抜けました#

スキャナースクリプトの名前にsecretを入れたところ、グローバルgitignoreのsecret*パターンに当たり、git addから黙って外れました。ワークフローは存在しないファイルを呼ぶことになりました。

今はファイル名をgitleaks_scan.pyのようにツール名で付け、コミット直後にgit ls-filesで新しいファイルが入ったかを確認しています。

PRのheadをcheckoutして「Start directory is not importable」#

セキュリティ用のワークフローがPRのheadコミットをcheckoutするようにしていたところ、スキャナーを追加する前に分岐したブランチには、スキャナーのディレクトリ自体がありませんでした。テストのステップがこのエラーで落ち、ShellCheckとgitleaksのステップは実行されませんでした。

Start directory is not importable

解決策は、checkoutにrefを指定しないことでした。pull_requestイベントは、既定でベースとマージしたmergeコミットを取得します。そうすると、ベースにあるスキャナーとPRの変更が一緒に入ります。

テスト用の偽キーが検出されませんでした#

gitleaksがきちんと検出するかを確認する回帰テストに、公式ドキュメントのサンプルキーを使いました。ところが、そういうサンプルキーはgitleaksの既定ルールで例外になっていて、検出されませんでした。テストは最初から何も確認できていなかったんです。

今はルールが求める文字セットに合わせた合成キーを作り、まず検出されること(テストが失敗すること)を確認してからテストに使っています。

4つのツールに共通して適用した原則#

  1. バージョンを固定します。 ランナーに決めたバージョンがない、または違う場合は、スキップせずに失敗させます。
  2. ローカルは開き、CIは閉じます。 プッシュ前のフックはツールが落ちたら通し、CIはツールが落ちたら失敗させます。
  3. 既存の指摘の扱い方を先に決めます。 変更されたファイルだけを見る(ShellCheck)、重大度の基準とファイル単位のベースライン(zizmor)、正確なフィンガープリント(gitleaks)の中から選びます。
  4. 出力にシークレットを残しません。 値は伏せて、ルール名、ファイル、行、コミットだけを残します。
  5. 外部APIの上限に頼りません。 上限を使い切ると、検査の代わりに警告メッセージだけが残ります。

エージェントに作業を完了条件付きのIssueに分解して任せるのと同じくらい、その成果物を毎回同じ基準でふるいにかける仕組みも必要です。4つを一度に入れるのが大変なら、gitleaksのpre-pushフック1つから始めてみてください。gitleaksをインストールして、グローバルのpre-pushフックから上のコマンドを呼ぶところから試せます。


You can do it if you believe you can!

— Napoleon Hill


他の投稿
AIエージェントのワークフロー:アイデアを完了条件付きのIssueに分解する 커버 이미지
 ・ 7分

AIエージェントのワークフロー:アイデアを完了条件付きのIssueに分解する

AIエージェント自動化の事例4つ、対話ではなく目標を任せる 커버 이미지
 ・ 9分

AIエージェント自動化の事例4つ、対話ではなく目標を任せる

フロントエンド開発環境の基礎6つを2026年基準で整理し直す 커버 이미지
 ・ 13分

フロントエンド開発環境の基礎6つを2026年基準で整理し直す