Exporting Security Command Center data

This page describes two methods for exporting Security Command Center data, including assets, findings, and security marks:

• One-time exports for current findings, assets, and security marks
• Continuous Exports, available to Security Command Center Premium customers, that automatically export new findings to Pub/Sub

Security Command Center lets you export data using the Security Command Center API or the Google Cloud Console.

One-time exports

One-time exports let you manually transfer and download current and historical findings and assets. You can transfer data to a Cloud Storage bucket and download it to your local workstation.

Permissions

To perform one-time exports, you need the following:

• An Identity and Access Management (IAM) role that includes the permissions of the Security Center Admin Viewer role.
• The Storage Admin role, which lets you store data in Cloud Storage buckets.

Security Command Center roles are granted at the organization, folder, or project level. Your ability to view, edit, create, or update findings, assets, security sources, and security marks depends on the level for which you are granted access. To learn more about Security Command Center roles, see Access control.

Export data using the Cloud Console

This section describes how to export Security Command Center data using the Cloud Console. When you click Export in the Security Command Center dashboard, Security Command Center automatically gets credentials or permissions to write to the Cloud Storage bucket.

Exporting data

Findings and assets are exported in separate operations. You can export a JSON or JSONL file to an existing Cloud Storage bucket or create one during the export process.

You can export all current assets or findings, or select the filters you want to use before you export.

1. Go to Security Command Center in the Cloud Console.

   Go to Security Command Center

2. To export assets, click the Assets tab; for findings, click the Findings tab.

3. In the Filter field, select the attributes, properties, and security marks you want to use to filter your data. A blank filter is evaluated as a wildcard and all assets or findings are exported. For more information on creating filters, see Using the Security Command Center dashboard.

4. When you're done creating a filter, click Export, and then, under One-time, click Cloud Storage.

5. On the Export page, configure the export:

   1. Confirm that Entity Type matches your choice of Findings or Assets. If it doesn't, make the right selection.
   2. On the Group Results By drop-down list, select how you want to group the export data.
   3. On the Format drop-down list, select JSON or JSONL.
      • The Filters field displays the filters you selected for the entity type, if any.
   4. Under Display Results From, select the timestamp of the data you want to export.
   5. Under Export to, select the project where you want to export the data.
   6. In the Export Path box, click Browse.
   7. On the Select object panel, select an existing Cloud Storage bucket or create a storage bucket.
   8. After you select or create a bucket, under Filename, enter a name for the export file, and then click Select.

6. When you're finished configuring the export, click Export. If you selected an existing file in the bucket, the Confirm Overwrite dialog displays.

   • To overwrite the existing file, click Confirm.
   • To change the file you're writing to, click Cancel, then click Browse in the Export Path box and select or create a different file.

The configured data is saved to the Cloud Storage bucket you specified.

Downloading exported data

To download the exported JSON or JSONL data, perform the following steps:

1. Go to the Storage browser page in the Cloud Console.

   Go to Storage browser

2. Select your project, and then click the bucket to which you exported data.

3. Select the checkbox next to the export file, and then click Download.

4. On the Save File dialog, select the location where you want to save the file, and then click Save.

The JSON or JSONL file is downloaded to the location you specified.

Export data using the Security Command Center API

You can export assets, findings, and security marks to a Cloud Storage bucket or your local workstation using Security Command Center API. Follow the guides for listing security findings or listing assets. Once listed, the API responses for findings or assets can be downloaded or exported.

To list findings or assets, with any attached security marks, you use the ListFindings or ListAssets API methods. The APIs return assets or findings with their full set of properties, attributes, and associated marks in JSON format. If your application requires data to be in a different format, you need to write custom code to convert the JSON output.

If you specify a value in the groupBy field, then the GroupAssets or GroupFindings method is used. If you don't specify a groupBy value, then the ListAssets or ListFindings method is used. TheGroupAssets and GroupFindings methods return a list of an organization's assets or findings, group by specified properties.

To export API output to a Cloud Storage bucket, use Cloud Shell to list assets or findings, write the output to a file, and then copy that file to your selected storage bucket.

1. Open Cloud Shell.

   Go to Cloud Shell

2. To write findings or assets to a file, add an output string to the gcloud tool commands for listing findings or listing assets.

   For example, the following command stores listed findings in a text file named MY_FINDINGS.txt.

     ORGANIZATION_ID=ORGANIZATION_ID
     SOURCE_ID="SOURCE_ID"
     FILTER="category=\"MEDIUM_RISK_ONE\""
   
     gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
       --filter="$FILTER" > MY_FINDINGS.txt
   

   Replace the following:

   • ORGANIZATION_ID: your organization ID.
   • SOURCE_ID: the source ID for the finding provider. Learn how to get a provider's source ID

3. Copy MY_FINDINGS.txt to your Cloud Storage bucket.

   gsutil cp MY_FINDINGS.txt gs://MY_BUCKET

   Replace MY_BUCKET with the name of your bucket.

