Google Cloud console

To create a custom module in the Google Cloud console, complete thefollowing steps:

1. Go to the Security Command CenterSettings page in theGoogle Cloud console.

   Go to Settings

2. If prompted, select the organization, folder, or project in which youneed to create the custom module.

3. On theSecurity Health Analytics card, clickManage Settings.

4. Click theModules tab.

5. Clickadd_boxCreate module.TheCreate module for Security Health Analytics page opens.

6. On theConfigure module panel, define the display name, resourcesto scan, and the detection logic:

   1. In theModule name field, specify a name for the module.The name must be between 1 and 128 characters, start with alowercase letter, and contain alphanumeric characters or underscoresonly. This name becomes the finding category of the findings thatthis detector produces. You can't change the name after the moduleis created.

   2. UnderAdd resource type, specify one to five resource typesto scan. You cannot specify a resource type more than once.

      For a list of supported resource types, seeSupported resource types.

   3. In theExpression editor, write CEL expressionsto run boolean checks on one or more properties of the resourcethat you specified in the last step. To trigger a finding, theexpression must resolve toTRUE.For example, the following expression triggers a finding if aCryptoKey resource has a rotation period defined and therotation period is longer than 2,592,000 seconds (30 days):

      has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))

      For more information, see the following:

      • Write CEL expressions
      • Referencing resource and policy properties in custom modules
      • List of Standard CEL Definitions

   4. ClickNext. TheDefine finding details panel opens.

7. On theDefine finding details panel, describe the issue thatthe custom module detects, including its severity, what the issue is,how to fix the issue, and any data that you want to include in thefindings as custom source properties:

   1. In theSeverity field, specify the severity of the issue.You can specifyLow,Medium,High, orCritical.Mediumis the default.

      For information about severity levels, seeSeverity classifications for findings.

   2. In theFinding description field, explain the issue that thecustom module detects. This explanation appears in each findinginstance to help security teams understand and address thedetected issue.

   3. In theFinding next steps field, explain the steps that yoursecurity team can take to fix or otherwise address the detected issue.

      The steps display with each finding instance. Include specificsteps that the security team can take to address the issue asquickly as possible.

   4. Optional: In theCustom finding properties field, specifyup to 10 name-value pairs to define custom source properties toreturn with each finding instance. The information is returnedas source properties in the finding JSON and is displayedon theSource properties tab in the finding details in theGoogle Cloud console. Specify the text or property values askey-value pairs:

      • In theProperty name field, specify a name for the customsource property. The name must conform to the following rules:
        • The name must begin with a lowercase letter.
        • The name must contain only alphanumeric characters orunderscores.
        • The name must be between 1 and 128 characters in length.
        • Each name must be unique among the other source properties.
      • In theProperty value field, specify one of the followingvalues in 1024 characters or less:
        • A text string enclosed in quotation marks. The quotation marksare included in the 1024 character limit. For example,"This string provides additional useful information."
        • Any property of the resource that is being scanned.For example, if you are checking theCryptoKey resource,you might specifyresource.rotationPeriod. The value oftherotationPeriod property is returned.

   5. ClickNext. TheEnable module panel opens.

8. Optional: Use the drop-down menu of theEnable module panel tospecify whether the custom module is enabled or disabled upon creation.By default, custom modules are enabled upon creation. If you specifyDisable, you can enable the module later on theModules tab inthe Security Health Analytics settings page.

9. ClickNext. TheTest module panel opens.

10. Optional: Before you create your custom module, we recommend that youtest it.

    To test a custom module, follow these steps:

    1. Create a YAML file that contains test resource definitions for theresources that your custom module checks.

       For information about how to create a test data file, seeCreate test resources in a YAML file.

    2. UnderUpload the YAML file, clickBrowse to upload the YAMLfile that contains the test resource definitions. The test startsautomatically when the file is uploaded.

    3. UnderTest results preview, check the results.

       • If there are syntax or other errors in your YAML file, a floatingerror message displays near the bottom of the browser page.

       • If the test is a success, the test returns the following information:

         • The display name of the custom module.
         • The arbitrary name that you specified on theresource propertyin the test data file.
         • The organization, folder, or project in which the custom modulewas, or will be, created.

    Test results are not stored or written to Security Command Center.

    For more information, seeTesting custom modules.

11. ClickCreate. You are returnedto theModules page and should see the module that you createdwith a status ofEnabled.

New custom modules are not immediately available for use bySecurity Health Analytics in scans. For more information, seeDetection latency.

gcloud CLI

To create a custom module by usinggcloud commands, you first need tocode the definition of the custom module in a YAML file that includesCEL expressions for the detection logic and output properties.

After the definition is complete, you upload the definition toSecurity Command Center by using gcloud CLI commands.

