GitGuardian
Documentation Powered by ReDoc

GitGuardian API (1.1.0)

Download OpenAPI specification:Download

GitGuardian: support@gitguardian.com URL: https://www.gitguardian.com License: GitGuardian Terms of Service

Introduction

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.

  • The base url for the latest version is api.gitguardian.com/v1 over HTTPS.
  • All data is sent and received as JSON by default.
  • All timestamps returned are ISO-8601 compliant, example:
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.

Authentication

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

API Key

Usage: Token <API Key> in Authorization header.

Security Scheme Type HTTP
HTTP Authorization Scheme Bearer

Secret Incidents

Manage incidents found by post-receive hooks on your GitGuardian Dashboard.

List secret incidents

List secret incidents detected by the GitGuardian dashboard. Occurrences are not returned in this route.

Authorizations:
API Key (incidents:read)
query Parameters
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 NONE if you want to filter incidents with no tags.

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a secret incident

Retrieve secret incident detected by the GitGuardian dashboard with its occurrences.

Authorizations:
API Key (incidents:read)
path Parameters
incident_id
required
integer

The id of the incident to retrieve

query Parameters
with_occurrences
integer [ 0 .. 100 ]
Default: 20

Retrieve a number of occurrences of this incident.

Responses

Response samples

Content type
application/json
{}

Update a secret incident

Update a secret incident

Authorizations:
API Key (incidents:write)
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
severity
string
Enum: "critical" "high" "medium" "low" "info" "unknown"

Responses

Request samples

Content type
application/json
{
  • "severity": "critical"
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3899",
  • "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,
  • "share_url": "https://dashboard.gitguardian.com/share/incidents/11111111-1111-1111-1111-111111111111",
  • "tags": [
    ]
}

Assign a secret incident

Assign secret incident detected by the GitGuardian dashboard to a workspace member by email.

Authorizations:
API Key (incidents:write)
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
email
string

email of the member to assign. This parameter is mutually exclusive with member_id.

member_id
number

id of the member to assign. This parameter is mutually exclusive with email.

Responses

Request samples

Content type
application/json
{
  • "email": "eric@gitguardian.com",
  • "member_id": 4295
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3899",
  • "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,
  • "share_url": "https://dashboard.gitguardian.com/share/incidents/11111111-1111-1111-1111-111111111111",
  • "tags": [
    ]
}

Unassign a secret incident

Unassign secret incident from a workspace member by email.

Authorizations:
API Key (incidents:write)
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3899",
  • "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,
  • "share_url": "https://dashboard.gitguardian.com/share/incidents/11111111-1111-1111-1111-111111111111",
  • "tags": [
    ]
}

Resolve a secret incident

Resolve a secret incident detected by the GitGuardian dashboard.

Authorizations:
API Key (incidents:write)
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
secret_revoked
required
boolean

Responses

Request samples

Content type
application/json
{
  • "secret_revoked": true
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3899",
  • "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,
  • "share_url": "https://dashboard.gitguardian.com/share/incidents/11111111-1111-1111-1111-111111111111",
  • "tags": [
    ]
}

Ignore a secret incident

Ignore a secret incident detected by the GitGuardian dashboard.

Authorizations:
API Key (incidents:write)
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
ignore_reason
required
string
Enum: "test_credential" "false_positive" "low_risk"

Responses