AI 併走するときに Git への出口をセキュリティチェックする setup-securecheck をつくったメモ
AI 併走するときに Git への出口をセキュリティチェックする setup-securecheck をつくったメモです。
現在のスナップショットです
まず現時点でのスナップショットをリリースタグで置いてあります。
きっかけ
AI とともに継続的に開発したり試行錯誤や経緯が残るような仕組みを作ったメモ 2026 年 1 月版
以前こんな仕組みをつくりました。これはうまく回ってます。
で、まず、この時点でガシガシと GitHub にナレッジや経緯を出せる仕組みはできたのですが、この状態だと、唯一の防波堤は docs/actions/01_git_push.md というプッシュ前にAI自身へ最終チェックを指示するファイルだけでした。
ここで最初の発見がありました。
開発してきたのと同じセッションでこのチェックをAIにやらせると、精度が落ちる現象が起きました。自分が触った範囲だけをチェックしがちになり、「自分が書いたものだから大丈夫だろう」という自己チェックの甘さが出てしまうのです。とても人間ぽい。
対策として、開発の文脈を持たないまっさらな別セッションでチェックする運用に変えたところ、これが大きく改善しました。
そして、もう一つの発見。注意喚起そのものの効き目にはムラがあるということでした。
もちろん、もともとノートや申し送りの指示には最初から機密情報への注意喚起が入っていましたが、効くときもあれば何もされないときもありましたね。それでも無駄ではなかったのは、注意喚起とは別次元で「 AI はコミットまでしか許されない、プッシュはしない」という設計上の制約そのものが、AI の動きをローカルで確実にブロックをかけていたからでした。
この時点でプロンプト頼むよりも、構造で縛る方が強い、という気づきがありました。
専用ツールの必要性を感じはじめた
しかし、こんなにがんばっても AI のチェックだけでは拾いきれない観点があります。
既知パターンの網羅的な検出や、ランダムな文字列からの推測、過去のコミット履歴のスキャンといった領域は AI が苦手とするところだったんです。
ここで専用ツールの必要性に感じはじめました。
色々な検討を行って secretlint と gitleaks に狙いを定めました。この 2 つはそれぞれ得意な領域が違い、さらにAIの文脈判断とも穴の位置が異なります。穴の位置が違う層を重ねれば、すべてを貫通する漏洩経路は生まれにくくなる、という考え方です。
このようにチーズの穴という話がありますが、だんだんとこの多層防御の考え方もみえてきます。
こうして最初に手動で secretlint + gitleaks + husky を組んでみたのですが、正直 gitleaks のインストールが OS ごとに不安定だったり、設定が合っているかを確認する仕組みがそもそも無かったりと、まだこの時点では穴だらけでした。ここから、セットアップそのものを独立したパターンとして育てていくことになります。
おおまかな変遷
手運用からトリプルチェックの発見へ(2025-10〜2026-01)
AIによるプッシュ前チェックだけの時代から、別セッション運用への転換、コミットのみ制約という堰き止め設計の発見を経て、secretlint・gitleaksの導入を検討する段階に進みました。手動でセットアップした結果が72点/100点というところからのスタートです。
ウィザード化
2026/2 ごろ。
「AIが提示→人間が実行→結果をAIが読む」という流れに再設計しました。OS/arch自動判定のインストーラーと、10項目のヘルスチェックスクリプトを新規作成。設定ファイルはAIに生成させず、テンプレートをコピーする方式に変更しています。
v2.0.0
2026/4 ごろ。
煩雑になっていた husky + lint-staged をやめ package.json だけで完結する simple-git-hooks に移行しました。実行ログも残すようにして「動いていると思ったら無効だった」事故を防止できるようになってきました。
v2.0.1〜v3.0.0
2026/6 から 2026/7 ごろ。
実運用の中で、「チェックは動いているように見えるが実は握りつぶされていた」「検出ルールが 0 件のまま動いていた」といった、見た目は正常でも実効性がゼロという類のバグが何度か見つかりました。
この苦労を経て、毎回のコミットで合成シークレットを使った自己検証(カナリアテスト)を自動で仕込む仕組みに辿り着きます。これはかなり効きましたね。
さらに v3.0.0 にバージョンアップ。
ここでは、ツール未導入のときにチェックを素通りさせてしまう「フェイルオープン」を廃止し、わからなければブロックする「フェイルクローズ」に方針転換しました。あわせて散らばっていたファイルを .security-check/ 1フォルダに集約し、見通しをよくしました。
最近 v3.1.0
そして、もはや Node.js で動かす仕組みなら Node.js で確実に動くようにすれば AI の読み違いでのインストールミスや OS 間の導入に関しての挙動違いの追従もできそうだなと、導入手順を「確定的に進められる部分」と「人間の判断が必要な部分」に分解し、install.js ・ scan ・ setup-local という形でコマンド化しました。Windows・Linux実機両方でだいぶ導入手順が安定してきました。
いやー、ここでもかなり手順を見直したり概念整理したいしましたね。
現在地
というわけで、ダイジェストでお伝えしました。
現在 2026/9 時点では v3.1.0 です。
secretlint + gitleaks + AIという三層のチェックと、毎コミット自動の自己検証、OS問わず使えるセットアップ手順、という形に落ち着いています。ただし完成というわけではなく、gitleaksを今後もローカルで持ち続けるかCI/CD側に寄せるかといった論点はまだ検討中です。
docs-structure との組み合わせ方もまとまってきていて、今はこの2つをセットで導入する接点パターンも用意しはじめてます。
まとめ
今回のセキュリティチェック、いまのところこんな仕組みが作れています。
- 堰き止め設計
- コミットのみ許可する構造そのものが、注意喚起のムラを補う安全弁になる
- チーズの穴問題の回避
- AI・secretlint・gitleaksはそれぞれ穴の位置が違う、重ねることで漏洩経路を塞ぐ
- ウィザード化
- AIに全自動で設定させず、AI と人間が一緒に対応して確認する流れへ
- simple-git-hooks 化
- 依存を減らし、実行ログで動作を可視化
- 自己検証＝カナリアテスト
- 毎コミット、合成シークレットで検出器自体が生きているかを確認
- フェイルクローズ化
- わからなければブロックする、を既定に
- コマンド化 install.js・scan・setup-local
- 確定的に進む部分と人間の判断が要る部分を分離
といったものです。このように secretlint + gitleaks + AIによるシークレット検出の仕組みとして使えるところまで育ってきました。
ともあれ、まだまだブラッシュアップ中なので、これからも変わっていく部分もあると思います。現時点のスナップショットとして残しておきます！