Security and Compliance Center API

Introduction

Last updated: 2023-07-14

With IBM Cloud® Security and Compliance Center, you can embed security checks into your everyday workflows to continuously monitor for security vulnerabilities across multiple cloud environments. You can manage your current account settings such as the location in which the data that is generated by the service is stored and processed.

For highly regulated industries, such as financial services, achieving continuous compliance within a cloud environment is an important first step toward protecting customer and application data. Historically, that process was difficult and manual, which placed your organization at risk. But, with Security and Compliance Center, you can integrate daily, automatic compliance checks into your development lifecycle to help minimize that risk.

Before you get started with this API, you must first complete the initial set up. For help, see Getting started with Security and Compliance Center.

An SDK for Go is available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy.

import (
	"github.com/IBM/scc-go-sdk/v5/securityandcompliancecenterapiv3"
)

Go get

go get -u github.com/IBM/scc-go-sdk/v5/securityandcompliancecenterapiv3

View on GitHub

https://github.com/IBM/scc-go-sdk

Installing the Python SDK

pip install --upgrade "ibm-scc"

View on GitHub:

https://github.com/IBM/scc-python-sdk

Installing the Java SDK

Maven
<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>security-and-compliance-center-sdk</artifactId>
    <version>${version}</version>
</dependency>

Gradle
compile 'com.ibm.cloud:security-and-compliance-center-sdk:${version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/scc-java-sdk

Installing the Node SDK

npm install --save ibm-scc

View on GitHub:

https://github.com/IBM/scc-node-sdk

Endpoint URLs

Security and Compliance Center supports location-specific endpoint URLs that you can use to interact with the service over the public internet. A location represents the geographic area where your requests are handled and processed. When you call this API, be sure to use the endpoint URL that corresponds with the location settings that are configured in the Security and Compliance Center.

For more information about viewing and managing your location settings, check out the docs.

Endpoint URLs by region

Americas:
- United States
  - Dallas: https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3
- Canada:
  - Toronto: https://ca-tor.compliance.cloud.ibm.com/instances/{instance_id}/v3
European Union:
- Frankfurt: https://eu-de.compliance.cloud.ibm.com/instances/{instance_id}/v3

To find your instance ID, you can look in the settings page of the Security and Compliance UI or in your resource list.

Base URL

https://{region}.compliance.cloud.ibm.com/instances/{instance_id}/v3

Example for the us-south region

import (
    "encoding/json"
    "fmt"
    "github.com/IBM/go-sdk-core/v5/core"
    scc "github.com/IBM/scc-go-sdk/securityandcompliancecenterapiv3"
)

func main() {

    securityAndComplianceCenterService, err := scc.NewSecurityAndComplianceCenterApiV3(&scc.SecurityAndComplianceCenterApiV3Options {
        URL: "https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3",
        Authenticator: & core.IamAuthenticator {
            ApiKey: "<IAM_API_KEY>",
        },
    })

    if err != nil {
        panic(err)
    }
}

Example for the us-south region

from ibm_scc.security_and_compliance_center_api_v3 import SecurityAndComplianceCenterApiV3
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('<IAM_API_KEY>')

service = SecurityAndComplianceCenterApiV3(authenticator=authenticator)

service.set_service_url('https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3')

Example for the us-south region

import com.ibm.cloud.security_and_compliance_center_api.v3.SecurityAndComplianceCenterApi;
import com.ibm.cloud.security_and_compliance_center_api.v3.model.*;
import com.ibm.cloud.sdk.core.http.Response;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

import java.util.Collections;
...

// Create an IAM authenticator
IamAuthenticator iamAuthenticator = new IamAuthenticator.Builder()
        .apikey("<API_KEY>")
        .build();

// Construct the service client
SecurityAndComplianceCenterApi securityAndComplianceCenterService = new SecurityAndComplianceCenterApi("My Security And Compliance Center Service", iamAuthenticator);

// Set the service URL
securityAndComplianceCenterService.setServiceUrl("https://us-south.cloud.ibm.com/instances/{instance_id}/v3");

Example for the us-south region

const { SecurityAndComplianceCenterApiV3 } = require('ibm-scc@4.0.0');
const { IamAuthenticator } = require('ibm-cloud-sdk-core');

