Create a Security Health Analytics custom module

Sample code for creation of Security Health Analytics custom modules.

Code sample

Java

To authenticate to Security Command Center, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.securitycentermanagement.v1.CreateSecurityHealthAnalyticsCustomModuleRequest;
import com.google.cloud.securitycentermanagement.v1.CustomConfig;
import com.google.cloud.securitycentermanagement.v1.CustomConfig.ResourceSelector;
import com.google.cloud.securitycentermanagement.v1.CustomConfig.Severity;
import com.google.cloud.securitycentermanagement.v1.SecurityCenterManagementClient;
import com.google.cloud.securitycentermanagement.v1.SecurityHealthAnalyticsCustomModule;
import com.google.cloud.securitycentermanagement.v1.SecurityHealthAnalyticsCustomModule.EnablementState;
import com.google.type.Expr;
import java.io.IOException;

public class CreateSecurityHealthAnalyticsCustomModule {

  public static void main(String[] args) throws IOException {
    // https://cloud.google.com/security-command-center/docs/reference/security-center-management/rest/v1/organizations.locations.securityHealthAnalyticsCustomModules/create
    // TODO: Developer should replace project_id with a real project ID before running this code
    String projectId = "project_id";

    String customModuleDisplayName = "custom_module_display_name";

    createSecurityHealthAnalyticsCustomModule(projectId, customModuleDisplayName);
  }

  public static SecurityHealthAnalyticsCustomModule createSecurityHealthAnalyticsCustomModule(
      String projectId, String customModuleDisplayName) throws IOException {

    // Initialize client that will be used to send requests. This client only needs
    // to be created
    // once, and can be reused for multiple requests.
    try (SecurityCenterManagementClient client = SecurityCenterManagementClient.create()) {

      String name =
          String.format(
              "projects/%s/locations/global/securityHealthAnalyticsCustomModules/%s",
              projectId, "custom_module");

      // define the CEL expression here and this will scans for keys that have not been rotated in
      // the last 30 days, change it according to the your requirements
      Expr expr =
          Expr.newBuilder()
              .setExpression(
                  "has(resource.rotationPeriod) && (resource.rotationPeriod > "
                      + "duration('2592000s'))")
              .build();

      // define the resource selector
      ResourceSelector resourceSelector =
          ResourceSelector.newBuilder()
              .addResourceTypes("cloudkms.googleapis.com/CryptoKey")
              .build();

      // define the custom module configuration, update the severity, description,
      // recommendation below
      CustomConfig customConfig =
          CustomConfig.newBuilder()
              .setPredicate(expr)
              .setResourceSelector(resourceSelector)
              .setSeverity(Severity.MEDIUM)
              .setDescription("add your description here")
              .setRecommendation("add your recommendation here")
              .build();

      // define the security health analytics custom module configuration, update the
      // EnablementState below
      SecurityHealthAnalyticsCustomModule securityHealthAnalyticsCustomModule =
          SecurityHealthAnalyticsCustomModule.newBuilder()
              .setName(name)
              .setDisplayName(customModuleDisplayName)
              .setEnablementState(EnablementState.ENABLED)
              .setCustomConfig(customConfig)
              .build();

      CreateSecurityHealthAnalyticsCustomModuleRequest request =
          CreateSecurityHealthAnalyticsCustomModuleRequest.newBuilder()
              .setParent(String.format("projects/%s/locations/global", projectId))
              .setSecurityHealthAnalyticsCustomModule(securityHealthAnalyticsCustomModule)
              .build();

      SecurityHealthAnalyticsCustomModule response =
          client.createSecurityHealthAnalyticsCustomModule(request);

      return response;
    }
  }
}

Node.js

To authenticate to Security Command Center, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

// npm install '@google-cloud/securitycentermanagement'
const {
  SecurityCenterManagementClient,
  protos,
} = require('@google-cloud/securitycentermanagement');

const client = new SecurityCenterManagementClient();

const EnablementState =
  protos.google.cloud.securitycentermanagement.v1
    .SecurityHealthAnalyticsCustomModule.EnablementState;

const Severity =
  protos.google.cloud.securitycentermanagement.v1.CustomConfig.Severity;

/*
 * Required. The name of the parent resource of security health analytics module
 *     Its format is
 *    `organizations/[organization_id]/locations/[location_id]`
 *    `folders/[folder_id]/locations/[location_id]`
 *    `projects/[project_id]/locations/[location_id]`
 */
const parent = `organizations/${organizationId}/locations/${locationId}`;

