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.
409 Conflict Resource already exists.
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

Body for query findings

Response

Status Code

  • OK

No Sample Response

This method does not specify any sample responses.

Lists all `Providers` for a given account id.

GET /v1/{account_id}/providers
Request

Custom Headers

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

Path Parameters

  • Account ID

Query Parameters

  • Limit the number of the returned documents to the specified number. limit value should be greater than 1. In case of 0 and 1, status code 400 will be thrown.

    Constraints: value ≥ 2

  • The offset is the index of the item from which you want to start returning data from. Default is 0.

  • The first provider_id to include in the result (sorted in ascending order). Ignored if not provided.

  • The last provider_id to include in the result (sorted in ascending order). Ignored if not provided.

Response

Response including listed providers

Status Code

  • List all Providers successful

No Sample Response

This method does not specify any sample responses.

Creates a new `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}

Body for Note creation

Response

Provides a detailed description of a Note.

Status Code

  • Note created successfully

No Sample Response

This method does not specify any sample responses.

Lists all `Notes` for a given 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. page_size value should be greater than 1. In case of 0 and 1, status code 400 will be thrown.

    Constraints: value ≥ 2

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

Response

Response including listed notes.

Status Code

  • List all Notes successful

No Sample Response

This method does not specify any sample responses.

Returns the requested `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

  • Return the requested Note successful

No Sample Response

This method does not specify any sample responses.

Updates an existing `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}

Body for Note updation

Response

Provides a detailed description of a Note.

Status Code

  • Update an existing Note Successful

No Sample Response

This method does not specify any sample responses.

Deletes the given `Note` from the system.

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

  • Delete the given Note successful

No Sample Response

This method does not specify any sample responses.

Gets the `Note` attached to the given `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

  • Gets the Note attached to the given Occurrence successful

No Sample Response

This method does not specify any sample responses.

Creates a new `Occurrence`. Use this method to create `Occurrences` for a resource.

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}

Body for Occurence creation

Response

Occurrence includes information about analysis occurrences for an image.

Status Code

  • Create a new Occurence successful

No Sample Response

This method does not specify any sample responses.

Lists active `Occurrences` for a given provider matching the filters.

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. page_size value should be greater than 1. In case of 0 and 1, status code 400 will be thrown.

    Constraints: value ≥ 2

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

Response

Response including listed active occurrences.

Status Code

  • All active Occurences listed successfully

No Sample Response

This method does not specify any sample responses.

Lists `Occurrences` referencing the specified `Note`. Use this method to get all occurrences referencing your `Note` across all your customer providers.

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. page_size value should be greater than 1. In case of 0 and 1, status code 400 will be thrown.

    Constraints: value ≥ 2

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

Response

Response including listed occurrences for a note.

Status Code

  • Occurence referenced the specified Note successfully

No Sample Response

This method does not specify any sample responses.

Returns the requested `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

  • Returns the requested Occurence successful

No Sample Response

This method does not specify any sample responses.

Updates an existing `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}

Body for Occurence updation

Response

Occurrence includes information about analysis occurrences for an image.

Status Code

  • Update an existing Occurence successfull

No Sample Response

This method does not specify any sample responses.

Deletes the given `Occurrence` from the system.

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

  • Delete the Occurence successful

No Sample Response

This method does not specify any sample responses.