GitGuardian API (1.1.0)

Download OpenAPI specification:Download

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 Tokens

Manage API tokens.

Retrieve details of the current API token.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
{
  • "id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
  • "name": "myTokenName",
  • "workspace_id": 42,
  • "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": [
    ]
}

Revoke the current API token.

Authorizations:
api-key

Responses

Response samples

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
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

Content type
application/json
[
  • {
    }
]

Retrieve details of an API token.

Authorizations:
api-key
path Parameters
token_id
required
string
Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

Content type
application/json
{
  • "id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
  • "name": "myTokenName",
  • "workspace_id": 42,
  • "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": [
    ]
}

Revoke an an API token.

Authorizations:
api-key
path Parameters
token_id
required
string
Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid API key."
}

Create a JSON Web Token.

Create a short lived JWT for authentication to specific GitGuardian services, including HasMySecretLeaked.

Authorizations:
api-key
Request Body schema: application/json
audience
required
string

Audience of the JWT.

audience_type
string

Type of audience.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJS[...]"
}

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
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: DEFAULT_BRANCH FROM_HISTORICAL_SCAN CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED 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

Content type
application/json
[
  • {
    }
]

Retrieve a secret incident

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

Authorizations:
api-key
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
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "ignore_reason": "test_credential",
  • "triggered_at": "2019-05-12T09:37:49Z",
  • "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,
  • "tags": [
    ],
  • "occurrences": [
    ]
}

Update a secret incident

Update a secret incident

Authorizations:
api-key
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": "high"
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "ignore_reason": "test_credential",
  • "triggered_at": "2019-05-12T09:37:49Z",
  • "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,
  • "tags": [
    ],
  • "occurrences": null
}

Retrieve where a secret has been publicly leaked

Retrieve where a secret has been publicly leaked.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Responses

Response samples

Content type
application/json

Assign a secret incident

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

Authorizations:
api-key
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",
  • "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "ignore_reason": "test_credential",
  • "triggered_at": "2019-05-12T09:37:49Z",
  • "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,
  • "tags": [
    ],
  • "occurrences": null
}

Unassign a secret incident

Unassign secret incident from a workspace member by email.

Authorizations:
api-key
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",
  • "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "ignore_reason": "test_credential",
  • "triggered_at": "2019-05-12T09:37:49Z",
  • "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,
  • "tags": [
    ],
  • "occurrences": null
}

Resolve a secret incident

Resolve a secret incident detected by the GitGuardian dashboard.

Authorizations:
api-key
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",
  • "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "ignore_reason": "test_credential",
  • "triggered_at": "2019-05-12T09:37:49Z",
  • "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,
  • "tags": [
    ],
  • "occurrences": null
}

Ignore a secret incident

Ignore a secret incident detected by the GitGuardian dashboard.

Authorizations:
api-key
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

Request samples

Content type
application/json
{
  • "ignore_reason": "low_risk"
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "ignore_reason": "test_credential",
  • "triggered_at": "2019-05-12T09:37:49Z",
  • "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,
  • "tags": [
    ],
  • "occurrences": null
}

Reopen a secret incident

Unresolve or unignore a secret incident detected by the GitGuardian dashboard.

Authorizations:
api-key
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",
  • "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "ignore_reason": "test_credential",
  • "triggered_at": "2019-05-12T09:37:49Z",
  • "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,
  • "tags": [
    ],
  • "occurrences": null
}

Share a secret incident

Share a secret incident by creating a public link.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
auto_healing
boolean
Default: false

Allow the developer to resolve or ignore through the share link

feedback_collection
boolean
Default: true

Allow the developer to submit their feedback through the share link

lifespan
integer >= 0
Default: 0

Lifespan, in hours, of the share link. If 0 or unset, a default value will be applied based on the workspace settings.

Responses

Request samples

Content type
application/json
{
  • "auto_healing": true,
  • "feedback_collection": true,
  • "lifespan": 720
}

Response samples

Content type
application/json
{}

Unshare a secret incident

