Cloud Topology

The Cloud Topology view provides an interactive visualization of your AWS cloud infrastructure, automatically built from VPC Flow Log data ingested via Amazon SQS. Select the Cloud tab on the Topology page to switch to this view. WhiteOwl maps out your VPCs, subnets, availability zones, and EC2 instances, and overlays real-time traffic flow data so you can visually inspect how traffic moves across your cloud environment.

AWS VPC Flow Logs Only

Cloud Topology currently supports AWS VPC Flow Logs as the sole cloud data source. Support for additional cloud providers may be added in future releases.

How It Works

WhiteOwl ingests AWS VPC Flow Logs through an Amazon SQS (Simple Queue Service) integration. The data pipeline works as follows:

1. VPC Flow Logs are configured in your AWS account to publish to an S3 bucket.
2. S3 Event Notifications are configured to send new-object events to an SQS queue when flow log files arrive.
3. WhiteOwl polls the SQS queue, retrieves the S3 object references, downloads the flow log files, and parses them into the same unified flow schema used by NetFlow and sFlow data.
4. Cloud-specific fields are extracted and stored alongside standard flow fields, enabling filtering and analysis by AWS account, VPC, subnet, instance, region, and availability zone.

For instructions on configuring the SQS integration, see SQS Configuration below.

Cloud-Enriched Fields

In addition to all standard flow fields (source/destination IP, port, protocol, bytes, packets, etc.), AWS VPC Flow Log records are enriched with the following cloud-specific fields:

Field	Description
cloud_account	The AWS account ID that owns the VPC (e.g., 123456789012). Useful for multi-account environments.
cloud_region	The AWS region where the VPC resides (e.g., us-east-1, eu-west-2).
cloud_az	The Availability Zone of the source or destination ENI (e.g., us-east-1a).
cloud_vpc	The VPC ID associated with the flow (e.g., vpc-0a1b2c3d4e5f).
cloud_subnet	The subnet ID within the VPC (e.g., subnet-0a1b2c3d).
cloud_instance	The EC2 instance ID attached to the ENI generating the flow (e.g., i-0abcdef1234567890).
cloud_interface	The Elastic Network Interface (ENI) ID (e.g., eni-0a1b2c3d4e5f).
cloud_sublocation_type	The type of sublocation, such as wavelength or outpost, for flows involving AWS edge locations.
cloud_sublocation_id	The ID of the sublocation (Wavelength zone or Outpost ID) associated with the flow.

These fields are available throughout WhiteOwl — in the Flow Explorer, Custom Dashboards, Report Center, and Alert Management — enabling cloud-aware filtering and grouping across the platform.

Topology Map

The Cloud Topology map organizes your AWS infrastructure hierarchically:

• AWS Accounts — Top-level grouping for multi-account environments.
• Regions — AWS regions containing your VPCs.
• VPCs — Individual Virtual Private Clouds displayed as container nodes.
• Subnets / Availability Zones — Subdivisions within each VPC, grouped by AZ.
• Instances — EC2 instances shown as individual nodes within their parent subnet.

Links between nodes represent observed traffic flows. The thickness and color of each link reflects traffic volume and health status, following the same conventions as the Network Topology view.

Viewing Flow Details

Click on any link between cloud nodes to open the Link Flow Details panel on the right side of the screen. This works identically to the Network Topology view and provides:

Traffic Summary

Four summary tiles showing aggregate statistics for the selected connection:

Metric	Description
Total	Total bytes transferred across the link.
Avg Rate	Average throughput rate.
Packets	Total packet count observed.
Flows	Total number of unique flow records.

Traffic Direction

A breakdown of traffic by source → destination IP pair, sorted by volume. Each row shows the IP pair and total bytes, helping you quickly identify which conversations dominate a link.

Top Flows (by bytes)

A detailed table of individual flow records traversing the selected link, including:

Column	Description
Src IP	Source IP address.
Dst IP	Destination IP address.
Port	Destination port number.
Proto	Protocol (TCP, UDP, ICMP, etc.).
Bytes	Total bytes for this flow.
Pkts	Total packets for this flow.

Cloud-specific columns such as VPC, subnet, and instance IDs are also available in the flow detail view, allowing you to trace traffic back to specific AWS resources.

Investigating Security Group Issues

