detect secrets
v1.5.0
detect-secrets adalah modul yang diberi nama tepat untuk (kejutan, kejutan) mendeteksi rahasia dalam basis kode.
Namun, tidak seperti paket serupa lainnya yang hanya berfokus pada pencarian rahasia, paket ini dirancang dengan mempertimbangkan klien perusahaan: menyediakan sarana yang kompatibel dan sistematis untuk:
Mencegah rahasia baru memasuki basis kode,
Mendeteksi apakah pencegahan tersebut secara eksplisit dilewati, dan
Memberikan daftar rahasia untuk disebarkan, dan dimigrasikan ke penyimpanan yang lebih aman.
Dengan cara ini, Anda membuat pemisahan kekhawatiran: menerima bahwa saat ini mungkin ada rahasia yang bersembunyi di repositori besar Anda (inilah yang kami sebut sebagai baseline ), namun mencegah masalah ini menjadi lebih besar, tanpa berurusan dengan upaya yang berpotensi besar untuk memindahkan rahasia yang ada.
Hal ini dilakukan dengan menjalankan keluaran diff secara periodik terhadap pernyataan regex yang dibuat secara heuristik, untuk mengidentifikasi apakah ada rahasia baru yang telah dilakukan. Dengan cara ini, hal ini menghindari biaya tambahan untuk menggali seluruh riwayat git, serta kebutuhan untuk memindai seluruh repositori setiap saat.
Untuk melihat perubahan terkini, silakan lihat CHANGELOG.md.
Jika Anda ingin berkontribusi, silakan lihat CONTRIBUTING.md.
Untuk dokumentasi lebih detail, lihat dokumentasi kami yang lain.
Buat garis dasar rahasia potensial yang saat ini ditemukan di repositori git Anda.
$ deteksi-pindaian rahasia > .rahasia.baseline
atau, untuk menjalankannya dari direktori lain:
$ deteksi-rahasia -C /jalur/ke/pemindaian direktori > /jalur/ke/direktori/.rahasia.baseline
Memindai file yang dilacak non-git:
$ deteksi-rahasia pindai test_data/ --all-files > .secrets.baseline
Ini akan memindai ulang basis kode Anda, dan:
Perbarui/tingkatkan baseline Anda agar kompatibel dengan versi terbaru,
Tambahkan rahasia baru apa pun yang ditemukannya ke dasar Anda,
Hapus rahasia apa pun yang tidak lagi ada dalam basis kode Anda
Ini juga akan menjaga rahasia berlabel apa pun yang Anda miliki.
$ deteksi-pemindaian rahasia --baseline .secrets.baseline
Untuk baseline yang lebih lama dari versi 0.9, buat ulang saja.
Hanya Memindai File Bertahap:
$ git diff --dipentaskan --hanya nama -z | xargs -0 deteksi-rahasia-hook --baseline .secrets.baseline
Memindai Semua File yang Dilacak:
$ git ls-file -z | xargs -0 deteksi-rahasia-hook --baseline .secrets.baseline
$ deteksi-rahasia memindai --daftar-semua-plugin ArtifactoryDetector AWSKeyDetector AzureStorageKeyDetector BasicAuthDetector Detektor Cloudant DiscordBotTokenDetector GitHubTokenDetector Detektor GitLabToken Base64HighEntropyString HexHighEntropyString IbmCloudIamDetector IbmCosHmacDetector Detektor Publik IPP JwtTokenDetector Detektor Kata Kunci Detektor Mailchimp Detektor Npm OpenAIDetector Detektor Kunci Pribadi Detektor PypiToken KirimGridDetektor Detektor Slack Detektor Lapisan Lunak SquareOAuthDetector Detektor Garis TelegramBotTokenDetector Detektor TwilioKey
$ deteksi-pindaian rahasia --disable-plugin Kata KunciDetector --disable-plugin AWSKeyDetector
Jika Anda hanya ingin menjalankan plugin tertentu, Anda dapat melakukan:
$ deteksi-rahasia pemindaian --daftar-semua-plugin |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs mendeteksi-rahasia memindai test_dataIni adalah langkah opsional untuk memberi label pada hasil di garis dasar Anda. Ini dapat digunakan untuk mempersempit daftar rahasia yang akan dimigrasi, atau untuk mengonfigurasi plugin Anda dengan lebih baik guna meningkatkan rasio signal-to-noise.
$ deteksi-rahasia audit .rahasia.baseline
Penggunaan Dasar:
dari deteksi_rahasia impor SecretsCollectionfrom deteksi_rahasia.settings impor default_settingssecrets = SecretsCollection()dengan default_settings():secrets.scan_file('test_data/config.ini')impor jsonprint(json.dumps(secrets.json(), indent=2))Konfigurasi Lebih Lanjut:
from detector_secrets import SecretsCollectionfrom detector_secrets.settings import transient_settingssecrets = SecretsCollection()with transient_settings({# Hanya jalankan pemindaian hanya dengan plugin ini.# Format ini sama dengan format yang disimpan dalam baseline yang dihasilkan.'plugins_used': [# Contoh untuk mengonfigurasi plugin bawaan{'name': 'Base64HighEntropyString','limit': 5.0,
},# Contoh penggunaan plugin khusus{'name': 'HippoDetector','path': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
},
],# Kita juga dapat menentukan filter tambahan mana yang kita inginkan.# Ini adalah contoh penggunaan fungsi `is_identified_by_ML_model` dalam# file lokal `./private-filters/example.py`.'filters_used': [
{'jalur': 'file://private-filters/example.py::is_identified_by_ML_model',
},
]
}) sebagai pengaturan:# Jika kita ingin melakukan penyesuaian lebih lanjut pada objek pengaturan yang dibuat (misalnya# menonaktifkan filter default), kita dapat melakukannya seperti itu.settings.disable_filters('detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign','detect_secrets .filters.heuristic.is_likely_id_string',
)rahasia.scan_file('test_data/config.ini')$ pip install deteksi-rahasia ?
Instal melalui minuman:
$ brew install deteksi-rahasia
detect-secrets hadir dengan tiga alat berbeda, dan sering kali terjadi kebingungan mana yang akan digunakan. Gunakan daftar periksa praktis ini untuk membantu Anda memutuskan:
Apakah Anda ingin menambahkan rahasia ke dasar Anda? Jika demikian, gunakan detect-secrets scan .
Apakah Anda ingin memperingatkan rahasia baru yang tidak ada dalam baseline? Jika demikian, gunakan detect-secrets-hook .
Apakah Anda menganalisis baseline itu sendiri? Jika demikian, gunakan 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
Kami merekomendasikan pengaturan ini sebagai hook pra-komitmen. Salah satu cara untuk melakukan ini adalah dengan menggunakan kerangka pra-komitmen:
# .pre-commit-config.yamlrepos:
- repo: https://github.com/Yelp/detect-secretsrev: v1.5.0hooks:
- id: deteksi-secretsargs: ['--baseline', '.secrets.baseline']kecualikan: package.lock.jsonAda kalanya kita ingin mengecualikan positif palsu dari pemblokiran penerapan, tanpa membuat dasar untuk melakukannya. Anda dapat melakukannya dengan menambahkan komentar seperti ini:
secret = "hunter2" # pragma: rahasia daftar yang diizinkan
atau
// pragma: daftar yang diizinkan baris berikutnya secretconst secret = "hunter2";
$ deteksi-rahasia audit --help
penggunaan: audit deteksi rahasia [-h] [--diff] [--stats]
[--laporan] [--hanya-nyata | --hanya-salah]
[--json]
nama file [nama file ...]
Mengaudit garis dasar memungkinkan analis memberi label pada hasil, dan mengoptimalkan plugin untuk rasio signal-to-noise tertinggi untuk lingkungannya.
argumen posisi:
nama file Audit file dasar tertentu untuk membedakan perbedaannya
antara positif palsu dan positif sebenarnya.
argumen opsional:
-h, --help tampilkan pesan bantuan ini dan keluar
--diff Memungkinkan perbandingan dua file dasar, untuk
secara efektif membedakan perbedaan antara berbagai plugin
konfigurasi.
--stats Menampilkan hasil sesi audit interaktif yang
telah disimpan ke file dasar.
--report Menampilkan laporan dengan rahasia yang terdeteksi
pelaporan:
Tampilkan ringkasan dengan semua temuan dan keputusan yang dibuat. Untuk digunakan dengan mode laporan (--report).
--only-real Hanya menyertakan rahasia nyata dalam laporan
--only-false Hanya menyertakan positif palsu dalam laporan
analitik:
Hitung keberhasilan plugin Anda berdasarkan hasil yang diberi label di
garis dasar. Untuk digunakan dengan mode statistik (--stats).
--json Output menghasilkan format yang dapat dibaca mesin.Alat ini beroperasi melalui sistem plugin dan filter .
Plugin menemukan rahasia dalam kode
Filter mengabaikan positif palsu untuk meningkatkan presisi pemindaian
Anda dapat menyesuaikan keduanya agar sesuai dengan kebutuhan presisi/recall Anda.
Ada tiga strategi berbeda yang kami terapkan untuk mencoba dan menemukan rahasia dalam kode:
Aturan berbasis Regex
Ini adalah jenis plugin yang paling umum, dan berfungsi baik dengan rahasia yang terstruktur dengan baik. Rahasia-rahasia ini secara opsional dapat diverifikasi, sehingga meningkatkan presisi pemindaian. Namun, hanya bergantung pada hal ini dapat berdampak negatif pada penarikan kembali pemindaian Anda.
Detektor Entropi
Ini mencari string yang "tampak rahasia" melalui berbagai pendekatan heuristik. Ini bagus untuk rahasia yang tidak terstruktur, namun mungkin memerlukan penyesuaian untuk menyesuaikan presisi pemindaian.
Detektor Kata Kunci
Ini mengabaikan nilai rahasia, dan mencari nama variabel yang sering dikaitkan dengan penetapan rahasia dengan nilai hard-coded. Ini bagus untuk string yang "tidak tampak rahasia" (misalnya kata sandi le3tc0de), tetapi mungkin memerlukan filter penyetelan untuk menyesuaikan presisi pemindaian.
Ingin mencari rahasia yang saat ini belum kami ketahui? Anda juga dapat (dengan mudah) mengembangkan plugin Anda sendiri, dan menggunakannya dengan mesinnya! Untuk informasi lebih lanjut, lihat dokumentasi plugin.
detect-secrets hadir dengan beberapa filter bawaan berbeda yang mungkin sesuai dengan kebutuhan Anda.
Terkadang, Anda ingin mengizinkan garis tertentu secara global dalam pemindaian Anda, jika garis tersebut cocok dengan pola tertentu. Anda dapat menentukan aturan regex seperti ini:
$ deteksi-rahasia scan --exclude-lines 'kata sandi = (bla|palsu)'
Atau Anda dapat menentukan beberapa aturan regex seperti:
$ deteksi-rahasia scan --exclude-lines 'password = bla' --exclude-lines 'password = fake'
Terkadang, Anda ingin mengabaikan file tertentu dalam pemindaian Anda. Anda dapat menentukan pola regex untuk melakukannya, dan jika nama file memenuhi pola regex ini, maka tidak akan dipindai:
$ deteksi-rahasia pemindaian --exclude-files '.*.signature$'
Atau Anda dapat menentukan beberapa pola regex seperti:
$ deteksi-rahasia memindai --exclude-files '.*.signature$' --exclude-files '.*/i18n/.*'
Terkadang, Anda ingin mengabaikan nilai rahasia tertentu dalam pemindaian Anda. Anda dapat menentukan aturan regex seperti ini:
$ deteksi-rahasia scan --exclude-secrets '(fakesecret|${.*})'Atau Anda dapat menentukan beberapa aturan regex seperti:
$ deteksi-rahasia memindai --mengecualikan-rahasia 'rahasia palsu' --mengecualikan-rahasia '${.*})'Terkadang, Anda ingin menerapkan pengecualian pada baris tertentu, daripada mengecualikannya secara global. Anda dapat melakukannya dengan pemberian izin sebaris seperti ini:
API_KEY = 'ini-biasanya-akan-terdeteksi-oleh-a-plugin' # pragma: rahasia daftar yang diizinkan
Komentar ini didukung dalam berbagai bahasa. misalnya
const GoogleCredentialPassword = "sesuatu-rahasia-di sini"; // pragma: rahasia daftar yang diizinkan
Anda juga dapat menggunakan:
# pragma: daftar yang diizinkan baris berikutnya secretAPI_KEY = 'WillAlsoBeIgnored'
Ini mungkin cara mudah bagi Anda untuk mengabaikan rahasia, tanpa perlu membuat ulang seluruh garis dasar lagi. Jika Anda perlu mencari rahasia yang diizinkan ini secara eksplisit, Anda juga dapat melakukan:
$ deteksi-pindaian rahasia --hanya-diizinkan
Ingin menulis lebih banyak logika khusus untuk menyaring positif palsu? Lihat cara melakukan ini di dokumentasi filter kami.
Bendera --exclude-secrets memungkinkan Anda menentukan aturan regex untuk mengecualikan nilai rahasia. Namun, jika Anda ingin menentukan daftar kata yang besar, Anda dapat menggunakan tanda --word-list .
Untuk menggunakan fitur ini, pastikan untuk menginstal paket pyahocorasick , atau cukup gunakan:
$ pip install deteksi-rahasia[word_list]
Kemudian, Anda dapat menggunakannya seperti ini:
$cat daftar kata.txt bukan-benar-benar-rahasia $ sampel kucing.ini kata sandi = bukan-rahasia-nyata# Akan menampilkan hasil$ sampel pemindaian deteksi-rahasia.ini# Hasil tidak ditemukan$ pemindaian deteksi-rahasia --daftar kata wordlist.txt
Gibberish Detector adalah model ML sederhana yang mencoba menentukan apakah suatu nilai rahasia benar-benar omong kosong, dengan asumsi bahwa nilai rahasia sebenarnya tidak seperti kata-kata.
Untuk menggunakan fitur ini, pastikan untuk menginstal paket gibberish-detector , atau gunakan:
$ pip install deteksi-rahasia[omong kosong]
Lihat paket pendeteksi omong kosong untuk informasi lebih lanjut tentang cara melatih model. Model terlatih (diunggulkan dengan memproses RFC) akan disertakan agar mudah digunakan.
Anda juga dapat menentukan model Anda sendiri seperti:
$ deteksi-rahasia memindai --gibberish-model custom.model
Ini bukan plugin default karena ini akan mengabaikan rahasia seperti password .
Hal ini tidak dimaksudkan sebagai solusi jitu untuk mencegah rahasia memasuki basis kode. Hanya pendidikan pengembang yang tepat yang benar-benar dapat melakukan hal tersebut. Kait pra-komitmen ini hanya mengimplementasikan beberapa heuristik untuk mencoba dan mencegah kasus-kasus nyata dalam melakukan rahasia.
Hal-hal yang Tidak Dapat Dicegah:
Rahasia multi-baris
Kata sandi default yang tidak memicu KeywordDetector (misalnya login = "hunter2" )
"Tidak mendeteksi repositori git." peringatan ditemui, meskipun saya berada di repo git.
Periksa untuk melihat apakah versi git Anda >= 1.8.5. Jika belum, harap tingkatkan versinya lalu coba lagi. Lebih detailnya di sini.
detect-secrets audit menampilkan "Bukan file dasar yang valid!" setelah membuat garis dasar.
Pastikan pengkodean file dari file dasar Anda adalah UTF-8. Lebih detailnya di sini.
