Security Command Center

See the official Security Center Python Client documentation here: link.

class bibt.gcp.scc.classes.FindingInfo(notification, gcp_org_id, client=None)[source]

This class compiles information related to a given SCC finding in a standard way. One of the issues with SCC findings is that different SCC sources pass different fields; here, we can standardize how fields are passed around in functions and pipelines.

package()[source]

Converts this object into a dict.

bibt.gcp.scc.methods.get_all_findings(filter, gcp_org_id, order_by=None, page_size=1000, credentials=None, client=None)[source]

Returns an iterator for all findings matching a particular filter.

from bibt.gcp.scc import get_all_findings
for _ in get_all_findings(
    filter='category="PUBLIC_BUCKET_ACL"',
    order_by='eventTime desc',
    gcp_org_id=123123
):
    print(_.finding.name, _.resource.name)
Parameters:

  • filter (str) – the filter to use. See here for more on valid filter syntax.

  • gcp_org_id (str) – the GCP organization ID under which to search.

  • order_by (str) – (optional) the sort order of the findings. See here for more on valid arguments. Default is None.

  • page_size (int) – (optional) the page size for the API requests. max and default is 1000 .

  • credentials (google.oauth2.credentials.Credentials) – (optional) the credentials object to use when making the API call, if not to use the account running the function for authentication.

  • client (google.cloud.securitycenter_v1.services.security_center.SecurityCenterClient) – (optional) the SCC client to use for API calls. will generate one if not passed.

Return type:

google.cloud.securitycenter_v1.types.ListFindingsResponse

Returns:

an iterator for all findings matching the filter.

bibt.gcp.scc.methods.get_finding(name, gcp_org_id, credentials=None, client=None)[source]

This function returns the finding object specified by name.

from bibt.gcp import scc
f = scc.get_finding(
    name="organizations/123123/sources/123123/findings/123123",
    gcp_org_id=123123
)
print(f.finding.name, f.resource.name)
Parameters:
Return type:

google.cloud.securitycenter_v1.types.ListFindingsResponse.ListFindingsResult

Returns:

the specified finding object, paired with its resource information.

Raises:

ValueError – if no finding under the supplied name is found.

bibt.gcp.scc.methods.get_security_marks(scc_name, gcp_org_id, credentials=None, client=None)[source]

Gets security marks on an asset or finding in SCC and returns them as a dict.

from bibt.gcp import scc
for k, v in scc.get_security_marks(
    scc_name="organizations/123123/sources/123123/findings/123123",
    os.environ["GCP_ORG_ID"]
).items():
    print(k, v)
Parameters:

  • scc_name (str) – may be either an SCC finding.name or a GCP resourceName . format is: organizations/123123/sources/123123/findings/123123 or //storage.googleapis.com/my-bucket. note this does not accept ``asset.name`` format!

  • gcp_org_id (str) – the GCP organization ID under which to search.

  • credentials (google.oauth2.credentials.Credentials) – the credentials object to use when making the API call, if not to use the account running the function for authentication.

  • client (google.cloud.securitycenter_v1.services.security_center.SecurityCenterClient) – (optional) the SCC client to use for API calls. will generate one if not passed.

Return type:

dict

Returns:

a dictionary containing security marks as key/value pairs.

Raises:

TypeError – if scc_name is not in a recognizeable format.

bibt.gcp.scc.methods.get_sources(parent_name, credentials=None, client=None)[source]

Returns a list of all sources in the parent.

for source in get_sources("organizations/123456"):
    print(source.display_name)
Parameters:
Return type:

list gcp_scc:google.cloud.securitycenter_v1.types.Sources

Returns:

a list of SCC Source objects

bibt.gcp.scc.methods.get_value(obj, path, raise_exception=True)[source]
Fetches the value in the given obj according to the given path.

Works on objects and dicts. Supports arrays in a few ways:

  • if the path is resource.folders[].resource_folder_display_name OR resource.folders[0].resource_folder_display_name, it will just consider the first element in the array.

  • if the path is resource.folders[*].resource_folder_display_name, it will return a list of resource_folder_display_name values, one for each folder.