Unshare a secret incident by revoking its public link.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Grant access to a secret incident

Grant a user, an existing invitee or a team access to a secret incident.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
email
string

Email address of a user or invitee. This parameter is mutually exclusive with member_id, invitation_id and team_id.

member_id
number

Id of a member. This parameter is mutually exclusive with email, invitation_id and team_id.

invitation_id
number

Id of an invitation. This parameter is mutually exclusive with email, member_id and team_id.

team_id
number

Id of a team, except for the global team. This parameter is mutually exclusive with email, member_id and invitation_id.

incident_permission
string
Enum: can_view can_edit full_access

Responses

Request samples

Content type
application/json
{
  • "member_id": 1492,
  • "incident_permission": "can_edit"
}

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Revoke access to a secret incident

Revoke access of a user, an existing invitee or a team to a secret incident.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
email
string

Email address of a user or invitee. This parameter is mutually exclusive with member_id, invitation_id and team_id.

member_id
number

Id of a member. This parameter is mutually exclusive with email, invitation_id and team_id.

invitation_id
number

Id of an invitation. This parameter is mutually exclusive with email, member_id and team_id.

team_id
number

Id of a team, except for the global team. This parameter is mutually exclusive with email, member_id and invitation_id.

Responses

Request samples

Content type
application/json
{
  • "member_id": 1492
}

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

List members having access to a secret incident

List all the members having access to a secret incident.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

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.

member_id
number
Example: member_id=1234

filter on a specific member id.

incident_permission
string
Enum: can_view can_edit full_access
Example: incident_permission=can_view
role
string
Deprecated
Enum: owner manager member restricted

Filter members based on their role.

search
string
Deprecated

Search members based on their name or email.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List teams having access to a secret incident

List all the teams having access to a secret incident.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

query Parameters
cursor
string

Pagination cursor.

team_id
number
Example: team_id=1234

filter on a specific team id.

incident_permission
string
Enum: can_view can_edit full_access
Example: incident_permission=can_view

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List invitations having access to a Secret Incident

List all the invitations having access to a Secret Incident.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

query Parameters
cursor
string

Pagination cursor.

invitation_id
number
Example: invitation_id=1234

filter on a specific invitation id.

incident_permission
string
Enum: can_view can_edit full_access
Example: incident_permission=can_view

filter accesses with a specific permission.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List secret incidents of a source

List secret incidents linked to a source. Occurrences are not returned in this route.

Authorizations:
api-key
path Parameters
source_id
required
integer
Example: 5523

The id of the source to filter on.

query Parameters
cursor
string

Pagination cursor.

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: DEFAULT_BRANCH FROM_HISTORICAL_SCAN CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED 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

Content type
application/json
[
  • {
    }
]

List secret incidents of a team

List secret incidents of a particular team. Occurrences are not returned in this route.

Authorizations:
api-key
path Parameters
team_id
required
integer

The id of the team

query Parameters
cursor
string

Pagination cursor.

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: DEFAULT_BRANCH FROM_HISTORICAL_SCAN CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED 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

Content type
application/json
[
  • {
    }
]

Secret Occurrences

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

List secret occurrences

List occurrences of secrets in the monitored perimeter.

Authorizations:
api-key
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.

source_id
integer
Example: source_id=5523

Filter on the source ID.

source_name
string
Example: source_name=gitguardian/test-repository

Entries matching this source name search.

source_type
string
Enum: bitbucket github gitlab azure_devops slack jira_cloud confluence_cloud microsoft_teams
Example: source_type=github

Filter by integration type.

incident_id
integer

Filter by incident ID.

presence
string
Enum: present removed

Entries that have the following presence status.

author_name
string >= 3 characters
Example: author_name=John Doe

Entries matching this author name search.

author_info
string >= 3 characters
Example: author_info=john.doe@gitguardian.com

Entries matching this author email search.

sha
string >= 3 characters
Example: sha=fccebf0562698ab99dc10dcb2e864fc563b25ac4

