detect secrets
v1.5.0
detect-secretsコード ベース内の秘密を検出する(サプライズ、サプライズ) ための、適切な名前のモジュールです。
ただし、シークレットの検索のみに焦点を当てた他の同様のパッケージとは異なり、このパッケージは企業クライアントを念頭に置いて設計されており、下位互換性があり、以下の体系的な手段を提供します。
新しいシークレットがコードベースに入るのを防ぎ、
そのような防止が明示的にバイパスされているかどうかを検出し、
ロールアウトし、より安全なストレージに移行するシークレットのチェックリストを提供します。
このようにして、懸念事項の分離を作成します。現在、大規模なリポジトリ (これをベースラインと呼びます) に秘密が隠されている可能性があることを受け入れますが、潜在的に膨大な作業に対処することなく、この問題がこれ以上大きくなるのを防ぎます。既存の秘密を遠ざけること。
これは、ヒューリスティックに作成された正規表現ステートメントに対して定期的な diff 出力を実行し、新しいシークレットがコミットされたかどうかを識別することによって行われます。こうすることで、すべての git 履歴を調査するオーバーヘッドが回避され、毎回リポジトリ全体をスキャンする必要もなくなります。
最近の変更については、CHANGELOG.md を参照してください。
貢献したい場合は、CONTRIBUTING.md をご覧ください。
さらに詳細なドキュメントについては、他のドキュメントを参照してください。
現在 git リポジトリ内で見つかっている潜在的なシークレットのベースラインを作成します。
$ detect-secrets scan > .secrets.baseline
または、別のディレクトリから実行するには:
$ detect-secrets -C /ディレクトリスキャンへのパス > /ディレクトリへのパス/.secrets.baseline
git 以外の追跡ファイルのスキャン:
$ detect-secrets scan test_data/ --all-files > .secrets.baseline
これにより、コードベースが再スキャンされ、次のことが行われます。
最新バージョンと互換性があるようにベースラインを更新/アップグレードします。
見つかった新しいシークレットをベースラインに追加します。
コードベースに存在しないシークレットを削除します。
これにより、ラベル付きシークレットも保持されます。
$ detect-secrets scan --baseline .secrets.baseline
バージョン 0.9 より古いベースラインの場合は、再作成するだけです。
ステージングされたファイルのみをスキャンする:
$ git diff --staged --name-only -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline
すべての追跡ファイルをスキャンしています:
$ git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline
$ detect-secrets scan --list-all-plugins 人工物検出器 AWSキーディテクタ AzureStorageKeyDetector BasicAuthDetector クラウダントディテクタ DiscordBotTokenDetector GitHubトークン検出器 GitLabTokenDetector Base64HighEntropyString HexHighEntropyString IBMCloudIamDetector IBMCosHmacDetector IPパブリックディテクタ JwtTokenDetector キーワード検出器 メールチンプディテクタ Npm検出器 OpenAI検出器 秘密鍵検出器 PypiTokenDetector SendGridDetector スラックディテクター ソフトレイヤー検出器 SquareOAuthDetector ストライプディテクタ TelegramBotTokenDetector TwilioKeyDetector
$ detect-secrets scan --disable-plugin KeywordDetector --disable-plugin AWSKeyDetector
特定のプラグインのみを実行したい場合は、次のようにします。
$ detect-secrets scan --list-all-plugins |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs detect-secrets scan test_dataこれは、ベースラインの結果にラベルを付けるためのオプションの手順です。これを使用して、移行するシークレットのチェックリストを絞り込んだり、プラグインをより適切に構成して S/N 比を向上させることができます。
$ detect-secrets Audit .secrets.baseline
基本的な使用法:
from detect_secrets import SecretsCollectionfrom detect_secrets.settings importdefault_settingssecrets = SecretsCollection()withdefault_settings():secrets.scan_file('test_data/config.ini')import jsonprint(json.dumps(secrets.json(), indent=2))より高度な構成:
from detect_secrets import SecretsCollectionfrom detect_secrets.settings import transient_settingssecrets = SecretsCollection()with transient_settings({# これらのプラグインのみでスキャンを実行します。# この形式は、生成されたベースラインに保存されるものと同じです。'plugins_used': [# Example組み込みプラグインの構成{'name': 'Base64HighEntropyString','limit': 5.0、
},# カスタム プラグインの使用例{'name': 'HippoDetector','path': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
}、
],# 必要な追加フィルターを指定することもできます。# これは、# ローカル ファイル `./private-filters/example.py` 内で関数 `is_identified_by_ML_model` を使用する例です。'filters_used': [
{'パス': 'file://private-filters/example.py::is_identified_by_ML_model',
}、
】
}) 設定として:# 作成した設定オブジェクトにさらに調整を加えたい場合 (例: デフォルトのフィルターを無効にする)、 such.settings.disable_filters('detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign','detect_secrets) のように行うことができます。 .filters.heuristic.is_likely_id_string',
)secrets.scan_file('test_data/config.ini')$ pip install 検出シークレット ?
brew 経由でインストールします。
$ brew install 検出シークレット
detect-secrets 3 つの異なるツールが付属しており、どれを使用すればよいか混乱することがよくあります。この便利なチェックリストを使用して、次のことを決定してください。
ベースラインにシークレットを追加しますか?その場合は、 detect-secrets scanを使用します。
ベースラインにない新しいシークレットを警告しますか?その場合は、 detect-secrets-hook使用します。
ベースライン自体を分析していますか?その場合は、 detect-secrets auditを使用します。
$ detect-secrets scan --help usage: detect-secrets scan [-h] [--string [STRING]] [--only-allowlisted] [--all-files] [--baseline FILENAME] [--force-use-all-plugins] [--slim] [--list-all-plugins] [-p PLUGIN] [--base64-limit [BASE64_LIMIT]] [--hex-limit [HEX_LIMIT]] [--disable-plugin DISABLE_PLUGIN] [-n | --only-verified] [--exclude-lines EXCLUDE_LINES] [--exclude-files EXCLUDE_FILES] [--exclude-secrets EXCLUDE_SECRETS] [--word-list WORD_LIST_FILE] [-f FILTER] [--disable-filter DISABLE_FILTER] [path [path ...]] Scans a repository for secrets in code. The generated output is compatible with `detect-secrets-hook --baseline`. positional arguments: path Scans the entire codebase and outputs a snapshot of currently identified secrets. optional arguments: -h, --help show this help message and exit --string [STRING] Scans an individual string, and displays configured plugins' verdict. --only-allowlisted Only scans the lines that are flagged with `allowlist secret`. This helps verify that individual exceptions are indeed non-secrets. scan options: --all-files Scan all files recursively (as compared to only scanning git tracked files). --baseline FILENAME If provided, will update existing baseline by importing settings from it. --force-use-all-plugins If a baseline is provided, detect-secrets will default to loading the plugins specified by that baseline. However, this may also mean it doesn't perform the scan with the latest plugins. If this flag is provided, it will always use the latest plugins --slim Slim baselines are created with the intention of minimizing differences between commits. However, they are not compatible with the `audit` functionality, and slim baselines will need to be remade to be audited. plugin options: Configure settings for each secret scanning ruleset. By default, all plugins are enabled unless explicitly disabled. --list-all-plugins Lists all plugins that will be used for the scan. -p PLUGIN, --plugin PLUGIN Specify path to custom secret detector plugin. --base64-limit [BASE64_LIMIT] Sets the entropy limit for high entropy strings. Value must be between 0.0 and 8.0, defaults to 4.5. --hex-limit [HEX_LIMIT] Sets the entropy limit for high entropy strings. Value must be between 0.0 and 8.0, defaults to 3.0. --disable-plugin DISABLE_PLUGIN Plugin class names to disable. e.g. Base64HighEntropyString filter options: Configure settings for filtering out secrets after they are flagged by the engine. -n, --no-verify Disables additional verification of secrets via network call. --only-verified Only flags secrets that can be verified. --exclude-lines EXCLUDE_LINES If lines match this regex, it will be ignored. --exclude-files EXCLUDE_FILES If filenames match this regex, it will be ignored. --exclude-secrets EXCLUDE_SECRETS If secrets match this regex, it will be ignored. --word-list WORD_LIST_FILE Text file with a list of words, if a secret contains a word in the list we ignore it. -f FILTER, --filter FILTER Specify path to custom filter. May be a python module path (e.g. detect_secrets.filters.common.is_invalid_file) or a local file path (e.g. file://path/to/file.py::function_name). --disable-filter DISABLE_FILTER Specify filter to disable. e.g. detect_secrets.filters.common.is_invalid_file
$ detect-secrets-hook --help usage: detect-secrets-hook [-h] [-v] [--version] [--baseline FILENAME] [--list-all-plugins] [-p PLUGIN] [--base64-limit [BASE64_LIMIT]] [--hex-limit [HEX_LIMIT]] [--disable-plugin DISABLE_PLUGIN] [-n | --only-verified] [--exclude-lines EXCLUDE_LINES] [--exclude-files EXCLUDE_FILES] [--exclude-secrets EXCLUDE_SECRETS] [--word-list WORD_LIST_FILE] [-f FILTER] [--disable-filter DISABLE_FILTER] [filenames [filenames ...]] positional arguments: filenames Filenames to check. optional arguments: -h, --help show this help message and exit -v, --verbose Verbose mode. --version Display version information. --json Print detect-secrets-hook output as JSON --baseline FILENAME Explicitly ignore secrets through a baseline generated by `detect-secrets scan` plugin options: Configure settings for each secret scanning ruleset. By default, all plugins are enabled unless explicitly disabled. --list-all-plugins Lists all plugins that will be used for the scan. -p PLUGIN, --plugin PLUGIN Specify path to custom secret detector plugin. --base64-limit [BASE64_LIMIT] Sets the entropy limit for high entropy strings. Value must be between 0.0 and 8.0, defaults to 4.5. --hex-limit [HEX_LIMIT] Sets the entropy limit for high entropy strings. Value must be between 0.0 and 8.0, defaults to 3.0. --disable-plugin DISABLE_PLUGIN Plugin class names to disable. e.g. Base64HighEntropyString filter options: Configure settings for filtering out secrets after they are flagged by the engine. -n, --no-verify Disables additional verification of secrets via network call. --only-verified Only flags secrets that can be verified. --exclude-lines EXCLUDE_LINES If lines match this regex, it will be ignored. --exclude-files EXCLUDE_FILES If filenames match this regex, it will be ignored. --exclude-secrets EXCLUDE_SECRETS If secrets match this regex, it will be ignored. -f FILTER, --filter FILTER Specify path to custom filter. May be a python module path (e.g. detect_secrets.filters.common.is_invalid_file) or a local file path (e.g. file://path/to/file.py::function_name). --disable-filter DISABLE_FILTER Specify filter to disable. e.g. detect_secrets.filters.common.is_invalid_file
これをコミット前フックとして設定することをお勧めします。これを行う 1 つの方法は、プリコミット フレームワークを使用することです。
# .pre-commit-config.yamlrepos:
- リポジトリ: https://github.com/Yelp/detect-secretsrev: v1.5.0hooks:
- id: detect-secretsargs: ['--baseline', '.secrets.baseline']exclude: package.lock.jsonベースラインを作成せずに、誤検知をコミットのブロックから除外したい場合があります。これを行うには、次のようにコメントを追加します。
Secret = "hunter2" # プラグマ: ホワイトリスト シークレット
または
// プラグマ:allowlist nextline Secretconst Secret = "hunter2";
$ detect-secrets Audit --help
使用法: 検出秘密監査 [-h] [--diff] [--stats]
[--レポート] [--only-real | --false のみ]
[--json]
ファイル名 [ファイル名 ...]
ベースラインを監査することで、アナリストは結果にラベルを付け、環境に応じて最高の信号対雑音比が得られるようにプラグインを最適化できます。
位置引数:
filename 指定されたベースライン ファイルを監査して違いを区別します
偽陽性と真陽性の間。
オプションの引数:
-h、--help このヘルプ メッセージを表示して終了します
--diff 2 つのベースライン ファイルを比較できるようにします。
さまざまなプラグインの違いを効果的に区別します
構成。
--stats インタラクティブな監査セッションの結果を表示します。
ベースライン ファイルに保存されています。
--report 検出されたシークレットを含むレポートを表示します
報告：
すべての結果と下された決定を含む概要を表示します。レポート モード (--report) とともに使用します。
--only-real レポートには実際のシークレットのみが含まれます
--only-false レポートには誤検知のみが含まれます
分析:
ラベル付けされた結果に基づいてプラグインの成功を定量化します。
ベースライン。統計モード (--stats) で使用します。
--json 結果を機械可読形式で出力します。このツールは、プラグインとフィルターのシステムを通じて動作します。
プラグインはコード内の秘密を見つけます
フィルタは誤検知を無視してスキャン精度を向上させます
精度/再現率のニーズに合わせて両方を調整できます。
コード内の秘密を見つけるために採用する 3 つの異なる戦略があります。
正規表現ベースのルール
これらは最も一般的なタイプのプラグインであり、適切に構造化されたシークレットとうまく連携します。これらの秘密はオプションで検証できるため、スキャンの精度が向上します。ただし、これらだけに依存すると、スキャンのリコールに悪影響を及ぼす可能性があります。
エントロピー検出器
これは、さまざまなヒューリスティックなアプローチを通じて「秘密に見える」文字列を検索します。これは非構造化秘密には最適ですが、スキャン精度を調整するための調整が必要になる場合があります。
キーワード検出器
これはシークレット値を無視し、ハードコーディングされた値を使用したシークレットの割り当てに関連する変数名を検索します。これは、「秘密に見えない」文字列 (le3tc0de パスワードなど) には最適ですが、スキャン精度を調整するためにフィルターを調整する必要がある場合があります。
私たちが現在解明していない秘密を見つけたいですか?独自のプラグインを (簡単に) 開発して、エンジンで使用することもできます。詳細については、プラグインのドキュメントを参照してください。
detect-secretsニーズに合ったいくつかの異なる組み込みフィルターが付属しています。
場合によっては、特定の行が特定のパターンに一致する場合、スキャン内の特定の行をグローバルに許可できるようにしたいことがあります。次のように正規表現ルールを指定できます。
$ detect-secrets scan --exclude-lines 'password = (blah|fake)'
または、次のように複数の正規表現ルールを指定することもできます。
$ detect-secrets scan --exclude-lines 'password = blah' --exclude-lines 'password = fake'
場合によっては、スキャンで特定のファイルを無視できるようにしたいことがあります。これを行うには正規表現パターンを指定できます。ファイル名がこの正規表現パターンに一致する場合、ファイルはスキャンされません。
$ detect-secrets scan --exclude-files '.*.signature$'
または、次のように複数の正規表現パターンを指定することもできます。
$ detect-secrets scan --exclude-files '.*.signature$' --exclude-files '.*/i18n/.*'
場合によっては、スキャンで特定のシークレット値を無視できるようにしたいことがあります。次のように正規表現ルールを指定できます。
$ detect-secrets scan --exclude-secrets '(fakesecret|${.*})'または、次のように複数の正規表現ルールを指定することもできます。
$ detect-secrets scan --exclude-secrets 'fakesecret' --exclude-secrets '${.*})'場合によっては、グローバルに除外するのではなく、特定の行に除外を適用したいことがあります。インライン許可リストを使用してこれを行うことができます。
API_KEY = 'これは通常プラグインによって検出される' # pragma: ホワイトリスト シークレット
これらのコメントは複数の言語でサポートされています。例えば
const GoogleCredentialPassword = "ここに何か秘密"; // プラグマ: ホワイトリスト シークレット
次のものも使用できます。
# プラグマ: ホワイトリスト nextline SecretAPI_KEY = 'WillAlsoBeIgnored'
これは、ベースライン全体を再度生成する必要がなく、シークレットを無視するのに便利な方法です。これらのホワイトリストに登録されたシークレットを明示的に検索する必要がある場合は、次のこともできます。
$ detect-secrets scan --only-allowlisted
誤検知を除外するためにさらにカスタム ロジックを作成したいですか?フィルタのドキュメントでこれを行う方法を確認してください。
--exclude-secretsフラグを使用すると、シークレット値を除外する正規表現ルールを指定できます。ただし、代わりに大きな単語のリストを指定したい場合は、 --word-listフラグを使用できます。
この機能を使用するには、必ずpyahocorasickパッケージをインストールするか、単に次を使用します。
$ pip install detect-secrets[word_list]
その後、次のように使用できます。
$ 猫の単語リスト.txt 本当の秘密ではない $猫サンプル.ini パスワード = not-a-real-secret# 結果が表示されます$ detect-secrets scan sample.ini# 結果が見つかりません$ detect-secrets scan --word-list wordlist.txt
Gibberish Detector は単純な ML モデルであり、実際の秘密の値は単語のようなものではないという前提で、秘密の値が実際に意味不明であるかどうかを判断しようとします。
この機能を使用するには、必ずgibberish-detectorパッケージをインストールするか、以下を使用してください。
$ pip install detect-secrets[意味不明]
モデルをトレーニングする方法の詳細については、gibberish-detector パッケージを確認してください。簡単に使用できるように、事前トレーニングされたモデル (RFC の処理によってシードされる) が含まれます。
次のように独自のモデルを指定することもできます。
$ detect-secrets scan --gibberish-model Custom.model
これは、 passwordなどのシークレットを無視するため、デフォルトのプラグインではありません。
これは、コードベースへのシークレットの侵入を防ぐ確実な解決策を意図したものではありません。それを本当に実現できるのは、適切な開発者教育だけです。このプリコミットフックは、シークレットがコミットされる明らかなケースを防止するために、いくつかのヒューリスティックを実装しているだけです。
防止できないこと:
複数行のシークレット
KeywordDetectorトリガーしないデフォルトのパスワード (例: login = "hunter2" )
「git リポジトリが検出されませんでした。」 git リポジトリ内にいるにもかかわらず、警告が発生しました。
gitバージョンが 1.8.5 以上であるかどうかを確認してください。そうでない場合は、アップグレードしてからもう一度お試しください。詳細はこちら。
detect-secrets audit 「有効なベースライン ファイルではありません!」と表示されるベースラインを作成した後。
ベースライン ファイルのファイル エンコーディングが UTF-8 であることを確認してください。詳細はこちら。
