AWS VPC Flow Logs Visualizer (Django DRF + React)

This starter implements a full-stack baseline for your use case:

• ingest AWS VPC flow logs
• correlate client->server (c2s) and server->client (s2c) directions
• enrich IPs with metadata (name, provider/team, tags, attributes)
• group IPs into CIDR-based VPC/container/external network groups
• visualize provider/consumer relationships as a bubble mesh graph
• generate firewall rule suggestions from observed traffic

Table of Contents

• Project Layout
• Screenshots & Demo
• Backend Setup
• Frontend Setup
• Container (Docker)
• GitHub Container Registry (GHCR)
• Core API Endpoints
• Example Upload Request
• Notes

Project Layout

• backend/ Django + DRF API
• frontend/ React (Vite) UI

Screenshots & Demo

• Demo video: Streamable walkthrough

Dashboard	Map View
Flow Logs	Assets
Firewall Simulator

Backend Setup

cd backend
poetry install
poetry run python manage.py migrate
poetry run python manage.py runserver

Backend runs on http://localhost:8000.

Seed realistic demo data (assets/groups/flows/correlations + firewall simulator snapshots):

./scripts/seed_demo_data.sh

Equivalent direct command:

cd backend && poetry run python manage.py seed_demo_data --reset --source demo-seed --seed 20260301 --days 14 --flow-pairs 2200

Database behavior:

• default is SQLite (backend/db.sqlite3)
• set DJANGO_DATABASE_URL (or DATABASE_URL) to use PostgreSQL, for example: postgresql://user:password@localhost:5432/aws_vpc_flow_logs
• for local Poetry runs with PostgreSQL, install driver once: cd backend && poetry add "psycopg[binary]"

Optional API login:

• leave unset for open access (current default behavior)
• set WRITE_ACCOUNT=username:password for read/write access
• set READ_ACCOUNT=username:password for read-only access
• when either variable is set, API endpoints require HTTP Basic auth

Frontend Setup

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5173 and proxies /api to the Django backend.

Container (Docker)

Build and run the full app (frontend + backend) as one container:

docker build -t aws-vpc-flow-logs-visualizer:local .
docker run --rm -p 8000:8000 aws-vpc-flow-logs-visualizer:local

Use PostgreSQL in container runtime by passing a DB URL:

docker run --rm -p 8000:8000 \
  -e DJANGO_DATABASE_URL='postgresql://user:password@host:5432/aws_vpc_flow_logs' \
  aws-vpc-flow-logs-visualizer:local

Enable optional auth in container runtime:

docker run --rm -p 8000:8000 \
  -e WRITE_ACCOUNT='admin:admin' \
  -e READ_ACCOUNT='user:user' \
  aws-vpc-flow-logs-visualizer:local

Then open:

• http://localhost:8000/ (React app)
• http://localhost:8000/api/docs/ (Swagger UI)
• http://localhost:8000/api/redoc/ (ReDoc)

You can also run with Docker Compose:

docker compose up --build

Production-style Compose (pull app image from GHCR + run PostgreSQL):

export POSTGRES_PASSWORD='change-me'
docker compose -f docker-compose.prod.yml up -d

Optional overrides:

• APP_IMAGE (defaults to ghcr.io/jbhoorasingh/aws-vpc-flow-logs-visualizer:latest)
• APP_PORT (defaults to 8000)
• DJANGO_ALLOWED_HOSTS
• WRITE_ACCOUNT / READ_ACCOUNT (format: username:password)

GitHub Container Registry (GHCR)

This repo includes .github/workflows/container.yml, which builds and publishes:

• ghcr.io/jbhoorasingh/aws-vpc-flow-logs-visualizer:latest on pushes to main
• ghcr.io/jbhoorasingh/aws-vpc-flow-logs-visualizer:v* when you push a version tag
• ghcr.io/jbhoorasingh/aws-vpc-flow-logs-visualizer:sha-... for immutable deploys

Single-line deploy from GHCR:

docker run -d --name aws-vpc-flow-logs-visualizer --restart unless-stopped -p 8000:8000 ghcr.io/jbhoorasingh/aws-vpc-flow-logs-visualizer:latest

Core API Endpoints

• GET /api/health/
• GET /api/search/?q=<term> (global search across flows/assets/groups)
• POST /api/uploads/flow-logs/
  • accepts multipart file, repeated files (bulk), or text lines
  • file supports plain text flow logs and gzip-compressed .log.gz
  • optional: source, auto_correlate=true|false
  • optional: log_format (space-separated fields, defaults to version account-id interface-id srcaddr dstaddr srcport dstport protocol packets bytes start end action log-status)
• POST /api/correlation/rebuild/
• GET /api/flow-logs/
  • optional advanced expression filter with advanced_filter, e.g. ((addr.src == 10.108.1.1) or (addr.dst == 10.108.1.1)) and (protocol == icmp) and (port.dst == 80)
  • protocol names accepted in advanced filters: icmp, ipip, tcp, udp (or numeric values)
  • supports asset metadata fields like instance.owner=4442424324, instance.name=*aws*, instance.region=us-east-1, instance.az=us-east-1d, and instance.tags.environment="prod" (asset.* is an alias)
• GET /api/correlated-flows/
• GET/POST /api/ip-metadata/
• POST /api/metadata/import/
• GET/POST /api/network-groups/
• POST /api/maintenance/network-groups/import/
• GET /api/mesh/
• GET /api/firewall/recommendations/?min_bytes=0
• GET /api/schema/ (OpenAPI schema)
• GET /api/docs/ (Swagger UI)
• GET /api/redoc/ (ReDoc)

Network groups support either a single cidr or a cidrs list:

{
  "name": "prod-vpc",
  "kind": "VPC",
  "cidrs": ["10.0.0.0/16", "10.1.0.0/16"]
}

Example Upload Request

curl -X POST http://localhost:8000/api/uploads/flow-logs/ \
  -F "source=prod-vpc" \
  -F "auto_correlate=true" \
  -F "log_format=version account-id interface-id srcaddr dstaddr srcport dstport protocol packets bytes start end action log-status" \
  -F "file=@sample-flow.log"

Notes

• Correlation uses server-port inference heuristics to pair c2s/s2c conversations.
• Firewall recommendations aggregate by CIDR group when available; otherwise by host CIDR.
• Service mesh view uses Cytoscape.js with interactive zoom/pan, layout switching, and node/edge inspection.
• SQLite is configured by default for fast local iteration.

License

This project is licensed under the custom non-commercial license in LICENSE. Commercial use is reserved for the Licensor.