Entries starting with the commit sha search string.

filepath
string >= 3 characters
Example: filepath=myfile.txt

Entries matching this filepath search.

tags
string
Enum: DEFAULT_BRANCH FROM_HISTORICAL_SCAN CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE NONE
Example: tags=FROM_HISTORICAL_SCAN,SENSITIVE_FILE

Occurrences with one of the following tags. Use NONE if you want to filter occurrences with no tags.

ordering
string
Enum: date -date

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Secret Incident Notes

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

List notes on a secret incident

List notes left on a secret incident in chronological order.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

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.

ordering
string
Enum: created_at -created_at updated_at -updated_at

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

member_id
integer
Example: member_id=1

Filter by member id.

search
string
Example: search=I revoked this

Search notes based on the comment field content.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a secret incident note

Add a note on a secret incident.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
comment
required
string

Content of the incident note

Responses

Request samples

Content type
application/json
{
  • "comment": "I revoked this secret"
}

Response samples

Content type
application/json
{
  • "id": 17,
  • "incident_id": 42,
  • "member_id": 38,
  • "api_token": null,
  • "api_token_id": "3220d951-00ce-446c-ac90-9822f0f9b71e",
  • "created_at": "2019-08-22T14:15:22Z",
  • "updated_at": null,
  • "comment": "I revoked this secret",
  • "issue_id": 42,
  • "user_id": 38
}

Update a secret incident note

Update an existing comment on a secret incident. Only incident notes created by the current API key can be updated.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

note_id
required
integer

The id of the incident note to update

Request Body schema: application/json
comment
required
string

Content of the incident note

Responses

Request samples

Content type
application/json
{
  • "comment": "I revoked this secret"
}

Response samples

Content type
application/json
{
  • "id": 17,
  • "incident_id": 42,
  • "member_id": 38,
  • "api_token": null,
  • "api_token_id": "3220d951-00ce-446c-ac90-9822f0f9b71e",
  • "created_at": "2019-08-22T14:15:22Z",
  • "updated_at": null,
  • "comment": "I revoked this secret",
  • "issue_id": 42,
  • "user_id": 38
}

Delete a secret incident note

Delete an existing comment on a secret incident. Only incident notes created by the current API key can be deleted.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

note_id
required
integer

The id of the incident note to delete

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Honeytokens

Manage honeytokens.

List honeytokens

This endpoint allows you to list all the honeytokens of your workspace.

The response contains the list of honeytokens and a pagination cursor to retrieve the next page.

The honeytokens are sorted by id.

If you are using a personal access token, you need to have a role superior or equal to manager.

Authorizations:
api-key
query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

status
string
Enum: triggered active revoked

Status of a honeytoken.

type
string
Value: AWS

Type of a honeytoken.

search
string

Search honeytokens based on their name and/or description.

creator_id
number

Member id of the honeytoken creator.

revoker_id
number

Member id of the honeytoken revoker.

creator_api_token_id
string

Token id of the honeytoken creator.

revoker_api_token_id
string

Token id of the honeytoken creator.

tags
string

Comma-separated list of tags to filter on.

ordering
string
Enum: created_at -created_at triggered_at -triggered_at revoked_at -revoked_at name -name

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

show_token
boolean
Default: false

Show token details (access_token_id and secret_key).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a honeytoken

This endpoint allows you to create a honeytoken of a type.

If you are using a personal access token, you need to have a role superior or equal to manager.

Authorizations:
api-key
Request Body schema: application/json
name
required
string

honeytoken name.

description
string

honeytoken description.

type
required
string
Value: AWS

honeytoken type

Array of objects (Honeytoken Label)

Labels to set on the honeytoken. If the label doesn't exist, it will be created.

Responses

Request samples

