BLACKSHIELD

Guia público

Deploy Network Sensor on AWS

Capture live network traffic using VPC Traffic Mirroring, deploy sensor instances with CloudFormation or CDK, and stream findings automatically to the platform. Público: Platform engineers, network architects, security engineers. Tempo típico de configuração: 10 minutes.

quickstart

Use isto se

Capture live network traffic using VPC Traffic Mirroring, deploy sensor instances with CloudFormation or CDK, and stream findings automatically to the platform.

Audience
Platform engineers, network architects, security engineers
Typical time
10 minutes

Antes de começar

  • You have an AWS VPC with production workloads running in EC2 instances.
  • You have created an ingestion API key in Settings → API Keys with Ingestion scope.
  • You have permissions to create VPC Traffic Mirror resources and EC2 instances.

Caminho rápido

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

Obtém o bundle de código fonte

Descarrega os ficheiros exatos usados neste guia ou executa o instalador de um só comando para os escrever localmente antes do deploy.

AWS network sensor CDK source

Creates the AWS CDK project under `deploy/aws-network-sensor/` with the current platform API URL prefilled so the deployment commands on this page are runnable without editing boilerplate first.

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

Executar isto

create-traffic-mirror-session.sh

bash
#!/bin/bash
# Create VPC Traffic Mirroring session to capture traffic from production VMs

MIRROR_TARGET_ENI="eni-0123456789abcdef0"  # Sensor instance ENI
SOURCE_ENI="eni-abcdef0123456789"          # Production VM ENI

aws ec2 create-traffic-mirror-target \
  --network-interface-id "$MIRROR_TARGET_ENI" \
  --description "Network sensor mirror target"

Entender e personalizar

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

Passo 1

Set up VPC Traffic Mirroring

Configure traffic mirror target, filter, and session to capture traffic from production workloads.

  • Create a traffic mirror target pointing to the primary sensor instance (ENI).
  • Define traffic mirror filter to capture inbound + outbound TCP/UDP (or specific ports).
  • Create traffic mirror session on production VPC resources (EC2 instances or network interfaces).
  • Start the session and verify packets are flowing using tcpdump on the sensor instance.

Como é o sucesso

Start the session and verify packets are flowing using tcpdump on the sensor instance.

Open AWS network sensor prep

Passo 2

Deploy sensor instance with CDK

Use the ready-made CDK stack to deploy the sensor with IAM, security groups, and CloudWatch monitoring.

  • Use the source bundle on this page to download the AWS network sensor CDK project into deploy/aws-network-sensor/ with `api_url` already prefilled for your deployed platform.
  • Open deploy/aws-network-sensor/cdk.json and set your VPC ID, subnet ID, and any non-default sensor settings.
  • Run: cdk bootstrap (first time only) && cdk deploy --require-approval never from deploy/aws-network-sensor/.
  • The stack creates an EC2 instance with IAM role, inbound rule on 4789/UDP for VXLAN, and CloudWatch logging for the sensor container.

Como é o sucesso

The stack creates an EC2 instance with IAM role, inbound rule on 4789/UDP for VXLAN, and CloudWatch logging for the sensor container.

AWS Deployment Guide

Passo 3

Configure the sensor and validate

Set environment variables and start ingestion to verify findings are flowing.

  • SSH to the sensor instance and set BLACKSHIELD_API_KEY + BLACKSHIELD_API_URL.
  • The sensor container starts automatically and begins pulling API key from Secrets Manager.
  • Check logs: docker logs -f $(docker ps -q) — look for 'starting packet capture' and 'findings sent'.
  • Verify in the platform: Findings view should show network-based alerts within 5 minutes.

Como é o sucesso

Verify in the platform: Findings view should show network-based alerts within 5 minutes.

View Findings · Requer login

Como é o sucesso

  • Findings are appearing in the platform Findings view with scanner=network (AWS).
  • CloudWatch shows CPU < 50% and memory < 400 MB on the sensor instance.
  • No dropped packets reported in the traffic mirror session (verify via AWS CLI or console).
Deploy Network Sensor on AWS | Documentação BlackShield