const authenticator = new IamAuthenticator({
    apikey: '{apikey}'
});

const securityAndComplianceCenterService = new SecurityAndComplianceCenterApiV3({
    authenticator: authenticator
});

securityAndComplianceCenterService.setServiceUrl('{https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3}');

Authentication

Authorization to the Security and Compliance Center API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

To work with the API, include a valid IAM token in each outgoing request to the service. You can generate an access token by first creating an API key and then exchanging your API key for an IBM Cloud IAM token.

Don't have an API key? Try running ibmcloud iam oauth-tokens in the IBM Cloud Shell to quickly generate a personal access token.

To generate an access token from your API key, use the following cURL command.

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --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=<API_KEY>'

Replace <API_KEY> with your IBM Cloud API key.

When you use the SDK, configure an IAM authenticator with an IBM Cloud IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can configure an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

Example API request

curl -X {request_method} "https://{region}.compliance.cloud.ibm.com/instances/{instance_id}/v3/{method_endpoint}" --header "Authorization: Bearer {IAM_token}"

Replace {IAM_token} with your access token.

Authentication example

import (
    "encoding/json"
    "fmt"
    "github.com/IBM/go-sdk-core/v5/core"
    scc "github.com/IBM/scc-go-sdk/securityandcompliancecenterapiv3"
)

func main() {

    securityAndComplianceCenterService, err := scc.NewSecurityAndComplianceCenterApiV3(&scc.SecurityAndComplianceCenterApiV3Options {
        URL: "https://{region}.compliance.cloud.ibm.com/instances/{instance_id}/v3",
        Authenticator: & core.IamAuthenticator {
            ApiKey: "<IAM_API_KEY>",
        },
    })

    if err != nil {
        panic(err)
    }
}

Authentication example

from ibm_scc.security_and_compliance_center_api_v3 import SecurityAndComplianceCenterApiV3
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('<IAM_API_KEY>')

service = SecurityAndComplianceCenterApiV3(authenticator=authenticator)

service.set_service_url('https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3')

Authentication example

import com.ibm.cloud.security_and_compliance_center_api.v3.SecurityAndComplianceCenterApi;
import com.ibm.cloud.security_and_compliance_center_api.v3.model.*;
import com.ibm.cloud.sdk.core.http.Response;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

import java.util.Collections;
...

// Create an IAM authenticator
IamAuthenticator iamAuthenticator = new IamAuthenticator.Builder()
        .apikey("<API_KEY>")
        .build();

// Construct the service client
SecurityAndComplianceCenterApi securityAndComplianceCenterService = new SecurityAndComplianceCenterApi("My Security And Compliance Center Service", iamAuthenticator);

// Set the service URL
securityAndComplianceCenterService.setServiceUrl("https://{region}.cloud.ibm.com/instances/{instance_id}/v3");

Authentication example

const { SecurityAndComplianceCenterApiV3 } = require('ibm-scc@4.0.0');
const { IamAuthenticator } = require('ibm-cloud-sdk-core');

const authenticator = new IamAuthenticator({
    apikey: '{apikey}'
});

const securityAndComplianceCenterService = new SecurityAndComplianceCenterApiV3({
    authenticator: authenticator
});

securityAndComplianceCenterService.setServiceUrl('{url}');

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker.

For more information about how to track activity, see Auditing events for Security and Compliance Center.

Error handling

The Security and Compliance Center API use standard HTTP status codes to indicate whether a method was completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is a failure, and a response in the 5xx range usually indicates an internal system error.

Status code summary
Status code	Description
200 OK	Everything worked as expected.
300 Multiple Choices	The request has more than one possible responses.
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 to insufficient permissions.
402 Payment Required	Your Trial plan is now expired.
403 Forbidden	You are not allowed to access this resource.
404 Not Found	The requested resource doesn't exist.
409 Conflict	The requested resource conflicts with an existing resource.
410 Gone	The requested resource was deleted and no longer exists.
429 Too Many Requests	Too many requests were sent to the API too quickly.
500 Internal Server Error	Something went wrong on Security and Compliance Center's end.

Example error handling

import (
    scc "github.com/IBM/scc-go-sdk/securityandcompliancecenterapiv3"
)

// Instantiate a service
securityAndComplianceCenterService, err := scc.NewSecurityAndComplianceCenterApiV3(options)

