Accessing Cloud SCC programmatically

This page walks you through accessing Cloud Security Command Center (Cloud SCC) using the Cloud SCC Python library to review your organization's Google Cloud Platform (GCP) resources.

Before you begin

To access Cloud SCC programmatically, you must have one of the following Cloud Identity and Access Management (Cloud IAM) roles:

securitycenter.viewer
securitycenter.editor

For more information about these Cloud IAM roles, see Access control.

To complete this guide, you'll need the following:

An existing directory path in which a service account private key can be stored. This path is in the context of your Cloud Shell environment, such as /home/myuser/mykeys/.

Accessing Cloud SCC

To access Cloud SCC programmatically, you'll use Cloud Shell to get the client library and authenticate a service account. To get the Cloud SCC client library, follow the steps below:

Setting up environment variables

Go to the Google Cloud Platform Console.
Go to the Google Cloud Platform Console
Click Activate Cloud Shell.
Run the following commands to set environment variables:
1. Set your organization name:
```
ORG_ID=YOUR_ORGANIZATION_ID
```
2. Set the project ID for which Cloud SCC is enabled:
```
PROJECT_ID=Cloud SCC-ENABLED_PROJECT_ID
```
3. Set the custom ID you want to use for a new service account, such as SCC-SA:
```
SERVICE_ACCOUNT=CUSTOM_ID
```
4. Set the path in which the service account key should be stored, such as /home/myuser/mykeys/SERVICE_ACCOUNT.json:
```
KEY_LOCATION=FULL_PATH
```

Installing the Python library

Download and untar the client library to the location you prefer:

gsutil cp gs://cscc-client-libraries/v1alpha3.1.tar.gz .
tar -zxvf v1alpha3.1.tar.gz

[Optional] Before you install the Python library, we recommend using Virtualenv to create an isolated Python environment.
```
virtualenv onboarding_example
source onboarding_example/bin/activate
      
```
Install pip to manage the Python library installation.

Run the following commands to install the Python library:

pip install v1alpha3/python/securitycenter-v1alpha3/

Setting up a service account

The Python library takes a private key from a service account to be used by the client. The service account must have the organization level role securitycenter.editor.

Create a service account that's associated with your project ID:

gcloud iam service-accounts create SERVICE_ACCOUNT  --display-name
 "Service Account for USER"  --project PROJECT_ID

Create a key to associate with the service account. The key will be used for the life of the service and persistently stored at the KEY_LOCATION you specify.
```
gcloud iam service-accounts keys create KEY_LOCATION  --iam-account
 SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com
      
```

Grant the service account the securitycenter.editor role for the organization.

gcloud beta organizations add-iam-policy-binding $ORG_ID
  --member="serviceAccount:SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
  --role='roles/securitycenter.editor'

Starting the service

Start the interactive Python shell and set up imports, variables, and helper function.

$ python

from google.cloud import securitycenter
from google.oauth2 import service_account
from google.protobuf import timestamp_pb2, duration_pb2, struct_pb2
from datetime import datetime, timedelta

ORGANIZATION = "organizations/TO_BE_UPDATED"
credentials = service_account.Credentials.from_service_account_file(
  'FULL_PATH_TO_SERVICE_ACCOUNT_CREDENTIALS')
scoped_credentials = credentials.with_scopes(
  ['https://www.googleapis.com/auth/cloud-platform'])
client = securitycenter.SecurityCenterClient(credentials = scoped_credentials)
def print_iterator( resource_iterator ):
  for asset in resource_iterator:
    print(asset)
def unix_time_millis(dt):
  return int((dt - datetime.utcfromtimestamp(0)).total_seconds())

Example calls

Python

Most of the following example calls use the print_iterator defined above to print results. In the following examples, the : operator performs partial and substring matching.

Projects

Return a summary of all the organization's projects:

print_iterator(client.search_assets(ORGANIZATION,
 query = 'attribute.asset_type = "PROJECT"'))

