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.
https://api.gitguardian.com/v1
or https://api.eu1.gitguardian.com/v1
depending on your location.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. For a detailed explanation, please refer to our dedicated documentation.
Use /v1/health to check the validity of your token if needed.
The GitGuardian API employs cursor-based pagination. For a detailed explanation, please refer to our dedicated documentation.
{- "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": [
- "incidents:read",
- "scan"
]
}
List all the tokens in the workspace, some filters are available and described below.
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 ip_allowlist:read ip_allowlist: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 '-'. |
[- {
- "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": [
- "incidents:read",
- "scan"
]
}
]
token_id required | string Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360 Id of the token. |
{- "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": [
- "incidents:read",
- "scan"
]
}
Create a short lived JWT for authentication to specific GitGuardian services, including HasMySecretLeaked.
audience required | string Audience of the JWT. |
audience_type | string Type of audience. |
{- "audience_type": "hmsl"
}
{- "token": "eyJhbGciOiJS[...]"
}
List secret incidents detected by the GitGuardian dashboard. Occurrences are not returned in this route.
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 |
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. |
feedback | boolean Incidents with or without feedback. |
[- {
- "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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
]
Retrieve secret incident detected by the GitGuardian dashboard with its occurrences.
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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": [
- {
- "id": 4421,
- "incident_id": 3759,
- "kind": "realtime",
- "source": {
- "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": {
- "open_secret_incidents": {
- "total": 0,
- "severity_breakdown": {
- "critical": 0,
- "high": 0,
- "medium": 0,
- "low": 0,
- "info": 0,
- "unknown": 0
}
}, - "closed_secret_incidents": {
- "total": 0,
- "severity_breakdown": {
- "critical": 0,
- "high": 0,
- "medium": 0,
- "low": 0,
- "info": 0,
- "unknown": 0
}
}
}, - "visibility": "public",
- "external_id": "125",
- "source_criticality": "critical",
- "last_scan": {
- "date": "2021-05-20T12:40:55.662949Z",
- "status": "finished",
- "failing_reason": "DMCA takedown",
- "commits_scanned": 123,
- "branches_scanned": 2,
- "duration": "1:30.454444"
}, - "monitored": true
}, - "author_name": "Eric",
- "author_info": "eric@gitguardian.com",
- "date": "2021-05-20T12:40:55.662949Z",
- "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
}
], - "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "sha": "d670460b4b4aece5915caf5c68d12f560a9fe3e4",
- "presence": "present",
- "filepath": "test_data/12123testfile.txt"
}
]
}
Update a secret incident
incident_id required | integer The id of the incident to retrieve |
severity | string Enum: critical high medium low info unknown |
{- "severity": "high"
}
{- "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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
Retrieve where a secret has been publicly leaked.
incident_id required | integer The id of the incident to retrieve |
[- {
- "source": "github",
- "name": "GitGuardian / ggshield",
}
]
Assign secret incident detected by the GitGuardian dashboard to a workspace member by email.
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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
Unassign secret incident from a workspace member by email.
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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
Resolve a secret incident detected by the GitGuardian dashboard.
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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
Ignore a secret incident detected by the GitGuardian dashboard.
incident_id required | integer The id of the incident to retrieve |
ignore_reason required | string Enum: test_credential false_positive low_risk |
{- "ignore_reason": "low_risk"
}
{- "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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
Unresolve or unignore a secret incident detected by the GitGuardian dashboard.
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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
incident_id required | integer The id of the incident to retrieve |
string Email address of a user or invitee. This parameter is mutually exclusive
with | |
member_id | number Id of a member. This parameter is mutually exclusive with |
invitation_id | number Id of an invitation. This parameter is mutually exclusive with |
team_id | number Id of a team, except for the global team. This parameter is mutually
exclusive with |
incident_permission | string Enum: can_view can_edit full_access |
{- "member_id": 1492,
- "incident_permission": "can_edit"
}
{- "detail": "Invalid data."
}
incident_id required | integer The id of the incident to retrieve |
string Email address of a user or invitee. This parameter is mutually exclusive
with | |
member_id | number Id of a member. This parameter is mutually exclusive with |
invitation_id | number Id of an invitation. This parameter is mutually exclusive with |
team_id | number Id of a team, except for the global team. This parameter is mutually
exclusive with |
{- "member_id": 1492
}
{- "detail": "Invalid data."
}
List all the members having access to a secret incident.
DEPRECATED: This endpoint has been replaced by /v1/secret-incidents/{incident_id}/members
incident_id required | integer The id of the incident to retrieve |
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 access level. |
search | string Deprecated Search members based on their name or email. |
[- {
- "member_id": 3252,
- "incident_id": 3252,
- "incident_permission": "can_edit",
- "id": 1234,
- "name": "John Smith",
- "email": "john.smith@example.org",
- "role": "owner"
}
]
List all the teams having access to a secret incident.
DEPRECATED: This endpoint has been replaced by /v1/secret-incidents/{incident_id}/teams
incident_id required | integer The id of the incident to retrieve |
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 |
[- {
- "team_id": 3252,
- "incident_id": 3252,
- "incident_permission": "can_edit"
}
]
List all the invitations having access to a Secret Incident.
DEPRECATED: This endpoint has been replaced by /v1/secret-incidents/{incident_id}/invitations
incident_id required | integer The id of the incident to retrieve |
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. |
[- {
- "invitation_id": 3252,
- "incident_id": 3252,
- "incident_permission": "can_edit"
}
]
Retrieve metrics about the impacted perimeter of a secret incident detected by the GitGuardian dashboard.
incident_id required | integer The id of the incident to retrieve |
{- "id": 1,
- "status": "TRIGGERED",
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "sources": [
- {
- "id": 1,
- "type": "github",
- "full_name": "GitGuardian/ggshield",
- "files": {
- "files_requiring_code_fix": [
- {
- "filepath": "foo.txt",
- "mentions_count": 1,
}
], - "files_pending_merge": [
- {
- "filepath": "bar.txt",
- "mentions_count": 1,
}
], - "files_fixed": [
- {
- "filepath": "baz.txt",
- "mentions_count": 1,
}
]
}
}
]
}
List members that have access to a secret incident.
incident_id required | integer The id of the incident to retrieve |
cursor | string Pagination cursor. |
per_page | integer [ 1 .. 100 ] Default: 20 Number of items to list per page. |
role | string Deprecated Enum: owner manager member restricted Filter members based on their access level. Use |
access_level | string Enum: owner manager member restricted Filter members based on their access level. |
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 '-'. |
direct_access | boolean Filter on direct or indirect accesses. |
[- {
- "id": 3252,
- "name": "John Smith",
- "email": "john.smith@example.org",
- "role": "owner",
- "access_level": "owner",
- "created_at": "2023-06-28T16:40:26.897Z",
- "last_login": "2023-06-28T16:40:26.897Z"
}
]
List teams that have access to a secret incident.
incident_id required | integer The id of the incident to retrieve |
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. |
direct_access | boolean Filter on direct or indirect accesses. |
[- {
- "id": 3252,
- "name": "feature team A",
- "description": "Description of my team",
- "is_global": false,
}
]
List invitations that have access to a secret incident.
incident_id required | integer The id of the incident to retrieve |
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 '-'. |
direct_access | boolean Filter on direct or indirect accesses. |
[- {
- "id": 3252,
- "email": "john.smith@example.org",
- "role": "manager",
- "access_level": "manager",
- "date": "2019-08-22T14:15:22Z"
}
]
List secret incidents linked to a source. Occurrences are not returned in this route.
source_id required | integer Example: 5523 The id of the source to filter on. |
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 |
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. |
feedback | boolean Incidents with or without feedback. |
[- {
- "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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
]
List secret incidents of a particular team. Occurrences are not returned in this route.
DEPRECATED: THis endpoint has been replaced by /v1/teams/{team_id}/secret-incidents
team_id required | integer The id of the team |
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 |
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. |
[- {
- "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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
]
List occurrences of secrets in the monitored perimeter.
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 bitbucket_cloud github gitlab azure_devops slack jira_cloud confluence_cloud microsoft_teams confluence_data_center jira_data_center 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 |
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 '-'. |
[- {
- "id": 4421,
- "incident_id": 3759,
- "kind": "realtime",
- "source": {
- "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": {
- "open_secret_incidents": {
- "total": 0,
- "severity_breakdown": {
- "critical": 0,
- "high": 0,
- "medium": 0,
- "low": 0,
- "info": 0,
- "unknown": 0
}
}, - "closed_secret_incidents": {
- "total": 0,
- "severity_breakdown": {
- "critical": 0,
- "high": 0,
- "medium": 0,
- "low": 0,
- "info": 0,
- "unknown": 0
}
}
}, - "visibility": "public",
- "external_id": "125",
- "source_criticality": "critical",
- "last_scan": {
- "date": "2021-05-20T12:40:55.662949Z",
- "status": "finished",
- "failing_reason": "DMCA takedown",
- "commits_scanned": 123,
- "branches_scanned": 2,
- "duration": "1:30.454444"
}, - "monitored": true
}, - "author_name": "Eric",
- "author_info": "eric@gitguardian.com",
- "date": "2021-05-20T12:40:55.662949Z",
- "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
}
], - "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "sha": "d670460b4b4aece5915caf5c68d12f560a9fe3e4",
- "presence": "present",
- "filepath": "test_data/12123testfile.txt"
}
]
Manage notes on incidents found by post-receive hooks on your GitGuardian Dashboard.
List notes left on a secret incident in chronological order.
incident_id required | integer The id of the incident to retrieve |
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. |
[- {
- "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
}
]
Add a note on a secret incident.
incident_id required | integer The id of the incident to retrieve |
comment required | string <= 10000 characters Content of the incident note |
{- "comment": "I revoked this secret"
}
{- "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 an existing comment on a secret incident. Only incident notes created by the current API key can be updated.
incident_id required | integer The id of the incident to retrieve |
note_id required | integer The id of the incident note to update |
comment required | string <= 10000 characters Content of the incident note |
{- "comment": "I revoked this secret"
}
{- "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 an existing comment on a secret incident. Only incident notes created by the current API key can be deleted.
incident_id required | integer The id of the incident to retrieve |
note_id required | integer The id of the incident note to delete |
{- "detail": "Invalid data."
}
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 an access level superior or equal to manager
.
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 ( |
[- {
- "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": {
- "access_token_id": "AAAA",
- "secret_key": "BBB"
}, - "tags": [
- "publicly_exposed"
], - "labels": [
- {
- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "key": "env",
- "value": "production"
}
]
}
]
This endpoint allows you to create a honeytoken of a type.
If you are using a personal access token, you need to have an access level superior or equal to manager
.
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. |
{- "name": "honeytoken name",
- "description": "This honeytoken was placed in the repository test",
- "type": "AWS",
- "labels": [
- {
- "key": "env",
- "value": "production"
}
]
}
{- "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": {
- "access_token_id": "AAAA",
- "secret_key": "BBB"
}, - "tags": [
- "publicly_exposed"
], - "labels": [
- {
- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "key": "env",
- "value": "production"
}
]
}
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.
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 |
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. |
{- "name": "honeytoken name",
- "description": "This honeytoken was placed in the repository test",
- "type": "AWS",
- "labels": [
- {
- "key": "env",
- "value": "production"
}
], - "language": "python",
- "filename": "test_config.py",
- "project_extensions": [
- ".c",
- ".h"
]
}
{- "content": "string",
- "filepath": "config_prod.py",
- "language": "python",
- "suggested_commit_message": "adding test config",
- "honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
}
Retrieve an existing honeytoken.
If you are using a personal access token, you need to have an access level greater or equal to manager
.
honeytoken_id required | string <uuid> The id of the honeytoken to retrieve |
show_token | boolean Default: false Show token details ( |
{- "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": {
- "access_token_id": "AAAA",
- "secret_key": "BBB"
}, - "tags": [
- "publicly_exposed"
], - "labels": [
- {
- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "key": "env",
- "value": "production"
}
]
}
Update a name or descriptions of an existing honeytoken.
honeytoken_id required | string <uuid> The id of the honeytoken to retrieve |
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. |
{- "name": "test-honeytoken",
- "description": "honeytoken in repository test",
- "labels": [
- {
- "key": "env",
- "value": "production"
}
]
}
{- "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": {
- "access_token_id": "AAAA",
- "secret_key": "BBB"
}, - "tags": [
- "publicly_exposed"
], - "labels": [
- {
- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "key": "env",
- "value": "production"
}
]
}
Resets a triggered honeytoken. All the associated events will be closed.
honeytoken_id required | string <uuid> The id of the honeytoken to retrieve |
{- "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": {
- "access_token_id": "AAAA",
- "secret_key": "BBB"
}, - "tags": [
- "publicly_exposed"
], - "labels": [
- {
- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "key": "env",
- "value": "production"
}
]
}
Revokes an active or triggered honeytoken. All the associated events will be closed.
honeytoken_id required | string <uuid> The id of the honeytoken to retrieve |
{- "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": {
- "access_token_id": "AAAA",
- "secret_key": "BBB"
}, - "tags": [
- "publicly_exposed"
], - "labels": [
- {
- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "key": "env",
- "value": "production"
}
]
}
List events related to all honeytokens of the workspace.
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 |
[- {
- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
- "triggered_at": "2019-08-22T14:15:22Z",
- "status": "open",
- "ip_address": "8.8.8.8",
- "action": "string",
- "data": { },
- "tags": [
- "publicly_exposed"
]
}
]
List notes left on a honeytoken in chronological order.
honeytoken_id required | string <uuid> The id of the honeytoken to retrieve |
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. |
[- {
- "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"
}
]
Add a note on a honeytoken.
honeytoken_id required | string <uuid> The id of the honeytoken to retrieve |
comment required | string <= 10000 characters Content of the honeytoken note |
{- "comment": "I revoked this honeytoken"
}
{- "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 an existing comment on a honeytoken. Only honeytoken notes created by the current API key can be updated.
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 |
comment required | string <= 10000 characters Content of the honeytoken note |
{- "comment": "I revoked this"
}
{- "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 an existing comment on a honeytoken. Only honeytoken notes created by the current API key can be deleted.
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 |
{- "detail": "Invalid data."
}
List sources where a honeytoken appears.
honeytoken_id required | string <uuid> The id of the honeytoken to retrieve |
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 '-'. |
[- {
- "type": "github",
- "name": "gitguardian/gg-shield",
- "open_issues_count": 3,
- "total_files_count": 2,
- "files": [
- ".env"
], - "source_id": 0
}
]
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 created for honeytokens in chronological order.
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. |
[- {
- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "key": "env",
- "value": "production"
}
]
Create a label for honeytokens.
key required | string Label's key's content. |
value required | string Label's value's content. |
{- "key": "env",
- "value": "production"
}
{- "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
- "key": "env",
- "value": "production"
}
Rename a label key. It will be renamed in all the labels using this key.
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 |
{- "detail": "Invalid data."
}
Delete a key. All the labels using this key will be deleted.
key | string Example: key=env A specified key to use to delete all labels which have the key matched. |
{- "detail": "Invalid data."
}
Rename the value of a label.
label_id required | string Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360 Id of the label. |
value required | string New value for the label. |
{- "value": "production"
}
{- "detail": "Invalid data."
}
List sources known by GitGuardian.
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 pending_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 bitbucket_cloud github gitlab azure_devops slack jira_cloud confluence_cloud microsoft_teams confluence_data_center jira_data_center 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. |
[- {
- "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": {
- "open_secret_incidents": {
- "total": 0,
- "severity_breakdown": {
- "critical": 0,
- "high": 0,
- "medium": 0,
- "low": 0,
- "info": 0,
- "unknown": 0
}
}, - "closed_secret_incidents": {
- "total": 0,
- "severity_breakdown": {
- "critical": 0,
- "high": 0,
- "medium": 0,
- "low": 0,
- "info": 0,
- "unknown": 0
}
}
}, - "visibility": "public",
- "external_id": "125",
- "source_criticality": "critical",
- "last_scan": {
- "date": "2021-05-20T12:40:55.662949Z",
- "status": "finished",
- "failing_reason": "DMCA takedown",
- "commits_scanned": 123,
- "branches_scanned": 2,
- "duration": "1:30.454444"
}, - "monitored": true
}
]
Retrieve a source known by GitGuardian.
source_id required | integer Example: 5523 The id of the source to retrieve. |
{- "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": {
- "open_secret_incidents": {
- "total": 0,
- "severity_breakdown": {
- "critical": 0,
- "high": 0,
- "medium": 0,
- "low": 0,
- "info": 0,
- "unknown": 0
}
}, - "closed_secret_incidents": {
- "total": 0,
- "severity_breakdown": {
- "critical": 0,
- "high": 0,
- "medium": 0,
- "low": 0,
- "info": 0,
- "unknown": 0
}
}
}, - "visibility": "public",
- "external_id": "125",
- "source_criticality": "critical",
- "last_scan": {
- "date": "2021-05-20T12:40:55.662949Z",
- "status": "finished",
- "failing_reason": "DMCA takedown",
- "commits_scanned": 123,
- "branches_scanned": 2,
- "duration": "1:30.454444"
}, - "monitored": true
}
List secret incidents linked to a source. Occurrences are not returned in this route.
source_id required | integer Example: 5523 The id of the source to filter on. |
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 |
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. |
feedback | boolean Incidents with or without feedback. |
[- {
- "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",
- "hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "secret_presence": {
- "files_requiring_code_fix": 1,
- "files_pending_merge": 1,
- "files_fixed": 1,
- "outside_vcs": 1,
- "removed_outside_vcs": 0,
- "in_vcs": 3,
- "removed_in_vcs": 0
}, - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "feedback_list": [
- {
- "created_at": "2021-05-20T12:40:55.662949Z",
- "updated_at": "2021-05-20T12:40:55.662949Z",
- "member_id": 42,
- "email": "eric@gitguardian.com",
- "answers": [
- {
- "type": "boolean",
- "field_ref": "actual_secret_yes_no",
- "field_label": "Is it an actual secret?",
- "boolean": true
}
]
}
], - "occurrences": null
}
]
List members of the workspace.
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 Deprecated Enum: owner manager member restricted Filter members based on their access level. Use |
access_level | string Enum: owner manager member restricted Filter members based on their access level. |
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 '-'. |
[- {
- "id": 3252,
- "name": "John Smith",
- "email": "john.smith@example.org",
- "role": "owner",
- "access_level": "owner",
- "created_at": "2023-06-28T16:40:26.897Z",
- "last_login": "2023-06-28T16:40:26.897Z"
}
]
Retrieve an existing workspace member.
If you are using a personal access token, you need to have an access level greater or equal to member
.
member_id required | integer The id of the workspace member |
{- "id": 3252,
- "name": "John Smith",
- "email": "john.smith@example.org",
- "role": "owner",
- "access_level": "owner",
- "created_at": "2023-06-28T16:40:26.897Z",
- "last_login": "2023-06-28T16:40:26.897Z"
}
Delete an existing workspace member.
If you are using a personal access token, you need to have an access level greater or equal to manager
.
member_id required | integer The id of the workspace member |
{- "detail": "Invalid data."
}
Update an existing workspace member.
If you are using a personal access token, you need to have an access level greater or equal to manager
.
member_id required | integer The id of the workspace member |
role | string Deprecated Enum: owner manager member restricted |
access_level | string Enum: owner manager member restricted |
{- "role": "owner",
- "access_level": "owner"
}
{- "id": 3252,
- "name": "John Smith",
- "email": "john.smith@example.org",
- "role": "owner",
- "access_level": "owner",
- "created_at": "2023-06-28T16:40:26.897Z",
- "last_login": "2023-06-28T16:40:26.897Z"
}
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 an access level superior or equal to manager
except if the requested member is yourself.
member_id required | integer The id of the workspace member |
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. |
[- {
- "id": 3252,
- "name": "feature team A",
- "description": "Description of my team",
- "is_global": false,
}
]
Return the permission a member has on a resource.
The permission is the higher value between the different accesses the member can have (direct access, member's teams accesses, and administrator access).
member_id required | integer The id of the workspace member |
resource_type required | string Value: secret-incidents The kind of resource of the access |
resource_id required | integer The id of the resource of the access |
{- "member_id": 1345,
- "resource_id": 3252,
- "resource_type": "secret-incidents",
- "permission": "can_edit"
}
This will create or update a direct access for the member on the resource.
If the member has higher permission from another source, they will take precedence over those you have given.
member_id required | integer The id of the workspace member |
resource_type required | string Value: secret-incidents The kind of resource of the access |
resource_id required | integer The id of the resource of the access |
permission | string Enum: can_view can_edit full_access |
{- "permission": "can_edit"
}
{- "member_id": 1345,
- "resource_id": 3252,
- "resource_type": "secret-incidents",
- "permission": "can_edit"
}