Content type
application/json
{
  • "name": "honeytoken name",
  • "description": "This honeytoken was placed in the repository test",
  • "type": "AWS",
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "name": "honeytoken A",
  • "description": "honeytoken used in the repository AA",
  • "created_at": "2019-08-22T14:15:22Z",
  • "status": "active",
  • "triggered_at": "2019-08-22T14:15:22Z",
  • "revoked_at": "2019-08-22T14:15:22Z",
  • "open_events_count": 122,
  • "type": "AWS",
  • "creator_id": 122,
  • "revoker_id": 122,
  • "creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
  • "revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
  • "token": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

Create a honeytoken within a context

This endpoint allows you to create a honeytoken of a given type within a context. The context is a realistic file in which your honeytoken is inserted.

If language, project_extensions and filename are not provided, a random context will be generated.

Authorizations:
api-key
Request Body schema: application/json
name
required
string

Honeytoken name.

description
string

Honeytoken description.

type
required
string
Value: AWS

Honeytoken type.

Array of objects (Honeytoken Label)

Labels to set on the honeytoken. If the label doesn't exist, it will be created.

language
string

Language to use for the context. If not set but project_extensions is set, the languages will be inferred from the extensions.

filename
string

Filename to use for the context.

project_extensions
Array of strings

An array of file extensions that can be used for the context.

Responses

Request samples

Content type
application/json
{
  • "name": "honeytoken name",
  • "description": "This honeytoken was placed in the repository test",
  • "type": "AWS",
  • "labels": [
    ],
  • "language": "python",
  • "filename": "test_config.py",
  • "project_extensions": [
    ]
}

Response samples

Content type
application/json
{}

Retrieve a honeytoken

Retrieve an existing honeytoken.

If you are using a personal access token, you need to have a role greater or equal to manager.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

query Parameters
show_token
boolean
Default: false

Show token details (access_token_id and secret_key).

Responses

Response samples

Content type
application/json
{
  • "id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "name": "honeytoken A",
  • "description": "honeytoken used in the repository AA",
  • "created_at": "2019-08-22T14:15:22Z",
  • "status": "active",
  • "triggered_at": "2019-08-22T14:15:22Z",
  • "revoked_at": "2019-08-22T14:15:22Z",
  • "open_events_count": 122,
  • "type": "AWS",
  • "creator_id": 122,
  • "revoker_id": 122,
  • "creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
  • "revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
  • "token": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

Update a honeytoken

Update a name or descriptions of an existing honeytoken.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

Request Body schema: application/json
name
string

A new honeytoken name

description
string

A new honeytoken description

Array of objects (Honeytoken Label)

A new set of labels for the honeytoken. Will completely override the former labels.

Responses

Request samples

Content type
application/json
{
  • "name": "test-honeytoken",
  • "description": "honeytoken in repository test",
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "name": "honeytoken A",
  • "description": "honeytoken used in the repository AA",
  • "created_at": "2019-08-22T14:15:22Z",
  • "status": "active",
  • "triggered_at": "2019-08-22T14:15:22Z",
  • "revoked_at": "2019-08-22T14:15:22Z",
  • "open_events_count": 122,
  • "type": "AWS",
  • "creator_id": 122,
  • "revoker_id": 122,
  • "creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
  • "revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
  • "token": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

Reset the honeytoken

Resets a triggered honeytoken. All the associated events will be closed.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "name": "honeytoken A",
  • "description": "honeytoken used in the repository AA",
  • "created_at": "2019-08-22T14:15:22Z",
  • "status": "active",
  • "triggered_at": "2019-08-22T14:15:22Z",
  • "revoked_at": "2019-08-22T14:15:22Z",
  • "open_events_count": 122,
  • "type": "AWS",
  • "creator_id": 122,
  • "revoker_id": 122,
  • "creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
  • "revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
  • "token": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

Revoke the honeytoken

Revokes an active or triggered honeytoken. All the associated events will be closed.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "name": "honeytoken A",
  • "description": "honeytoken used in the repository AA",
  • "created_at": "2019-08-22T14:15:22Z",
  • "status": "active",
  • "triggered_at": "2019-08-22T14:15:22Z",
  • "revoked_at": "2019-08-22T14:15:22Z",
  • "open_events_count": 122,
  • "type": "AWS",
  • "creator_id": 122,
  • "revoker_id": 122,
  • "creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
  • "revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
  • "token": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

Honeytokens Events

Manage events on honeytokens.

List all honeytokens events

List events related to all honeytokens of the workspace.

Authorizations:
api-key
query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

ordering
string
Enum: triggered_at -triggered_at

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'

honeytoken_id
string <uuid>
Example: honeytoken_id=d45a123f-b15d-4fea-abf6-ff2a8479de5b

Filter by honeytoken id

status
string
Default: open
Enum: open archived allowed

Filter by status

ip_address
string
Example: ip_address=8.8.8.8

Filter by ip address

tags
string

Comma-separated list of tags to filter on

search
string
Example: search=I revoked this

Search events based on the data field content

Responses

Response samples

Content type
application/json
[]

Honeytoken Notes

Manage notes on honeytokens.

List notes on an honeytoken

List notes left on a honeytoken in chronological order.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

ordering
string
Enum: created_at -created_at updated_at -updated_at

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

member_id
integer
Example: member_id=1

Filter by member id.

api_token_id
string <uuid>
Example: api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8

Entries matching this API token id.

search
string
Example: search=I revoked this

Search notes based on the comment field content.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an honeytoken note

Add a note on a honeytoken.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

Request Body schema: application/json
comment
required
string

Content of the honeytoken note

Responses

Request samples

Content type
application/json
{
  • "comment": "I revoked this honeytoken"
}

Response samples

Content type
application/json
{
  • "id": "1b99892e-6254-4f8a-9e98-559ed810b7da",
  • "honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "member_id": 38,
  • "api_token_id": "37d5b0d7-9f89-4b80-9070-261e26637836",
  • "created_at": "2019-08-22T14:15:22Z",
  • "updated_at": null,
  • "comment": "I revoked this secret"
}

Update a honeytoken note

Update an existing comment on a honeytoken. Only honeytoken notes created by the current API key can be updated.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

note_id
required
string <uuid>

The id of the honeytoken note to update

Request Body schema: application/json
comment
required
string

Content of the honeytoken note

Responses

Request samples

Content type
application/json
{
  • "comment": "I revoked this"
}

Response samples

Content type
application/json
{
  • "id": "1b99892e-6254-4f8a-9e98-559ed810b7da",
  • "honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "member_id": 38,
  • "api_token_id": "37d5b0d7-9f89-4b80-9070-261e26637836",
  • "created_at": "2019-08-22T14:15:22Z",
  • "updated_at": null,
  • "comment": "I revoked this secret"
}

Delete a honeytoken note

Delete an existing comment on a honeytoken. Only honeytoken notes created by the current API key can be deleted.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

note_id
required
string <uuid>

The id of the honeytoken note to update

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Honeytoken Sources

Manage sources on honeytokens.

List sources on an honeytoken

List sources where a honeytoken appears.

Authorizations:
api-key
path Parameters
honeytoken_id
required
string <uuid>

The id of the honeytoken to retrieve

query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

ordering
string
Enum: source_id -source_id

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

Responses

Response samples

Content type
application/json
[]

Labels

Manage labels for honeytokens. Labels provide a flexible way to organize honeytokens. You can create your own labels in the form of keys and values, assign them to honeytokens, and use them to filter and search for honeytokens based on specific characteristics.

List labels

List labels created for honeytokens in chronological order.

Authorizations:
api-key
query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

search
string
Example: search=env:production

Search string to filter only labels which contains the search string in either its key or value. The search string can also be in the key:value format.

key
string
Example: key=env

Filter only labels which have the given key.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a label

Create a label for honeytokens.

Authorizations:
api-key
Request Body schema: application/json
key
required
string

Label's key's content.

value
required
string

Label's value's content.

Responses

Request samples

Content type
application/json
{
  • "key": "env",
  • "value": "production"
}

Response samples

Content type
application/json
{
  • "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
  • "key": "env",
  • "value": "production"
}

Update a key

Rename a label key. It will be renamed in all the labels using this key.

Authorizations:
api-key
query Parameters
old_key
required
string
Example: old_key=env

an existing key that we want to rename

new_key
required
string
Example: new_key=env prod

a new name of the key

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Delete a key

Delete a key. All the labels using this key will be deleted.

Authorizations:
api-key
query Parameters
key
string
Example: key=env

A specified key to use to delete all labels which have the key matched.

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Update a value

Rename the value of a label.

Authorizations:
api-key
path Parameters
label_id
required
string
Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the label.

Request Body schema: application/json
value
required
string

New value for the label.

Responses

Request samples

Content type
application/json
{
  • "value": "production"
}

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Delete a label

Delete a label for honeytokens.

Authorizations:
api-key
path Parameters
label_id
required
string
Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the label.

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid API key."
}

Sources

Retrieve details on sources known by GitGuardian.

List sources

List sources known by GitGuardian.

Authorizations:
api-key
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.

search
string
Example: search=test-repository

Sources matching this search.

last_scan_status
string
Enum: pending running canceled failed too_large timeout finished

Filter sources based on the status of their latest historical scan.

health
string
Enum: safe unknown at_risk

Filter sources based on their health status.

type
string
Enum: bitbucket github gitlab azure_devops slack jira_cloud confluence_cloud microsoft_teams
Example: type=github

Filter by integration type.

ordering
string
Enum: last_scan_date -last_scan_date

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

visibility
string
Enum: public private internal
Example: visibility=public

Filter by visibility status.

external_id
string
Example: external_id=1

Filter by specific external id.

source_criticality
string
Enum: critical high medium low unknown
Example: source_criticality=critical

Filter by source criticality.

monitored
boolean
Example: monitored=true

Filter by monitored value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a source

Retrieve a source known by GitGuardian.

Authorizations:
api-key
path Parameters
source_id
required
integer
Example: 5523

The id of the source to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": 6531,
  • "type": "github",
  • "full_name": "gitguardian/gg-shield",
  • "health": "at_risk",
  • "default_branch": "main",
  • "default_branch_head": "abcd97b4aaf927ea934504263322e75e86c31xyz",
  • "open_incidents_count": 3,
  • "closed_incidents_count": 2,
  • "secret_incidents_breakdown": {
    },
  • "visibility": "public",
  • "external_id": "125",
  • "source_criticality": "critical",
  • "last_scan": {
    },
  • "monitored": true
}

List secret incidents of a source

List secret incidents linked to a source. Occurrences are not returned in this route.

Authorizations:
api-key
path Parameters
source_id
required
integer
Example: 5523

The id of the source to filter on.

query Parameters
cursor
string

Pagination cursor.

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: DEFAULT_BRANCH FROM_HISTORICAL_SCAN CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED 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

Content type
application/json
[
  • {
    }
]

Members

Retrieve details about workspace members.

List members

List members of the workspace.

Authorizations:
api-key
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.

role
string
Enum: owner manager member restricted

Filter members based on their role.

search
string

Search members based on their name or email.

ordering
string
Enum: created_at -created_at last_login -last_login

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a member

Retrieve an existing workspace member.

If you are using a personal access token, you need to have a role greater or equal to member.

Authorizations:
api-key
path Parameters
member_id
required
integer

The id of the workspace member

Responses

Response samples

Content type
application/json
{
  • "id": 3252,
  • "name": "John Smith",
  • "email": "john.smith@example.org",
  • "role": "owner",
  • "created_at": "2023-06-28T16:40:26.897Z",
  • "last_login": "2023-06-28T16:40:26.897Z"
}

Delete a member

Delete an existing workspace member.

If you are using a personal access token, you need to have a role greater or equal to manager.

Authorizations:
api-key
path Parameters
member_id
required
integer

The id of the workspace member

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Update a member

Update an existing workspace member.

If you are using a personal access token, you need to have a role greater or equal to manager.

Authorizations:
api-key
path Parameters
member_id
required
integer

The id of the workspace member

Request Body schema: application/json
role
string
Enum: owner manager member restricted

Responses

Request samples

Content type
application/json
{
  • "role": "owner"
}

Response samples

Content type
application/json
{
  • "id": 3252,
  • "name": "John Smith",
  • "email": "john.smith@example.org",
  • "role": "owner",
  • "created_at": "2023-06-28T16:40:26.897Z",
  • "last_login": "2023-06-28T16:40:26.897Z"
}

List teams of a member

List teams of a workspace member. The response contains the list of teams and a pagination cursor to retrieve the next page.

The teams are sorted by id.

If you are using a personal access token, you need to have a role superior or equal to manager except if the requested member is yourself.

Authorizations:
api-key
path Parameters
member_id
required
integer

The id of the workspace member

query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

search
string

Search teams based on their name and/or description.

is_global
boolean

Filter on/exclude the "All-incidents" team.

Responses

Response samples

Content type
application/json
[]

List team memberships of a member

List team memberships of a workspace member. The response contains the list of team memberships and a pagination cursor to retrieve the next page.

The team memberships are sorted by id.

If you are using a personal access token, you need to have a role superior or equal to manager except if the requested member is yourself.

Authorizations:
api-key
path Parameters
member_id
required
integer

The id of the workspace member

query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

team_id
integer

The id of a team to filter on

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Invitations

Manage workspace invitations.

List invitations

This endpoint allows you to list all pending invitations.

The response contains the list of invitations and a pagination cursor to retrieve the next page.

The invitations are sorted by id.

If you are using a personal access token, you need to have a role superior or equal to member.

Authorizations:
api-key
query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

search
string

Search invitations based on the email field.

ordering
string
Enum: date -date

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an invitation

This endpoint allows you to send an invitation to a user.

If you are using a personal access token, you need to have a role superior or equal to member.

Authorizations:
api-key
Request Body schema: application/json
email
required
string

email of the user to invite.

role
string
Default: member
Enum: manager member restricted

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": 3252,
  • "email": "john.smith@example.org",
  • "role": "manager",
  • "date": "2019-08-22T14:15:22Z"
}