1. Code a custom module definition in a YAML file according to theinstructions inCode a custom module for Security Health Analytics.
2. Save the YAML file to a location that is accessible to your instanceof gcloud CLI.

3. Upload the custom definition to Security Command Center:

   gcloud scc custom-modules sha create \PARENT_FLAG=PARENT_ID \    --display-name="MODULE_DISPLAY_NAME" \    --enablement-state="ENABLEMENT_STATE" \    --custom-config-from-file=MODULE_FILE_NAME.yaml

   Replace the following:

   • PARENT_FLAG: the level at which you arecreating the custom module, either--organization,--folder, or--project.
   • PARENT_ID: the ID of the organization, folder,or project in which you are creating the custom module.
   • ENABLEMENT_STATE: eitherenabled ordisabled.
   • MODULE_DISPLAY_NAME: the finding categoryname that you want to display when the custom module returns a finding.The name must be between 1 and 128 characters, start with a lowercaseletter, and contain alphanumeric characters or underscores only.
   • MODULE_FILE_NAME: the path and file name ofthe YAML file that contains the definition of the custom module.

Terraform

Create a custom module for an organization:

resource"google_scc_management_organization_security_health_analytics_custom_module""example"{organization="123456789"display_name="basic_custom_module"location="global"enablement_state="ENABLED"custom_config{predicate{expression="resource.rotationPeriod > duration(\"2592000s\")"}resource_selector{resource_types=["cloudkms.googleapis.com/CryptoKey",]}description="The rotation period of the identified cryptokey resource exceeds 30 days."recommendation="Set the rotation period to at most 30 days."severity="MEDIUM"}}

Create a custom module for a folder:

resource"google_folder""folder"{parent="organizations/123456789"display_name="folder-name"deletion_protection=false}resource"google_scc_management_folder_security_health_analytics_custom_module""example"{folder=google_folder.folder.folder_idlocation="global"display_name="basic_custom_module"enablement_state="ENABLED"custom_config{predicate{expression="resource.rotationPeriod > duration(\"2592000s\")"}resource_selector{resource_types=["cloudkms.googleapis.com/CryptoKey",]}description="The rotation period of the identified cryptokey resource exceeds 30 days."recommendation="Set the rotation period to at most 30 days."severity="MEDIUM"}}

Create a custom module for a project:

resource"google_scc_management_project_security_health_analytics_custom_module""example"{location="global"display_name="basic_custom_module"enablement_state="ENABLED"custom_config{predicate{expression="resource.rotationPeriod > duration(\"2592000s\")"}resource_selector{resource_types=["cloudkms.googleapis.com/CryptoKey",]}description="The rotation period of the identified cryptokey resource exceeds 30 days."recommendation="Set the rotation period to at most 30 days."severity="MEDIUM"}}

Google Cloud console

To update an existing custom module in the Google Cloud console,follow these steps:

1. Go to the Security Command CenterSettings page in theGoogle Cloud console.

   Go to Settings

2. In the project selector, select the organization, folder, or projectin which the custom module was originally created. You can't edit acustom module anywhere else.

3. On theSecurity Health Analytics card, clickManage Settings.

4. Select theModules tab. All of the Security Health Analytics detectionmodules are displayed.

5. Use the filter field at the top of the list of modules or scroll to findthe custom module that you need to modify.

6. On the right side of the row of your custom module, click theActionmenu icon,more_vert.

7. From theAction menu, click theEdit icon(edit). TheView module page opens and displays theConfigure module tab.

8. Edit the custom module fields of each tab on theView modulepage as needed.

9. Optional: Before you save your updates, we recommend that you test them.

   To test a custom module, follow these steps:

   1. Create a YAML file that contains test resource definitions for theresources that your custom module checks.

      For information about how to create a test data file, seeCreate test resources in a YAML file.

   2. UnderUpload the YAML file, clickBrowse to upload the YAMLfile that contains the test resource definitions. The test startsautomatically when the file is uploaded.

   3. UnderTest results preview, check the results.

      • If there are syntax or other errors in your YAML file, a floatingerror message displays near the bottom of the browser page.

      • If the test is a success, the test returns the following information:

        • The display name of the custom module.
        • The arbitrary name that you specified on theresource propertyin the test data file.
        • The organization, folder, or project in which the custom modulewas, or will be, created.

   Test results are not stored or written to Security Command Center.

   For more information, seeTesting custom modules.

10. At the bottom of the page, clickSave. Your changes are applied tothe custom module.

gcloud CLI

To update a custom module by using the gcloud CLI,you first edit the YAML definition of the custom module and then usegcloud commands to update the custom module in Security Health Analytics.

1. Edit the custom module definition. For information about how to codea custom module definition, seeCoding a custom module for Security Health Analytics.

2. Save the edited YAML file to a location that is accessible to thegcloud CLI.

