GIgitguardian
NHI Identities

List identities

Changed on

List the non-human identities (NHIs) of the workspace.

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

Filters that take a list accept comma-separated values. The __nin variant of a filter excludes the identities that match it.

An identity id stays the same while the identity holds the same secrets. When a secret is rotated, or two identities merge, the id can change and the owners set on the previous id are not carried over. Look up the identity again rather than storing its id.

The API token must have the Manager access level or above, or be a service account token.

get/v1/nhi/identities

Request

  • Base URL
    https://api.gitguardian.com
  • URL
    https://api.gitguardian.com/v1/nhi/identities
  • Auth
    HTTP bearer

Query parameters

cursorstring

Pagination cursor.

per_pageinteger

Number of items to list per page.

searchstring

Search on the resource id and display name of the identity, and on the email of its owners.

ordering'id' | '-id'

Sort the results by id. Prefix with - to sort in descending order.

source__instring

Source types the identity is found in, for example awssecretsmanager or k8s.

env__instring

Environments of the identity: production, pre-production, staging, testing, development.

policy__instring

Policies the identity breaches: cross_environment, duplicated_secrets, endpoint_secret_high_risk, improper_offboarding, insecure_cloud_deployment_configuration, long_lived_secret, overprivileged_identity, reused_secrets, secret_internally_leaked, secret_publicly_leaked.

risk_criticality__instring

Risk criticality of the identity: low, medium, high, critical.

validity__instring

Validity of the identity: valid, invalid, failed_to_check, no_checker, unknown.

principal_type__instring

Principal types of the identity: no_type, user, service_account, assumable_role, group, application.

owner_id__instring

Owner ids, as returned by the identity owners endpoints. The value 0 matches the identities without an owner.

vault_source_id__instring

Ids of the secrets manager sources that store a secret of the identity. See List sources.

consumer_source_id__instring

Ids of the consumer sources (k8s, gitlabci, githubactions) that use a secret of the identity.

endpoint_source_id__instring

Ids of the endpoint sources that hold a secret of the identity.

provider_source_id__instring

Ids of the provider sources (for example a cloud account) that declare the identity.

detector_group_name__instring

Detectors that classify the secrets of the identity. The value Unknown matches the identities without a classification.

detector_type__instring

Detector types: generic or specific. The value Unknown matches the identities without a classification.

secret_family__instring

Families that the detectors declare. The value Unknown matches the identities without a classification.

secret_category__instring

Categories that the detectors declare. The value Unknown matches the identities without a classification.

secret_provider__instring

Providers that the detectors declare. The value Unknown matches the identities without a classification.

has_ownerboolean

Keep only the identities with (true) or without (false) an owner.

has_detectorboolean

Keep only the identities with (true) or without (false) a secret classified by a detector.

is_adminboolean

Keep only the identities with (true) or without (false) admin-level permissions.

hmsl_hashstring

Keep only the identities that hold a secret matching this HasMySecretLeaked hash.

Response

A page of identities.

idinteger required
namestring required

Display name of the identity.

hmsl_hashstring nullable

HasMySecretLeaked hash of the secret value behind the identity, the key that links it to incidents and to other products. null when the identity holds no hashed secret.

environmentsstring[] required
companiesstring[] required

Services that the secrets of the identity give access to.

detector_typesstring[]
secret_categoriesstring[]
secret_familiesstring[]
secret_providersstring[]
last_used_atstring date-time nullable
created_atstring date-time nullable
breached_policiesstring[] required

NHI policies that the identity breaches.

risk_criticality'low' | 'medium' | 'high' | 'critical' required
is_adminboolean nullable

Whether the identity has admin-level permissions. null when unknown.

validity'valid' | 'invalid' | 'failed_to_check' | 'no_checker' | 'unknown' nullable

Validity of the identity: the highest-ranked validity among its secrets. null when the identity holds no secret.

checked_atstring date-time nullable

Date of the validity check that gives validity.

Example response

[
  {
    "id": 1234,
    "name": "arn:aws:iam::123456789012:user/ci-deployer",
    "companies": [
      "MongoDB"
    ],
    "detectors": [
      {
        "name": "aws_iam",
        "display_name": "AWS Keys"
      }
    ],
    "detector_types": [
      "specific"
    ],
    "provider": {
      "id": 56,
      "type": "awssecretsmanager",
      "name": "prod-eu-west-1"
    },
    "secrets_managers": [
      {
        "id": 56,
        "type": "awssecretsmanager",
        "name": "prod-eu-west-1"
      }
    ],
    "consumers": [
      {
        "id": 56,
        "type": "awssecretsmanager",
        "name": "prod-eu-west-1"
      }
    ],
    "endpoints": [
      {
        "id": 56,
        "type": "awssecretsmanager",
        "name": "prod-eu-west-1"
      }
    ],
    "breached_policies": [
      "long_lived_secret"
    ],
    "owners": [
      {
        "id": 42,
        "email": "jane.doe@example.com"
      }
    ],
    "validity": "valid"
  }
]

Changes