This guide walks you through using the Security Command Center API to create a source to generate findings. When you add a source, Security Command Center creates appropriate sources and assigns them the relevant permissions.
The IAM roles for Security Command Center can be granted at the organization, folder, or project level. Your ability to view, edit, create, or update findings, assets, and security sources depends on the level for which you are granted access. To learn more about Security Command Center roles, see Access control.
Before you begin
Before you set up a source, you need to Set up a service account. If you're calling the Security Command Center API directly, get a bearer token.
Creating a source
This example shows how to create a source with a specific display name and description that is used in the Security Command Center dashboard.
The server automatically assigns an ID to the source.
Python
Java
Go
Node.js
API
In the API, make a request to the organizations.sources.create
method. The
request body contains an instance of Source.
POST https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources -d { "name": "SOURCE_NAME", "description": "SOURCE_DESCRIPTION", "displayName": "DISPLAY_NAME" }
Replace the following:
- API_VERSION: the API version you're targeting.
- ORGANIZATION_ID: your organization ID.
- SOURCE_NAME: the name of the source.
- SOURCE_DESCRIPTION: a description of the source (max: 1,024 characters).
- DISPLAY_NAME: the display name of the source (between one and 64 characters).
The source is not visible in the Security Command Center dashboard until it generates findings. You can verify it was created by following the instructions in Get a specific source.
Updating a source
You can update a source's display name and description after it's created. You can also use a field mask to update only one field. The example below uses a field mask to only update the display name, leaving the description unchanged.
Python
Java
Go
Node.js
API
In the API, make a request to the organizations.sources.patch
method. The
request body contains an instance of Source.
PATCH https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources/SOURCE_ID?updateMask=displayName -d { "description": "SOURCE_DESCRIPTION", "displayName": "DISPLAY_NAME", }
Replace the following:
- API_VERSION: the API version you're targeting.
- ORGANIZATION_ID: your organization ID.
- SOURCE_ID: the source ID. For instructions on retrieving a source ID, see Getting the source ID.
- SOURCE_DESCRIPTION: a description of the source (max: 1024 characters).
- DISPLAY_NAME: the display name of the source (between one and 64 characters).
Setting IAM policies on a source
After you create a source, update the Identity and Access Management (IAM) policies to allow access.
Python
Java
Go
Node.js
API
In the API, make a request to the organizations.sources.setIamPolicy
method. The request body includes an instance of Policy.
POST https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources/SOURCE_ID:setIamPolicy -d { "version": POLICY_FORMAT, "bindings": [ { "role": IAM_ROLE, "members": [ IAM_EMAIL ] } ], "auditConfigs": [ { "service": "SERVICE", "auditLogConfigs": [ { "logType": "LOG_PERMISSION", "exemptedMembers": [ "user:EXEMPT_EMAIL" ] } ] } ], "etag": ETAG }
Replace the following:
- API_VERSION: the API version you're targeting.
- ORGANIZATION_ID: your organization ID.
- SOURCE_ID: the source ID. See Get a specific source for instructions on retrieving a source ID.
- POLICY_FORMAT: 0, 1, or 3 to specify the format of the policy.
- IAM_ROLE: the IAM role being granted.
- IAM_USER_EMAIL: the email address for the user you are granting the role.
- SERVICE: the Google Cloud service for which you are enabling audit logging.
- LOG_PERMISSION: the log permissions being granted:
ADMIN_READ
,DATA_READ
, orDATA_WRITE
. - EXEMPT_EMAIL: identities that do not cause logging for the permission type.
- ETAG: a string returned in the response to
getIamPolicy
that should be included to help prevent simultaneous updates of a policy from overwriting each other.
Get a specific source
Verify that a source is created or updated appropriately by querying Security Command Center with the source's absolute resource name:
gcloud
# Note: For GCloud you can use either full resource name or just ID Flags. # In this example, we are using ID Flags. # ORGANIZATION_ID=12344321 # SOURCE_ID=43211234 gcloud scc sources describe $ORGANIZATION_ID --source=$SOURCE_ID
For more examples, run:
gcloud scc sources describe --help
Python
Java
Go
Node.js
API
In the API, make a request to the organizations.sources.get
method. The
request body is empty.
GET https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources/SOURCE_ID
Replace the following:
- API_VERSION: the API version you're targeting.
- ORGANIZATION_ID: your organization ID.
- SOURCE_ID: the source ID.
Listing Sources
Security Command Center enables you to list a specific source, and to list all sources currently available in an organization:
Python
Java
Go
Node.js
API
In the API, make a request to the organizations.sources.list
method. The
request body is empty.
GET https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources
Replace the following:
- API_VERSION: the API version you're targeting.
- ORGANIZATION_ID: your organization ID.
Getting IAM policies
You can check if the appropriate IAM policies have been applied to a source by getting the current IAM policy data from Security Command Center:
Python
Java
Go
Node.js
API
In the API, make a request to the organizations.sources.getIamPolicy
method. The request body contains a
GetIamPolicyRequest
request message. The options
object is optional and used to
request a policy format.
GET https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources/SOURCE_ID:getIamPolicy -d { "resource": "organizations/ORGANIZATION_ID/sources/SOURCE_ID", "options": { "requestedPolicyVersion": POLICY_VERSION } }
Replace the following:
- API_VERSION: the API version you're targeting.
- ORGANIZATION_ID: your organization ID.
- SOURCE_ID: the source ID. See Get a specific source for instructions on retrieving a source ID.
- POLICY_VERSION: the policy format to be returned, 0, 1, or 3.
What's next
Learn more about Accessing Security Command Center using an SDK.