National Cyber Warfare Foundation (NCWF)login

CredSweeper for hunting exposed credentials in codebases and repositories


0 user ratings
2026-11-10 23:31:04
milo
Red Team (CNA)
"CredSweeper

CredSweeper is Samsung's open-source credential scanner that combines pattern rules, machine learning validation, and deep file inspection to find leaked password, token, and API key material in authorized security work.








ToolSamsung/CredSweeper — credential detection scanner for source code, configs, documents, archives, and Git history
CategorySecret scanning / static analysis (Python)
Primary UseAuditing owned codebases, repositories, and container images for exposed password, token, API key, and key-file material before it leaks
Safe UseDefensive and educational analysis for authorized professionals: scanning your own repositories, CI pipelines, and code under explicit assessment scope; the tool only reads files you point it at and reports findings
Telemetry NotePurely local file analysis with no network callbacks — defenders observe it as read-only scan activity on monitored endpoints, and its JSON reports are safe to ingest into SIEM triage workflows

CredSweeper is Samsung's answer to one of the most persistent problems in modern software hygiene: secrets committed to source control and forgotten. The tool is described in its README as an advanced credential detection engine that identifies exposed passwords, API keys, tokens, and other sensitive material across source code, configuration files, documents, and binary assets. What sets it apart from naive grep-style scanners is its layered pipeline — pattern-based detection, algorithmic filters, machine learning validation, and deep file inspection — which together aim to keep precision high while still digging through formats most scanners skip. It is published under the MIT license and hosted at Samsung/CredSweeper with around 222 stars, an actively maintained Python codebase, and full documentation on Read the Docs.


The scope of what CredSweeper will chew on is unusually broad. It scans regular files, embedded data inside containers, compressed archives, documents, binary formats, and — critically for incident response — files added in Git commits. That last capability matters because credentials rarely live only in HEAD; they sit in history, in diffed commits, in stashes, and in files that were "removed" three years ago. A scanner that only walks the working tree misses the majority of the exposure surface, and the README explicitly positions Git repository analysis and diff scanning as a key capability alongside plain directory scanning.


Installation follows the standard Python distribution path. The package is on PyPI as credsweeper, supports Python 3.11 through 3.14, and installs with a single pip install credsweeper. Invocation is via the module entry point, and the README's example is representative of daily use: python -m credsweeper --path tests/samples/password.gradle --save-json output.json. The --path flag accepts the target to scan and --save-json directs structured findings to a report file — enough for a quick local audit or for wiring into a larger pipeline that consumes the JSON.


The JSON output schema deserves attention because it is clearly designed for downstream automation rather than just human reading. Each finding carries a rule name, a severity field (high in the sample), a confidence rating, and an ml_probability score — in the README's example, 0.993. Below that sits a line_data_list with the full matched line, line_num, and path, plus granular detail: the detected variable and value with start and end offsets into the line, and a computed entropy figure (2.52164 in the sample). The combination of rule severity, confidence, ML probability, and entropy gives a triage analyst multiple independent signals to prioritize on, which is exactly what you want when a scan of a large monorepo returns thousands of candidates.


Architecture-wise, the README points to two configuration layers that reveal how the engine is structured. The first, credsweeper/secret/config.json, governs pre-processing: which files get scanned at all. Its exclude block lets you suppress findings by pattern (the example excludes AWS documentation placeholder keys matching AKIA[0-9A-Z]{9}EXAMPLE), by extension (gif, jpg), and by path (/.git/, /openssl/). The same file controls source_ext and source_quote_ext — lists of extensions categorized as source code, with or without quote semantics — plus find_by_ext_list for extension-only detection of sensitive file types like .pem and .cer, a check_for_literals toggle, and configurable line_data_output and candidate_output attribute lists that shape what the report actually contains.


The second layer, credsweeper/rules/config.yaml, defines the detection rules themselves, and the README's example rule is instructive. A rule named Credential carries severity: medium, confidence: moderate, type: keyword, a values list containing credential, a filter_type of GeneralKeyword, use_ml: true, a min_line_len of 18, required_substrings, and a target that includes code. The YAML structure means detection logic is data, not hardcoded behavior — a team can tune sensitivity, add organization-specific secret formats, or adjust severity mappings without touching Python. The use_ml flag per rule shows that ML validation is opt-in at the rule level rather than applied indiscriminately across all detections.


The machine learning component is not a black box, which is a notable differentiator. The README's "Retrain Model" section points to an experiment/ folder with documentation on how the model was trained and how to retrain it on your own data. For an enterprise deploying this at scale, that matters: false-positive rates on secret scanners are highly corpus-dependent, and the ability to retrain against your own codebase's idioms — your internal library names, your test fixtures, your documentation examples — can be the difference between a signal and noise. The ML backend is worth investigating in the docs before relying on ml_probability thresholds for automated blocking decisions.


There is also a serious evaluation story. The project maintains Samsung/CredData, a dedicated dataset for benchmarking credential scanners, with documented benchmark instructions in that repository's README. This is the kind of rigor that separates tools you can defend in a design review from tools you hope work. Alongside it, the development workflow shows CI badges for tests and codecov coverage, plus CII Best Practices and OpenSSF Scorecard badges — signals that the maintainers treat supply-chain hygiene as part of the product, not an afterthought. Contributors run the suite with python -m pytest --cov=credsweeper --cov-report=term-missing --random-order --random-order-bucket=global -s tests/, the random ordering being a deliberate guard against inter-test coupling.


In an authorized workflow, CredSweeper slots into several distinct phases. Pre-commit, it can run as a gate in CI to catch secrets before they enter history, where remediation is expensive. During assessments, the Git-history and container-scanning capabilities make it a first-pass triage tool over client-owned repositories — always within the engagement scope, since scanning repositories you do not own or administer raises the same authorization questions as any other assessment technique. Post-incident, the JSON output and severity/confidence model feed directly into a remediation queue: rotate, purge from history, verify. The tool is read-only in nature — it detects and reports, it does not exfiltrate or transmit findings anywhere — so its footprint on a target environment is limited to file reads and CPU cycles, and defenders monitoring an endpoint would see nothing beyond local process activity.


What to watch for in operational use: the exclusion configuration is powerful but double-edged, and an overly broad exclude block can silently hide real findings, so changes to config.json deserve the same review discipline as code. Entropy scoring has known blind spots — short, low-entropy passwords that happen to look like words will score low, which is precisely why the tool layers ML probability and rule confidence on top rather than relying on entropy alone. The find_by_ext_list approach to .pem and .cer files is extension-based, so renamed key material will pass through unless a content rule catches it. None of these are fatal; they are the ordinary trade-offs of a layered detector, and the per-rule configurability exists largely to manage them.


The project's governance is also worth a note. It follows an explicit Open Source Development model with formal Contributor and Maintainer roles, a meritocratic progression path, and a named maintainer team reachable through GitHub issues — four Samsung engineers listed with contact addresses in the README. For an organization considering adoption, that structure, combined with the MIT license, the benchmark dataset, the retrainable model, and current support for Python 3.14, suggests a project built for long-term institutional use rather than a weekend experiment. For anyone whose job includes keeping secrets out of source control, CredSweeper earns a place on the shortlist of scanners worth benchmarking.



Official project repository for Samsung/CredSweeper.

Download Tool

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.






Source: OffensiveSec
Source Link: https://www.offsecblog.com/2026/11/credsweeper-for-hunting-exposed.html


Comments
new comment
Nobody has commented yet. Will you be the first?
 
Forum
Red Team (CNA)



Copyright 2012 through 2026 - National Cyber Warfare Foundation - All rights reserved worldwide.