If you see unexpected REJECT actions in your flow data, use the Cloud Topology to visually identify which instances and subnets are affected. Click the link to drill into the specific flows being rejected, then cross-reference the source/destination IPs and ports with your Security Group and NACL rules in the AWS console.

Interacting with the Map

• Pan — Click and drag on the background to pan the view.
• Zoom — Use the scroll wheel to zoom in and out.
• Move Nodes — Click and drag any node to reposition it. Use Save Layout to persist your arrangement.
• Click a Link — Opens the Link Flow Details panel showing real-time flow data for that connection.
• Click a Node — Drills into the selected VPC, subnet, or instance for detailed metrics.

SQS Configuration

VPC Flow Log ingestion is configured via the Vector pipeline configuration file at /etc/chompy/vector-config/vector.toml. There is currently no UI for this configuration — it must be edited directly on the WhiteOwl server.

AWS Prerequisites

Before configuring WhiteOwl, set up the following in your AWS environment:

1. Enable VPC Flow Logs — Configure flow logs on the desired VPCs or subnets, publishing to an S3 bucket. Use the default or custom log format — WhiteOwl parses both.
2. Create an SQS Queue — Create a standard SQS queue (FIFO is not required). Note the queue URL and region.
3. Configure S3 Event Notifications — Set up the S3 bucket to send s3:ObjectCreated:* events to the SQS queue whenever new flow log files are written.
4. IAM Permissions — The IAM user or role used by WhiteOwl needs the following permissions:
   • sqs:ReceiveMessage, sqs:DeleteMessage, sqs:GetQueueAttributes on the SQS queue.
   • s3:GetObject on the S3 bucket containing the flow logs.

Vector Configuration

Edit /etc/chompy/vector-config/vector.toml and add or update the AWS source section (note the AWS secret and key shoud be configured in the /etc/chompy/.env):

# Source: VPC Flow Logs from S3
[sources.vpc_flow_logs]
type = "aws_s3"
region = "us-east-2"
strategy = "sqs"
sqs.queue_url = "https://sqs.us-east-2.amazonaws.com/YOUR_ACCOUNT_ID/your-sqs-queue-name"
sqs.delete_message = true

# Uncomment and populate if not using an IAM role
[sources.vpc_flow_logs.auth]
access_key_id = "${AWS_ACCESS_KEY_ID}"
secret_access_key = "${AWS_SECRET_ACCESS_KEY}"

Parameter	Description
region	The AWS region where your SQS queue and S3 bucket are located (e.g., us-east-2).
sqs.queue_url	The full URL of the SQS queue receiving S3 object-created notifications.
sqs.delete_message	When set to true, messages are deleted from the queue after successful processing. Set to false for testing or if multiple consumers share the queue.
access_key_id	AWS access key ID. Only required if WhiteOwl is not running with an IAM role that has the necessary permissions.
secret_access_key	AWS secret access key. Only required if WhiteOwl is not running with an IAM role.

After editing the configuration, restart the Vector service for changes to take effect:

docker restart chompy-vector

IAM Roles vs. Access Keys

If your WhiteOwl instance is running on an EC2 instance or ECS task, the recommended approach is to attach an IAM role with the required SQS and S3 permissions rather than hardcoding access keys. Leave the access_key_id and secret_access_key fields empty and Vector will automatically use the instance role credentials.

Queue Visibility Timeout

Set the SQS queue visibility timeout to at least 300 seconds (5 minutes). If the timeout is too short, messages may be re-processed before WhiteOwl finishes downloading and parsing the flow log files, resulting in duplicate flow records.

Filtering by Cloud Fields

All cloud-specific fields are available as filter criteria throughout WhiteOwl. Common use cases include:

• Filter by VPC — Isolate traffic to a specific VPC in the Flow Explorer or dashboards using the cloud_vpc field.
• Filter by Account — In multi-account environments, use cloud_account to scope analysis to a single AWS account.
• Group by AZ — Use cloud_az as a grouping dimension to compare traffic patterns across Availability Zones.
• Instance-level analysis — Filter by cloud_instance to see all traffic to and from a specific EC2 instance, useful for troubleshooting connectivity or performance issues.

These filters can be combined with standard flow fields (IP, port, protocol, application) for precise cross-domain analysis — for example, finding all TCP port 443 traffic from a specific subnet in us-east-1a.