TruffleHog
Application Security- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The TruffleHog Enterprise Connector integrates with the TruffleHog Enterprise / API platform to fetch and synchronize secret scanning data, including sources, detected secrets, and secret occurrences. It maps these external objects into the internal Unified Data Model (UDM) to enable comprehensive sensitivity analysis, automated remediation, and security posture management.
Data retrieved from TruffleHog Enterprise
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Source | Yes | Cloud Resource |
| Secret | Yes | Violation |
| Secret Definition | Yes | Violation Definition |
Model relationships
For detailed steps on how to view the data retrieved from TruffleHog Enterprise in the Brinqa Platform, see How to view your data.
Connection settings
When setting up a data integration, select TruffleHog Enterprise from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| Server URL | Yes | https://<instance>.trufflehog.com/ | TruffleHog API base URL |
| API key | Yes | — | API key for authenticating requests |
| API secret | Yes | — | API secret for authenticating requests |
| Page size | No | 100 | Maximum number of records to get per API request |
| Maximum retries | No | 5 | Maximum number of retry attempts before giving up a request |
Authentication
The connector authenticates with the TruffleHog API using API key and secret authentication. There is no token-exchange or session step: the API key and secret are static credentials that are sent as request headers on every API call. Connectivity and credentials are validated by issuing a request against the sources endpoint.
Endpoint
| Method | URL | Purpose |
|---|---|---|
GET | api/v1/sources | Validate credentials / test connectivity |
Request Headers
| Header | Value | Description |
|---|---|---|
X-Thog-Key | <thog-key> | API key from connector configuration |
X-Thog-Secret | <thog-secret> | API secret from connector configuration |
Content-Type | application/json | Request content type |
Request Body
No request body is required. The credentials are supplied entirely through the request headers above.
Sample Response
{
"data": [
{
"id": 1,
"name": "example-github-source",
"last_completed": "2026-06-01T12:00:00Z"
}
],
"next": null,
"last_page": 1
}
Response Fields
| Field | Type | Description |
|---|---|---|
data | Array | List of resource objects returned by the endpoint |
next | String | URL/cursor for the next page, or null when none remain |
last_page | Integer | Index of the last available page |
Credential Usage in Subsequent Requests
A successful response (HTTP 2xx) confirms the credentials are valid. The same X-Thog-Key and X-Thog-Secret headers are attached to every subsequent request (sources, secrets, and secret locations); no bearer token or session cookie is issued or stored.
Sync Behavior
The connector performs a mix of full and incremental (delta) syncs depending on the model. Models that support delta filter by the sync token (see each model's Sync Duration Parameter below); the rest perform a full sync every run.
How to obtain TruffleHog Enterprise credentials
Obtain the required credentials (url, apiKey, apiSecret) from your TruffleHog Enterprise administrator or the TruffleHog Enterprise admin console, then enter them in the connection settings above.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes:
Source
| Source Field Name | SDM Attribute |
|---|---|
active | SOURCE_STATUS |
| Cloud Resource | CATEGORIES |
Source.id | UID |
Source.last_completed | LAST_COMPLETED |
Source.name or Source.id | NAME |
| sync time | LAST_CAPTURED |
| UNKNOWN | PROVIDER_STATUS |
Secret
| Source Field Name | SDM Attribute |
|---|---|
Secret.analyze_id | ANALYZE_ID |
Secret.analyzer_type | ANALYZER_TYPE |
Secret.created_date | CREATED_DATE |
Secret.created_date | SOURCE_CREATED_DATE |
Secret.date_rotated | DATE_ROTATED |
Secret.distinct_source_names | DISTINCT_SOURCE_NAMES |
Secret.distinct_source_types | DISTINCT_SOURCE_TYPES |
Secret.id | UID |
Secret.last_seen | LAST_SEEN |
Secret.last_verified | LAST_VERIFIED |
Secret.modified_date | MODIFIED_DATE |
Secret.modified_date | SOURCE_LAST_MODIFIED |
Secret.redacted | REDACTED |
Secret.secret_locations_count | LOCATIONS_COUNT |
Secret.secret_type | SECRET_TYPE |
Secret.secret_type | CATEGORIES |
Secret.secret_type | TYPE |
Secret.secret_type or Secret.id | NAME |
Secret.triage_state | TRIAGE_STATE |
Secret.triage_state (normalized) or active | SOURCE_STATUS |
Secret.triage_state or UNKNOWN | PROVIDER_STATUS |
Secret.user_defined | IS_USER_DEFINED |
Secret.verification_error_message | VERIFICATION_ERROR_MESSAGE |
Secret.verified | IS_VERIFIED |
SecretAnalyze.permissions | PERMISSIONS |
SecretLocation[].account_name | RESULTS |
SecretLocation[].azure_container | RESULTS |
SecretLocation[].bucket | RESULTS |
SecretLocation[].build_number | RESULTS |
SecretLocation[].build_step | RESULTS |
SecretLocation[].channel_identifier | RESULTS |
SecretLocation[].channel_name | RESULTS |
SecretLocation[].channel_visibility | RESULTS |
SecretLocation[].commit | RESULTS |
SecretLocation[].created_date | RESULTS |
SecretLocation[].decoder_type | RESULTS |
SecretLocation[].email | RESULTS |
SecretLocation[].extra_data | RESULTS |
SecretLocation[].file_name | RESULTS |
SecretLocation[].image_name | RESULTS |
SecretLocation[].issue | RESULTS |
SecretLocation[].layer_hash | RESULTS |
SecretLocation[].line | RESULTS |
SecretLocation[].link | RESULTS |
SecretLocation[].location | RESULTS |
SecretLocation[].location_metadata | RESULTS |
SecretLocation[].modified_date | RESULTS |
SecretLocation[].org | RESULTS |
SecretLocation[].package_name | RESULTS |
SecretLocation[].page | RESULTS |
SecretLocation[].pipeline | RESULTS |
SecretLocation[].project_name | RESULTS |
SecretLocation[].region | RESULTS |
SecretLocation[].registry | RESULTS |
SecretLocation[].release_name | RESULTS |
SecretLocation[].repository | RESULTS |
SecretLocation[].snippet_id | RESULTS |
SecretLocation[].source.id | TARGETS |
SecretLocation[].source.name | RESULTS |
SecretLocation[].source.type | RESULTS |
SecretLocation[].space | RESULTS |
SecretLocation[].tag | TAGS |
SecretLocation[].tag | RESULTS |
SecretLocation[].timestamp | RESULTS |
SecretLocation[].title | RESULTS |
SecretLocation[].user_id | RESULTS |
SecretLocation[].username | RESULTS |
SecretLocation[].vcs_type | RESULTS |
SecretLocation[].version | RESULTS |
SecretLocation[].workspace_name | RESULTS |
| sync time | LAST_CAPTURED |
Secret Definition
| Source Field Name | SDM Attribute |
|---|---|
Secret.rotation_guide | RECOMMENDATION |
Secret.rotation_guide | ROTATION_GUIDE |
Secret.secret_type | UID |
Secret.secret_type | NAME |
| sync time | LAST_CAPTURED |
Operations & API
Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).
Source
Operation options
This object does not support any operation options.
Delta sync
Not supported. The connector performs a full sync of Source on every run and applies no incremental date filter.
API
- Type: REST endpoint · Endpoint:
GET api/v1/sources
Secret
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
verified | Boolean | — | Filter secrets by verified status (true/false) |
triage_state | String | — | Filter secrets by triage state ("UNTRIAGED"/"FALSE_POSITIVE/"RESOLVED"/"WILL_NOT_FIX") |
secret_type | String | — | Filter secrets by secret type |
date_rotated_isnull | Boolean | — | Filter secrets by rotation status (true = non-rotated, false = rotated) |
fetch_secret_permissions | Boolean | false | Fetch permissions for each secret via the Analyze API and populate PERMISSIONS |
Delta sync
Supported. The connector performs an incremental (delta) sync via the last_seen_after sync token, filtering on last_seen.
API
- Type: REST endpoint · Endpoint:
GET api/v2/secrets - Default filters:
last_seen_after(applied when asincetimestamp is available)
Secret Definition
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
verified | Boolean | — | Filter secrets by verified status (true/false) |
triage_state | String | — | Filter secrets by triage state ("UNTRIAGED"/"FALSE_POSITIVE/"RESOLVED"/"WILL_NOT_FIX") |
secret_type | String | — | Filter secrets by secret type |
date_rotated_isnull | Boolean | — | Filter secrets by rotation status (true = non-rotated, false = rotated) |
Delta sync
Supported. The connector performs an incremental (delta) sync via the last_seen_after sync token, filtering on last_seen.
API
- Type: REST endpoint · Endpoint:
GET api/v2/secrets - Default filters:
last_seen_after(applied when asincetimestamp is available)
Changelog
The TruffleHog Enterprise connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.0.4 | New Features - Secrets can now be enriched with the permissions granted by their exposed credentials. When the new fetch_secret_permissions option is enabled, the connector calls the TruffleHog Analyze API for each detected secret and records the resulting permissions on the Secret model. - Added a multi-valued PERMISSIONS attribute on the Secret model that lists the permissions associated with each secret. - Added the fetch_secret_permissions operation option (Boolean, default false) on the Secret model to turn permission enrichment on or off. Improvements - The Secret ANALYZE_ID attribute is now stored as an integer to match the value returned by the TruffleHog API. | • Secret: ANALYZE_ID data type changed from String to Integer — Action: re-sync |
| 3.0.3 | New Features - Added date_rotated_isnull operation-level filter to allow filtering secrets and secret definitions by rotation status — set to true to retrieve only non-rotated secrets, or false to retrieve only rotated secrets | N/A |
| 3.0.2 | Improvements - The last_seen_after timestamp and operation-level filters are now forwarded to the Secret Locations API, ensuring consistent filtering across secret and secret-location fetches - Added null-safe deserialization in TruffleHogModel.deserializeListResource; when the API returns a null response body or null data array, the connector now returns an empty ApiResponse instead of propagating a NullPointerException Dependency Upgrades - Upgraded parent POM ( http-connectors-parent) from 2.1.11 to 2.1.12 - Upgraded connectors-model from 1.6.15 to 1.6.19 | N/A |
| 3.0.1 | Improvements - Secret locations are now fetched per-secret using the secret__id filter parameter, replacing the previous bulk-fetch approach for more targeted and efficient API usage - The connector display name has been updated from TruffleHog to TruffleHog Enterprise; no new integration is required—just update the version in the existing integration | N/A |
| 3.0.0 | New Features Source Inventory Support Added a new Source asset model for discovering and tracking source resources (repositories, buckets, and other scan targets) from TruffleHog. Sources are mapped to the CloudResource UDM model with full support for unique identification, naming, and last-completed scan timestamps. Secret Finding Detection Added a new Secret finding model that syncs detected secret findings from TruffleHog's scanning engine. - Secrets are mapped to the Violation UDM model with comprehensive attribute coverage including triage state, secret type categorization, and creation/modification timestamps. - Each secret includes detailed location information (file name, line number, commit hash) fetched from the Secret Locations API. - Secrets are automatically linked to their parent Source assets via the TARGETS attribute. Secret Definition Support Added a new SecretDefinition model that derives metadata and remediation guidance for each type of secret. - Secret Definitions are mapped to the ViolationDefinition UDM model, providing a correlation layer between individual findings and their type. - Includes rotation guide recommendations sourced directly from TruffleHog to assist with remediation workflows. - Deduplicated across sync runs using SpeedB-backed local store caching. Incremental Sync Full support for SyncToken-based delta synchronization using last_seen_after timestamp filtering directly at the source. Only new or recently seen secrets are fetched on subsequent syncs, reducing API usage and improving sync performance in large environments. Operation-Level Filtering Filter secret and secret definition syncs directly at the source using configurable operation options: - verified — Filter secrets by their verified status. (possible values - true or false) - triage_state — Filter secrets by triage state (possible values - UNTRIAGED or FALSE_POSITIVE or RESOLVED or WILL_NOT_FIX). - secret_type — Filter secrets by secret type for targeted data collection. Custom Header Authentication Authentication is handled via custom API headers ( X-Thog-Key and X-Thog-Secret), supporting TruffleHog's native key/secret authentication scheme without relying on basic auth. Configurable Pagination Page size is configurable up to a maximum of 250 results per page (default 100), with cursor-based pagination for seamless traversal of large result sets. Retry Resilience Configurable maximum retry attempts (default 5) for transient API failures, ensuring reliable data synchronization in unstable network conditions. | N/A |