GitGuardian
Application Security- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The GitGuardian Connector integrates with the GitGuardian secrets detection platform to synchronize security findings, source repositories, and incident definitions. It connects to the GitGuardian REST API (v1) to fetch secret incidents, source repositories, and detector-based incident definitions. A public secret incident model is also defined for future use but is not currently synchronized.
Data retrieved from GitGuardian
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Source | Yes | Code Repository |
| Secret Incident | Yes | Incident |
| Public Secret Incident | Yes | Incident |
| Secret Incident Definition | Yes | Incident Definition |
Model relationships
For detailed steps on how to view the data retrieved from GitGuardian in the Brinqa Platform, see How to view your data.
Connection settings
When setting up a data integration, select GitGuardian from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| API URL | Yes | https://api.gitguardian.com | GitGuardian API URL |
| API Key | Yes | — | GitGuardian API key |
| Page Size | No | 100 | Number of results per API request page (default: 100) |
| Max retries | No | 10 | Specifies the maximum number of retries permitted during a request. The default value is 10. |
Authentication
The connector uses a static API token to authenticate with the GitGuardian API. GitGuardian API tokens do not expire and are user-provided through the workspace configuration.
Endpoint
| Method | URL |
|---|---|
GET | https://api.gitguardian.com/v1/health |
Request Headers
| Header | Value |
|---|---|
Authorization | Token <api-token> |
Accept | application/json |
Request Body
None. The token is supplied via the Authorization header; no request body is sent.
Sample Response (GET /v1/health)
{
"detail": "Valid API key."
}
| Field | Description |
|---|---|
detail | Human-readable status message confirming the API key is valid |
Usage
All API requests include the token in the Authorization header:
Authorization: Token <api-token>
How to obtain GitGuardian credentials
Generate GitGuardian API keys
For the GitGuardian connector to access the GitGuardian API, you must provide an API key. GitGuardian supports two types of API keys: service accounts and personal access tokens. To use the connector, you need to create a personal access token. To do so, follow these steps:
-
Log in to your GitGuardian workspace.
-
Navigate to API > Personal access tokens and click Create token.
-
Name your token and optionally set an expiry date.
-
Under Scope, select at minimum the following permissions: Scan, Incidents:read, and Sources:read. Selecting broader permissions that include these scopes also works.
-
Click Create token and copy the generated API key. Store it in a secure location, as it cannot be viewed again.
Note: The Sources:read scope is only available to accounts with Manager or Owner role and may not be visible to member accounts. If you do not have the required role, contact your GitGuardian administrator. For additional information, see GitGuardian documentation.
GitGuardian uses a Token scheme (not Bearer). API tokens are generated from the GitGuardian dashboard and do not have an expiration — they remain valid until revoked.
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 |
|---|---|
LastScanResource.branchesScanned | LAST_SCAN_BRANCHES_SCANNED |
LastScanResource.commitsScanned | LAST_SCAN_COMMITS_SCANNED |
LastScanResource.date | LAST_SCAN_DATE |
LastScanResource.duration | LAST_SCAN_DURATION |
LastScanResource.failingReason | LAST_SCAN_FAILING_REASON |
LastScanResource.progress | LAST_SCAN_PROGRESS |
LastScanResource.status | LAST_SCAN_STATUS |
SecretIncidentsBreakdownResource.closedSecretIncidents.total | CLOSED_INCIDENTS_TOTAL |
SecretIncidentsBreakdownResource.openSecretIncidents.total | OPEN_INCIDENTS_TOTAL |
SeverityBreakdownResource.critical (closed) | CLOSED_INCIDENTS_CRITICAL |
SeverityBreakdownResource.critical (open) | OPEN_INCIDENTS_CRITICAL |
SeverityBreakdownResource.high (closed) | CLOSED_INCIDENTS_HIGH |
SeverityBreakdownResource.high (open) | OPEN_INCIDENTS_HIGH |
SeverityBreakdownResource.info (closed) | CLOSED_INCIDENTS_INFO |
SeverityBreakdownResource.info (open) | OPEN_INCIDENTS_INFO |
SeverityBreakdownResource.low (closed) | CLOSED_INCIDENTS_LOW |
SeverityBreakdownResource.low (open) | OPEN_INCIDENTS_LOW |
SeverityBreakdownResource.medium (closed) | CLOSED_INCIDENTS_MEDIUM |
SeverityBreakdownResource.medium (open) | OPEN_INCIDENTS_MEDIUM |
SeverityBreakdownResource.unknown (closed) | CLOSED_INCIDENTS_UNKNOWN |
SeverityBreakdownResource.unknown (open) | OPEN_INCIDENTS_UNKNOWN |
SourceResource.closedIncidentsCount | CLOSED_INCIDENTS_COUNT |
SourceResource.defaultBranch | DEFAULT_BRANCH |
SourceResource.defaultBranchHead | DEFAULT_BRANCH_HEAD |
SourceResource.deleted | DELETED |
SourceResource.externalId | EXTERNAL_ID |
SourceResource.fullName | NAME |
SourceResource.health | HEALTH |
SourceResource.id | UID |
SourceResource.monitored | MONITORED |
SourceResource.openIncidentsCount | OPEN_INCIDENTS_COUNT |
SourceResource.sourceCriticality | SOURCE_CRITICALITY |
SourceResource.type | SOURCE_TYPE |
SourceResource.url | URL |
SourceResource.visibility | VISIBILITY |
| — | STATUS |
| — | CATEGORIES |
| — | TAGS |
| — | LAST_CAPTURED |
Secret Incident
| Source Field Name | SDM Attribute |
|---|---|
CustomTagResource.key | CUSTOM_TAG_KEYS |
CustomTagResource.value | CUSTOM_TAG_VALUES |
DestinationTicketResource.id | DESTINATION_TICKET_IDS |
DestinationTicketResource.link | DESTINATION_TICKET_LINKS |
DestinationTicketResource.type | DESTINATION_TICKET_TYPES |
FeedbackResource.email | FEEDBACK_EMAILS |
IncidentResource.assigneeEmail | ASSIGNEE_EMAIL |
IncidentResource.assigneeId | ASSIGNEE_ID |
IncidentResource.date | SOURCE_CREATED_DATE |
IncidentResource.detector.detectorGroupName | TYPE |
IncidentResource.gitguardianUrl | URL |
IncidentResource.gitguardianUrl | GITGUARDIAN_URL |
IncidentResource.hmslHash | HMSL_HASH |
IncidentResource.id | INCIDENT_ID |
IncidentResource.ignoredAt | IGNORED_AT |
IncidentResource.ignorerApiTokenId | IGNORER_API_TOKEN_ID |
IncidentResource.ignoreReason | IGNORE_REASON |
IncidentResource.ignorerId | IGNORER_ID |
IncidentResource.incidentName | INCIDENT_NAME |
IncidentResource.isVaulted | IS_VAULTED |
IncidentResource.occurrencesCount | OCCURRENCES_COUNT |
IncidentResource.regression | REGRESSION |
IncidentResource.resolvedAt | LAST_FIXED |
IncidentResource.resolvedAt | RESOLVED_AT |
IncidentResource.resolverApiTokenId | RESOLVER_API_TOKEN_ID |
IncidentResource.resolverId | RESOLVER_ID |
IncidentResource.riskScore | RISK_SCORE |
IncidentResource.secretHash | SECRET_HASH |
IncidentResource.secretId | SECRET_ID |
IncidentResource.secretRevoked | SECRET_REVOKED |
IncidentResource.shareUrl | SHARE_URL |
IncidentResource.status | PROVIDER_STATUS |
IncidentResource.status | SOURCE_STATUS |
IncidentResource.status | STATUS |
IncidentResource.status | STATUS_CATEGORY |
IncidentResource.tags | TAGS |
IncidentResource.triggeredAt | FIRST_FOUND |
IncidentResource.triggeredAt | TRIGGERED_AT |
IncidentResource.validity | VALIDITY |
MatchResource.name | MATCH_NAMES |
OccurrenceResource.authorInfo | AUTHOR_INFO |
OccurrenceResource.authorName | AUTHOR_NAME |
OccurrenceResource.changeType | CHANGE_TYPE |
OccurrenceResource.filepath | FILEPATH |
OccurrenceResource.id | UID |
OccurrenceResource.kind | KIND |
OccurrenceResource.presence | PRESENCE |
OccurrenceResource.sha | SHA |
OccurrenceResource.source.fullName | SOURCE_NAME |
OccurrenceResource.source.id | TARGETS |
OccurrenceResource.url | OCCURRENCE_URL |
PublicExposureResource.leakedOutsidePerimeter | LEAKED_OUTSIDE_PERIMETER |
PublicExposureResource.publicIncidentLinked | PUBLIC_INCIDENT_LINKED |
PublicExposureResource.sourcePubliclyVisible | SOURCE_PUBLICLY_VISIBLE |
SecretPresenceResource.filesFixed | FILES_FIXED |
SecretPresenceResource.filesPendingMerge | FILES_PENDING_MERGE |
SecretPresenceResource.filesRequiringCodeFix | FILES_REQUIRING_CODE_FIX |
SecretPresenceResource.inVcs | IN_VCS |
SecretPresenceResource.outsideVcs | OUTSIDE_VCS |
SecretPresenceResource.removedInVcs | REMOVED_IN_VCS |
SecretPresenceResource.removedOutsideVcs | REMOVED_OUTSIDE_VCS |
| — | LAST_CAPTURED |
TYPE is the UUID5 hash of the incident's detector group name, linking each finding to its Secret Incident Definition. STATUS/SOURCE_STATUS/STATUS_CATEGORY are derived from the normalized incident status (see Status Mapping).
Public Secret Incident
| Source Field Name | SDM Attribute |
|---|---|
"public-" + OccurrenceResource.id | UID |
CustomTagResource.key | CUSTOM_TAG_KEYS |
CustomTagResource.value | CUSTOM_TAG_VALUES |
DestinationTicketResource.id | DESTINATION_TICKET_IDS |
DestinationTicketResource.link | DESTINATION_TICKET_LINKS |
DestinationTicketResource.type | DESTINATION_TICKET_TYPES |
FeedbackResource.email | FEEDBACK_EMAILS |
MatchResource.name | MATCH_NAMES |
OccurrenceResource.actor | ACTORS |
OccurrenceResource.attachmentReasons | ATTACHMENT_REASONS |
OccurrenceResource.filepath | FILEPATH |
OccurrenceResource.kind | KIND |
OccurrenceResource.presence | PRESENCE |
OccurrenceResource.sha | SHA |
OccurrenceResource.source.fullName | SOURCE_NAME |
OccurrenceResource.source.id | TARGETS |
OccurrenceResource.url | OCCURRENCE_URL |
PublicExposureResource.leakedOutsidePerimeter | LEAKED_OUTSIDE_PERIMETER |
PublicExposureResource.publicIncidentLinked | PUBLIC_INCIDENT_LINKED |
PublicExposureResource.sourcePubliclyVisible | SOURCE_PUBLICLY_VISIBLE |
PublicIncidentResource.assigneeEmail | ASSIGNEE_EMAIL |
PublicIncidentResource.assigneeId | ASSIGNEE_ID |
PublicIncidentResource.date | SOURCE_CREATED_DATE |
PublicIncidentResource.declarativeSecretStatus | DECLARATIVE_SECRET_STATUS |
PublicIncidentResource.detector.detectorGroupName | TYPE |
PublicIncidentResource.gitguardianUrl | URL |
PublicIncidentResource.gitguardianUrl | GITGUARDIAN_URL |
PublicIncidentResource.hmslHash | HMSL_HASH |
PublicIncidentResource.id | INCIDENT_ID |
PublicIncidentResource.ignoredAt | IGNORED_AT |
PublicIncidentResource.ignorerApiTokenId | IGNORER_API_TOKEN_ID |
PublicIncidentResource.ignoreReason | IGNORE_REASON |
PublicIncidentResource.ignorerId | IGNORER_ID |
PublicIncidentResource.incidentName | INCIDENT_NAME |
PublicIncidentResource.isVaulted | IS_VAULTED |
PublicIncidentResource.occurrencesCount | OCCURRENCES_COUNT |
PublicIncidentResource.regression | REGRESSION |
PublicIncidentResource.resolvedAt | LAST_FIXED |
PublicIncidentResource.resolvedAt | RESOLVED_AT |
PublicIncidentResource.resolverApiTokenId | RESOLVER_API_TOKEN_ID |
PublicIncidentResource.resolveReason | RESOLVE_REASON |
PublicIncidentResource.resolverId | RESOLVER_ID |
PublicIncidentResource.riskScore | RISK_SCORE |
PublicIncidentResource.secretHash | SECRET_HASH |
PublicIncidentResource.secretId | SECRET_ID |
PublicIncidentResource.secretRevoked | SECRET_REVOKED |
PublicIncidentResource.shareUrl | SHARE_URL |
PublicIncidentResource.status | PROVIDER_STATUS |
PublicIncidentResource.status | SOURCE_STATUS |
PublicIncidentResource.status | STATUS |
PublicIncidentResource.status | STATUS_CATEGORY |
PublicIncidentResource.tags | TAGS |
PublicIncidentResource.triggeredAt | FIRST_FOUND |
PublicIncidentResource.triggeredAt | TRIGGERED_AT |
PublicIncidentResource.validity | VALIDITY |
SecretPresenceResource.filesFixed | FILES_FIXED |
SecretPresenceResource.filesPendingMerge | FILES_PENDING_MERGE |
SecretPresenceResource.filesRequiringCodeFix | FILES_REQUIRING_CODE_FIX |
SecretPresenceResource.inVcs | IN_VCS |
SecretPresenceResource.outsideVcs | OUTSIDE_VCS |
SecretPresenceResource.removedInVcs | REMOVED_IN_VCS |
SecretPresenceResource.removedOutsideVcs | REMOVED_OUTSIDE_VCS |
| — | LAST_CAPTURED |
This model is defined in the connector but is not currently registered for synchronization — it is reserved for a future release. The attribute mapping below describes the model as implemented.
Secret Incident Definition
| Source Field Name | SDM Attribute |
|---|---|
DetectorResource.detectorGroupDisplayName | DETECTOR_GROUP_DISPLAY_NAME |
DetectorResource.detectorGroupName | DETECTOR_GROUP_NAME |
DetectorResource.family | DETECTOR_FAMILY |
DetectorResource.nature | DETECTOR_NATURE |
IncidentResource.severity | SEVERITY |
IncidentResource.severity | SOURCE_SEVERITY |
IncidentResource.severity | SEVERITY_SCORE |
IncidentResource.tags | TAGS |
SecretDetectorResource.category | CATEGORIES |
SecretDetectorResource.checkable | CHECKABLE |
SecretDetectorResource.displayName | NAME |
SecretDetectorResource.displayName | DETECTOR_DISPLAY_NAME |
SecretDetectorResource.frequency | FREQUENCY |
SecretDetectorResource.ignoredIncidentsCount | IGNORED_INCIDENTS_COUNT |
SecretDetectorResource.isActive | IS_ACTIVE |
SecretDetectorResource.isRecommendedForBusiness | IS_RECOMMENDED_FOR_BUSINESS |
SecretDetectorResource.name | UID |
SecretDetectorResource.name | DETECTOR_NAME |
SecretDetectorResource.openIncidentsCount | OPEN_INCIDENTS_COUNT |
SecretDetectorResource.removedAt | REMOVED_AT |
SecretDetectorResource.resolvedIncidentsCount | RESOLVED_INCIDENTS_COUNT |
SecretDetectorResource.scansCodeOnly | SCANS_CODE_ONLY |
SecretDetectorResource.type | DETECTOR_TYPE |
| — | 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:
GET /v1/sources - Default filters: None — the endpoint does not support
date_after, so all sources are fetched on every sync
Secret Incident
Operation options
This object does not support any operation options.
Delta sync
Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on date_after.
API
- Type: REST (two calls: list incidents, then list occurrences per incident)
- Default filters:
date_after={since}applied to/v1/incidents/secretswhen syncing incrementally
Public Secret Incident
Operation options
This object does not support any operation options.
Delta sync
Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on date_after.
API
- Type: REST (two calls: list public incidents, then list occurrences per incident)
- Default filters:
date_after={since}applied to/v1/public-incidents/secretswhen syncing incrementally
Secret Incident Definition
Operation options
This object does not support any operation options.
Delta sync
Not supported. The connector performs a full sync of Secret Incident Definition on every run and applies no incremental date filter.
API
- Type: REST (one call per detector to enrich with a sample incident)
- Default filters: Only detectors with at least one incident (open + ignored + resolved > 0) produce a definition
Changelog
The GitGuardian connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.0.0 | Overview The GitGuardian connector integrates with the GitGuardian secrets detection platform to synchronize source repositories, secret incidents, and incident definitions. It surfaces leaked-secret findings and the repositories they originate from so they can be tracked and remediated alongside the rest of your security data. Category: Application Security Models | N/A |