Return a summary of all projects owned by OWNER:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = ('attribute.asset_type = "PROJECT" '
          'AND attribute.owners : "OWNER"')))

Return a comparison of all projects owned by OWNER between yesterday and now:

print_iterator(client.search_assets(ORGANIZATION,
 compare_duration = duration_pb2.Duration(seconds=60*60*24),
 query = ('attribute.asset_type = "PROJECT" '
          'AND attribute.owners : "OWNER"')))

Return a summary of all projects between last week and now:

print_iterator(client.search_assets(
 ORGANIZATION,
 compare_duration = duration_pb2.Duration(seconds=60*60*24*7),
 query = 'attribute.asset_type = "PROJECT"'))

Return a summary of all projects between five and eight days ago:

print_iterator(client.search_assets(
 ORGANIZATION,
 compare_duration = duration_pb2.Duration(seconds=60*60*24*3),
 reference_time = timestamp_pb2.Timestamp(
   seconds=unix_time_millis(datetime.now() - timedelta(days = 5)))
 query = 'attribute.asset_type = "PROJECT"'))

Return all projects that include dev in the name:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = ('attribute.asset_type = "PROJECT" '
          'AND property.name : "dev"')))

Return all projects that include prod3 in the name AND mark.type of qa:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = ('attribute.asset_type = "PROJECT" '
          'AND property.name : "prod3" '
          'AND mark.type : "qa"')))

Resources

Return the current state of all resources and marks:

print_iterator(client.search_assets(ORGANIZATION))

Return the state of all resources and marks that were snapshotted at 6 days, 4 hours, and 10 minutes ago:

print_iterator(client.search_assets(
 ORGANIZATION,
 reference_time = timestamp_pb2.Timestamp(
   seconds=unix_time_millis(
     datetime.now() - timedelta(days = 6, hours = 4, minutes = 10)))))

Return all resources in only PROJECT_A_ID and PROJECT_B_ID:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = ('attribute.parent_id : "PROJECT_A_ID" '
          'OR attribute.parent_id : "PROJECT_B_ID"')))

Return all firewall rules across the organization that have open HTTP ports:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = ('attribute.asset_type = "FIREWALL" '
          'AND property.name = "default-allow-http"')))

Return all images across the organization that include Debia in the name:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = ('attribute.asset_type = "IMAGE" '
          'AND property.name : "Debia"')))

List Marks

Return all assets with mark.group equal to foo:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = 'mark.group = "foo"'))

Return all assets for which mark.group is NOT equal to bar2:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = 'NOT mark.group : "bar2"'))

Return all assets for which mark.status is equal to assigned AND mark.assignee is NOT equal to kevin:

