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:

Python: py-gitguardian

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

API Tokens

Manage API tokens.

Retrieve details of the current API token.

Authorizations:

API Key

Responses

Response samples

200
401

Content type

application/json

{"id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
"name": "myTokenName",
"type": "personal_access_token",
"status": "revoked",
"created_at": "2023-05-20T12:40:55.662949Z",
"last_used_at": "2023-05-24T12:40:55.662949Z",
"expire_at": null,
"revoked_at": "2023-05-27T12:40:55.662949Z",
"member_id": 22015,
"creator_id": 22015,
"scopes": ["incidents:read",
"scan"
]
}

Revoke the current API token.

Authorizations:

API Key

Responses

Response samples

401

Content type

application/json

{"detail": "Invalid API key."
}

List API tokens.

List all the tokens in the workspace, some filters are available and described below.

Authorizations:

API Key (api_tokens:read)

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
status	string Enum: "active" "expired" "revoked" Status of the token.
member_id	integer Example: member_id=1 Filter by member id.
creator_id	integer Example: creator_id=1 Filter by creator id.
scopes	string Enum: "scan" "incidents:read" "incidents:write" "incidents:share" "members:read" "members:write" "teams:read" "teams:write" "audit_logs:read" "honeytokens:read" "honeytokens:write" "api_tokens:read" "api_tokens:write" Example: scopes=incidents:read,api_tokens:read Tokens with one of the following scopes.
search	string Search tokens based on their name.
ordering	string Enum: "created_at" "-created_at" "last_used_at" "-last_used_at" "expire_at" "-expire_at" "revoked_at" "-revoked_at" Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

Responses

Response samples

200
400
401

Content type

application/json

[{"id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
"name": "myTokenName",
"type": "personal_access_token",
"status": "revoked",
"created_at": "2023-05-20T12:40:55.662949Z",
"last_used_at": "2023-05-24T12:40:55.662949Z",
"expire_at": null,
"revoked_at": "2023-05-27T12:40:55.662949Z",
"member_id": 22015,
"creator_id": 22015,
"scopes": ["incidents:read",
"scan"
]
}
]

Retrieve details of an API token.

Authorizations:

API Key (api_tokens:read)

path Parameters

token_id

required

string

Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

200
401
404

Content type

application/json

{"id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
"name": "myTokenName",
"type": "personal_access_token",
"status": "revoked",
"created_at": "2023-05-20T12:40:55.662949Z",
"last_used_at": "2023-05-24T12:40:55.662949Z",
"expire_at": null,
"revoked_at": "2023-05-27T12:40:55.662949Z",
"member_id": 22015,
"creator_id": 22015,
"scopes": ["incidents:read",
"scan"
]
}

Revoke an an API token.

Authorizations:

API Key (api_tokens:write)

path Parameters

token_id

required

string

Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

401
404

Content type

application/json

{"detail": "Invalid API key."
}

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.
assignee_id	integer Example: assignee_id=4932 Incidents assigned to this user id.
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.
ignorer_id	integer Example: ignorer_id=4932 Incidents ignored by this user id.
ignorer_api_token_id	string <uuid> Example: ignorer_api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8 Incidents ignored by this API token id.
resolver_id	integer Example: resolver_id=4932 Incidents resolved by this user id.
resolver_api_token_id	string <uuid> Example: resolver_api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8 Incidents resolved by this API token id.

Responses

Response samples

200
400
401
503

Content type

application/json

[{"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",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3899",
"regression": false,
"status": "IGNORED",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"occurrences_count": 4,
"occurrences": null,
"ignore_reason": "test_credential",
"ignored_at": "2019-08-24T14:15:22Z",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"severity": "high",
"validity": "valid",
"resolved_at": null,
"share_url": "https://dashboard.gitguardian.com/share/incidents/11111111-1111-1111-1111-111111111111",
"tags": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
]
}
]

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

200
400
401
503

Content type

application/json

{"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",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3899",
"regression": false,
"status": "IGNORED",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"occurrences_count": 4,
"occurrences": [{"id": 4421,
"incident_id": 3759,
"kind": "Realtime",
"sha": "d670460b4b4aece5915caf5c68d12f560a9fe3e4",
"source": {"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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",
"url": "https://github.com/prm-dev-team/QATest_staging/commit/76dd18a2a8d27eaf00a45851cc7731c53b59ed19#diff-0f372f3171c8f13a15a22a1081487ed54fa70ad088e17c6c6386196a179a04ffR1",
"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",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"resolved_at": null,
"share_url": "https://dashboard.gitguardian.com/share/incidents/11111111-1111-1111-1111-111111111111",
"tags": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
]
}

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

Payload

Content type

application/json

{"severity": "critical"
}

Response samples

200
400
401
503

Content type

application/json

{"id": 3759,
"date": "201