// Check for errors
if err != nil {
  panic(err)
}

// Call a method
result, response, err := securityAndComplianceCenterService.MethodName(&methodOptions)

// Check for errors
if err != nil {
  panic(err)
}

Example error handling

from ibm_scc.security_and_compliance_center_api_v3 import SecurityAndComplianceCenterApiV3
from ibm_cloud_sdk_core import ApiException

# Instantiate a service
try:
securityAndComplianceCenterService = SecurityAndComplianceCenterApiV3(authenticator)
except Exception as err:
    raise err

# Call a method
try:
    response = securityAndComplianceCenterService.getmethod(params)
except ApiException as err:
    raise err

Example error handling

import com.ibm.cloud.security_and_compliance_center_api.v3.SecurityAndComplianceCenterApi;

// Instantiate a service
try {
    SecurityAndComplianceCenterApi securityAndComplianceCenterApiService = SecurityAndComplianceCenterApi.newInstance();
}
// Check for errors 
catch (Exception e) {
    logger.error(String.format("Service returned status code %s: %s%nError details: %s",
        e.getStatusCode(), e.getMessage(), e.getDebuggingInfo()), e);
}
// Call a method
try {
    response = securityAndComplianceCenterApiService.getMethod(methodOptions);
}
// Check for errors 
catch (Exception e) {
    logger.error(String.format("Service returned status code %s: %s%nError details: %s",
        e.getStatusCode(), e.getMessage(), e.getDebuggingInfo()), e);
}

Example error handling

securityAndComplianceCenterService.method(params)
  .catch(err => {
    console.log('Error:', err);
  });

Pagination

Some API requests might return a large number of results. To avoid performance issues, the APIs return one page of results at a time, with a limited number of results on each page.

The default page size is 100 objects. To use a different page size, use the limit query parameter.

For any request that uses pagination, the response includes URLs you can use to make subsequent requests:

first.href: The URL for requesting the first page of results.
last.href: The URL for requesting the last page of results.
next: The URL for requesting the next page of results.

You can also use start as a bookmark.

Retrieve the settings of your service instance.

GET /settings

(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) GetSettings(getSettingsOptions *GetSettingsOptions) (result *Settings, response *core.DetailedResponse, err error)

(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) GetSettingsWithContext(ctx context.Context, getSettingsOptions *GetSettingsOptions) (result *Settings, response *core.DetailedResponse, err error)

getSettings(params)

get_settings(
        self,
        *,
        x_correlation_id: str = None,
        x_request_id: str = None,
        **kwargs,
    ) -> DetailedResponse

ServiceCall<Settings> getSettings(GetSettingsOptions getSettingsOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

compliance.admin.settings-read

Auditing

Calling this method generates the following auditing event.

compliance.admin-settings.read

Request

Instantiate the GetSettingsOptions struct and set the fields to provide parameter values for the GetSettings method.

Use the GetSettingsOptions.Builder to create a GetSettingsOptions object that contains the parameter values for the getSettings method.

Custom Headers

X-Correlation-ID
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9 ,\-_]+$
Example: 1a2b3c4d-5e6f-4a7b-8c9d-e0f1a2b3c4d5
X-Request-ID
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9 ,\-_]+$

parameter

WithContext method only

GetSettingsOptions

The GetSettings options.

parameters

xCorrelationId
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/
Examples:
value
_source
_lines
_html
xRequestId
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/

parameters

x_correlation_id
str
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/
Examples:
value
_source
_lines
_html
x_request_id
str
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/

GetSettingsOptions

The getSettings options.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/settings"

Example request

getSettingsOptions := securityAndComplianceCenterApiService.NewGetSettingsOptions()
getSettingsOptions.SetXCorrelationID(xCorrelationIdLink)