Additionally, if unsuccessful with exactly what was passed as path, it will convert and try both camelized and underscored attribute names (resource_folder_display_name and resourceFolderDisplayName). As a last resort it will try a key lookup (e.g. obj[key]).

from bibt.gcp import scc
f = scc.get_finding(
    name="organizations/123123/sources/123123/findings/123123",
    gcp_org_id=123123
)
v = scc.get_value(
    f,
    "finding.source_properties.abuse_target_ips"
)
print(v)
Parameters:

  • obj (object) – the object from which to extract a value.

  • path (str) – the path to follow to find the desired value(s).

  • raise_exception (bool) – whether it should raise an exception if the path isn’t resolved successfully, or just return None.

Returns:

whatever it finds at the end of the specified path.

Raises:

KeyError – if the next part of the path cannot be found.

bibt.gcp.scc.methods.parse_notification(notification, ignore_unknown_fields=False)[source]

This method takes the notification received from a SCC Notification Pubsub and returns a Python object.

import base64
from bibt.gcp import scc
def main(event, context):
    raw_notification = base64.b64decode(event["data"]).decode("utf-8")
    notification = scc.parse_notification(raw_notification)
    print(
        notification.finding.name,
        notification.finding.category,
        notification.resource.name
    )
Parameters:

  • notification (str OR dict) – the notification to parse. may be either a dictionary or a json string.

  • ignore_unknown_fields (bool) – whether or not unrecognized fields should be ignored when parsing. fields may be unrecognized if they are added to the finding category in later releases of google-cloud-securitycenter library.

Return type:

google.cloud.securitycenter_v1.types.ListFindingsResponse.ListFindingsResult

Returns:

the finding notification as a Python object.

Raises:

TypeError – if it is passed anything aside from a str or dict, or it has an issue parsing the finding into an object.

bibt.gcp.scc.methods.set_finding_state(finding_name, state='INACTIVE', credentials=None, client=None)[source]

This method will set the finding to inactive state by default.

from bibt.gcp import scc
scc.set_finding_state(
    finding_name="organizations/123123/sources/123123/findings/123123"
)
Parameters:
Raises:

KeyError – if the argument supplied for state is not a valid name for google.cloud.securitycenter_v1.types.Finding.State.

bibt.gcp.scc.methods.set_mute_status(finding_name, status='MUTED', credentials=None, client=None)[source]

This method will mute the finding by default. May also be used to unmute with status="UNMUTED" .

from bibt.gcp import scc
scc.set_mute_status(
    finding_name="organizations/123123/sources/123123/findings/123123"
)
Parameters:
Raises:

KeyError – if the argument supplied for status is not MUTED or UNMUTED .

bibt.gcp.scc.methods.set_security_marks(scc_name, marks, gcp_org_id=None, credentials=None, client=None)[source]
Sets security marks on an asset or finding in SCC. Usually, if we’re setting

them on a finding, it means we’re setting a mark of reason for setting it to inactive. if we’re setting them on an asset, it is usually to allow_{finding.category}=true .

from bibt.gcp import scc
scc.set_security_mark(
    scc_name="organizations/123123/sources/123123/findings/123123",
    marks={
        'reason': 'intentionally public'
    }
)
Parameters:

  • scc_name (str) – may be either an SCC finding.name or a GCP resourceName . format is: organizations/123123/sources/123123/findings/123123 or //storage.googleapis.com/my-bucket. note this does not accept ``asset.name`` format!

  • marks (dict) – a dictionary of marks to set on the asset or finding. format it: marks={"allow_public_bucket_acl": "true", "reason": "intentional"} . note this must be a dict and not a list!

  • credentials (google.oauth2.credentials.Credentials) – the credentials object to use when making the API call, if not to use the account running the function for authentication.

  • client (google.cloud.securitycenter_v1.services.security_center.SecurityCenterClient) – (optional) the SCC client to use for API calls. will generate one if not passed.

Raises:

TypeError – if the argument supplied for marks is not a dict