Skip to content

Commit 8e4ed92

Browse files
bryanbeverlycursoragent
bryanbeverly
and
cursoragent
committed
Update README formatting and CLI help output
Simplify HTML markup to plain markdown, update the git --help output to reflect current flags and subcommands, and fix minor formatting inconsistencies. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent ec1d9a6 commit 8e4ed92

File tree

1 file changed

+150
-75
lines changed

1 file changed

+150
-75
lines changed

‎README.md‎

Lines changed: 150 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,42 @@
1-
<p align="center">
2-
<img alt="GoReleaser Logo" src="https://storage.googleapis.com/trufflehog-static-sources/pixel_pig.png" height="140" />
3-
<h2 align="center">TruffleHog</h2>
4-
<p align="center">Find leaked credentials.</p>
5-
</p>
1+
2+
3+
## TruffleHog
4+
5+
Find leaked credentials.
6+
7+
68

79
---
810

9-
<div align="center">
1011

11-
[![Go Report Card](https://goreportcard.com/badge/github.com/trufflesecurity/trufflehog/v3)](https://goreportcard.com/report/github.com/trufflesecurity/trufflehog/v3)
12-
[![License](https://img.shields.io/badge/license-AGPL--3.0-brightgreen)](/LICENSE)
13-
[![Total Detectors](https://img.shields.io/github/directory-file-count/trufflesecurity/truffleHog/pkg/detectors?label=Total%20Detectors&type=dir)](/pkg/detectors)
1412

15-
</div>
13+
[Go Report Card](https://goreportcard.com/report/github.com/trufflesecurity/trufflehog/v3)
14+
[License](/LICENSE)
15+
[Total Detectors](/pkg/detectors)
16+
17+
1618

1719
---
1820

19-
# :mag_right: _Now Scanning_
21+
# :mag_right: *Now Scanning*
22+
23+
2024

21-
<div align="center">
2225

23-
<img src="assets/scanning_logos.svg">
2426

2527
**...and more**
2628

2729
To learn more about TruffleHog and its features and capabilities, visit our [product page](https://trufflesecurity.com/trufflehog?gclid=CjwKCAjwouexBhAuEiwAtW_Zx5IW87JNj97Ci7heFnA5ar6-DuNzT2Y5nIl9DuZ-FOUqx0Qg3vb9nxoClcEQAvD_BwE).
2830

29-
</div>
31+
3032

3133
# :globe_with_meridians: TruffleHog Enterprise
3234

33-
Are you interested in continuously monitoring **Git, Jira, Slack, Confluence, Microsoft Teams, Sharepoint (and more)** for credentials? We have an enterprise product that can help! Learn more at <https://trufflesecurity.com/trufflehog-enterprise>.
35+
Are you interested in continuously monitoring **Git, Jira, Slack, Confluence, Microsoft Teams, Sharepoint (and more)** for credentials? We have an enterprise product that can help! Learn more at [https://trufflesecurity.com/trufflehog-enterprise](https://trufflesecurity.com/trufflehog-enterprise).
3436

3537
We take the revenue from the enterprise product to fund more awesome open source projects that the whole community can benefit from.
3638

37-
</div>
39+
3840

3941
# What is TruffleHog 🐽
4042

@@ -66,7 +68,7 @@ Join the [Secret Scanning Discord](https://discord.gg/8Hzbrnkr7E)
6668

6769
# :tv: Demo
6870

69-
![GitHub scanning demo](https://storage.googleapis.com/truffle-demos/non-interactive.svg)
71+
GitHub scanning demo
7072

7173
```bash
7274
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --org=trufflesecurity
@@ -84,27 +86,27 @@ brew install trufflehog
8486

8587
### Docker:
8688

87-
<sub><i>_Ensure Docker engine is running before executing the following commands:_</i></sub>
89+
*_Ensure Docker engine is running before executing the following commands:_*
8890

89-
#### &nbsp;&nbsp;&nbsp;&nbsp;Unix
91+
#### Unix
9092

9193
```bash
9294
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys
9395
```
9496

95-
#### &nbsp;&nbsp;&nbsp;&nbsp;Windows Command Prompt
97+
#### Windows Command Prompt
9698

9799
```bash
98100
docker run --rm -it -v "%cd:/=\%:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys
99101
```
100102

101-
#### &nbsp;&nbsp;&nbsp;&nbsp;Windows PowerShell
103+
#### Windows PowerShell
102104

103105
```bash
104106
docker run --rm -it -v "${PWD}:/pwd" trufflesecurity/trufflehog github --repo https://github.com/trufflesecurity/test_keys
105107
```
106108

107-
#### &nbsp;&nbsp;&nbsp;&nbsp;M1 and M2 Mac
109+
#### M1 and M2 Mac
108110

109111
```bash
110112
docker run --platform linux/arm64 --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys
@@ -152,26 +154,21 @@ You need the following tool to verify signature:
152154
Verification steps are as follows:
153155

154156
1. Download the artifact files you want, and the following files from the [releases](https://github.com/trufflesecurity/trufflehog/releases) page.
155-
156-
- trufflehog\_{version}\_checksums.txt
157-
- trufflehog\_{version}\_checksums.txt.pem
158-
- trufflehog\_{version}\_checksums.txt.sig
159-
157+
- trufflehog{version}checksums.txt
158+
- trufflehog{version}checksums.txt.pem
159+
- trufflehog{version}checksums.txt.sig
160160
2. Verify the signature:
161-
162-
```shell
161+
```shell
163162
cosign verify-blob <path to trufflehog_{version}_checksums.txt> \
164163
--certificate <path to trufflehog_{version}_checksums.txt.pem> \
165164
--signature <path to trufflehog_{version}_checksums.txt.sig> \
166165
--certificate-identity-regexp 'https://github\.com/trufflesecurity/trufflehog/\.github/workflows/.+' \
167166
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
168-
```
169-
167+
```
170168
3. Once the signature is confirmed as valid, you can proceed to validate that the SHA256 sums align with the downloaded artifact:
171-
172-
```shell
169+
```shell
173170
sha256sum --ignore-missing -c trufflehog_{version}_checksums.txt
174-
```
171+
```
175172

176173
Replace `{version}` with the downloaded files version
177174

@@ -260,13 +257,15 @@ trufflehog filesystem path/to/file1.txt path/to/file2.txt path/to/dir
260257
## 9: Scan a local git repo
261258

262259
Clone the git repo. For example [test keys](git@github.com:trufflesecurity/test_keys.git) repo.
260+
263261
```bash
264-
$ git clone git@github.com:trufflesecurity/test_keys.git
262+
git clone git@github.com:trufflesecurity/test_keys.git
265263
```
266264

267265
Run trufflehog from the parent directory (outside the git repo).
266+
268267
```bash
269-
$ trufflehog git file://test_keys --results=verified,unknown
268+
trufflehog git file://test_keys --results=verified,unknown
270269
```
271270

272271
To guard against malicious git configs in local scanning (see CVE-2025-41390), TruffleHog clones local git repositories to a temporary directory prior to scanning. This follows [Git's security best practices](https://git-scm.com/docs/git#_security). If you want to specify a custom path to clone the repository to (instead of tmp), you can use the `--clone-path` flag. If you'd like to skip the local cloning process and scan the repository directly (only do this for trusted repos), you can use the `--trust-local-git-config` flag.
@@ -439,56 +438,133 @@ Each subcommand can have options that you can see with the `--help` flag provide
439438

440439
```
441440
$ trufflehog git --help
442-
usage: TruffleHog git [<flags>] <uri>
441+
usage: TruffleHog [<flags>] <command> [<args> ...]
442+
443+
TruffleHog is a tool for finding credentials.
443444
444-
Find credentials in git repositories.
445445
446446
Flags:
447-
-h, --help Show context-sensitive help (also try --help-long and --help-man).
448-
--log-level=0 Logging verbosity on a scale of 0 (info) to 5 (trace). Can be disabled with "-1".
449-
--profile Enables profiling and sets a pprof and fgprof server on :18066.
450-
-j, --json Output in JSON format.
451-
--json-legacy Use the pre-v3.0 JSON format. Only works with git, gitlab, and github sources.
452-
--github-actions Output in GitHub Actions format.
453-
--concurrency=20 Number of concurrent workers.
454-
--no-verification Don't verify the results.
455-
--results=RESULTS Specifies which type(s) of results to output: verified (confirmed valid by API), unknown (verification failed due to error), unverified (detected but not verified), filtered_unverified (unverified but would have been filtered out). Defaults to all types.
456-
--allow-verification-overlap
447+
-h, --[no-]help Show context-sensitive help (also try --help-long and --help-man).
448+
--log-level=0 Logging verbosity on a scale of 0 (info) to 5 (trace). Can be
449+
disabled with "-1".
450+
--[no-]profile Enables profiling and sets a pprof and fgprof server on :18066.
451+
-j, --[no-]json Output in JSON format.
452+
--[no-]json-legacy Use the pre-v3.0 JSON format. Only works with git, gitlab,
453+
and github sources.
454+
--[no-]github-actions Output in GitHub Actions format.
455+
--concurrency=12 Number of concurrent workers.
456+
--[no-]no-verification Don't verify the results.
457+
--results=RESULTS Specifies which type(s) of results to output: verified (confirmed
458+
valid by API), unknown (verification failed due to error),
459+
unverified (detected but not verified), filtered_unverified
460+
(unverified but would have been filtered out). Defaults to
461+
verified,unverified,unknown.
462+
--[no-]no-color Disable colorized output
463+
--[no-]allow-verification-overlap
457464
Allow verification of similar credentials across detectors
458-
--filter-unverified Only output first unverified result per chunk per detector if there are more than one results.
465+
--[no-]filter-unverified Only output first unverified result per chunk per detector if there
466+
are more than one results.
459467
--filter-entropy=FILTER-ENTROPY
460468
Filter unverified results with Shannon entropy. Start with 3.0.
461469
--config=CONFIG Path to configuration file.
462-
--print-avg-detector-time
470+
--[no-]print-avg-detector-time
463471
Print the average time spent on each detector.
464-
--no-update Don't check for updates.
465-
--fail Exit with code 183 if results are found.
472+
--[no-]no-update Don't check for updates.
473+
--[no-]fail Exit with code 183 if results are found.
474+
--[no-]fail-on-scan-errors
475+
Exit with non-zero error code if an error occurs during the scan.
466476
--verifier=VERIFIER ... Set custom verification endpoints.
467-
--custom-verifiers-only Only use custom verification endpoints.
477+
--[no-]custom-verifiers-only
478+
Only use custom verification endpoints.
479+
--detector-timeout=DETECTOR-TIMEOUT
480+
Maximum time to spend scanning chunks per detector (e.g., 30s).
468481
--archive-max-size=ARCHIVE-MAX-SIZE
469482
Maximum size of archive to scan. (Byte units eg. 512B, 2KB, 4MB)
470483
--archive-max-depth=ARCHIVE-MAX-DEPTH
471484
Maximum depth of archive to scan.
472485
--archive-timeout=ARCHIVE-TIMEOUT
473486
Maximum time to spend extracting an archive.
474-
--include-detectors="all" Comma separated list of detector types to include. Protobuf name or IDs may be used, as well as ranges.
487+
--include-detectors="all" Comma separated list of detector types to include. Protobuf name or
488+
IDs may be used, as well as ranges.
475489
--exclude-detectors=EXCLUDE-DETECTORS
476-
Comma separated list of detector types to exclude. Protobuf name or IDs may be used, as well as ranges. IDs defined here take precedence over the include list.
477-
--version Show application version.
478-
-i, --include-paths=INCLUDE-PATHS
479-
Path to file with newline separated regexes for files to include in scan.
480-
-x, --exclude-paths=EXCLUDE-PATHS
481-
Path to file with newline separated regexes for files to exclude in scan.
482-
--exclude-globs=EXCLUDE-GLOBS
483-
Comma separated list of globs to exclude in scan. This option filters at the `git log` level, resulting in faster scans.
484-
--since-commit=SINCE-COMMIT
485-
Commit to start scan from.
486-
--branch=BRANCH Branch to scan.
487-
--max-depth=MAX-DEPTH Maximum depth of commits to scan.
488-
--bare Scan bare repository (e.g. useful while using in pre-receive hooks)
489-
490-
Args:
491-
<uri> Git repository URL. https://, file://, or ssh:// schema expected.
490+
Comma separated list of detector types to exclude. Protobuf name
491+
or IDs may be used, as well as ranges. IDs defined here take
492+
precedence over the include list.
493+
--[no-]no-verification-cache
494+
Disable verification caching
495+
--[no-]force-skip-binaries
496+
Force skipping binaries.
497+
--[no-]force-skip-archives
498+
Force skipping archives.
499+
--[no-]skip-additional-refs
500+
Skip additional references.
501+
--user-agent-suffix=USER-AGENT-SUFFIX
502+
Suffix to add to User-Agent.
503+
--[no-]version Show application version.
504+
505+
Commands:
506+
help [<command>...]
507+
Show help.
508+
509+
git [<flags>] <uri>
510+
511+
Find credentials in git repositories.
512+
513+
github [<flags>]
514+
Find credentials in GitHub repositories.
515+
516+
github-experimental --repo=REPO [<flags>]
517+
Run an experimental GitHub scan. Must specify at least one experimental sub-module to run:
518+
object-discovery.
519+
520+
gitlab --token=TOKEN [<flags>]
521+
Find credentials in GitLab repositories.
522+
523+
filesystem [<flags>] [<path>...]
524+
Find credentials in a filesystem.
525+
526+
s3 [<flags>]
527+
Find credentials in S3 buckets.
528+
529+
gcs [<flags>]
530+
Find credentials in GCS buckets.
531+
532+
syslog --format=FORMAT [<flags>]
533+
Scan syslog
534+
535+
circleci --token=TOKEN
536+
Scan CircleCI
537+
538+
docker [<flags>]
539+
Scan Docker Image
540+
541+
542+
travisci --token=TOKEN
543+
Scan TravisCI
544+
545+
postman [<flags>]
546+
Scan Postman
547+
548+
elasticsearch [<flags>]
549+
Scan Elasticsearch
550+
551+
jenkins --url=URL [<flags>]
552+
Scan Jenkins
553+
554+
huggingface [<flags>]
555+
Find credentials in HuggingFace datasets, models and spaces.
556+
557+
stdin
558+
Find credentials from stdin.
559+
560+
multi-scan
561+
Find credentials in multiple sources defined in configuration.
562+
563+
json-enumerator [<path>...]
564+
Find credentials from a JSON enumerator input.
565+
566+
analyze
567+
Analyze API keys for fine-grained permissions information.
492568
```
493569

494570
For example, to scan a `git` repository, start with
@@ -613,7 +689,7 @@ Depending on the event type (push or PR), we calculate the number of commits pre
613689
614690
TruffleHog statically detects [https://canarytokens.org/](https://canarytokens.org/).
615691
616-
![image](https://github.com/trufflesecurity/trufflehog/assets/52866392/74ace530-08c5-4eaf-a169-84a73e328f6f)
692+
image
617693
618694
### Advanced Usage
619695
@@ -694,6 +770,7 @@ your custom detector has multiple `regex` set (in this example `hogID`, and `hog
694770
**NB:** This feature is alpha and subject to change.
695771

696772
### Regex Detector Example
773+
697774
[Here](/pkg/custom_detectors/CUSTOM_DETECTORS.md) is how to setup a custom regex detector with verification server.
698775

699776
## Generic JWT Detection
@@ -713,9 +790,7 @@ trufflehog analyze
713790

714791
This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
715792

716-
<a href="https://github.com/trufflesecurity/trufflehog/graphs/contributors">
717-
<img src="https://contrib.rocks/image?repo=trufflesecurity/trufflehog" />
718-
</a>
793+
719794

720795
# :computer: Contributing
721796

@@ -734,4 +809,4 @@ the stability of the public APIs at this time.
734809

735810
# License Change
736811

737-
Since v3.0, TruffleHog is released under a AGPL 3 license, included in [`LICENSE`](LICENSE). TruffleHog v3.0 uses none of the previous codebase, but care was taken to preserve backwards compatibility on the command line interface. The work previous to this release is still available licensed under GPL 2.0 in the history of this repository and the previous package releases and tags. A completed CLA is required for us to accept contributions going forward.
812+
Since v3.0, TruffleHog is released under a AGPL 3 license, included in `[LICENSE](LICENSE)`. TruffleHog v3.0 uses none of the previous codebase, but care was taken to preserve backwards compatibility on the command line interface. The work previous to this release is still available licensed under GPL 2.0 in the history of this repository and the previous package releases and tags. A completed CLA is required for us to accept contributions going forward.

0 commit comments

Comments
 (0)