BLACKSHIELD

Public Guide

Deploy Network Sensor on GCP

Stream live traffic using Packet Mirroring, deploy sensor VM with Terraform, and ingest findings via the managed SIEM connector. Audience: Platform engineers, GCP administrators, security engineers. Typical setup time: 15 minutes.

quickstart

Use this if

Stream live traffic using Packet Mirroring, deploy sensor VM with Terraform, and ingest findings via the managed SIEM connector.

Audience
Platform engineers, GCP administrators, security engineers
Typical time
15 minutes

Before You Begin

  • You have a GCP project with production VMs running workloads.
  • You have created an ingestion API key in Settings → API Keys with Ingestion scope.
  • You have the gcloud CLI configured with appropriate permissions to create compute resources.

Fast path

Copy a working starter, run it in your environment, then come back here for the deeper rollout details.

Demonstration only

This configuration is designed for ease of use. To deploy scanner clients at scale, please plan your deployment architecture accordingly or contact us for enterprise best practices.

Get the source bundle

Download the exact source files referenced on this page, or run the one-command installer to write them locally before following the deployment steps.

GCP network sensor Terraform source

Creates the GCP Terraform project under `deploy/gcp-network-sensor/` with the current platform API URL prefilled for packet mirroring-based network telemetry ingestion.

deploy/gcp-network-sensor/
bash
BLACKSHIELD_NETWORK_SENSOR_IMAGE=public.ecr.aws/blackshield-security/network-sensor:1.0.6 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/gcp-network-sensor.sh)
cd deploy/gcp-network-sensor
Download source

Run This

gcp-packet-mirroring.sh

bash
#!/bin/bash
# Complete GCP Packet Mirroring setup

PROJECT_ID="my-project"
REGION="us-central1"
SUBNET="my-subnet"
NETWORK="my-vpc"
SENSOR_MIG="network-sensor-mig" # The Instance Group from your Terraform deployment

echo "1. Creating Health Check & Backend Service..."
gcloud compute health-checks create tcp network-sensor-hc --port=8080 --project="$PROJECT_ID"

gcloud compute backend-services create network-sensor-backend \
  --region="$REGION" \
  --health-checks=network-sensor-hc \
  --load-balancing-scheme=INTERNAL \
  --protocol=TCP \
  --project="$PROJECT_ID"

gcloud compute backend-services add-backend network-sensor-backend \
  --region="$REGION" \
  --instance-group="$SENSOR_MIG" \
  --project="$PROJECT_ID"

echo "2. Creating Forwarding Rule (Mirroring Target)..."
gcloud compute forwarding-rules create network-sensor-fr \
  --region="$REGION" \
  --network="$NETWORK" \
  --subnet="$SUBNET" \
  --load-balancing-scheme=INTERNAL \
  --backend-service=network-sensor-backend \
  --is-mirroring-collector \
  --project="$PROJECT_ID"

echo "3. Creating Packet Mirroring Policy..."
gcloud compute packet-mirrorings create prod-workload-mirror \
  --region="$REGION" \
  --network="$NETWORK" \
  --collector-ilb=network-sensor-fr \
  --mirrored-subnets="$SUBNET" \
  --project="$PROJECT_ID"

echo "Success! Packet mirroring policy active."

gcp-terraform-deploy.sh

bash
# 1. Configure Terraform Variables
cat > deploy/gcp-network-sensor/terraform.tfvars << EOF
gcp_project_id         = "my-project-id"
gcp_region             = "us-central1"
vpc_network_name       = "default"
api_key                = "sp_your_ingestion_key"
EOF

# 2. Deploy Infrastructure
cd deploy/gcp-network-sensor
terraform init
terraform apply -auto-approve

network-sensor.tf

terraform
# GCP Terraform snippet for Network Sensor Deployment
resource "google_compute_instance" "network_sensor" {
  name         = "blackshield-network-sensor"
  machine_type = "e2-medium"
  zone         = "us-central1-a"

  boot_disk {
    initialize_params {
      image = "ubuntu-os-cloud/ubuntu-2204-lts"
    }
  }

  network_interface {
    network    = var.vpc_network_name
    subnetwork = var.monitoring_subnet_name
  }

  metadata = {
    startup-script = templatefile("${path.module}/startup.sh.tftpl", {
      api_url      = "https://api.blackshield.chaplau.com"
      sensor_type  = "suricata"
      min_severity = "high"
    })
  }

  service_account {
    scopes = ["cloud-platform"]
  }
}

Understand and customize

Use the guided steps below when you want to tailor the rollout, validate ownership, or expand the deployment safely.

Step 1

Deploy Sensor VM with Terraform

Use the provided Terraform module to deploy the sensor VM (or Managed Instance Group). This acts as the destination for your mirrored traffic.

  • Use the source bundle below to download the GCP network sensor Terraform project into `deploy/gcp-network-sensor/`.
  • Copy `terraform.tfvars.example` to `terraform.tfvars` and customize your GCP project ID, region, VPC network, subnet, and API key.
  • Run `terraform init` and `terraform apply`.
  • Note the generated Managed Instance Group (MIG) name from the Terraform output — you'll need this to set up the Internal Load Balancer target.

What success looks like

Note the generated Managed Instance Group (MIG) name from the Terraform output — you'll need this to set up the Internal Load Balancer target.

Download source bundle

Step 2

Configure GCP Packet Mirroring

Create a packet mirroring policy to duplicate traffic from your production VMs and route it to the sensor instances via an Internal Load Balancer.

  • Create a regional Backend Service and attach your Sensor MIG.
  • Create an Internal Forwarding Rule that acts as the mirroring target (`--is-mirroring-collector`).
  • Define a Packet Mirroring Policy targeting your source workloads (using network, subnet, or tags).
  • Verify the mirroring policy status is 'ACTIVE' in the GCP Console.

What success looks like

Verify the mirroring policy status is 'ACTIVE' in the GCP Console.

GCP Deployment Guide

Helpful context

GCP Packet Mirroring Overview

Step 3

Verify Ingestion

Confirm the sensor container is running properly on your VM and receiving the mirrored VXLAN traffic.

  • SSH into the sensor VM: `gcloud compute ssh [instance-name] --zone [zone]`.
  • Check the container logs using `docker logs -f $(docker ps -q)`. Look for 'capture interface ready' and 'findings sent'.
  • Check the platform Findings view to see network-based alerts within 5 minutes.

What success looks like

Check the platform Findings view to see network-based alerts within 5 minutes.

View Findings · Sign-in required

What success looks like

  • Findings are flowing to the platform with scanner=network (GCP) in the Findings view.
  • Packet mirroring policy shows 'ACTIVE' status in the GCP Console.
  • Sensor VM CPU and memory utilization remain within expected ranges.
Deploy Network Sensor on GCP | BlackShield Docs