print_iterator(client.search_assets(
 ORGANIZATION,
 query = ('mark.status = "assigned" '
          'AND NOT mark.assignee = "kevin"'))

Modify Marks

Add marks to the organization with keys test_a and test_b and values value_a and value_b:

client.modify_asset(
  ORGANIZATION,
  ORGANIZATION,
  add_or_update_marks = {
    'test_a' : 'value_a',
    'test_b' : 'value_b' })

Remove all marks from the organization with key test_a or test_b:

client.modify_asset(
  ORGANIZATION,
  ORGANIZATION,
  remove_marks_with_keys = ["test_a", "test_b"])

Add and remove marks from the organization in a single request:

Remove all marks from the organization with keys my_key_a or my_key_b.
Add two marks with keys test_a and test_b and values value_a and value_b.

client.modify_asset(
  ORGANIZATION,
  ORGANIZATION,
  remove_marks_with_keys = ["my_key_a", "my_key_b"],
  add_or_update_marks = {
    'test_a' : 'value_a',
    'test_b' : 'value_b' })

Findings

The API supports the following methods:

SearchFindings performs like SearchAssets, but SearchFindings doesn't support time diff queries at this time.
ModifyFindings performs like ModifyAssets.
CreateFindings enables users and services with the appropriate permissions to write to the Cloud SCC findings database. You can use this method to integrate results from your security detectors and tools into Cloud SCC. Your integrated results will be indexed with all other findings, assets, attributes, properties, and security marks to create a single holistic view of security risks for your deployment.

Examples for these methods will be added in a future update.

Search Findings

Return all findings for a particular SCANNER_NAME, such as Sensitive Information Scanner:

print_iterator(client.search_findings(
 ORGANIZATION,
 query='attribute.scanner_id = "SCANNER_NAME"'))

Return all findings for SCANNER_NAME_A that are for a specific RESULT_TYPE, such as US_CENSUS_NAME:

print_iterator(client.search_findings(
 ORGANIZATION,
 query='attribute.scanner_id = "SCANNER_NAME_A"
   AND attribute.result_type = "RESULT_TYPE"'))

Return all findings for a particular ASSET_ID:

print_iterator(client.search_findings(
 ORGANIZATION,
 query='attribute.asset_id = "ASSET_ID"'))

Return all findings for a particular ASSET_ID that were snapshotted X days ago:

print_iterator(client.search_findings(
 ORGANIZATION,
 query='attribute.asset_id = "ASSET_ID"',
    reference_time = timestamp_pb2.Timestamp(seconds=unix_time_millis(datetime.now()
    - timedelta(days = DAYS)))))

Return all findings that have a mark.status equal to completed:

print_iterator(client.search_findings(
 ORGANIZATION,
 query='mark.status = "completed"'))

Return all findings that have a mark.status NOT equal to completed:

print_iterator(client.search_findings(
 ORGANIZATION,
 query='NOT mark.status = "completed"'))

Modify Marks on Findings

Add marks to the FINDING_ID with keys test_a and test_b and values value_a and value_b:

client.modify_finding(
  ORGANIZATION,
  FINDING_ID,
  add_or_update_marks = {
    'test_a' : 'value_a',
    'test_b' : 'value_b' })

Remove all marks from FINDING_ID with key test_a or test_b:

client.modify_finding(
  ORGANIZATION,
  FINDING_ID,
  remove_marks_with_keys = ["test_a", "test_b"])

Add and remove marks from FINDING_ID in a single request:

Remove all marks from the FINDING_ID with keys my_key_a or my_key_b.
Add two marks with keys test_a and test_b and values value_a and value_b.

client.modify_asset(
  ORGANIZATION,
  FINDING_ID,
  remove_marks_with_keys = ["my_key_a", "my_key_b"],
  add_or_update_marks = {
    'test_a' : 'value_a',
    'test_b' : 'value_b' })

Create Findings

Create a finding of type MEDIUM_RISK_ONE, for the Scanner type GOOGLE_ANOMALY_DETECTION with no properties:

client.create_finding(
  ORGANIZATION, source_finding={'id':'UNIQUE_FINDING_ID_TO_REPLACE',
  'category':'MEDIUM_RISK_ONE',
  'asset_ids':['ASSET_ID_TO_REPLACE'],
  'source_id':'GOOGLE_ANOMALY_DETECTION',
  'event_time':timestamp_pb2.Timestamp(
     seconds=unix_time_millis(datetime.now())), 'properties':{}})

Create a finding of type SCARY_ONE, for the Scanner type REDLOCK with properties of two key-value pairs:

client.create_finding(
  ORGANIZATION,
  source_finding={'id':'UNIQUE_FINDING_ID_TO_REPLACE',
  'category':'SCARY_ONE',
  'asset_ids':['ASSET_ID_TO_REPLACE'],
  'source_id':'REDLOCK',
  'event_time':timestamp_pb2.Timestamp(seconds=unix_time_millis(datetime.now())),
  'url':'YOUR_URL',
  'properties':{'fields':{'PROPERTY_KEY1_TO_REPLACE'
     :struct_pb2.Value(string_value='property value1'),
     'PROPERTY_KEY2_TO_REPLACE'
     :struct_pb2.Value(string_value='property value2')} } })

Was this page helpful? Let us know how we did:

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated September 20, 2018.