Download OpenAPI specification:Download
Whether you want to build a complete integration with your software development workflow or simply want to test GitGuardian's policy break detection on any text content, you can use our API.
api.gitguardian.com/v1
over HTTPS
.2020-03-16T04:46:00+00:00 # for date-time
GitGuardian supported wrappers:
GitGuardian provides you with GitGuardian Shield, a CLI application that uses the GitGuardian API through py-gitguardian to scan your files and detect potential secrets or issues in your code.
This CLI application can be used in many CIs (such as GitHub Actions, GitLab Pipelines, CircleCI,...) or as a pre-commit or pre-receive hook.
The GitGuardian API uses API keys to authenticate requests.
You need to create an account before getting started in order to get an API key.
Your API key can be created and revoked from the API section of your dashboard.
Your API key must kept private and should neither be embedded directly in the code nor versioned in Git. (Please do not push GitGuardian's API keys to public GitHub repositories ^^).
Beware your API keys can expire and can be revoked.
Use /v1/health to check the validity of your token if needed.
curl -H "Authorization: Token ${TOKEN}" \
https://api.gitguardian.com/v1/health
List secret incidents detected by the GitGuardian dashboard. Occurrences are not returned in this route.
incidents:read
) cursor | string Pagination cursor. |
page | integer >= 0 Deprecated Default: 1 Page number. |
per_page | integer [ 1 .. 100 ] Default: 20 Number of items to list per page. |
date_before | string <datetime> Example: date_before=2019-08-30T14:15:22Z Entries found before this date. |
date_after | string <datetime> Example: date_after=2019-08-22T14:15:22Z Entries found after this date. |
assignee_email | string Example: assignee_email=eric@gitguardian.com Incidents assigned to this email. |
status | string Enum: "IGNORED" "TRIGGERED" "ASSIGNED" "RESOLVED" Incidents with the following status. |
severity | string Enum: "critical" "high" "medium" "low" "info" "unknown" Filter incidents by severity. |
validity | string Enum: "valid" "invalid" "failed_to_check" "no_checker" "unknown" Secrets with the following validity. |
tags | string Enum: "FROM_HISTORICAL_SCAN" "IGNORED_IN_CHECK_RUN" "PUBLIC" "REGRESSION" "SENSITIVE_FILE" "TEST_FILE" "NONE" Example: tags=FROM_HISTORICAL_SCAN,SENSITIVE_FILE Incidents with one of the following tags. Use |
ordering | string Enum: "date" "-date" "resolved_at" "-resolved_at" "ignored_at" "-ignored_at" Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'. |
detector_group_name | string Example: detector_group_name=slackbot_token Incidents belonging to the specified detector group. |
[- {
- "id": 3759,
- "date": "2019-08-22T14:15:22Z",
- "detector": {
- "name": "slack_bot_token",
- "display_name": "Slack Bot Token",
- "nature": "specific",
- "family": "apikey",
- "detector_group_name": "slackbot_token",
- "detector_group_display_name": "Slack Bot Token"
}, - "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
- "regression": false,
- "status": "IGNORED",
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "occurrences": null,
- "ignore_reason": "test_credential",
- "ignored_at": "2019-08-24T14:15:22Z",
- "secret_revoked": false,
- "severity": "high",
- "validity": "valid",
- "resolved_at": null,
- "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
]
}
]
Retrieve secret incident detected by the GitGuardian dashboard with its occurrences.
incidents:read
) incident_id required | integer The id of the incident to retrieve |
with_occurrences | integer [ 0 .. 100 ] Default: 20 Retrieve a number of occurrences of this incident. |
{- "id": 3759,
- "date": "2019-08-22T14:15:22Z",
- "detector": {
- "name": "slack_bot_token",
- "display_name": "Slack Bot Token",
- "nature": "specific",
- "family": "apikey",
- "detector_group_name": "slackbot_token",
- "detector_group_display_name": "Slack Bot Token"
}, - "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
- "regression": false,
- "status": "IGNORED",
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "occurrences": [
- {
- "id": 4421,
- "incident_id": 3759,
- "kind": "Realtime",
- "sha": "d670460b4b4aece5915caf5c68d12f560a9fe3e4",
- "source": {
- "id": 6531,
- "type": "github",
- "full_name": "gitguardian/gg-shield",
- "health": "at_risk",
- "open_incidents_count": 3,
- "closed_incidents_count": 2,
- "visibility": "public",
- "external_id": "125",
- "last_scan": {
- "date": "2021-05-20T12:40:55.662949Z",
- "status": "finished"
}
}, - "author_name": "Eric",
- "author_info": "eric@gitguardian.com",
- "date": "2021-05-20T12:40:55.662949Z",
- "presence": "present",
- "matches": [
- {
- "name": "apikey",
- "indice_start": 32,
- "indice_end": 79,
- "pre_line_start": null,
- "pre_line_end": null,
- "post_line_start": 1,
- "post_line_end": 1
}
], - "filepath": "test_data/12123testfile.txt"
}
], - "ignore_reason": "test_credential",
- "severity": "high",
- "validity": "valid",
- "ignored_at": "2019-08-24T14:15:22Z",
- "secret_revoked": false,
- "resolved_at": null,
- "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
]
}
Update a secret incident
incidents:write
) incident_id required | integer The id of the incident to retrieve |
severity | string Enum: "critical" "high" "medium" "low" "info" "unknown" |
{- "severity": "critical"
}
{- "id": 3759,
- "date": "2019-08-22T14:15:22Z",
- "detector": {
- "name": "slack_bot_token",
- "display_name": "Slack Bot Token",
- "nature": "specific",
- "family": "apikey",
- "detector_group_name": "slackbot_token",
- "detector_group_display_name": "Slack Bot Token"
}, - "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
- "regression": false,
- "status": "IGNORED",
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "occurrences": null,
- "ignore_reason": "test_credential",
- "ignored_at": "2019-08-24T14:15:22Z",
- "secret_revoked": false,
- "severity": "high",
- "validity": "valid",
- "resolved_at": null,
- "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
]
}
Assign secret incident detected by the GitGuardian dashboard to a workspace member by email.
incidents:write
) incident_id required | integer The id of the incident to retrieve |
string email of the member to assign. This parameter is mutually exclusive with | |
member_id | number id of the member to assign. This parameter is mutually exclusive with |
{- "email": "eric@gitguardian.com",
- "member_id": 4295
}
{- "id": 3759,
- "date": "2019-08-22T14:15:22Z",
- "detector": {
- "name": "slack_bot_token",
- "display_name": "Slack Bot Token",
- "nature": "specific",
- "family": "apikey",
- "detector_group_name": "slackbot_token",
- "detector_group_display_name": "Slack Bot Token"
}, - "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
- "regression": false,
- "status": "IGNORED",
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "occurrences": null,
- "ignore_reason": "test_credential",
- "ignored_at": "2019-08-24T14:15:22Z",
- "secret_revoked": false,
- "severity": "high",
- "validity": "valid",
- "resolved_at": null,
- "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
]
}
Unassign secret incident from a workspace member by email.
incidents:write
) incident_id required | integer The id of the incident to retrieve |
{- "id": 3759,
- "date": "2019-08-22T14:15:22Z",
- "detector": {
- "name": "slack_bot_token",
- "display_name": "Slack Bot Token",
- "nature": "specific",
- "family": "apikey",
- "detector_group_name": "slackbot_token",
- "detector_group_display_name": "Slack Bot Token"
}, - "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
- "regression": false,
- "status": "IGNORED",
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "occurrences": null,
- "ignore_reason": "test_credential",
- "ignored_at": "2019-08-24T14:15:22Z",
- "secret_revoked": false,
- "severity": "high",
- "validity": "valid",
- "resolved_at": null,
- "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
]
}
Resolve a secret incident detected by the GitGuardian dashboard.
incidents:write
) incident_id required | integer The id of the incident to retrieve |
secret_revoked required | boolean |
{- "secret_revoked": true
}
{- "id": 3759,
- "date": "2019-08-22T14:15:22Z",
- "detector": {
- "name": "slack_bot_token",
- "display_name": "Slack Bot Token",
- "nature": "specific",
- "family": "apikey",
- "detector_group_name": "slackbot_token",
- "detector_group_display_name": "Slack Bot Token"
}, - "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
- "regression": false,
- "status": "IGNORED",
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "occurrences": null,
- "ignore_reason": "test_credential",
- "ignored_at": "2019-08-24T14:15:22Z",
- "secret_revoked": false,
- "severity": "high",
- "validity": "valid",
- "resolved_at": null,
- "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
]
}
Ignore a secret incident detected by the GitGuardian dashboard.
incidents:write
) incident_id required | integer The id of the incident to retrieve |
ignore_reason required | string Enum: "test_credential" "false_positive" "low_risk" |