BLACKSHIELD

Guida pubblica

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. Pubblico: Platform engineers, network architects, security engineers. Tempo medio di configurazione: 15 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
15 minutes

Prima di iniziare

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

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.

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.6 \
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

Esegui

aws-cdk-deploy.sh

bash
# 1. Create API Key Secret
aws secretsmanager create-secret \
  --name blackshield/network-sensor-key-prod \
  --secret-string "sp_your_ingestion_key"

# 2. Deploy Infrastructure
cd deploy/aws-network-sensor
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# IMPORTANT: Edit cdk.json and replace vpc-REPLACE_ME and subnet-REPLACE_ME 
# with your actual AWS IDs before deploying!

cdk bootstrap
cdk deploy --require-approval never

network-sensor-stack.py

python
"""CDK stack for the BlackShield AWS network sensor."""
from aws_cdk import Stack
from aws_cdk import aws_ec2 as ec2
from aws_cdk import aws_iam as iam
from constructs import Construct

class NetworkSensorStack(Stack):
    def __init__(self, scope: Construct, id: str, vpc_id: str, subnet_id: str, sensor_secret_name: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        vpc = ec2.Vpc.from_lookup(self, "Vpc", vpc_id=vpc_id)
        subnet = ec2.Subnet.from_subnet_attributes(
            self, "Subnet",
            subnet_id=subnet_id,
            availability_zone=vpc.availability_zones[0]
        )

        role = iam.Role(
            self, "NetworkSensorRole",
            assumed_by=iam.ServicePrincipal("ec2.amazonaws.com"),
            managed_policies=[iam.ManagedPolicy.from_aws_managed_policy_name("AmazonSSMManagedInstanceCore")]
        )
        role.add_to_policy(
            iam.PolicyStatement(
                actions=["secretsmanager:GetSecretValue"],
                resources=[f"arn:aws:secretsmanager:${self.region}:${self.account}:secret:${sensor_secret_name}*"],
            )
        )

        security_group = ec2.SecurityGroup(self, "SensorSG", vpc=vpc, description="Allow VXLAN")
        security_group.add_ingress_rule(ec2.Peer.ipv4("10.0.0.0/8"), ec2.Port.udp(4789), "VXLAN")

        instance = ec2.Instance(
            self, "NetworkSensorInstance",
            vpc=vpc,
            vpc_subnets=ec2.SubnetSelection(subnets=[subnet]),
            instance_type=ec2.InstanceType("t3.medium"),
            machine_image=ec2.MachineImage.latest_amazon_linux2023(),
            security_group=security_group,
            role=role,
        )

vpc-traffic-mirroring-setup.sh

bash
#!/bin/bash
# Complete AWS VPC Traffic Mirroring setup script

SENSOR_ENI="eni-0123456789abcdef0"  # Target Sensor ENI
SOURCE_ENI="eni-abcdef0123456789"    # Production VM ENI
VNI=7392                             # VXLAN Network Identifier (default)

echo "1. Creating Traffic Mirror Target..."
TARGET_ID=$(aws ec2 create-traffic-mirror-target \
  --network-interface-id "$SENSOR_ENI" \
  --description "Network Sensor Target" \
  --query 'TrafficMirrorTarget.TrafficMirrorTargetId' \
  --output text)

echo "2. Creating Traffic Mirror Filter (Capture all TCP/UDP)..."
FILTER_ID=$(aws ec2 create-traffic-mirror-filter \
  --description "Capture all TCP/UDP" \
  --query 'TrafficMirrorFilter.TrafficMirrorFilterId' \
  --output text)

aws ec2 create-traffic-mirror-filter-rule \
  --traffic-mirror-filter-id "$FILTER_ID" \
  --traffic-direction INGRESS --rule-number 100 --rule-action accept \
  --protocol 6 --source-cidr-block "0.0.0.0/0" --destination-cidr-block "0.0.0.0/0" > /dev/null

aws ec2 create-traffic-mirror-filter-rule \
  --traffic-mirror-filter-id "$FILTER_ID" \
  --traffic-direction INGRESS --rule-number 200 --rule-action accept \
  --protocol 17 --source-cidr-block "0.0.0.0/0" --destination-cidr-block "0.0.0.0/0" > /dev/null

echo "3. Creating Traffic Mirror Session..."
SESSION_ID=$(aws ec2 create-traffic-mirror-session \
  --network-interface-id "$SOURCE_ENI" \
  --traffic-mirror-target-id "$TARGET_ID" \
  --traffic-mirror-filter-id "$FILTER_ID" \
  --session-number 1 \
  --virtual-network-id "$VNI" \
  --description "Production workload mirroring" \
  --query 'TrafficMirrorSession.TrafficMirrorSessionId' \
  --output text)

echo "Success! Mirror Session $SESSION_ID is routing traffic to $TARGET_ID"

Understand and customize

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

Passo 1

Deploy sensor instance with CDK

Use the ready-made CDK stack to deploy a right-sized EC2 instance with the necessary IAM roles, security groups, and CloudWatch monitoring. This acts as the destination for mirrored traffic.

  • Use the source bundle below to download the AWS network sensor CDK project into `deploy/aws-network-sensor/`.
  • Store your ingestion API key in AWS Secrets Manager as `blackshield/network-sensor-key-prod`.
  • Open `deploy/aws-network-sensor/cdk.json` and set your VPC ID, subnet ID, and instance sizing.
  • Set up a Python 3 virtual environment and install dependencies (`pip install -r requirements.txt`).
  • Run `cdk bootstrap` (first time only) and `cdk deploy --require-approval never`.
  • Note the newly created EC2 Instance ID and ENI (Elastic Network Interface) ID from the CDK outputs — you'll need this for the mirror target.

What success looks like

Note the newly created EC2 Instance ID and ENI (Elastic Network Interface) ID from the CDK outputs — you'll need this for the mirror target.

Download source bundle

Passo 2

Create Traffic Mirror Filter

Define what traffic should be captured. A mirror filter contains inbound and outbound rules, similar to a Network ACL.

  • Create a new Traffic Mirror Filter in the VPC console or via the AWS CLI.
  • Add an inbound rule to capture TCP and UDP traffic (or restrict to specific high-risk ports if volume is a concern).
  • Add an outbound rule to capture return traffic if bidirectional inspection is required.
  • Keep the filter ID handy for the next step.

What success looks like

Keep the filter ID handy for the next step.

AWS Deployment Guide

Helpful context

AWS Traffic Mirror Filters Guide

Passo 3

Set up the Mirror Target & Session

Route the filtered traffic from your production workloads (Source ENI) to your sensor instance (Target ENI).

  • Create a Traffic Mirror Target pointing to the Sensor ENI you deployed in Step 1.
  • Identify the Source ENI(s) belonging to the production EC2 instances you want to monitor.
  • Create a Traffic Mirror Session that links the Source ENI to the Target ENI, using the Filter from Step 2.
  • Ensure the sensor's Security Group allows inbound UDP on port 4789 (VXLAN), which is how mirrored traffic is encapsulated.

What success looks like

Ensure the sensor's Security Group allows inbound UDP on port 4789 (VXLAN), which is how mirrored traffic is encapsulated.

View Findings · Sign-in required

Passo 4

Configure the sensor and validate

Start the sensor container and verify that traffic is being successfully decapsulated and inspected.

  • If using the CDK bundle, the sensor container starts automatically via user-data and pulls the API key from Secrets Manager.
  • SSH into the sensor instance and check logs: `docker logs -f $(docker ps -q)`. Look for 'starting packet capture' and 'findings sent'.
  • Run `sudo tcpdump -i eth0 port 4789` on the sensor host to verify VXLAN traffic is physically arriving from AWS.
  • 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 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