Delete an invitation

Delete an existing invitation.

If you are using a personal access token, you need to have a role superior or equal to manager.

Authorizations:
api-key
path Parameters
invitation_id
required
integer

The id of the invitation to retrieve

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid data."
}

Resend an invitation

Resend an existing invitation.

If you are using a personal access token, you need to have a role superior or equal to manager.

Authorizations:
api-key
path Parameters
invitation_id
required
integer

The id of the invitation to retrieve

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "detail": "Email sent"
}

Scan Methods

Use GitGuardian's brain at your leisure.

Scanning API allows you to scan any content you want using GitGuardian's secrets detection algorithms.

Content scan

Scan provided document content for policy breaks.

Request body shouldn't exceed 1MB.

This endpoint is stateless and as such will not store in our servers neither the documents nor the secrets found.

Authorizations:
api-key
Request Body schema: application/json
filename
string <= 256 characters
document
required
string

Responses

Request samples

Content type
application/json
{
  • "filename": ".env",
  • "document": "\nimport urllib.request\nurl = 'http://jen_barber:correcthorsebatterystaple@cake.gitguardian.com/isreal.json'\nresponse = urllib.request.urlopen(url)\nconsume(response.read())\n"
}

Response samples

Content type
application/json
{
  • "policy_break_count": 2,
  • "policies": [
    ],
  • "policy_breaks": [
    ]
}