settings, response, err := securityAndComplianceCenterApiService.GetSettings(getSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(settings, "", "  ")
fmt.Println(string(b))

Example request

const params = {
  xCorrelationId: xCorrelationIdLink,
};

let res;
try {
  res = await securityAndComplianceCenterApiService.getSettings(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

response = security_and_compliance_center_api_service.get_settings(
  x_correlation_id=x_correlation_id_link,
)
settings = response.get_result()

print(json.dumps(settings, indent=2))

Example request

GetSettingsOptions getSettingsOptions = new GetSettingsOptions.Builder()
  .xCorrelationId(xCorrelationIdLink)
  .build();

Response<Settings> response = securityAndComplianceCenterApiService.getSettings(getSettingsOptions).execute();
Settings settings = response.getResult();

System.out.println(settings);

Response

Response Body

Settings

The settings.

Settings

The settings.

Examples:

View

Settings

The settings.

Examples:

View

Settings

The settings.

Examples:

View

Settings

The settings.

Examples:

View

Status Code

200
The settings were successfully retrieved.
401
You are not authorized to make this request.
403
You are not allowed to make this request.
404
The specified resource was not found.

Example responses

Status 200

{
  "event_notifications": {
    "instance_crn": "crn:v1:public:event-notifications:us-south:a/2411ffdc16844b07a42521c3443f456d:14c58404-b332-4178-86de-83141a7f93af::",
    "updated_on": "2023-04-19T17:39:44.668Z",
    "source_id": "crn:v1:bluemix:public:compliance:global:a/2411ffdc16844b07a42521c3443f456d:::"
  },
  "object_storage": {
    "instance_crn": "crn:v1:public:cloud-object-storage:global:a/2411ffdc16844b07a42521c3443f456d:ecca7d23-77d0-4a9b-8a24-3b761c63a460::",
    "bucket": "scc-bucket",
    "bucket_location": "us-south",
    "bucket_endpoint": "s3.us.private.cloud-object-storage.test.appdomain.cloud",
    "updated_on": "2023-03-01T22:00:05.917Z"
  }
}

Success example

{
  "event_notifications": {
    "instance_crn": "crn:v1:public:event-notifications:us-south:a/2411ffdc16844b07a42521c3443f456d:14c58404-b332-4178-86de-83141a7f93af::",
    "updated_on": "2023-04-19T17:39:44.668Z",
    "source_id": "crn:v1:bluemix:public:compliance:global:a/2411ffdc16844b07a42521c3443f456d:::"
  },
  "object_storage": {
    "instance_crn": "crn:v1:public:cloud-object-storage:global:a/2411ffdc16844b07a42521c3443f456d:ecca7d23-77d0-4a9b-8a24-3b761c63a460::",
    "bucket": "scc-bucket",
    "bucket_location": "us-south",
    "bucket_endpoint": "s3.us.private.cloud-object-storage.test.appdomain.cloud",
    "updated_on": "2023-03-01T22:00:05.917Z"
  }
}

Status 401

{
  "status_code": 401,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ]
}

Error example

{
  "status_code": 401,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ]
}

Status 403

{
  "status_code": 403,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "request_not_authorized",
      "message": "The request could not be authorized",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Error example

{
  "status_code": 403,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "request_not_authorized",
      "message": "The request could not be authorized",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Status 404

{
  "status_code": 404,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "not_found",
      "message": "The requested resource was not found\"",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Error example

{
  "status_code": 404,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "not_found",
      "message": "The requested resource was not found\"",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Update the settings of your service instance.

PATCH /settings

(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) UpdateSettings(updateSettingsOptions *UpdateSettingsOptions) (result *Settings, response *core.DetailedResponse, err error)

(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) UpdateSettingsWithContext(ctx context.Context, updateSettingsOptions *UpdateSettingsOptions) (result *Settings, response *core.DetailedResponse, err error)

updateSettings(params)

update_settings(
        self,
        *,
        event_notifications: 'EventNotifications' = None,
        object_storage: 'ObjectStorage' = None,
        x_correlation_id: str = None,
        x_request_id: str = None,
        **kwargs,
    ) -> DetailedResponse

ServiceCall<Settings> updateSettings(UpdateSettingsOptions updateSettingsOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

compliance.admin.settings-update

Auditing

Calling this method generates the following auditing event.

compliance.admin-settings.update

Request

Instantiate the UpdateSettingsOptions struct and set the fields to provide parameter values for the UpdateSettings method.

Use the UpdateSettingsOptions.Builder to create a UpdateSettingsOptions object that contains the parameter values for the updateSettings method.

Custom Headers

X-Correlation-ID
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9 ,\-_]+$
Example: 1a2b3c4d-5e6f-4a7b-8c9d-e0f1a2b3c4d5
X-Request-ID
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9 ,\-_]+$

Request Body

Required*

Settings

The request body to update your settings.

Examples:

View

parameter

WithContext method only

UpdateSettingsOptions

The UpdateSettings options.

parameters

eventNotifications
The Event Notifications settings.

Examples:
View
objectStorage
The Cloud Object Storage settings.

Examples:
View
xCorrelationId
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/
Examples:
value
_source
_lines
_html
xRequestId
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/

parameters

event_notifications
The Event Notifications settings.

Examples:
View
object_storage
The Cloud Object Storage settings.

Examples:
View
x_correlation_id
str
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/
Examples:
value
_source
_lines
_html
x_request_id
str
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/

UpdateSettingsOptions

The updateSettings options.

Example request

curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "event_notifications": { "instance_crn": "crn:v1:bluemix:public:event-notifications:us-south:a/ff88f007f9ff4622aac4fbc0eda36255:7199ae60-a214-4dd8-9bf7-ce571de49d01::", "source_name": "compliance", "source_description": "This source is used for integration with IBM Cloud Security and Compliance Center." }, "object_storage": { "instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/ff88f007f9ff4622aac4fbc0eda36255:7199ae60-a214-4dd8-9bf7-ce571de49d01::", "bucket": "px-scan-results", "bucket_location": "us-south" } }'   "{base_url}/settings"

Example request

eventNotificationsModel := &securityandcompliancecenterapiv3.EventNotifications{
  InstanceCrn: &eventNotificationsCrnForUpdateSettingsLink,
  SourceDescription: core.StringPtr("This source is used for integration with IBM Cloud Security and Compliance Center."),
  SourceName: core.StringPtr("compliance"),
}

objectStorageModel := &securityandcompliancecenterapiv3.ObjectStorage{
  InstanceCrn: &objectStorageCrnForUpdateSettingsLink,
  Bucket: &objectStorageBucketForUpdateSettingsLink,
  BucketLocation: &objectStorageLocationForUpdateSettingsLink,
}

updateSettingsOptions := securityAndComplianceCenterApiService.NewUpdateSettingsOptions()
updateSettingsOptions.SetEventNotifications(eventNotificationsModel)
updateSettingsOptions.SetObjectStorage(objectStorageModel)
updateSettingsOptions.SetXCorrelationID(xCorrelationIdLink)

settings, response, err := securityAndComplianceCenterApiService.UpdateSettings(updateSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(settings, "", "  ")
fmt.Println(string(b))

Example request

// Request models needed by this operation.

// EventNotifications
const eventNotificationsModel = {
  instance_crn: eventNotificationsCrnForUpdateSettingsLink,
  source_description: 'This source is used for integration with IBM Cloud Security and Compliance Center.',
  source_name: 'compliance',
};

// ObjectStorage
const objectStorageModel = {
  instance_crn: objectStorageCrnForUpdateSettingsLink,
  bucket: objectStorageBucketForUpdateSettingsLink,
  bucket_location: objectStorageLocationForUpdateSettingsLink,
};

const params = {
  eventNotifications: eventNotificationsModel,
  objectStorage: objectStorageModel,
  xCorrelationId: xCorrelationIdLink,
};

let res;
try {
  res = await securityAndComplianceCenterApiService.updateSettings(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

event_notifications_model = {
  'instance_crn': event_notifications_crn_for_update_settings_link,
  'source_description': 'This source is used for integration with IBM Cloud Security and Compliance Center.',
  'source_name': 'compliance',
}

object_storage_model = {
  'instance_crn': object_storage_crn_for_update_settings_link,
  'bucket': object_storage_bucket_for_update_settings_link,
  'bucket_location': object_storage_location_for_update_settings_link,
}

response = security_and_compliance_center_api_service.update_settings(
  event_notifications=event_notifications_model,
  object_storage=object_storage_model,
  x_correlation_id=x_correlation_id_link,
)
settings = response.get_result()

print(json.dumps(settings, indent=2))

Example request

EventNotifications eventNotificationsModel = new EventNotifications.Builder()
  .instanceCrn(eventNotificationsCrnForUpdateSettingsLink)
  .sourceDescription("This source is used for integration with IBM Cloud Security and Compliance Center.")
  .sourceName("compliance")
  .build();
ObjectStorage objectStorageModel = new ObjectStorage.Builder()
  .instanceCrn(objectStorageCrnForUpdateSettingsLink)
  .bucket(objectStorageBucketForUpdateSettingsLink)
  .bucketLocation(objectStorageLocationForUpdateSettingsLink)
  .build();
UpdateSettingsOptions updateSettingsOptions = new UpdateSettingsOptions.Builder()
  .eventNotifications(eventNotificationsModel)
  .objectStorage(objectStorageModel)
  .xCorrelationId(xCorrelationIdLink)
  .build();

Response<Settings> response = securityAndComplianceCenterApiService.updateSettings(updateSettingsOptions).execute();
Settings settings = response.getResult();

System.out.println(settings);

Response

Response Body

Settings

The settings.

Settings

The settings.

Examples:

View

Settings

The settings.

Examples:

View

Settings

The settings.

Examples:

View

Settings

The settings.

Examples:

View

Status Code

200
The settings were successfully updated.
204
The settings were not changed. No content is provided.
400
The server cannot process the request.
401
You are not authorized to make this request.
403
You are not allowed to make this request.
404
The specified resource was not found.

Example responses

Status 200

{
  "event_notifications": {
    "instance_crn": "crn:v1:bluemix:public:event-notifications:us-south:a/130003ea8bfa43c5aacea07a86da3000:1c858449-3537-45b8-9d39-2707115b4cc7::",
    "updated_on": "2023-04-19T17:39:44.668Z",
    "source_id": "crn:v1:bluemix:public:compliance:global:a/130003ea8bfa43c5aacea07a86da3000:::"
  },
  "object_storage": {
    "instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/130003ea8bfa43c5aacea07a86da3000:1c858449-3537-45b8-9d39-2707115b4cc7::",
    "bucket": "scc-bucket",
    "bucket_location": "us-south",
    "bucket_endpoint": "s3.us.private.cloud-object-storage.test.appdomain.cloud",
    "updated_on": "2023-03-01T22:00:05.917Z"
  }
}

Success example

{
  "event_notifications": {
    "instance_crn": "crn:v1:bluemix:public:event-notifications:us-south:a/130003ea8bfa43c5aacea07a86da3000:1c858449-3537-45b8-9d39-2707115b4cc7::",
    "updated_on": "2023-04-19T17:39:44.668Z",
    "source_id": "crn:v1:bluemix:public:compliance:global:a/130003ea8bfa43c5aacea07a86da3000:::"
  },
  "object_storage": {
    "instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/130003ea8bfa43c5aacea07a86da3000:1c858449-3537-45b8-9d39-2707115b4cc7::",
    "bucket": "scc-bucket",
    "bucket_location": "us-south",
    "bucket_endpoint": "s3.us.private.cloud-object-storage.test.appdomain.cloud",
    "updated_on": "2023-03-01T22:00:05.917Z"
  }
}

Status 400

{
  "status_code": 400,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "bad_request",
      "message": "malformed request body: missing Event Notifications instance CRN, or Cloud Object Storage instance CRN",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin",
      "ref": "ADM22001"
    }
  ]
}

Error example

{
  "status_code": 400,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "bad_request",
      "message": "malformed request body: missing Event Notifications instance CRN, or Cloud Object Storage instance CRN",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin",
      "ref": "ADM22001"
    }
  ]
}

Status 401

{
  "status_code": 401,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ]
}

Error example

{
  "status_code": 401,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ]
}

