| --- |
| license: apache-2.0 |
| library_name: onnx |
| pipeline_tag: token-classification |
| tags: |
| - secret-detection |
| - password-detection |
| - credentials |
| - api-keys |
| - security |
| - onnx |
| language: |
| - en |
| - pl |
| - de |
| - es |
| - fr |
| --- |
| |
| # password-detector |
|
|
| **The main idea: keep it small and fast.** A model that runs anywhere on a CPU, with no GPU and no heavy dependencies. |
|
|
| A tiny model that finds passwords, API keys, tokens and private keys in any text: code, configs, logs, emails, |
| chats and documents. Byte-level CNN, no tokenizer, runs on one CPU core with `numpy` + `onnxruntime`. |
| From **97 KB** (tiny) to **0.7 MB** (recommended cascade). |
|
|
| ## Quick start |
|
|
| ```bash |
| pip install huggingface_hub numpy "onnxruntime>=1.17" |
| huggingface-cli download bardsai/password-detector --local-dir password-detector && cd password-detector |
| ``` |
|
|
| ```python |
| from password_detector.detector import SecretDetector |
| |
| det = SecretDetector("onnx/default/model_int8.onnx,onnx/large/model_int8.onnx", |
| prefilter="onnx/tiny/model_int8.onnx") |
| det.scan("Cześć, hasło do VPN to kawa2024!biuro") |
| # [{'value': 'kawa2024!biuro', 'score': 1.0, 'type': 'password', 'start': 23, 'end': 37}] |
| det.scan("password = os.environ['DB_PASSWORD']") |
| # [] |
| ``` |
|
|
| CLI (values masked unless `--show`; exit code 1 when anything is found): |
|
|
| ```bash |
| python -m password_detector --model onnx/tiny/model_int8.onnx path/to/files |
| ``` |
|
|
| Types: `password`, `api_key`, `token`, `private_key`, `generic`. Default threshold 0.5. |
|
|
| ## Results |
|
|
| Offline, one CPU core, int8 models at threshold 0.5. |
|
|
| | Model | Size | CredData F1 | GitHub issues F1 | Docs F1 | Speed | |
| |---|---|---|---|---|---| |
| | **cascade** (tiny → default + large) | 0.7 MB | **0.89** | 0.85 | **0.94** | 138 KB/s | |
| | tiny (`onnx/tiny`) | 97 KB | 0.87 | 0.85 | **0.94** | 137 KB/s | |
| | default (`onnx/default`) | 219 KB | 0.88 | **0.87** | 0.93 | 66 KB/s | |
| | CredSweeper 1.19 * | 12 MB | 0.94 | 0.79 | 0.41 | 230 KB/s | |
| | detect-secrets 1.5 | 1.1 MB | 0.57 | 0.48 | 0.32 | 155 KB/s | |
| | gitleaks 8 | 23 MB | 0.44 | 0.69 | 0.25 | 958 KB/s | |
|
|
| CredData: 64 held-out repos of [Samsung CredData](https://github.com/Samsung/CredData). GitHub issues: |
| [Ahmed et al. 2025](https://arxiv.org/abs/2410.23657). Docs: synthetic emails, chats and tickets in 5 languages. |
| \* CredSweeper was trained on all of CredData, so its CredData score is not held out. |
|
|
| ## Limitations |
|
|
| - Passwords in prose with unusual wording (short PINs, "access code X") can score below 0.5. |
| - Hex strings and UUIDs next to words like `secret` sometimes raise false alarms. |
| - Does not verify tokens with providers or detect secrets split across lines. |
|
|
| Training data: CredData training repos, synthetic code, configs and documents (randomly generated secrets) and |
| real non-secret text. No benchmark data was used for training. |
|
|
