Introduction

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

You can test REST endpoints by using Swagger or by running cURL requests in the command line.

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

To work with the API, authenticate your requests by including your IBM Cloud IAM access token and Account Id.

To retrieve your access token:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Accept: application/json" -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey={API_KEY}" https://iam.bluemix.net/identity/token

Replace {API_KEY} with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

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.

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

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.

Creates a new 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 a 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 a 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.