Find, verify, and analyze leaked credentials
HuggingFace Source
Overview
The HuggingFace source lets TruffleHog scan HuggingFace models, spaces, datasets, and buckets for secrets, credentials, and sensitive data. It uses the HuggingFace API to find repositories, then clones and scans each one with the git source underneath. Buckets are handled differently since they are plain file storage, not git repositories.
HuggingFace Fundamentals
What does this source scan?
This source finds models, spaces, and datasets through the HuggingFace API (by an explicit list, or by organization and user), then clones and scans each one the same way the git source does. Buckets are found the same way but are downloaded and scanned file by file instead of being cloned, since they are not git repositories.
Key HuggingFace Terminology
| Term | Description |
|---|---|
| Model | A trained machine learning model hosted on HuggingFace, stored as a git repository |
| Space | An application or demo hosted on HuggingFace, stored as a git repository |
| Dataset | A collection of data hosted on HuggingFace, stored as a git repository |
| Bucket | Plain object storage hosted on HuggingFace, not a git repository |
| Organization | A HuggingFace account that holds models, spaces, datasets, and buckets owned by a team |
| Discussion | A conversation thread attached to a model, space, or dataset |
Features
- Multiple Scan Targets: Scan models, spaces, datasets, and buckets, by an explicit list or by organization and user
- Multiple Authentication Methods: Personal access token, or unauthenticated for public repositories
- Repository Filtering: Include or exclude models, spaces, datasets, and buckets using glob patterns, or skip an entire resource type
- Discussion and Pull Request Scanning: Optionally scan the comments on discussions and pull requests
- Concurrent Processing: Repositories and bucket files are cloned, downloaded, and scanned in parallel across a configurable number of workers
Configuration
Note: as of this writing, pkg/config/config.go does not have a case for SOURCE_TYPE_HUGGINGFACE in its source loader, so a YAML --config file cannot be used for HuggingFace. Use the CLI flags or environment variable below instead.
Authentication Methods
1. Personal Access Token
CLI Usage:
trufflehog huggingface --org my-org --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
The token can also be set with the HUGGINGFACE_TOKEN environment variable instead of --token.
2. Unauthenticated
Only works for public models, spaces, datasets, and buckets.
CLI Usage:
trufflehog huggingface --org my-org
Choosing What to Scan
At least one of --org, --user, --model, --space, --dataset, or --bucket must be given.
Scan an Organization or User
trufflehog huggingface --org my-org --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
trufflehog huggingface --user my-user --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
This finds every model, space, dataset, and bucket owned by the organization or user. Use --skip-all-models, --skip-all-spaces, --skip-all-datasets, or --skip-all-buckets to leave out a whole resource type.
trufflehog huggingface --org my-org --skip-all-buckets --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Scan Specific Models, Spaces, Datasets, or Buckets
trufflehog huggingface --model my-org/my-model --space my-org/my-space --dataset my-org/my-dataset --bucket my-org/my-bucket --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Each of these flags can be repeated, and each name should be in owner/name form so TruffleHog can build the right URL for it. Unlike --include-* and --ignore-*, TruffleHog does not check this format for --model, --space, --dataset, or --bucket themselves, a name without a slash just produces a broken URL later instead of a clear error. When a model, space, dataset, or bucket is given directly this way, --include-* and --ignore-* filters are not applied to it.
Filtering What Gets Scanned
Include or Exclude Models, Spaces, Datasets, or Buckets
These only apply when scanning with --org or --user, not to resources given directly with --model, --space, --dataset, or --bucket. Each name must be in owner/name form, and can also be a glob pattern.
trufflehog huggingface --org my-org --include-models "my-org/prod-*" --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
trufflehog huggingface --org my-org --ignore-datasets "my-org/test-*" --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
The same pattern works for --include-spaces, --ignore-spaces, --include-buckets, and --ignore-buckets.
Number of Workers
There is no HuggingFace specific flag for this. Use TruffleHog's global --concurrency flag to set how many repositories and bucket files are processed at the same time.
trufflehog huggingface --org my-org --concurrency 10 --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Scanning Discussions and Pull Requests
trufflehog huggingface --org my-org --include-discussions --include-prs --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Only the comments on a discussion or pull request are scanned, there is no separate description text to scan.
Self Hosted Endpoint
trufflehog huggingface --org my-org --endpoint https://huggingface.mycompany.com --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
How Scanning Works
Scanning Process
- Enumeration: Lists models, spaces, datasets, and buckets from the given organizations and users, applying the include and exclude filters, then adds any models, spaces, datasets, and buckets given directly
- Model, Space, and Dataset Cloning: Clones each one using the git source, the same way the git source scans a remote repository
- Commit Scanning: Scans every commit in the clone for secrets, the same way the git source does, then deletes the clone
- Bucket File Listing: For each bucket, lists its files, skipping anything larger than 250MB
- Bucket File Scanning: Downloads each remaining bucket file and scans its contents directly, without cloning
- Discussion Scanning: If
--include-discussionsor--include-prsis set, fetches discussions and pull requests for each model, space, and dataset and scans their comments - Progress Tracking: Keeps track of which models, spaces, and datasets have already been scanned, so a scan can be resumed without redoing work
What Gets Scanned
- Every commit in every model, space, and dataset matching the scan target and filters
- Files in every bucket matching the scan target and filters, up to 250MB in size
- Comments on discussions and pull requests, when
--include-discussionsor--include-prsis set
What Doesn't Get Scanned
- An entire resource type, when its
--skip-all-*flag is set - Models, spaces, datasets, or buckets excluded by an
--include-*or--ignore-*filter, for an organization or user scan - Bucket files larger than 250MB
- Discussion and pull request descriptions, only their comments are scanned
Usage Examples
Scanning an Organization
trufflehog huggingface --org my-org --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Scanning a Specific Model
trufflehog huggingface --model my-org/my-model --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Scanning an Organization's Datasets Only
trufflehog huggingface --org my-org --skip-all-models --skip-all-spaces --skip-all-buckets --token hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Scanning a Public Model Without Authentication
trufflehog huggingface --model my-org/public-model
Troubleshooting
Common Issues
Issue: invalid config: you must specify at least one organization, user, model, space, dataset or bucket
Solution: Pass at least one of --org, --user, --model, --space, --dataset, or --bucket.
Issue: invalid owner/repo: <name>
Solution: A value passed to --include-models, --ignore-models, or any of the other include and ignore flags is not in owner/name form. TruffleHog checks this for the include and ignore flags only, not for --model, --space, --dataset, or --bucket themselves.
Issue: invalid API key
Solution: Check that the token is correct. This also appears if a token is required but was left out.
Issue: access to this repo is restricted and you are not in the authorized list
Solution: The authenticated account, or an unauthenticated request, does not have permission to read this model, space, or dataset. Request access on HuggingFace first.