Status 403

{
  "status_code": 403,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "request_not_authorized",
      "message": "The request could not be authorized",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Error example

{
  "status_code": 403,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "request_not_authorized",
      "message": "The request could not be authorized",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Status 404

{
  "status_code": 404,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "not_found",
      "message": "The requested resource was not found\"",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Error example

{
  "status_code": 404,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "not_found",
      "message": "The requested resource was not found\"",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Send a test event to your Event Notifications instance to ensure that the events that are generated by Security and Compliance Center are being forwarded to Event Notifications. For more information, see Enabling event notifications.

POST /test_event

(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) PostTestEvent(postTestEventOptions *PostTestEventOptions) (result *TestEvent, response *core.DetailedResponse, err error)

(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) PostTestEventWithContext(ctx context.Context, postTestEventOptions *PostTestEventOptions) (result *TestEvent, response *core.DetailedResponse, err error)

postTestEvent(params)

post_test_event(
        self,
        *,
        x_correlation_id: str = None,
        x_request_id: str = None,
        **kwargs,
    ) -> DetailedResponse

ServiceCall<TestEvent> postTestEvent(PostTestEventOptions postTestEventOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

compliance.admin.test-event-send

Auditing

Calling this method generates the following auditing event.

compliance.admin-test-event.send

Request

Instantiate the PostTestEventOptions struct and set the fields to provide parameter values for the PostTestEvent method.

Use the PostTestEventOptions.Builder to create a PostTestEventOptions object that contains the parameter values for the postTestEvent method.

Custom Headers

X-Correlation-ID
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9 ,\-_]+$
Example: 1a2b3c4d-5e6f-4a7b-8c9d-e0f1a2b3c4d5
X-Request-ID
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9 ,\-_]+$

parameter

WithContext method only

PostTestEventOptions

The PostTestEvent options.

parameters

xCorrelationId
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/
Examples:
value
_source
_lines
_html
xRequestId
string
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/

parameters

x_correlation_id
str
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/
Examples:
value
_source
_lines
_html
x_request_id
str
The supplied or generated value of this header is logged for a request, and repeated in a response header for the corresponding response. The same value is not used for downstream requests and retries of those requests. If a value of this header is not supplied in a request, the service generates a random (version 4) UUID.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression /^[a-zA-Z0-9 ,\\-_]+$/

PostTestEventOptions

The postTestEvent options.

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/test_event"

Example request

postTestEventOptions := securityAndComplianceCenterApiService.NewPostTestEventOptions()
postTestEventOptions.SetXCorrelationID(xCorrelationIdLink)

testEvent, response, err := securityAndComplianceCenterApiService.PostTestEvent(postTestEventOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(testEvent, "", "  ")
fmt.Println(string(b))

Example request

const params = {
  xCorrelationId: xCorrelationIdLink,
};

let res;
try {
  res = await securityAndComplianceCenterApiService.postTestEvent(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

response = security_and_compliance_center_api_service.post_test_event(
  x_correlation_id=x_correlation_id_link,
)
test_event = response.get_result()

print(json.dumps(test_event, indent=2))

Example request

PostTestEventOptions postTestEventOptions = new PostTestEventOptions.Builder()
  .xCorrelationId(xCorrelationIdLink)
  .build();

Response<TestEvent> response = securityAndComplianceCenterApiService.postTestEvent(postTestEventOptions).execute();
TestEvent testEvent = response.getResult();

System.out.println(testEvent);

Response

Response Body

TestEvent

The details of a test event response.

TestEvent

The details of a test event response.

Examples:

View

TestEvent

The details of a test event response.

Examples:

View

TestEvent

The details of a test event response.

Examples:

View

TestEvent

The details of a test event response.

Examples:

View

Status Code

202
The event was successfully sent to your Event Notifications instance.
401
You are not authorized to make this request.
403
You are not allowed to make this request.
404
The specified resource was not found.

Example responses

{ "success": true }
{ "success": true }

Status 401

{
  "status_code": 401,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ]
}

Error example

{
  "status_code": 401,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ]
}

Status 403

{
  "status_code": 403,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "request_not_authorized",
      "message": "The request could not be authorized",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Error example

{
  "status_code": 403,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "request_not_authorized",
      "message": "The request could not be authorized",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Status 404

{
  "status_code": 404,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "not_found",
      "message": "The requested resource was not found\"",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Error example

{
  "status_code": 404,
  "trace": "b05ed07e-c4d9-4285-841c-1e954c0b4a0e",
  "errors": [
    {
      "code": "not_found",
      "message": "The requested resource was not found\"",
      "more_info": "https://cloud.ibm.com/apidocs/security-compliance-admin"
    }
  ]
}

Retrieve all of the control libraries that are available in your account, including predefined, and custom libraries.

With Security and Compliance Center, you can create a custom control library that is specific to your organization's needs. You define the controls and specifications before you map previously created assessments. Each control has several specifications and assessments that are mapped to it. A specification is a defined requirement that is specific to a component. An assessment, or several, are mapped to each specification with a detailed evaluation that is done to check whether the specification is compliant. For more information, see Creating custom libraries.