google-secops

Example code for working with Google Security Operations (SecOps)

Health Checks

Example code to implement security data pipeline health checks with Google SecOps.

Please refer to the following blog series for further details and context: Practical Techniques for Monitoring Your Security Data Pipeline (Part 1, Part 2)

This example code can be customized and executed in Google Cloud Run Functions, an automation tool, or a CI/CD pipeline to validate that your security logging, ingestion, search, detection, and alerting capabilities are working properly. Refer to the above blog series for additional context and examples.

github/health-check-github-ping

Authenticates to GitHub's API and performs a basic read operation (retrieves the information for a GitHub organization) to generate an event in GitHub Enterprise's audit log.

Configuration

Environment Variables

HEALTH_CHECK_GITHUB_ORG_NAME

• The name of the GitHub organization to retrieve

Secrets

HEALTH_CHECK_GITHUB_PAT

• The GitHub Personal Access Token that has the permissions required to retrieve information for the specified GitHub organization

github/health-check-github-validate-log-ingestion

Validates that the event generated by github/health-check-github-ping is searchable in Google SecOps.

Configuration

Environment Variables

GOOGLE_SECOPS_API_BASE_URL

• Set the GOOGLE_SECOPS_API_BASE_URL variable to your regional service endpoint for Google SecOps' REST API
• For example, the base URL for the regional service endpoint in the US is https://us-chronicle.googleapis.com/v1alpha and the base URL for the regional service endpoint in Europe is https://eu-chronicle.googleapis.com/v1alpha

GOOGLE_SECOPS_INSTANCE

• Set the GOOGLE_SECOPS_INSTANCE variable as follows: projects/{google-cloud-project-id}/locations/{google-secops-instance-location}/instances/{google-secops-instance-id}
  • Replace the {google-cloud-project-id} placeholder with your Google Cloud project ID that is linked to your Google SecOps instance.
  • Replace the {google-secops-instance-location} placeholder with the location where your Google SecOps instance is running (e.g. us for the United States).
  • Replace the google-secops-instance-id placeholder with the Customer ID for your Google SecOps instance. You can find this under Settings - SIEM Settings - Profile in Google SecOps's UI.

GOOGLE_SECOPS_AUTHORIZATION_SCOPES

• Set the GOOGLE_SECOPS_AUTHORIZATION_SCOPES variable to AUTHORIZATION_SCOPES={"CHRONICLE_API":["https://www.googleapis.com/auth/cloud-platform"]}
• Refer to the Authentication methods at Google documentation for information on OAuth 2.0 scopes

SEARCH_TIME_WINDOW_HOURS

• Sets the start time to search for events in Google SecOps
• For example, a value of 1 will specify a start time for the search that is 1 hour ago from the current time

Secrets

GOOGLE_SECOPS_API_CREDENTIALS

• The service account key to authenticate to Google SecOps' REST API

github/health-check-github-validate-alert-generation

Validates that github/health-check-github-ping triggered a detection & alert in Google SecOps.

Configuration

Environment Variables

GOOGLE_SECOPS_API_BASE_URL

• Set the GOOGLE_SECOPS_API_BASE_URL variable to your regional service endpoint for Google SecOps' REST API
• For example, the base URL for the regional service endpoint in the US is https://us-chronicle.googleapis.com/v1alpha and the base URL for the regional service endpoint in Europe is https://eu-chronicle.googleapis.com/v1alpha

GOOGLE_SECOPS_INSTANCE

• Set the GOOGLE_SECOPS_INSTANCE variable as follows: projects/{google-cloud-project-id}/locations/{google-secops-instance-location}/instances/{google-secops-instance-id}
  • Replace the {google-cloud-project-id} placeholder with your Google Cloud project ID that is linked to your Google SecOps instance.
  • Replace the {google-secops-instance-location} placeholder with the location where your Google SecOps instance is running (e.g. us for the United States).
  • Replace the google-secops-instance-id placeholder with the Customer ID for your Google SecOps instance. You can find this under Settings - SIEM Settings - Profile in Google SecOps's UI.

GOOGLE_SECOPS_AUTHORIZATION_SCOPES

• Set the GOOGLE_SECOPS_AUTHORIZATION_SCOPES variable to AUTHORIZATION_SCOPES={"CHRONICLE_API":["https://www.googleapis.com/auth/cloud-platform"]}
• Refer to the Authentication methods at Google documentation for information on OAuth 2.0 scopes

GITHUB_HEALTH_CHECK_RULE_ID

• The unique ID of your GitHub health check rule in Google SecOps (e.g. ru_12345678-1234-1234-1234-abcd12345678)

SEARCH_TIME_WINDOW_HOURS

• Sets the start time to search for detections and alerts generated by your health check rule in Google SecOps
• For example, a value of 1 will specify a start time for the search that is 1 hour ago from the current time

Secrets

GOOGLE_SECOPS_API_CREDENTIALS

• The service account key to authenticate to Google SecOps' REST API