/*
 * Required. Resource name of security health analytics module.
 *     Its format is
 *    `organizations/[organization_id]/locations/[location_id]/securityHealthAnalyticsCustomModules/[custom_module]`
 *    `folders/[folder_id]/locations/[location_id]/securityHealthAnalyticsCustomModules/[custom_module]`
 *    `projects/[project_id]/locations/[location_id]/securityHealthAnalyticsCustomModules/[custom_module]`
 */
const name = `organizations/${organizationId}/locations/${locationId}/securityHealthAnalyticsCustomModules/custom_module`;

// define the CEL expression here and this will scans for keys that have not been rotated in
// the last 30 days, change it according to your requirements
const expr = {
  expression: `has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))`,
};

// define the resource selector
const resourceSelector = {
  resourceTypes: ['cloudkms.googleapis.com/CryptoKey'],
};

// define the custom module configuration, update the severity, description,
// recommendation below
const customConfig = {
  predicate: expr,
  resourceSelector: resourceSelector,
  severity: Severity.MEDIUM,
  description: 'add your description here',
  recommendation: 'add your recommendation here',
};

// define the security health analytics custom module configuration, update the
// EnablementState below
const securityHealthAnalyticsCustomModule = {
  name: name,
  displayName: customModuleDisplayName,
  enablementState: EnablementState.ENABLED,
  customConfig: customConfig,
};

async function createSecurityHealthAnalyticsCustomModule() {
  const [response] = await client.createSecurityHealthAnalyticsCustomModule({
    parent: parent,
    securityHealthAnalyticsCustomModule: securityHealthAnalyticsCustomModule,
  });
  console.log(
    'Security Health Analytics Custom Module creation succeeded: ',
    response
  );
}

createSecurityHealthAnalyticsCustomModule();

Python

To authenticate to Security Command Center, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

def create_security_health_analytics_custom_module(parent: str) -> securitycentermanagement_v1.SecurityHealthAnalyticsCustomModule:
    """
    Creates a Security Health Analytics custom module.

    This custom module evaluates Cloud KMS CryptoKeys to ensure their rotation period exceeds 30 days (2592000 seconds),
    as per security best practices. A shorter rotation period helps reduce the risk of exposure in the event of a compromise.

    Args:
        parent: Use any one of the following options:
                - organizations/{organization_id}/locations/{location_id}
                - folders/{folder_id}/locations/{location_id}
                - projects/{project_id}/locations/{location_id}
    Returns:
        Dict: Created custom module details.
    """
    client = securitycentermanagement_v1.SecurityCenterManagementClient()

    try:
        # Generate a unique suffix
        unique_suffix = str(uuid.uuid4()).replace("-", "_")
        # Generate a unique display name
        display_name = f"python_sample_sha_custom_module_{unique_suffix}"

        # Define the custom module configuration
        custom_module = {
            "display_name": display_name,
            "enablement_state": "ENABLED",
            "custom_config": {
                "description": (
                    "Sample custom module for testing purposes. This custom module evaluates "
                    "Cloud KMS CryptoKeys to ensure their rotation period exceeds 30 days (2592000 seconds)."
                ),
                "predicate": {
                    "expression": "has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))",
                    "title": "Cloud KMS CryptoKey Rotation Period",
                    "description": (
                        "Evaluates whether the rotation period of a Cloud KMS CryptoKey exceeds 30 days. "
                        "A longer rotation period might increase the risk of exposure."
                    ),
                },
                "recommendation": (
                    "Review and adjust the rotation period for Cloud KMS CryptoKeys to align with your security policies. "
                    "Consider setting a shorter rotation period if possible."
                ),
                "resource_selector": {"resource_types": ["cloudkms.googleapis.com/CryptoKey"]},
                "severity": "CRITICAL",
                "custom_output": {
                    "properties": [
                        {
                            "name": "example_property",
                            "value_expression": {
                                "description": "The resource name of the CryptoKey being evaluated.",
                                "expression": "resource.name",
                                "location": "global",
                                "title": "CryptoKey Resource Name",
                            },
                        }
                    ]
                },
            },
        }

        request = securitycentermanagement_v1.CreateSecurityHealthAnalyticsCustomModuleRequest(
            parent=parent,
            security_health_analytics_custom_module=custom_module,
        )

        response = client.create_security_health_analytics_custom_module(request=request)
        print(f"Created SecurityHealthAnalytics Custom Module: {response.name}")
        return response

    except GoogleAPICallError as e:
        print(f"Failed to create EventThreatDetectionCustomModule: {e}")
        raise

What's next

To search and filter code samples for other Google Cloud products, see the Google Cloud sample browser.