Introduction

The IBM Cloud™ Security Advisor service provides REST endpoints to post metadata and findings.

API endpoint

https://{region}.secadvisor.cloud.ibm.com/findings/

Replace {region} with the prefix that represents the geographic area where your Security Advisor service instance resides. Currently, the us-south and eu-gb regions are supported.

Authentication

This API is protected by IBM Cloud Identity and Access Management. You must also provide your account ID to authenticate your requests, you must provide your IBM Cloud account ID and an IBM Cloud Identity and Access Management IAM token. Your account ID can be found in your dashboard by clicking Manage > Account > Account settings. To obtain an IAM token, you can use the following steps.

  1. In the IBM Cloud dashboard, click Manage > Access (IAM).
  2. Select IBM Cloud API keys.
  3. Click Create an IBM Cloud API key
  4. Give your key a name and describe it. Click Create. A screen displays with your your key.
  5. Click Copy or Download your key. When you close the screen, you can no longer access the key.
  6. Make the following cURL request with the API key that you created.

    curl -k -X POST \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --header "Accept: application/json" \
     --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
     --data-urlencode "apikey={apikey}" \
     "https://iam.cloud.ibm.com/identity/token"
    

For more information, see the IAM documentation.

Error handling

The IBM Cloud™ Security Advisor service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Status code summary
Status code Description
200 OK Everything worked as expected.
201 OK Everything worked as expected. No content
400 Bad Request The request was unsuccessful, often due to a missing required parameter.
401 Unauthorized The parameters were valid but the request failed due insufficient permissions.
404 Not Found The requested resource doesn't exist.
410 Gone The requested resource was deleted and no longer exists.
429 Too Many Requests Too many requests hit the API too quickly.
500 Server Error Something went wrong on Security Advisor's end.

Methods

Query findings

query findings

POST /v1/{account_id}/graph
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

  • Allowable values: [application/graphql,application/json]

Path Parameters

  • Account ID

Example:
Response

Status Code

  • OK

No Sample Response

This method does not specify any sample responses.

List all Providers for an account

GET /v1/{account_id}/providers/
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

Query Parameters

  • The number of providers to return in the list.

  • Token to provide to skip to a particular spot in the list.

Response

Response including listed providers

Status Code

  • List all Providers successful

No Sample Response

This method does not specify any sample responses.

Create a note

POST /v1/{account_id}/providers/{provider_id}/notes
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • Part of parent. This field contains the provider ID. For example: providers/{provider_id}

Provides a detailed description of a Note.

Response

Provides a detailed description of a Note.

Status Code

No Sample Response

This method does not specify any sample responses.

List notes for a provider

GET /v1/{account_id}/providers/{provider_id}/notes
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • Part of parent. This field contains the provider_id for example: providers/{provider_id}

Query Parameters

  • Number of notes to return in the list.

  • Token to provide to skip to a particular spot in the list.

Response

Response including listed notes.

Status Code

No Sample Response

This method does not specify any sample responses.

Get a note

GET /v1/{account_id}/providers/{provider_id}/notes/{note_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • First part of note name: providers/{provider_id}/notes/{note_id}

  • Second part of note name: providers/{provider_id}/notes/{note_id}

Response

Provides a detailed description of a Note.

Status Code

No Sample Response

This method does not specify any sample responses.

Update a note

PUT /v1/{account_id}/providers/{provider_id}/notes/{note_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • First part of note name: providers/{provider_id}/notes/{note_id}

  • Second part of note name: providers/{provider_id}/notes/{note_id}

Provides a detailed description of a Note.

Response

Provides a detailed description of a Note.

Status Code

No Sample Response

This method does not specify any sample responses.

Delete a note

DELETE /v1/{account_id}/providers/{provider_id}/notes/{note_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • First part of note name: providers/{provider_id}/notes/{note_id}

  • Second part of note name: providers/{provider_id}/notes/{note_id}

Response

A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. The JSON representation for Empty is empty JSON object {}.

Status Code

No Sample Response

This method does not specify any sample responses.

Get the note attached to a occurrence

GET /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}/note
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • First part of occurrence name: providers/{provider_id}/occurrences/{occurrence_id}

  • Second part of occurrence name: providers/{provider_id}/occurrences/{occurrence_id}

Response

Provides a detailed description of a Note.

Status Code

No Sample Response

This method does not specify any sample responses.

Create an occurrence

POST /v1/{account_id}/providers/{provider_id}/occurrences
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

  • It allows replacing an existing occurrence when set to true.

Path Parameters

  • Account ID

  • Part of parent. This contains the provider_id for example: providers/{provider_id}

Occurrence includes information about analysis occurrences for an image.

Response

Occurrence includes information about analysis occurrences for an image.

Status Code

No Sample Response

This method does not specify any sample responses.

List occurrences for a provider

GET /v1/{account_id}/providers/{provider_id}/occurrences
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • Part of parent. This contains the provider_id for example: providers/{provider_id}

Query Parameters

  • Number of occurrences to return in the list.

  • Token to provide to skip to a particular spot in the list.

Response

Response including listed active occurrences.

Status Code

No Sample Response

This method does not specify any sample responses.

List occurrences for a note

GET /v1/{account_id}/providers/{provider_id}/notes/{note_id}/occurrences
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • First part of note name: providers/{provider_id}/notes/{note_id}

  • Second part of note name: providers/{provider_id}/notes/{note_id}

Query Parameters

  • Number of notes to return in the list.

  • Token to provide to skip to a particular spot in the list.

Response

Response including listed occurrences for a note.

Status Code

No Sample Response

This method does not specify any sample responses.

Get an occurrence

GET /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • First part of occurrence name: providers/{provider_id}/occurrences/{occurrence_id}

  • Second part of occurrence name: providers/{provider_id}/occurrences/{occurrence_id}

Response

Response including listed active occurrences.

Status Code

No Sample Response

This method does not specify any sample responses.

Update an occurrence

PUT /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • First part of occurrence name: providers/{provider_id}/occurrences/{occurrence_id}

  • Second part of occurrence name: providers/{provider_id}/occurrences/{occurrence_id}

Occurrence includes information about analysis occurrences for an image.

Response

Occurrence includes information about analysis occurrences for an image.

Status Code

No Sample Response

This method does not specify any sample responses.

Delete an occurrence

DELETE /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • First part of occurrence name: providers/{provider_id}/notes/{occurrence_id}

  • Second part of occurrence name: providers/{provider_id}/notes/{occurrence_id}

Response

A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. The JSON representation for Empty is empty JSON object {}.

Status Code

No Sample Response

This method does not specify any sample responses.