Scanning your resources
With IBM Cloud® Security and Compliance Center, you can evaluate your resources on a recurring schedule or you can initiate a scan at any time by creating an attachment. An attachment is the association between the set of resources that you want to evaluate and a profile that contains the specific controls that you want to evaluate.
To scan resources across multiple accounts for IBM Cloud resources, register these accounts as targets. Then, use the trusted profile to grant these accounts access to the main Security and Compliance Center instance.
Before you begin
Before you get started, be sure that you have the following Prerequisites:
-
The required level of access to create an attachment. To create an attachment, you need the Editor platform role or higher. For more information, see Assigning access.
-
A connected Cloud Object Storage bucket in which to store your results. To connect your bucket, you must have a service-to-service policy in place that enables communication between Security and Compliance Center and Cloud Object Storage.
-
A selected profile that you want to use in your attachment.
Want to use controls from multiple profiles? Create a custom profile from the existing control libraries and use that profile to create your attachment. Because you cannot create custom profiles from deprecated control library versions, work with the most recent version.
-
If you are scanning resources across accounts, a trusted profile with access policies (and assigned roles) set for the target account. For more information, see Scanning resources across accounts.
Scheduling a recurring scan
To start scanning your resource, you create an attachment. To create an attachment, you can use the Security and Compliance Center UI to complete the following steps.
-
In the Security and Compliance Center UI, navigate to the Attachments page and click Create.
Alternatively, you can create an attachment through the Profiles page. After you select the profile you want to use, on the Attachments tab of the profile details page, click Create.
-
Provide a name and description for your attachment. Be sure to be as descriptive as possible so that it's easy for other members of your team to understand what is being evaluated. Then, click Next.
-
Select the Profile that you want to use for your evaluation.
-
Customize the underlying evaluations in your scan by editing the default parameters to match your specific use case. Then, click Next.
-
Target the resources that you want to evaluate by defining a scope within a single enterprise account. Or, define a scope across each of the target accounts in an IBM Cloud environment that are outside of an enterprise. A flat list of the attachments in your account or across target accounts is displayed. For more information about evaluating resources in other accounts, see Scanning resources across accounts.
If you are working with IBM Cloud resources, you can also specify resources that you want to exclude from your scope. If you are working with resources from other environments, you must connect an instance of the Workload Protection service and provide any requested information to move forward.
-
Click Next.
-
Select the frequency at which you want to evaluate your attachment.
Options include every day, every 7 days, and every 30 days. Also, you can pause your scans if you need to.
-
Optional: Configure failure notifications.
-
If you want to receive notifications, toggle Notify me to On.
-
By default, when notifications are enabled, you are alerted when 15% or more of your controls fail in a single scan. You can change this by adjusting the Threshold percentage.
For example, if you have a profile with 100 controls and you want to be notified if 5 of them fail, you would select 5% as your threshold.
-
Select specific controls that you want to be notified about.
If there are high priority controls that pertain specifically to your job role, you might want to be notified every time that they fail. You can identify up to 15 controls per scan that you can receive individual notifications for. These notifications are sent regardless of whether the threshold that was identified in the previous step was met.
- Click Select control.
- Select the controls that you want to be notified about by checking the box next to the control.
- Click Ok.
-
Click Next.
-
-
Review your choices and click Create.
When you create your attachment, a scan is scheduled. When the scan completes, your results are available in the Security and Compliance Center dashboard. If your results are not updated, review the troubleshooting guide.
Scheduling a recurring scan with the API
To start evaluating your resources, you can use the Security and Compliance Center attachments API or SDKs.
curl -X POST
--location --header "Authorization: Bearer {iam_token}"
--header "Accept: application/json"
--header "Content-Type: application/json"
--data '{
"profile_id": "542b1aee-3ad8-49e9-a33c-44b64f117f18",
"attachments": {
"profile_id": "542b1aee-3ad8-49e9-a33c-44b64f117f18",
"account_id": "cg3335893hh1428692d6747cf300yeb5",
"instance_id": "edf9524f-406c-412c-acbb-ee371a5cabda",
"included_scope": {
"scope_id": "cg3335893hh1428692d6747cf300yeb5",
"scope_type": "account"
},
"exclusions": [
"created_by": "IBMid-6620049HI3",
"created_on": "2023-02-09T10:54:59Z",
"updated_by": "IBMid-6620049HI3",
"updated_on": "2023-02-09T10:54:59Z",
"status": "enabled",
"schedule": "daily",
"notifications": {
"enabled": false,
"controls": {
"threshold_limit": 15,
"failed_control_ids":
]
}
},
"attachment_parameters": [
{
"assessment_type": "Automated",
"assessment_id": "rule-a637949b-7e51-46c4-afd4-b96619001bf1",
"parameter_name": "session_invalidation_in_seconds",
"parameter_default_value": "120",
"parameter_display_name": "Sign out due to inactivity in seconds",
"parameter_type": "numeric"
}
],
"last_scan": {
"id": "0fd7e758-3ab3-492b-8b0d-0cd8ef3569d7",
"status": "in_progress",
"time": "2023-06-13T12:08:18Z"
},
"next_scan_time": "2023-06-13T13:08:18Z",
"name": "account-0d8c3805dfea40aa8ad02265a18eb12b"
},
"account_id": "130003ea8bfa43c5aacea07a86da3000"
}'
"https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3/attachments"
(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) CreateAttachment(createAttachmentOptions *CreateAttachmentOptions) (result *AttachmentPrototype, response *core.DetailedResponse, err error)
PropertyItem propertyItemModel = new PropertyItem.Builder()
.name("scope_id")
.value("cg3335893hh1428692d6747cf300yeb5")
.build();
MultiCloudScope multiCloudScopeModel = new MultiCloudScope.Builder()
.environment("ibm-cloud")
.xProperties(java.util.Arrays.asList(propertyItemModel))
.build();
FailedControls failedControlsModel = new FailedControls.Builder()
.thresholdLimit(Long.valueOf("15"))
.failedControlIds(java.util.Arrays.asList())
.build();
AttachmentsNotificationsPrototype attachmentsNotificationsPrototypeModel = new AttachmentsNotificationsPrototype.Builder()
.enabled(false)
.controls(failedControlsModel)
.build();
AttachmentParameterPrototype attachmentParameterPrototypeModel = new AttachmentParameterPrototype.Builder()
.assessmentType("Automated")
.assessmentId("rule-a637949b-7e51-46c4-afd4-b96619001bf1")
.parameterName("session_invalidation_in_seconds")
.parameterValue("120")
.parameterDisplayName("Sign out due to inactivity in seconds")
.parameterType("numeric")
.build();
AttachmentsPrototype attachmentsPrototypeModel = new AttachmentsPrototype.Builder()
.name("account-0d8c3805dfea40aa8ad02265a18eb12b")
.description("Test description")
.scope(java.util.Arrays.asList(multiCloudScopeModel))
.status("enabled")
.schedule("every_30_days")
.notifications(attachmentsNotificationsPrototypeModel)
.attachmentParameters(java.util.Arrays.asList(attachmentParameterPrototypeModel))
.build();
CreateAttachmentOptions createAttachmentOptions = new CreateAttachmentOptions.Builder()
.profilesId(profileIdLink)
.attachments(java.util.Arrays.asList(attachmentsPrototypeModel))
.build();
Response<AttachmentPrototype> response = securityAndComplianceCenterApiService.createAttachment(createAttachmentOptions).execute();
AttachmentPrototype attachmentPrototype = response.getResult();
System.out.println(attachmentPrototype);
// Request models needed by this operation.
// PropertyItem
const propertyItemModel = {
name: 'scope_id',
value: 'cg3335893hh1428692d6747cf300yeb5',
};
// MultiCloudScope
const multiCloudScopeModel = {
environment: 'ibm-cloud',
properties: [propertyItemModel],
};
// FailedControls
const failedControlsModel = {
threshold_limit: 15,
failed_control_ids: [],
};
// AttachmentsNotificationsPrototype
const attachmentsNotificationsPrototypeModel = {
enabled: false,
controls: failedControlsModel,
};
// AttachmentParameterPrototype
const attachmentParameterPrototypeModel = {
assessment_type: 'Automated',
assessment_id: 'rule-a637949b-7e51-46c4-afd4-b96619001bf1',
parameter_name: 'session_invalidation_in_seconds',
parameter_value: '120',
parameter_display_name: 'Sign out due to inactivity in seconds',
parameter_type: 'numeric',
};
// AttachmentsPrototype
const attachmentsPrototypeModel = {
name: 'account-0d8c3805dfea40aa8ad02265a18eb12b',
description: 'Test description',
scope: [multiCloudScopeModel],
status: 'enabled',
schedule: 'every_30_days',
notifications: attachmentsNotificationsPrototypeModel,
attachment_parameters: [attachmentParameterPrototypeModel],
};
const params = {
profilesId: profileIdLink,
attachments: [attachmentsPrototypeModel],
};
let res;
try {
res = await securityAndComplianceCenterApiService.createAttachment(params);
console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
console.warn(err);
}
property_item_model = {
'name': 'scope_id',
'value': 'cg3335893hh1428692d6747cf300yeb5',
}
multi_cloud_scope_model = {
'environment': 'ibm-cloud',
'properties': [property_item_model],
}
failed_controls_model = {
'threshold_limit': 15,
'failed_control_ids': [],
}
attachments_notifications_prototype_model = {
'enabled': False,
'controls': failed_controls_model,
}
attachment_parameter_prototype_model = {
'assessment_type': 'Automated',
'assessment_id': 'rule-a637949b-7e51-46c4-afd4-b96619001bf1',
'parameter_name': 'session_invalidation_in_seconds',
'parameter_value': '120',
'parameter_display_name': 'Sign out due to inactivity in seconds',
'parameter_type': 'numeric',
}
attachments_prototype_model = {
'name': 'account-0d8c3805dfea40aa8ad02265a18eb12b',
'description': 'Test description',
'scope': [multi_cloud_scope_model],
'status': 'enabled',
'schedule': 'every_30_days',
'notifications': attachments_notifications_prototype_model,
'attachment_parameters': [attachment_parameter_prototype_model],
}
response = security_and_compliance_center_api_service.create_attachment(
profiles_id=profile_id_link,
attachments=[attachments_prototype_model],
)
attachment_prototype = response.get_result()
print(json.dumps(attachment_prototype, indent=2))
A successful response returns an array that lists all the attachments to the specified profile, along with other metadata. For more information about the required and optional request parameters, check out the API docs.
Scheduling a recurring scan with the CLI
To create an attachment, you can use the Security and Compliance Center CLI. See the CLI referencce for more information.
ibmcloud security-compliance attachment create
--profile-id=exampleString
--attachments='[
{
"id": "130003ea8bfa43c5aacea07a86da3000",
"name": "account-0d8c3805dfea40aa8ad02265a18eb12b",
"description": "Test description",
"scope": [
{
"environment": "ibm-cloud",
"properties": [
{
"name": "scope_id",
"value": "cg3335893hh1428692d6747cf300yeb5"
}
]
}
],
"status": "enabled",
"schedule": "every_30_days",
"notifications": {
"enabled": false,
"controls": {
"threshold_limit": 15,
"failed_control_ids": []
}
},
"attachment_parameters": [
{
"assessment_type": "Automated",
"assessment_id": "rule-a637949b-7e51-46c4-afd4-b96619001bf1",
"parameter_name": "session_invalidation_in_seconds",
"parameter_value": "120",
"parameter_display_name": "Sign out due to inactivity in seconds",
"parameter_type": "numeric"
}
]
}
]'
--x-correlation-id=exampleString
--x-request-id=exampleString
When you create your attachment, a scan is scheduled. When the scan completes, your results are available in the Security and Compliance Center dashboard.
Scheduling a recurring scan with Terraform
To create an attachment, you can use Terraform.
resource "ibm_scc_profile_attachment" "scc-profile-attachment-instance" {
instance_id = ibm_resource_instance.scc_instance.guid
name = "scc-ibm-cis-benchmark-attachment"
description = "The IBM Cloud CIS Benchmark Evaluation"
profile_id = <scc_ibm_cloud_cis_profile_id>
# The following are values for <scc_ibm_cloud_cis_profile_id>:
#
# ca-tor: d8ac6f16-a55c-471c-89a1-abc61d90b620
# eu-es: 98d4e0cc-236a-4de6-b31b-13c6b6cdda8a
# us-south: 1c13d739-e09e-4bf4-8715-dd82e4498041
# eu-de: a0bd1ee2-1ed3-407e-a2f4-ce7a1a38f54d
schedule = "every_7_days"
status = "enabled"
scope {
environment = "ibm-cloud"
properties {
name = "scope_id"
value = data.ibm_iam_account_settings.iam-account.account_id
}
properties {
name = "scope_type"
value = "account"
}
}
attachment_parameters {
parameter_value = jsonencode(["1.2", "1.3"])
assessment_id = "rule-e16fcfea-fe21-4d30-a721-423611481fea"
assessment_type = "automated"
parameter_display_name = "IBM Cloud Internet Services TLS version"
parameter_name = "tls_version"
parameter_type = "string_list"
}
attachment_parameters {
parameter_value = "22"
assessment_id = "rule-f9137be8-2490-4afb-8cd5-a201cb167eb2"
assessment_type = "automated"
parameter_display_name = "Network ACL rule for allowed IPs to SSH port"
parameter_name = "ssh_port"
parameter_type = "numeric"
}
attachment_parameters {
parameter_value = "3389"
assessment_id = "rule-9653d2c7-6290-4128-a5a3-65487ba40370"
assessment_type = "automated"
parameter_display_name = "Security group rule RDP allow port number"
parameter_name = "rdp_port"
parameter_type = "numeric"
}
attachment_parameters {
parameter_value = "22"
assessment_id = "rule-7c5f6385-67e4-4edf-bec8-c722558b2dec"
assessment_type = "automated"
parameter_display_name = "Security group rule SSH allow port number"
parameter_name = "ssh_port"
parameter_type = "numeric"
}
attachment_parameters {
parameter_value = "3389"
assessment_id = "rule-f1e80ee7-88d5-4bf2-b42f-c863bb24601c"
assessment_type = "automated"
parameter_display_name = "Disallowed IPs for ingress to RDP port"
parameter_name = "rdp_port"
parameter_type = "numeric"
}
notifications {
enabled = false
controls {
failed_control_ids = []
threshold_limit = 10
}
}
}
When you create your attachment, a scan is scheduled. When the scan completes, your results are available in the Security and Compliance Center dashboard. For more information, check out the Terraform reference.
Running a scan on demand
If your attachment exists, but you don't want to wait for the next scan to see your posture, you can initiate an on-demand scan.
- In the IBM Cloud console, click the Menu icon
> Security and Compliance to access Security and Compliance Center. - In the navigation, click Profile.
- Click the options menu
in the row of the profile that you want to evaluate. - Click Run scan.
After your scan completes, your results are available in the Security and Compliance Center dashboard.
Running a scan on demand with the API
If your attachment exists, but you don't want to wait for the next scan to see your posture, you can initiate an on-demand scan.
curl -X POST
--location --header "Authorization: Bearer {iam_token}"
--header "Accept: application/json"
--header "Content-Type: application/json"
--data '{
"attachment_id":"a34fdceab3d89d91bd4f76d422bf0d26"
}'
"https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3/scans"
(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) CreateScan(createScanOptions *CreateScanOptions) (result *Scan, response *core.DetailedResponse, err error)
CreateScanOptions createScanOptions = new CreateScanOptions.Builder()
.attachmentId(attachmentIdLink)
.build();
Response<Scan> response = securityAndComplianceCenterApiService.createScan(createScanOptions).execute();
Scan scan = response.getResult();
System.out.println(scan);
const params = {
attachmentId: attachmentIdLink,
};
let res;
try {
res = await securityAndComplianceCenterApiService.createScan(params);
console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
console.warn(err);
}
create_scan(
self,
attachment_id: str,
*,
x_correlation_id: str = None,
x_request_id: str = None,
**kwargs,
) -> DetailedResponse
A successful response returns the scan ID, along with other metadata. For more information about the required and optional request parameters, check out the API docs.
Running a scan on demand with the CLI
If your attachment exists, but you don't want to wait for the next scan to see your posture, you can initiate an on-demand scan. For more information, see the CLI reference.
ibmcloud security-compliance attachment scan
--attachment-id=exampleString
--x-correlation-id=exampleString
--x-request-id=exampleString
After your scan completes, your results are available in the Security and Compliance Center dashboard.