Skip to content

Find, verify, and analyze leaked credentials

Add man page generation for trufflehog (#4894)

Bryan Beverly4d2a8ef68634
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index cddc6f1dd..affda2039 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -25,6 +25,22 @@ jobs:
# NOTE: Version and args must match scripts/lint.sh
version: v2.11.4
args: --disable errcheck,staticcheck --enable bodyclose,copyloopvar,misspell --timeout 10m
+ man-page-staleness:
+ name: man-page-staleness
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-go@v5
+ with:
+ go-version: "1.25"
+ - name: Regenerate man page
+ run: make man
+ - name: Check for staleness
+ run: |
+ if ! git diff --exit-code docs/man/trufflehog.1; then
+ echo "::error::docs/man/trufflehog.1 is stale. Run 'make man' and commit the result."
+ exit 1
+ fi
semgrep:
name: semgrep
runs-on: ubuntu-latest
diff --git a/.goreleaser.yml b/.goreleaser.yml
index 56ea7af1a..88e054c40 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -1,4 +1,8 @@
version: 2
+before:
+ hooks:
+ - mkdir -p docs/man
+ - sh -c 'CGO_ENABLED=0 go run -ldflags "-X github.com/trufflesecurity/trufflehog/v3/pkg/version.BuildVersion={{ .Version }}" . --generate-man-page > docs/man/trufflehog.1'
release:
# GoReleaser creates the GitHub release before artifacts finish uploading.
# scripts/install.sh queries /releases/latest to find the current version, so
@@ -31,6 +35,11 @@ builds:
goarch:
- amd64
- arm64
+archives:
+ - files:
+ - LICENSE
+ - README.md
+ - docs/man/trufflehog.1
dockers:
- image_templates: ["trufflesecurity/{{ .ProjectName }}:{{ .Version }}-amd64"]
dockerfile: Dockerfile.goreleaser
@@ -121,6 +130,8 @@ brews:
homepage: "https://github.com/trufflesecurity/trufflehog"
install: |
bin.install "trufflehog"
+ extra_install: |
+ man1.install "docs/man/trufflehog.1"
signs:
- cmd: cosign
signature: "${artifact}.sig"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2badad299..b17bb1e54 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,3 +40,7 @@ Example: `Logger().V(2).Info("skipping file: extension is ignored", "ext", mimeE
**Either log an error or return it**. Doing one or the other will help defer logging for when there is more context for it and prevent duplicate “bubbling up” logs.
**Log contextual information**. Every log emitted should contain this context via fields to easily filter and search.
+
+## Updating the man page
+
+If you add, remove, or rename CLI flags or subcommands, regenerate the man page with `make man` and commit the updated `docs/man/trufflehog.1`. CI will fail if the checked-in man page is stale.
diff --git a/Makefile b/Makefile
index 140e6fc1c..e9065d9ed 100644
--- a/Makefile
+++ b/Makefile
@@ -10,6 +10,7 @@ PROTOS_IMAGE ?= trufflesecurity/protos:1.22
.PHONY: protos-windows
.PHONY: vendor
.PHONY: dogfood
+.PHONY: man
dogfood:
CGO_ENABLED=0 go run . git file://. --json --log-level=2
@@ -61,5 +62,9 @@ release-protos-image:
docker buildx build --push --platform=linux/amd64,linux/arm64 \
-t ${PROTOS_IMAGE} -f hack/Dockerfile.protos .
+man:
+ @mkdir -p docs/man
+ CGO_ENABLED=0 go run . --generate-man-page > docs/man/trufflehog.1
+
test-release:
- goreleaser release --clean --skip-publish --snapshot
+ goreleaser release --clean --skip=publish,sign --snapshot
diff --git a/docs/man/trufflehog.1 b/docs/man/trufflehog.1
new file mode 100644
index 000000000..666b21e51
--- /dev/null
+++ b/docs/man/trufflehog.1
@@ -0,0 +1,680 @@
+.TH TRUFFLEHOG 1 "" "trufflehog dev" "Truffle Security"
+.SH NAME
+trufflehog \- find credentials in various sources
+.SH SYNOPSIS
+.TP
+\fBtrufflehog [<flags>] <command> [<args> ...]\fR
+
+.SH DESCRIPTION
+TruffleHog is a tool for finding credentials. Run without a command for interactive mode.
+.PP
+TruffleHog scans various data sources for verified and
+unverified secrets such as API keys, passwords, and other
+credentials. It supports scanning git repositories, GitHub
+and GitLab organizations, filesystems, S3 buckets, GCS
+buckets, Docker images, CI/CD systems, and more.
+.PP
+When run without a command in an interactive terminal,
+\fBtrufflehog\fR launches a TUI (text user interface) that
+guides you through selecting a scan source and configuring
+options.
+.SH OPTIONS
+.TP
+\fB-h, --help\fR
+Show context-sensitive help (also try --help-long and --help-man).
+.TP
+\fB--log-level=0\fR
+Logging verbosity on a scale of 0 (info) to 5 (trace). Can be disabled with "-1".
+.TP
+\fB--profile\fR
+Enables profiling and sets a pprof and fgprof server on :18066.
+.TP
+\fB-j, --json\fR
+Output in JSON format.
+.TP
+\fB--json-legacy\fR
+Use the pre-v3.0 JSON format. Only works with git, gitlab, and github sources.
+.TP
+\fB--github-actions\fR
+Output in GitHub Actions format.
+.TP
+\fB--concurrency=N\fR
+Number of concurrent workers.
+.TP
+\fB--no-verification\fR
+Don't verify the results.
+.TP
+\fB--results=RESULTS\fR
+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 verified,unverified,unknown.
+.TP
+\fB--no-color\fR
+Disable colorized output
+.TP
+\fB--allow-verification-overlap\fR
+Allow verification of similar credentials across detectors
+.TP
+\fB--filter-unverified\fR
+Only output first unverified result per chunk per detector if there are more than one results.
+.TP
+\fB--filter-entropy=FILTER-ENTROPY\fR
+Filter unverified results with Shannon entropy. Start with 3.0.
+.TP
+\fB--max-decode-depth=5\fR
+Maximum depth of iterative decoding. Each decoder's output is fed back through all decoders, up to this limit. 1 = single pass, 2+ = chained decoding (e.g., base64 inside utf16).
+.TP
+\fB--config=CONFIG\fR
+Path to configuration file.
+.TP
+\fB--print-avg-detector-time\fR
+Print the average time spent on each detector.
+.TP
+\fB--no-update\fR
+Don't check for updates.
+.TP
+\fB--fail\fR
+Exit with code 183 if results are found.
+.TP
+\fB--fail-on-scan-errors\fR
+Exit with non-zero error code if an error occurs during the scan.
+.TP
+\fB--verifier=VERIFIER\fR
+Set custom verification endpoints.
+.TP
+\fB--custom-verifiers-only\fR
+Only use custom verification endpoints.
+.TP
+\fB--detector-timeout=DETECTOR-TIMEOUT\fR
+Maximum time to spend scanning chunks per detector (e.g., 30s).
+.TP
+\fB--archive-max-size=ARCHIVE-MAX-SIZE\fR
+Maximum size of archive to scan. (Byte units eg. 512B, 2KB, 4MB)
+.TP
+\fB--archive-max-depth=ARCHIVE-MAX-DEPTH\fR
+Maximum depth of archive to scan.
+.TP
+\fB--archive-timeout=ARCHIVE-TIMEOUT\fR
+Maximum time to spend extracting an archive.
+.TP
+\fB--include-detectors="all"\fR
+Comma separated list of detector types to include. Protobuf name or IDs may be used, as well as ranges.
+.TP
+\fB--exclude-detectors=EXCLUDE-DETECTORS\fR
+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.
+.TP
+\fB--no-verification-cache\fR
+Disable verification caching
+.TP
+\fB--force-skip-binaries\fR
+Force skipping binaries.
+.TP
+\fB--force-skip-archives\fR
+Force skipping archives.
+.TP
+\fB--skip-additional-refs\fR
+Skip additional references.
+.TP
+\fB--user-agent-suffix=USER-AGENT-SUFFIX\fR
+Suffix to add to User-Agent.
+.TP
+\fB--version\fR
+Show application version.
+.SH COMMANDS
+.SS
+\fBhelp [<command>...]\fR
+Show help.
+.SS
+\fBgit [<flags>] <uri>\fR
+Find credentials in git repositories.
+.TP
+\fB-i, --include-paths=INCLUDE-PATHS\fR
+Path to file with newline separated regexes for files to include in scan.
+.TP
+\fB-x, --exclude-paths=EXCLUDE-PATHS\fR
+Path to file with newline separated regexes for files to exclude in scan.
+.TP
+\fB--exclude-globs=EXCLUDE-GLOBS\fR
+Comma separated list of globs to exclude in scan. This option filters at the `git log` level, resulting in faster scans.
+.TP
+\fB--since-commit=SINCE-COMMIT\fR
+Commit to start scan from.
+.TP
+\fB--branch=BRANCH\fR
+Branch to scan.
+.TP
+\fB--max-depth=MAX-DEPTH\fR
+Maximum depth of commits to scan.
+.TP
+\fB--bare\fR
+Scan bare repository (e.g. useful while using in pre-receive hooks)
+.TP
+\fB--clone-path=CLONE-PATH\fR
+Custom path where the repository should be cloned (default: temp dir).
+.TP
+\fB--no-cleanup\fR
+Do not delete cloned repositories after scanning (can only be used with --clone-path).
+.TP
+\fB--trust-local-git-config\fR
+Trust local git config.
+.TP
+\fB--allow\fR
+No-op flag for backwards compat.
+.TP
+\fB--entropy\fR
+No-op flag for backwards compat.
+.TP
+\fB--regex\fR
+No-op flag for backwards compat.
+.SS
+\fBgithub [<flags>]\fR
+Find credentials in GitHub repositories.
+.TP
+\fB--endpoint="https://api.github.com"\fR
+GitHub endpoint.
+.TP
+\fB--repo=REPO\fR
+GitHub repository to scan. You can repeat this flag. Example: "https://github.com/dustin-decker/secretsandstuff"
+.TP
+\fB--org=ORG\fR
+GitHub organization to scan. You can repeat this flag. Example: "trufflesecurity"
+.TP
+\fB--token=TOKEN\fR
+GitHub token. Can be provided with environment variable GITHUB_TOKEN.
+.TP
+\fB--include-forks\fR
+Include forks in scan.
+.TP
+\fB--include-members\fR
+Include organization member repositories in scan.
+.TP
+\fB--include-repos=INCLUDE-REPOS\fR
+Repositories to include in an org scan. This can also be a glob pattern. You can repeat this flag. Must use Github repo full name. Example: "trufflesecurity/trufflehog", "trufflesecurity/t*"
+.TP
+\fB--include-wikis\fR
+Include repository wikisin scan.
+.TP
+\fB--exclude-repos=EXCLUDE-REPOS\fR
+Repositories to exclude in an org scan. This can also be a glob pattern. You can repeat this flag. Must use Github repo full name. Example: "trufflesecurity/driftwood", "trufflesecurity/d*"
+.TP
+\fB-i, --include-paths=INCLUDE-PATHS\fR
+Path to file with newline separated regexes for files to include in scan.
+.TP
+\fB-x, --exclude-paths=EXCLUDE-PATHS\fR
+Path to file with newline separated regexes for files to exclude in scan.
+.TP
+\fB--issue-comments\fR
+Include issue descriptions and comments in scan.
+.TP
+\fB--pr-comments\fR
+Include pull request descriptions and comments in scan.
+.TP
+\fB--gist-comments\fR
+Include gist comments in scan.
+.TP
+\fB--comments-timeframe=COMMENTS-TIMEFRAME\fR
+Number of days in the past to review when scanning issue, PR, and gist comments.
+.TP
+\fB--auth-in-url\fR
+Embed authentication credentials in repository URLs instead of using secure HTTP headers
+.TP
+\fB--clone-path=CLONE-PATH\fR
+Custom path where the repository should be cloned (default: temp dir).
+.TP
+\fB--no-cleanup\fR
+Do not delete cloned repositories after scanning (can only be used with --clone-path).
+.TP
+\fB--ignore-gists\fR
+Ignore all gists in scan.
+.SS
+\fBgithub-experimental --repo=REPO [<flags>]\fR
+Run an experimental GitHub scan. Must specify at least one experimental sub-module to run: object-discovery.
+.TP
+\fB--object-discovery\fR
+Discover hidden data objects in GitHub repositories.
+.TP
+\fB--token=TOKEN\fR
+GitHub token. Can be provided with environment variable GITHUB_TOKEN.
+.TP
+\fB--repo=REPO\fR
+GitHub repository to scan. Example: https://github.com/<user>/<repo>.git
+.TP
+\fB--collision-threshold=1\fR
+Threshold for short-sha collisions in object-discovery submodule. Default is 1.
+.TP
+\fB--delete-cached-data\fR
+Delete cached data after object-discovery secret scanning.
+.SS
+\fBgitlab --token=TOKEN [<flags>]\fR
+Find credentials in GitLab repositories.
+.TP
+\fB--endpoint="https://gitlab.com"\fR
+GitLab endpoint.
+.TP
+\fB--repo=REPO\fR
+GitLab repo url. You can repeat this flag. Leave empty to scan all repos accessible with provided credential. Example: https://gitlab.com/org/repo.git
+.TP
+\fB--token=TOKEN\fR
+GitLab token. Can be provided with environment variable GITLAB_TOKEN.
+.TP
+\fB--group-id=GROUP-ID\fR
+GitLab group ID. If provided, it will scan the group and its subgroups. You can repeat this flag.
+.TP
+\fB-i, --include-paths=INCLUDE-PATHS\fR
+Path to file with newline separated regexes for files to include in scan.
+.TP
+\fB-x, --exclude-paths=EXCLUDE-PATHS\fR
+Path to file with newline separated regexes for files to exclude in scan.
+.TP
+\fB--include-repos=INCLUDE-REPOS\fR
+Repositories to include in an org scan. This can also be a glob pattern. You can repeat this flag. Must use Gitlab repo full name. Example: "trufflesecurity/trufflehog", "trufflesecurity/t*"
+.TP
+\fB--exclude-repos=EXCLUDE-REPOS\fR
+Repositories to exclude in an org scan. This can also be a glob pattern. You can repeat this flag. Must use Gitlab repo full name. Example: "trufflesecurity/driftwood", "trufflesecurity/d*"
+.TP
+\fB--auth-in-url\fR
+Embed authentication credentials in repository URLs instead of using secure HTTP headers
+.TP
+\fB--clone-path=CLONE-PATH\fR
+Custom path where the repository should be cloned (default: temp dir)
+.TP
+\fB--no-cleanup\fR
+Do not delete cloned repositories after scanning (can only be used with --clone-path).
+.SS
+\fBfilesystem [<flags>] [<path>...]\fR
+Find credentials in a filesystem.
+.TP
+\fB--directory=DIRECTORY\fR
+Path to directory to scan. You can repeat this flag.
+.TP
+\fB-i, --include-paths=INCLUDE-PATHS\fR
+Path to file with newline separated regexes for files to include in scan.
+.TP
+\fB-x, --exclude-paths=EXCLUDE-PATHS\fR
+Path to file with newline separated regexes for files to exclude in scan.
+.TP
+\fB-s, --max-symlink-depth=MAX-SYMLINK-DEPTH\fR
+Maximum depth to follow symlinks during filesystem scan.
+.SS
+\fBs3 [<flags>]\fR
+Find credentials in S3 buckets.
+.TP
+\fB--key=KEY\fR
+S3 key used to authenticate. Can be provided with environment variable AWS_ACCESS_KEY_ID.
+.TP
+\fB--role-arn=ROLE-ARN\fR
+Specify the ARN of an IAM role to assume for scanning. You can repeat this flag.
+.TP
+\fB--secret=SECRET\fR
+S3 secret used to authenticate. Can be provided with environment variable AWS_SECRET_ACCESS_KEY.
+.TP
+\fB--session-token=SESSION-TOKEN\fR
+S3 session token used to authenticate temporary credentials. Can be provided with environment variable AWS_SESSION_TOKEN.
+.TP
+\fB--cloud-environment\fR
+Use IAM credentials in cloud environment.
+.TP
+\fB--bucket=BUCKET\fR
+Name of S3 bucket to scan. You can repeat this flag. Incompatible with --ignore-bucket.
+.TP
+\fB--ignore-bucket=IGNORE-BUCKET\fR
+Name of S3 bucket to ignore. You can repeat this flag. Incompatible with --bucket.
+.TP
+\fB--max-object-size=250MB\fR
+Maximum size of objects to scan. Objects larger than this will be skipped. (Byte units eg. 512B, 2KB, 4MB)
+.SS
+\fBgcs [<flags>]\fR
+Find credentials in GCS buckets.
+.TP
+\fB--project-id=PROJECT-ID\fR
+GCS project ID used to authenticate. Can NOT be used with unauth scan. Can be provided with environment variable GOOGLE_CLOUD_PROJECT.
+.TP
+\fB--cloud-environment\fR
+Use Application Default Credentials, IAM credentials to authenticate.
+.TP
+\fB--service-account=SERVICE-ACCOUNT\fR
+Path to GCS service account JSON file.
+.TP
+\fB--without-auth\fR
+Scan GCS buckets without authentication. This will only work for public buckets
+.TP
+\fB--api-key=API-KEY\fR
+GCS API key used to authenticate. Can be provided with environment variable GOOGLE_API_KEY.
+.TP
+\fB-I, --include-buckets=INCLUDE-BUCKETS\fR
+Buckets to scan. Comma separated list of buckets. You can repeat this flag. Globs are supported
+.TP
+\fB-X, --exclude-buckets=EXCLUDE-BUCKETS\fR
+Buckets to exclude from scan. Comma separated list of buckets. Globs are supported
+.TP
+\fB-i, --include-objects=INCLUDE-OBJECTS\fR
+Objects to scan. Comma separated list of objects. you can repeat this flag. Globs are supported
+.TP
+\fB-x, --exclude-objects=EXCLUDE-OBJECTS\fR
+Objects to exclude from scan. Comma separated list of objects. You can repeat this flag. Globs are supported
+.TP
+\fB--max-object-size=10MB\fR
+Maximum size of objects to scan. Objects larger than this will be skipped. (Byte units eg. 512B, 2KB, 4MB)
+.SS
+\fBsyslog --format=FORMAT [<flags>]\fR
+Scan syslog
+.TP
+\fB--address=ADDRESS\fR
+Address and port to listen on for syslog. Example: 127.0.0.1:514
+.TP
+\fB--protocol=PROTOCOL\fR
+Protocol to listen on. udp or tcp
+.TP
+\fB--cert=CERT\fR
+Path to TLS cert.
+.TP
+\fB--key=KEY\fR
+Path to TLS key.
+.TP
+\fB--format=FORMAT\fR
+Log format. Can be rfc3164 or rfc5424
+.SS
+\fBcircleci --token=TOKEN\fR
+Scan CircleCI
+.TP
+\fB--token=TOKEN\fR
+CircleCI token. Can also be provided with environment variable
+.SS
+\fBdocker [<flags>]\fR
+Scan Docker Image
+.TP
+\fB--image=IMAGE\fR
+Docker image to scan. Use the file:// prefix to point to a local tarball, the docker:// prefix to point to the docker daemon, otherwise an image registry is assumed.
+.TP
+\fB--token=TOKEN\fR
+Docker bearer token. Can also be provided with environment variable
+.TP
+\fB--exclude-paths=EXCLUDE-PATHS\fR
+Comma separated list of paths to exclude from scan
+.TP
+\fB--namespace=NAMESPACE\fR
+Docker namespace (organization or user). For non-Docker Hub registries, include the registry address as well (e.g., ghcr.io/namespace or quay.io/namespace).
+.TP
+\fB--registry-token=REGISTRY-TOKEN\fR
+Optional Docker registry access token. Provide this if you want to include private images within the specified namespace.
+.SS
+\fBtravisci --token=TOKEN\fR
+Scan TravisCI
+.TP
+\fB--token=TOKEN\fR
+TravisCI token. Can also be provided with environment variable
+.SS
+\fBpostman [<flags>]\fR
+Scan Postman
+.TP
+\fB--token=TOKEN\fR
+Postman token. Can also be provided with environment variable
+.TP
+\fB--workspace-id=WORKSPACE-ID\fR
+Postman workspace ID to scan. You can repeat this flag.
+.TP
+\fB--collection-id=COLLECTION-ID\fR
+Postman collection ID to scan. You can repeat this flag.
+.TP
+\fB--environment=ENVIRONMENT\fR
+Postman environment to scan. You can repeat this flag.
+.TP
+\fB--include-collection-id=INCLUDE-COLLECTION-ID\fR
+Collection ID to include in scan. You can repeat this flag.
+.TP
+\fB--include-environments=INCLUDE-ENVIRONMENTS\fR
+Environments to include in scan. You can repeat this flag.
+.TP
+\fB--exclude-collection-id=EXCLUDE-COLLECTION-ID\fR
+Collection ID to exclude from scan. You can repeat this flag.
+.TP
+\fB--exclude-environments=EXCLUDE-ENVIRONMENTS\fR
+Environments to exclude from scan. You can repeat this flag.
+.TP
+\fB--workspace-paths=WORKSPACE-PATHS\fR
+Path to Postman workspaces.
+.TP
+\fB--collection-paths=COLLECTION-PATHS\fR
+Path to Postman collections.
+.TP
+\fB--environment-paths=ENVIRONMENT-PATHS\fR
+Path to Postman environments.
+.SS
+\fBelasticsearch [<flags>]\fR
+Scan Elasticsearch
+.TP
+\fB--nodes=NODES\fR
+Elasticsearch nodes
+.TP
+\fB--username=USERNAME\fR
+Elasticsearch username
+.TP
+\fB--password=PASSWORD\fR
+Elasticsearch password
+.TP
+\fB--service-token=SERVICE-TOKEN\fR
+Elasticsearch service token
+.TP
+\fB--cloud-id=CLOUD-ID\fR
+Elasticsearch cloud ID. Can also be provided with environment variable
+.TP
+\fB--api-key=API-KEY\fR
+Elasticsearch API key. Can also be provided with environment variable
+.TP
+\fB--index-pattern="*"\fR
+Filters the indices to search
+.TP
+\fB--query-json=QUERY-JSON\fR
+Filters the documents to search
+.TP
+\fB--since-timestamp=SINCE-TIMESTAMP\fR
+Filters the documents to search to those created since this timestamp; overrides any timestamp from --query-json
+.TP
+\fB--best-effort-scan\fR
+Attempts to continuously scan a cluster
+.SS
+\fBjenkins --url=URL [<flags>]\fR
+Scan Jenkins
+.TP
+\fB--url=URL\fR
+Jenkins URL
+.TP
+\fB--username=USERNAME\fR
+Jenkins username
+.TP
+\fB--password=PASSWORD\fR
+Jenkins password
+.TP
+\fB--insecure-skip-verify-tls\fR
+Skip TLS verification
+.SS
+\fBhuggingface [<flags>]\fR
+Find credentials in HuggingFace datasets, models and spaces.
+.TP
+\fB--endpoint="https://huggingface.co"\fR
+HuggingFace endpoint.
+.TP
+\fB--model=MODEL\fR
+HuggingFace model to scan. You can repeat this flag. Example: 'username/model'
+.TP
+\fB--space=SPACE\fR
+HuggingFace space to scan. You can repeat this flag. Example: 'username/space'
+.TP
+\fB--dataset=DATASET\fR
+HuggingFace dataset to scan. You can repeat this flag. Example: 'username/dataset'
+.TP
+\fB--org=ORG\fR
+HuggingFace organization to scan. You can repeat this flag. Example: "trufflesecurity"
+.TP
+\fB--user=USER\fR
+HuggingFace user to scan. You can repeat this flag. Example: "trufflesecurity"
+.TP
+\fB--token=TOKEN\fR
+HuggingFace token. Can be provided with environment variable HUGGINGFACE_TOKEN.
+.TP
+\fB--include-models=INCLUDE-MODELS\fR
+Models to include in scan. You can repeat this flag. Must use HuggingFace model full name. Example: 'username/model' (Only used with --user or --org)
+.TP
+\fB--include-spaces=INCLUDE-SPACES\fR
+Spaces to include in scan. You can repeat this flag. Must use HuggingFace space full name. Example: 'username/space' (Only used with --user or --org)
+.TP
+\fB--include-datasets=INCLUDE-DATASETS\fR
+Datasets to include in scan. You can repeat this flag. Must use HuggingFace dataset full name. Example: 'username/dataset' (Only used with --user or --org)
+.TP
+\fB--ignore-models=IGNORE-MODELS\fR
+Models to ignore in scan. You can repeat this flag. Must use HuggingFace model full name. Example: 'username/model' (Only used with --user or --org)
+.TP
+\fB--ignore-spaces=IGNORE-SPACES\fR
+Spaces to ignore in scan. You can repeat this flag. Must use HuggingFace space full name. Example: 'username/space' (Only used with --user or --org)
+.TP
+\fB--ignore-datasets=IGNORE-DATASETS\fR
+Datasets to ignore in scan. You can repeat this flag. Must use HuggingFace dataset full name. Example: 'username/dataset' (Only used with --user or --org)
+.TP
+\fB--skip-all-models\fR
+Skip all model scans. (Only used with --user or --org)
+.TP
+\fB--skip-all-spaces\fR
+Skip all space scans. (Only used with --user or --org)
+.TP
+\fB--skip-all-datasets\fR
+Skip all dataset scans. (Only used with --user or --org)
+.TP
+\fB--include-discussions\fR
+Include discussions in scan.
+.TP
+\fB--include-prs\fR
+Include pull requests in scan.
+.SS
+\fBstdin\fR
+Find credentials from stdin.
+.SS
+\fBmulti-scan\fR
+Find credentials in multiple sources defined in configuration.
+.SS
+\fBjson-enumerator [<path>...]\fR
+Find credentials from a JSON enumerator input.
+.SS
+\fBanalyze\fR
+Analyze API keys for fine-grained permissions information.
+.SH "EXIT STATUS"
+.TP
+.B 0
+Successful execution.
+.TP
+.B 183
+Credentials were found and \fB\-\-fail\fR was specified.
+.TP
+.B 1
+An error occurred during scanning.
+.SH EXAMPLES
+.TP
+.B Launch the interactive TUI
+.EX
+trufflehog
+.EE
+.TP
+.B Scan a git repository
+.EX
+trufflehog git https://github.com/example/repo.git
+.EE
+.TP
+.B Scan a GitHub organization
+.EX
+trufflehog github \-\-org=trufflesecurity \-\-token=$GITHUB_TOKEN
+.EE
+.TP
+.B Scan a local filesystem
+.EX
+trufflehog filesystem /path/to/directory
+.EE
+.TP
+.B Scan an S3 bucket
+.EX
+trufflehog s3 \-\-bucket=my\-bucket \-\-cloud\-environment
+.EE
+.TP
+.B Scan a Docker image
+.EX
+trufflehog docker \-\-image=myregistry/myimage:latest
+.EE
+.TP
+.B Read from stdin
+.EX
+cat secrets.txt | trufflehog stdin
+.EE
+.TP
+.B Output JSON and filter with jq
+.EX
+trufflehog git https://github.com/example/repo.git \-\-json \e
+ | jq 'select(.Verified == true)'
+.EE
+.TP
+.B Fail in CI if secrets are found
+.EX
+trufflehog git file://. \-\-fail \-\-results=verified,unknown
+.EE
+.TP
+.B Use a configuration file
+.EX
+trufflehog git https://github.com/example/repo.git \e
+ \-\-config=trufflehog\-config.yaml
+.EE
+.SH ENVIRONMENT
+.TP
+.B GITHUB_TOKEN
+Authentication token for GitHub scanning.
+.TP
+.B GITLAB_TOKEN
+Authentication token for GitLab scanning.
+.TP
+.B AWS_ACCESS_KEY_ID
+AWS access key for S3 scanning.
+.TP
+.B AWS_SECRET_ACCESS_KEY
+AWS secret key for S3 scanning.
+.TP
+.B AWS_SESSION_TOKEN
+AWS session token for temporary credentials.
+.TP
+.B GOOGLE_CLOUD_PROJECT
+GCP project ID for GCS scanning.
+.TP
+.B GOOGLE_API_KEY
+GCP API key for GCS scanning.
+.TP
+.B CIRCLECI_TOKEN
+Authentication token for CircleCI scanning.
+.TP
+.B DOCKER_TOKEN
+Authentication token for Docker scanning.
+.TP
+.B TRAVISCI_TOKEN
+Authentication token for TravisCI scanning.
+.TP
+.B POSTMAN_TOKEN
+Authentication token for Postman scanning.
+.TP
+.B HUGGINGFACE_TOKEN
+Authentication token for HuggingFace scanning.
+.TP
+.B ELASTICSEARCH_NODES
+Comma-separated list of Elasticsearch nodes.
+.TP
+.B JENKINS_URL
+URL of the Jenkins server.
+.SH FILES
+.TP
+.I trufflehog\-config.yaml
+Optional configuration file specified via \fB\-\-config\fR.
+See the project documentation for the configuration
+file format.
+.SH BUGS
+Report bugs at
+.UR https://github.com/trufflesecurity/trufflehog/issues
+the TruffleHog issue tracker
+.UE .
+.SH "SEE ALSO"
+.UR https://github.com/trufflesecurity/trufflehog
+TruffleHog on GitHub
+.UE ,
+.UR https://trufflesecurity.com
+Truffle Security website
+.UE .
diff --git a/main.go b/main.go
index d01a5fb50..a73df6c0b 100644
--- a/main.go
+++ b/main.go
@@ -44,7 +44,7 @@ import (
)
var (
- cli = kingpin.New("TruffleHog", "TruffleHog is a tool for finding credentials.")
+ cli = kingpin.New("trufflehog", "TruffleHog is a tool for finding credentials. Run without a command for interactive mode.")
cmd string
// https://github.com/trufflesecurity/trufflehog/blob/main/CONTRIBUTING.md#logging-in-trufflehog
logLevel = cli.Flag("log-level", `Logging verbosity on a scale of 0 (info) to 5 (trace). Can be disabled with "-1".`).Default("0").Int()
@@ -55,7 +55,7 @@ var (
jsonOut = cli.Flag("json", "Output in JSON format.").Short('j').Bool()
jsonLegacy = cli.Flag("json-legacy", "Use the pre-v3.0 JSON format. Only works with git, gitlab, and github sources.").Bool()
gitHubActionsFormat = cli.Flag("github-actions", "Output in GitHub Actions format.").Bool()
- concurrency = cli.Flag("concurrency", "Number of concurrent workers.").Default(strconv.Itoa(runtime.NumCPU())).Int()
+ concurrency = cli.Flag("concurrency", "Number of concurrent workers.").PlaceHolder("N").Int()
noVerification = cli.Flag("no-verification", "Don't verify the results.").Bool()
onlyVerified = cli.Flag("only-verified", "Only output verified results.").Hidden().Bool()
results = cli.Flag("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 verified,unverified,unknown.").String()
@@ -319,6 +319,8 @@ func init() {
cli.HelpFlag.Short('h')
cli.UsageWriter(os.Stdout)
+ registerManPageFlag(cli)
+
// Check if the TUI environment variable is set.
if ok, err := strconv.ParseBool(os.Getenv("TUI_PARENT")); err == nil {
usingTUI = ok
@@ -466,6 +468,10 @@ func run(state overseer.State, logSync func() error) {
os.Setenv("GITHUB_TOKEN", *githubScanToken)
}
+ if *concurrency <= 0 {
+ *concurrency = runtime.NumCPU()
+ }
+
// When setting a base commit, chunks must be scanned in order.
if *gitScanSinceCommit != "" {
*concurrency = 1
diff --git a/manpage.go b/manpage.go
new file mode 100644
index 000000000..986850208
--- /dev/null
+++ b/manpage.go
@@ -0,0 +1,201 @@
+package main
+
+import (
+ "os"
+
+ "github.com/alecthomas/kingpin/v2"
+)
+
+const enhancedManPageTemplate = `{{define "FormatFlags" -}}
+{{range .Flags -}}
+{{if not .Hidden -}}
+.TP
+\fB{{if .Short}}-{{.Short|Char}}, {{end}}--{{.Name}}{{if not .IsBoolFlag}}={{.FormatPlaceHolder}}{{end -}}\fR
+{{.Help}}
+{{end -}}
+{{end -}}
+{{end -}}
+
+{{define "FormatCommand" -}}
+{{if .FlagSummary}} {{.FlagSummary}}{{end -}}
+{{range .Args}}{{if not .Hidden}} {{if not .Required}}[{{end}}{{if .PlaceHolder}}{{.PlaceHolder}}{{else}}<{{.Name}}>{{end}}{{if .Value|IsCumulative}}...{{end}}{{if not .Required}}]{{end}}{{end}}{{end -}}
+{{end -}}
+
+{{define "FormatCommands" -}}
+{{range .FlattenedCommands -}}
+{{if not .Hidden -}}
+.SS
+\fB{{.FullCommand}}{{template "FormatCommand" . -}}\fR
+{{.Help}}
+{{template "FormatFlags" . -}}
+{{end -}}
+{{end -}}
+{{end -}}
+
+{{define "FormatUsage" -}}
+{{template "FormatCommand" .}}{{if .Commands}} <command> [<args> ...]{{end -}}\fR
+{{end -}}
+
+.TH TRUFFLEHOG 1 "" "{{.App.Version}}" "Truffle Security"
+.SH NAME
+trufflehog \- find credentials in various sources
+.SH SYNOPSIS
+.TP
+\fBtrufflehog{{template "FormatUsage" .App}}
+.SH DESCRIPTION
+{{.App.Help}}
+.PP
+TruffleHog scans various data sources for verified and
+unverified secrets such as API keys, passwords, and other
+credentials. It supports scanning git repositories, GitHub
+and GitLab organizations, filesystems, S3 buckets, GCS
+buckets, Docker images, CI/CD systems, and more.
+.PP
+When run without a command in an interactive terminal,
+\fBtrufflehog\fR launches a TUI (text user interface) that
+guides you through selecting a scan source and configuring
+options.
+.SH OPTIONS
+{{template "FormatFlags" .App -}}
+{{if .App.Commands -}}
+.SH COMMANDS
+{{template "FormatCommands" .App -}}
+{{end -}}
+.SH "EXIT STATUS"
+.TP
+.B 0
+Successful execution.
+.TP
+.B 183
+Credentials were found and \fB\-\-fail\fR was specified.
+.TP
+.B 1
+An error occurred during scanning.
+.SH EXAMPLES
+.TP
+.B Launch the interactive TUI
+.EX
+trufflehog
+.EE
+.TP
+.B Scan a git repository
+.EX
+trufflehog git https://github.com/example/repo.git
+.EE
+.TP
+.B Scan a GitHub organization
+.EX
+trufflehog github \-\-org=trufflesecurity \-\-token=$GITHUB_TOKEN
+.EE
+.TP
+.B Scan a local filesystem
+.EX
+trufflehog filesystem /path/to/directory
+.EE
+.TP
+.B Scan an S3 bucket
+.EX
+trufflehog s3 \-\-bucket=my\-bucket \-\-cloud\-environment
+.EE
+.TP
+.B Scan a Docker image
+.EX
+trufflehog docker \-\-image=myregistry/myimage:latest
+.EE
+.TP
+.B Read from stdin
+.EX
+cat secrets.txt | trufflehog stdin
+.EE
+.TP
+.B Output JSON and filter with jq
+.EX
+trufflehog git https://github.com/example/repo.git \-\-json \e
+ | jq 'select(.Verified == true)'
+.EE
+.TP
+.B Fail in CI if secrets are found
+.EX
+trufflehog git file://. \-\-fail \-\-results=verified,unknown
+.EE
+.TP
+.B Use a configuration file
+.EX
+trufflehog git https://github.com/example/repo.git \e
+ \-\-config=trufflehog\-config.yaml
+.EE
+.SH ENVIRONMENT
+.TP
+.B GITHUB_TOKEN
+Authentication token for GitHub scanning.
+.TP
+.B GITLAB_TOKEN
+Authentication token for GitLab scanning.
+.TP
+.B AWS_ACCESS_KEY_ID
+AWS access key for S3 scanning.
+.TP
+.B AWS_SECRET_ACCESS_KEY
+AWS secret key for S3 scanning.
+.TP
+.B AWS_SESSION_TOKEN
+AWS session token for temporary credentials.
+.TP
+.B GOOGLE_CLOUD_PROJECT
+GCP project ID for GCS scanning.
+.TP
+.B GOOGLE_API_KEY
+GCP API key for GCS scanning.
+.TP
+.B CIRCLECI_TOKEN
+Authentication token for CircleCI scanning.
+.TP
+.B DOCKER_TOKEN
+Authentication token for Docker scanning.
+.TP
+.B TRAVISCI_TOKEN
+Authentication token for TravisCI scanning.
+.TP
+.B POSTMAN_TOKEN
+Authentication token for Postman scanning.
+.TP
+.B HUGGINGFACE_TOKEN
+Authentication token for HuggingFace scanning.
+.TP
+.B ELASTICSEARCH_NODES
+Comma-separated list of Elasticsearch nodes.
+.TP
+.B JENKINS_URL
+URL of the Jenkins server.
+.SH FILES
+.TP
+.I trufflehog\-config.yaml
+Optional configuration file specified via \fB\-\-config\fR.
+See the project documentation for the configuration
+file format.
+.SH BUGS
+Report bugs at
+.UR https://github.com/trufflesecurity/trufflehog/issues
+the TruffleHog issue tracker
+.UE .
+.SH "SEE ALSO"
+.UR https://github.com/trufflesecurity/trufflehog
+TruffleHog on GitHub
+.UE ,
+.UR https://trufflesecurity.com
+Truffle Security website
+.UE .
+`
+
+func registerManPageFlag(app *kingpin.Application) {
+ app.Flag("generate-man-page", "Generate man page.").
+ Hidden().
+ PreAction(func(c *kingpin.ParseContext) error {
+ app.Writer(os.Stdout)
+ if err := app.UsageForContextWithTemplate(c, 2, enhancedManPageTemplate); err != nil {
+ return err
+ }
+ os.Exit(0)
+ return nil
+ }).Bool()
+}