BLACKSHIELD

公開ガイド

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. 対象: Platform engineers, network architects, security engineers. 一般的な設定時間: 10 minutes.

quickstart

Use this if

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

開始前に

  • 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.

Fast path

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

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.

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
Download source

実行する

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"

Understand and customize

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

ステップ 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.

What success looks like

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

Open AWS network sensor prep

ステップ 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.

What success looks like

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

ステップ 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.

What success looks like

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

View Findings · Sign-in required

What success looks like

  • 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 | BlackShield Docs