Multiple content scan

Scan provided document contents for policy breaks. Multiple documents are returned by the same index order.

There should not be more than 20 documents in the payload. Individual documents should not exceed 1MB.

Quota usage is based on requests and not on the content size. One request to this endpoint will consume 1 API call. Also note that the quota is set on a rolling month and not on a calendar month. See this documentation for more details.

This endpoint is stateless and as such will not store in our servers neither the documents nor the secrets found.

Authorizations:
api-key
Request Body schema: application/json
Array (non-empty)
filename
string <= 256 characters
document
required
string

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Secret Detectors

Retrieve details on detectors used for secret detection.

List secret detectors

List secret detectors.

Authorizations:
api-key
query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

is_active
boolean
Example: is_active=true

Filter only active or inactive detectors.

type
string
Enum: specific generic custom
Example: type=generic

Filter detectors on their type.

search
string
Example: search=aws
ordering
string
Enum: name -name

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a secret detector

Get a secret detector.

Authorizations:
api-key
path Parameters
detector_name
required
string
Example: aws_iam

Name of the detector to retrieve

Responses

Response samples

Content type
application/json
{
  • "name": "aws_iam",
  • "display_name": "AWS Keys",
  • "type": "specific",
  • "category": "Cloud Provider",
  • "is_active": true,
  • "scans_code_only": false,
  • "checkable": true,
  • "use_with_validity_check_disabled": true,
  • "frequency": "1O3.74",
  • "removed_at": null,
  • "open_incidents_count": 17,
  • "ignored_incidents_count": 9,
  • "resolved_incidents_count": 42
}

