Zero Point Secret Scanner

GitHubリポジトリ: Grimwald79/Zero-Point-Secret-Scanner

Gitの履歴に高エントロピーの暗号キーやAPIトークンが混入するのを防ぐために設計された、自動化されたローカルのPre-Commitシークレットスキャナーです。

従来の正規表現（Regex）に大きく依存する壊れやすいシークレットスキャナーとは異なり、このツールは「シャノンエントロピーの数学的アプローチ」と「抽象構文木（AST）解析」の組み合わせを活用してコードをセマンティック（意味論的）に理解し、誤検知（フォールスポジティブ）を劇的に減らします。

アーキテクチャ：なぜASTとエントロピーなのか？

多くのシークレットスキャナーは正規表現を使用して、「secret」や「password」といったキーワードを検索します。しかし、これは自然言語の文字列やドックストリング（docstring）が誤警報を引き起こし、頻繁に「アラート疲労（Alert Fatigue）」を招く原因となります。

このスキャナーは、コード解析に対して厳格に「スキルベース」のアプローチをとります：

セマンティックな理解（AST）: Pythonの標準ライブラリである ast モジュール（ast.walk）を使用します。変数名、関数定義、コメントはインテリジェントに無視され、コード内で割り当てられたリテラル値（ast.Constant）のみを評価します。

数学的ランダム性（シャノンエントロピー）: 文字列が評価される際、そのシャノンエントロピー（）を計算します。AWSのアクセスキーのような暗号キーは、その文字のランダム性により、自然と高いエントロピースコアを示します。

構造的ヒューリスティクス: 長い英語の文章がエントロピーのしきい値を超えないように、スキャナーは空白を含む文字列を明示的に除外（フィルタリング）します。

組み込み済みの脅威モデル緩和策

コマンドインジェクションの防止: Gitへのサブプロセスコールは、悪意のあるコマンド実行を防ぐため、shell=False を指定した厳密なリストベースの引数を利用しています。

DoS（サービス拒否）攻撃の防止: ASTパーサーにメモリを割り当てる前に、ファイルサイズ制限（デフォルトで500 KB）を強制し、システムリソースを保護します。

情報漏洩の防止: 発見されたシークレットは、生成されるMarkdownレポートに書き込まれる前にローカルでマスキング（例：AKI...[MASKED]...PLE）されます。

パストラバーサルの保護: すべてのローカルファイル生成において、厳格なパス解決制限を利用し、意図した場所にのみファイルが書き込まれるようにします。

要件

Python: 3.12以上（最新の型ヒントと構文を利用）

Git: リポジトリで初期化されている必要があります

OS: クロスプラットフォーム（Windows、macOS、Linux）

インストールとセットアップ

ローカルリポジトリの防御を開始するために、複雑なCI/CDパイプラインを設定する必要はありません。付属のインストーラーが、コミットを傍受するGitフックを動的に生成します。

スクリプトをリポジトリのルートにクローンまたはコピーします。secret_scanner.py と install_hook.py が存在することを確認してください。

ターミナルからフックインストーラーを実行します：

python install_hook.py

期待される出力:

[+] Successfully installed pre-commit hook at: .git/hooks/pre-commit

[+] Your repository is now actively defended.

使い方

通常通りにコードを書きます。準備ができたら、標準的なGitワークフローを使用して変更のコミットを試みます：

git add .

git commit -m "feat: added new S3 connection logic"

正常なルート（クリーンなコード）

シークレットが検出されない場合、コミットは静かに、そして通常通り進行し、あなたの作業を一切妨げません。

ブロックされたルート（シークレットの検出）

誤って高エントロピーのAPIトークンをステージングしてしまった場合、スキャナーはコミットのライフサイクルを傍受し、リポジトリを保護するために即座に操作を中止（アボート）します：

[*] Running Zero Point Secret Scanner...

--- Running Automated Verification Suite ---

[PASS] Entropy calculations are mathematically sound.

[PASS] Secret masking prevents local data leaks.

[PASS] AST Scanner accurately isolates high-entropy constants.

--- Verification Complete ---

[*] Starting Pre-Commit Secret Scan...

[!] Found 1 potential secrets. Report written to /path/to/secrets_report.md

[!] COMMIT REJECTED: Secrets detected. Review the markdown report.

[-] Commit aborted by Secret Scanner.

生成された secrets_report.md を開いて、違反の原因となったファイルと行番号を正確に確認してください。コード内のシークレットをマスキングまたは削除し、変更を再度ステージングして、コミットをやり直してください。

自動検証（プロトコル10）

このツールは、コードは「無実と証明されるまで有罪（疑わしきは罰する）」という前提に立っています。スキャナーが実行されるたびに、シャノンエントロピーの計算が正しく調整され、ASTパーサーが定数を正常に分離していることをアサート（検証）する内部テストスイートが最初に実行されます。何らかの理由で計算が失敗した場合、セキュリティチェックの破損からパイプラインを保護するため、スキャナーは安全にコミットを中止します。

ライセンスと教育目的の免責事項

これは、静的アプリケーションセキュリティテスト（SAST）のメカニズムを実証するために設計された教育用ツールです。エンタープライズレベルの分散型スキャンについては、このロジックを集中型の .pre-commit-config.yaml フレームワークに組み込むことを検討してください。