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 [] [ ...]\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 [...]\fR +Show help. +.SS +\fBgit [] \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 []\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 []\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//.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 []\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 [] [...]\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 []\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 []\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 []\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 []\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 []\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 []\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 []\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 []\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 [...]\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}} [ ...]{{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() +}