Quota

Retrieve details about quota usage.

Quota overview

Check available scanning calls for this token. Quota is shared between all tokens of a workspace

Authorizations:
api-key

Responses

Response samples

Content type
application/json
{
  • "content": {
    }
}

SCA

Software Composition Analysis

Compute SCA files amongst a list of files.

Compute SCA files amongst a list of files.

Authorizations:
api-key
query Parameters
files
string

List of input files, comma separated.

Responses

Response samples

Content type
application/json
{
  • "sca_files": [
    ],
  • "potential_siblings": [
    ]
}

Scan a directory using GitGuardian SCA engine

Scan a directory using GitGuardian SCA engine

Authorizations:
api-key
Request Body schema: multipart/form-data
object (Scan Parameters)
Default: [object Object]
directory
required
string (Directory)

Responses

Response samples

Content type
application/json
{
  • "scanned_files": [ ],
  • "found_package_vulns": [ ]
}

Scan a diff using GitGuardian SCA engine

Scan a diff using GitGuardian SCA engine

Authorizations:
api-key
Request Body schema: multipart/form-data
object (Scan Parameters)
Default: [object Object]
reference
required
string (Reference)
current
required
string (Current)

Responses

Response samples

Content type
application/json
{
  • "scanned_files": [ ],
  • "added_vulns": [ ],
  • "removed_vulns": [ ]
}