4. To save MY_FINDINGS.txt to your local workstation instead of a Cloud Storage bucket, run the following code.

   cloudshell download MY_FINDINGS.txt

Continuous Exports

Note: This feature is only available in Security Command Center Premium tier.

Continuous Exports, available to Security Command Center Premium customers, simplify the process of automatically exporting Security Command Center findings into Pub/Sub. When new findings are written, they are automatically exported to designated Pub/Sub topics in near-real time, letting you integrate them into your existing workflow.

To learn more about Pub/Sub, see What is Pub/Sub?

Continuous Exports versus finding notifications

Security Command Center lets you set up finding notifications for Pub/Sub using the Security Command Center API. The API requires you to use Cloud SDK to set up Pub/Sub topics, create finding filters, and create NotificationConfigs, files that contain configuration settings to send notifications. Continuous Exports offer the same functionality, but creating exports is simplified by using the Security Command Center dashboard.

Permissions

To create and manage continuous exports, you need one of the following roles.

• roles/securitycenter.adminEditor
• roles/securitycenter.adminViewer

You can also use any role that has the following permissions:

• To view or publish Pub/Sub topics:

  • pubsub.topics.publish
  • pubsub.topics.list

• To view the continuous exports page:

  • securitycenter.notificationconfig.get
  • securitycenter.notificationconfig.list

• To manage continuous exports:

  • securitycenter.notificationconfig.create
  • securitycenter.notificationconfig.update
  • securitycenter.notificationconfig.delete

To learn more about Security Command Center roles, see Access control.

Configuring Pub/Sub exports

Continuous Exports let you automate the export of all future findings to Pub/Sub or create filters to export future findings that meet specific criteria. You can filter findings by category, source, asset type, security marks, severity, state, and other variables.

Creating continuous exports

Your organization can create a maximum of 500 continuous exports.To create an export for Pub/Sub, do the following:

1. Go to the Security Command Center Findings page in the Cloud Console.

   Go to Findings

2. In the Filter field, select the attributes, properties, or security marks you want to use to filter findings and enter desired variables. A blank filter is evaluated as a wildcard and all findings are exported. For more information on finding properties, see Using the Security Command Center dashboard.

3. Click Export, and then, under Continuous, click Pub/Sub.

4. Review your filter to ensure it's correct and, if necessary, return to the Findings page to modify it.

5. Under Continuous export name, enter a name for the export.

6. Under Continuous export description, enter a description for the export.

7. Under Export to, select a project for your export. You can't create a project on this page. To create a new project, see Creating a project.

8. Under Pub/Sub topic, select the topic where you want to export findings. To create a topic, do the following:

   1. Select Create a topic.
   2. Enter a Topic ID, and then select other options as needed:
      1. Learn about Creating and managing schemas.
      2. Learn about using customer-managed encryption keys (CMEK) with Pub/Sub.
   3. Click Create Topic.

9. Click Save. You see a confirmation and are returned to the findings page.

10. Follow the guide to create a subscription for your Pub/Sub topic.

The Pub/Sub export configuration is complete. To publish notifications, a service account is created for you in the form of [e-mail]. This service account is automatically granted the securitycenter.notificationServiceAgent role at the organization level. This service account role is required for notifications to function.

Testing continuous exports

To confirm that an export is working, perform the following steps to toggle findings between active and inactive states.

1. Go to the Security Command Center Findings page in the Cloud Console.

   Go to Findings

2. If necessary, re-enter filter variables that match the export filter you're testing.

3. Click the box next to the name of a finding.

4. Select Change Active State, and then select Inactive.

5. Re-select the finding that you marked inactive.

6. Select Change Active State, and then select Active. A notification is sent for the newly active finding.

7. Go to the Pub/Sub page in the Cloud Console.

   Go to Pub/Sub

8. In the list of topics, click the name of your topic.

9. Select View Messages.

10. In the Messages panel, select your subscription from the drop-down list to see the finding notification. If necessary, click Pull to refresh messages.

Managing continuous exports

To view, edit, or delete exports, do the following:

1. Go to the Settings page in Security Command Center.

   Go to Settings

2. If necessary, select your organization.

3. Select Continuous Exports. You see a list of continuous exports for your organization.

From this page, you can take the following actions:

Viewing related findings

To see findings that match an export filter, do the following:

1. On the Continuous Exports page, next to the name of an export, select More , and then click View related filters.
2. The Findings page loads with findings that match the export filter.

Editing continuous exports

1. On the Continuous Exports page, click the name of the export you want to view or modify, or click More .
2. Select Edit.
3. Enter a new description, change the project that exports are saved to, or enter a new Pub/Sub topic.
4. When done, click Save.

Note: You can't change the name of an export or modify an export filter. To use a different name or filter, you must create a new export.

Deleting continuous exports

1. On the Continuous Exports page, click the name of the export you want to delete.
2. Click Delete.
3. In the dialog, click Delete. The export is deleted.

What's next

Learn more about finding notifications.