3. Update the custom module in Security Health Analytics by issuing the followingcommand:

   gcloud scc custom-modules sha updateMODULE_ID \PARENT_FLAG=PARENT_ID \   --enablement-state="ENABLED" \   --custom-config-from-file=MODULE_FILE_NAME.yaml

   Replace the following:

   • MODULE_ID: the ID or full resource name ofthe custom module.
   • PARENT_FLAG: the level at which the custommodule was created, either--organization,--folder, or--project.
   • PARENT_ID: the ID of the organization, folder,or project in which the custom module was created.
   • MODULE_FILE_NAME: the path and file name ofthe YAML file that contains the definition of the custom module.

Google Cloud console

To view custom modules in the Google Cloud console, follow these steps:

1. Go to theSecurity Health Analytics page in Security Command Centersettings.

   Go to Settings

2. Click theModules tab. TheModules panel opens.

3. If necessary, use the filter field at the top of the list of modulesto find the custom module that you need to modify.

4. To view the details of the custom module definition, click theActionmenu icon,more_vert, on the rightside of the custom module row.

5. From theAction menu, click theEdit icon,edit. TheView modulepage opens and displays theConfigure module tab.

6. Click through the tabs on theView module page to see all of thefields of the custom module definition.

gcloud CLI

To view the details of a custom module, enter the following command:

gcloud scc custom-modules sha getMODULE_ID \PARENT_FLAG=PARENT_ID

Replace the following:

• MODULE_ID: the ID or full resource name ofthe custom module.
• PARENT_FLAG: the level at which the custommodule was created, either--organization,--folder, or--project.
• PARENT_ID: the ID of the organization, folder,or project in which the custom module was created.

Google Cloud console

1. Go to theSecurity Health Analytics page in Security Command Centersettings.

   Go to Settings

2. Click theModules tab. TheModules panel opens.

3. Click in the filter field at the top of the list of modules to displaythe list of filter types.

4. SelectType and enterCustom. The modules lists is updated toshow only custom modules.

gcloud CLI

To view a list of custom modules, enter thefollowing command:

gcloud scc custom-modules sha list \PARENT_FLAG=PARENT_ID

Replace the following:

• PARENT_FLAG: the level at which the custommodule was created, either--organization,--folder, or--project.
• PARENT_ID: the ID of the organization, folder,or project in which the custom module was created.

1. Go to the Security Command CenterSettings page in theGoogle Cloud console.

   Go to Settings

2. If prompted, select your organization, folder, or project.

3. On theSecurity Health Analytics card, clickManage Settings.

4. Select theModules tab. All of the Security Health Analytics detectionmodules are displayed.

5. Use the filter field at the top of the list of modules or scroll to findthe custom module that you need to modify.

6. On the right side of the row of your custom module, click theActionmenu icon,more_vert.

7. From theAction menu, clickDelete. TheDelete custom moduledialog opens.

8. In the dialog, clickDelete.

gcloud CLI

To delete a custom module, enter the following command:

gcloud scc custom-modules sha deleteMODULE_ID \PARENT_FLAG=PARENT_ID

Replace the following:

• MODULE_ID: the ID or full resource name ofthe custom module.
• PARENT_FLAG: the level at which the custommodule was created, either--organization,--folder, or--project.
• PARENT_ID: the ID of the organization, folder,or project in which the custom module was created.

Console

1. In the Google Cloud console, go to theFindings page of Security Command Center.

   Go to Findings

2. Select your Google Cloud project or organization.
3. In theQuick filters section, in theSource display name subsection, selectSecurity Health Analytics Custom. The findings query results are updated to show only the findings from this source.
4. To view the details of a specific finding, click the finding name in theCategory column. The details panel for the finding opens and displays theSummary tab.
5. On theSummary tab, review the details of the finding, including information about what was detected, the affected resource, and—if available—steps that you can take to remediate the finding.
6. Optional: To view the full JSON definition of the finding, click theJSON tab.

gcloud CLI

To view findings, do the following:

1. Open a terminal window.

2. To get the source ID for Security Health Analytics, running thefollowing command:

   gcloud scc sources describe organizations/ORGANIZATION_ID \--source-display-name='Security Health Analytics Custom'

   The display output should resemble the following. In the example,SOURCE_ID is a server-assigned ID for securitysources.

   description: ...displayName: Security Health Analytics Customname: organizations/ORGANIZATION_ID/sources/SOURCE_ID

3. To list all findings generated by your custom modules, run the followingcommand:

   gcloud scc findings listORGANIZATION_ID --source=SOURCE_ID

4. To list findings for a specific custom module, run the following command:

   gcloud scc findings listORGANIZATION_ID --source=SOURCE_ID --filter="category=\"MODULE_NAME\""