IaC Scan Methods

Content scan

This feature is experimental.

Scan a tar file directory seeking potential IaC (Infrastructure as Code) vulnerabilities. Return a list of vulnerabilities found in the files of the scanned directory.

Authorizations:
api-key
Request Body schema: application/json
directory
required
object <tar>

Tar file containing the folder to be scanned.

object (Scan Parameters)
Default: [object Object]

Responses

Request samples

Content type
application/json
{
  • "directory": { },
  • "scan_parameters": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "iac_engine_version": "string",
  • "type": "string",
  • "source_found": true,
  • "entities_with_incidents": [
    ]
}

Differential scan

This feature is experimental.

Infrastructure as Code (IaC) differential scanning compares two states of the same project and reports any change in the vulnerabilities of your configuration.

Scan tar files containing two states of the same directory (under the names reference and current) seeking changes in potential IaC (Infrastructure as Code) vulnerabilities. Return the status of vulnerabilities found in the files of the compared scanned directories.

Authorizations:
api-key
Request Body schema: application/json
reference
required
object <tar>

Tar file containing reference folder to be scanned.

current
required
object <tar>

Tar file containing current folder to be scanned.

object (Scan Parameters)
Default: [object Object]

Responses

Request samples

Content type
application/json
{
  • "reference": { },
  • "current": { },
  • "scan_parameters": {
    }
}

Response samples

Content type
application/json