From zero to full certificate visibility in five minutes. Docker required, everything else is included.
CipherFlag runs as three Docker containers. You need Docker 20.10+ and Docker Compose v2+ installed. No other dependencies.
| Deployment | CPU | RAM | Disk |
|---|---|---|---|
| Evaluation / PCAP-only | 2 cores | 4 GB | 20 GB |
| Small network (< 1 Gbps) | 4 cores | 8 GB | 50 GB |
| Medium network (1–10 Gbps) | 8 cores | 16 GB | 100 GB |
For live certificate discovery, the CipherFlag host requires two network interfaces:
| Interface | Purpose | Configuration |
|---|---|---|
| Management NIC | SSH access, web UI (:8443), Venafi push | Standard IP, routable |
| Capture NIC | Receives mirrored/tapped traffic for Zeek | Connected to SPAN port, mirror port, or network TAP. No IP required. |
For PCAP-only analysis (offline), only one interface is needed — upload capture files through the web UI.
Choose the deployment model that matches your environment. CipherFlag supports on-premises, AWS, and Azure deployments.
The most common deployment: a server with two NICs connected to your network infrastructure.
Physical or virtual server with:
Configure your switch to mirror traffic from the VLANs or ports you want to monitor to the capture NIC. CipherFlag (via Zeek) sees a copy of all TLS handshakes on that segment.
# Example: Cisco SPAN configuration
monitor session 1 source vlan 10,20,30
monitor session 1 destination interface Gi1/0/24AWS provides VPC Traffic Mirroring to copy network traffic to an EC2 instance running CipherFlag.
Architecture: EC2 instance with two ENIs (Elastic Network Interfaces) — one for management, one as the traffic mirror target.
Step 1: Launch an EC2 instance
t3.large or larger (4+ vCPU, 8+ GB RAM recommended)Step 2: Create a second ENI (capture interface)
aws ec2 create-network-interface \
--subnet-id subnet-xxxxxxxx \
--description "CipherFlag capture" \
--groups sg-xxxxxxxx
aws ec2 attach-network-interface \
--network-interface-id eni-xxxxxxxx \
--instance-id i-xxxxxxxx \
--device-index 1Step 3: Set up VPC Traffic Mirroring
# Create a mirror target (the capture ENI)
aws ec2 create-traffic-mirror-target \
--network-interface-id eni-capture-xxxxxxxx
# Create a mirror filter (capture all TLS traffic)
aws ec2 create-traffic-mirror-filter
aws ec2 create-traffic-mirror-filter-rule \
--traffic-mirror-filter-id tmf-xxxxxxxx \
--rule-number 1 --rule-action accept \
--destination-port-range FromPort=443,ToPort=443 \
--protocol 6 --traffic-direction INGRESS
# Create a mirror session on each source ENI
aws ec2 create-traffic-mirror-session \
--network-interface-id eni-source-xxxxxxxx \
--traffic-mirror-target-id tmt-xxxxxxxx \
--traffic-mirror-filter-id tmf-xxxxxxxx \
--session-number 1Step 4: Configure CipherFlag to use the capture ENI
In CipherFlag Settings > Sources, select the capture interface (typically eth1 or ens6 — the second ENI). Or set NETWORK_INTERFACE=eth1 in your .env file.
AWS notes: VPC Traffic Mirroring requires Nitro-based instances (t3, m5, c5, etc.). Mirrored traffic is encapsulated in VXLAN — Zeek handles this automatically. Traffic mirroring incurs additional AWS charges per GB mirrored.
Azure provides Virtual Network TAP (vTAP) for traffic mirroring to a VM running CipherFlag.
Architecture: Azure VM with two NICs — one for management, one as the TAP destination. Or use Azure Network Watcher packet capture for PCAP-based analysis.
Option A: Azure vTAP (live capture)
# Create CipherFlag VM with two NICs
az vm create --name cipherflag \
--resource-group myResourceGroup \
--image Ubuntu2204 --size Standard_D4s_v3 \
--nics mgmt-nic capture-nic
# Create a Virtual Network TAP
az network vnet tap create \
--name cipherflag-tap \
--resource-group myResourceGroup \
--destination /subscriptions/.../capture-nic \
--port 4789
# Attach source NIC to the TAP
az network nic vtap-config create \
--nic-name source-nic \
--resource-group myResourceGroup \
--vnet-tap /subscriptions/.../cipherflag-tapOption B: Azure Network Watcher (PCAP analysis)
If vTAP isn't available in your region, use Azure Network Watcher to capture packets as PCAP files, then upload them to CipherFlag.
# Start a packet capture on a VM
az network watcher packet-capture create \
--resource-group myResourceGroup \
--vm target-vm \
--name tls-capture \
--filters '[{"protocol":"TCP","localPort":"443"}]' \
--storage-account mystorageaccount
# Download the PCAP and upload to CipherFlag
curl -X POST http://cipherflag:8443/api/v1/pcap/upload \
-F "file=@capture.pcap"Azure notes: vTAP uses VXLAN encapsulation (UDP 4789). Ensure the capture NIC's NSG allows inbound UDP 4789. vTAP availability varies by region — check Azure documentation for current support. Network Watcher packet capture is available in all regions as a fallback.
| Aspect | On-Prem | AWS | Azure |
|---|---|---|---|
| Traffic source | SPAN port / TAP | VPC Traffic Mirroring | vTAP / Network Watcher |
| Encapsulation | None (raw) | VXLAN | VXLAN (vTAP) / PCAP (Watcher) |
| NICs required | 2 (mgmt + capture) | 2 ENIs | 2 NICs (vTAP) / 1 (Watcher) |
| Live capture | Yes | Yes | Yes (vTAP) / No (Watcher) |
| Additional cost | None | Per-GB mirroring fee | vTAP free / Watcher per-capture |
| Instance type | Any | Nitro-based only | Standard_D4s_v3+ |
The install script downloads the correct binary for your platform (Linux/macOS, amd64/arm64) and places it in /usr/local/bin.
curl -fsSL https://raw.githubusercontent.com/net4n6-dev/cipherflag/main/scripts/install.sh | sh
cipherflag setupgit clone https://github.com/net4n6-dev/cipherflag.git
cd cipherflag
cp .env.example .env # edit to set NETWORK_INTERFACE
docker-compose up -dPre-built images are published to ghcr.io for both linux/amd64 and linux/arm64. Docker Compose will pull them automatically.
If you used the install script, run cipherflag setup for an interactive walkthrough that handles:
cipherflag setup
# The wizard will:
# 1. Detect available network interfaces
# 2. Let you select one for live capture (or skip for PCAP-only)
# 3. Ask for Venafi credentials (optional)
# 4. Validate the Venafi connection if configured
# 5. Generate config files (.env, cipherflag.toml)
# 6. Pull Docker images and start servicesYou can skip Venafi integration during setup and configure it later from the Settings page in the web UI.
If you prefer manual setup, two files control everything:
# Network interface for live capture (leave empty for PCAP-only)
NETWORK_INTERFACE=
# PostgreSQL password
POSTGRES_PASSWORD=changeme
# Venafi (optional)
VENAFI_ENABLED=false
VENAFI_BASE_URL=
VENAFI_CLIENT_ID=
VENAFI_REFRESH_TOKEN=
VENAFI_FOLDER=\VED\Policy\Discovered\CipherFlagControls analysis rules, polling intervals, export settings, and more. See the full configuration reference for all options.
Security note: CipherFlag listens on port 8443. Protect it with network segmentation, a reverse proxy with auth, or host firewall rules. Built-in authentication is available with admin/viewer RBAC.
Once services are running, check that everything is healthy:
# Check container status
docker-compose ps
# All three should be "Up":
# cipherflag → API + frontend on :8443
# zeek-sensor → network monitoring
# postgres → database
# Test the API
curl -s http://localhost:8443/api/v1/certificates | headOpen http://localhost:8443 in your browser. You'll see the dashboard — if this is a fresh install, it will be empty until certificates are discovered or uploaded.
The fastest way to see CipherFlag in action is to upload a packet capture file.
# From the UI:
# Navigate to the Upload page → drag & drop a .pcap or .pcapng file
# From the CLI:
curl -X POST http://localhost:8443/api/v1/pcap \
-F "file=@capture.pcap"Zeek processes the capture, extracts certificates, and they appear in your inventory within seconds. The upload page shows real-time job status: queued → processing → complete.
Test data: Don't have a PCAP handy? Capture some TLS traffic with tcpdump -i eth0 -w test.pcap port 443, then upload the file.
The dashboard is organized around the workflow: discover → inspect → assess → act.
The interactive force-directed graph shows your entire CA hierarchy. Click any node to see certificate details, or use blast radius analysis to trace every certificate a CA has signed.
Five tabs give you different views into your certificate posture: chain flow (Sankey diagram), ownership (treemap), crypto posture (donut + heatmap), expiry forecast (stacked timeline), and source lineage (where certificates were discovered).
Four report types — Domain Certificate, CA Authority, Crypto Compliance, and Expiry Risk — each with drill-down, print, and CSV export.
The search bar in the nav searches across certificate names, fingerprints, serial numbers, SANs, server names, and IPs. Type 2+ characters to see categorized results.
CipherFlag pushes discovered certificates to Venafi automatically. Both Cloud and on-prem TPP are supported.
# In .env or the Settings page:
VENAFI_ENABLED=true
VENAFI_PLATFORM=cloud
VENAFI_API_KEY=your-api-key
VENAFI_REGION=us # or "eu"VENAFI_ENABLED=true
VENAFI_PLATFORM=tpp
VENAFI_BASE_URL=https://tpp.example.com/vedsdk
VENAFI_CLIENT_ID=your-client-id
VENAFI_REFRESH_TOKEN=your-refresh-token
VENAFI_FOLDER=\VED\Policy\Discovered\CipherFlagThe push scheduler runs on a configurable interval (default 60 minutes), sending new and updated certificates. Per-certificate failure tracking includes exponential backoff and dead-lettering after 5 failures. Check status at Settings → Venafi or GET /api/v1/venafi/status.
CipherFlag runs as three containers orchestrated by Docker Compose:
The Zeek sensor watches a network interface for live traffic and processes uploaded PCAPs. CipherFlag's Go backend parses Zeek's JSON logs, scores certificates, and serves the SvelteKit frontend. PostgreSQL stores everything.
Check docker-compose logs for errors. Common issues: port 8443 already in use, or the .env file has a syntax error.
If using live capture, verify your NETWORK_INTERFACE is correct and the container has the necessary capabilities. Try uploading a PCAP first to confirm the pipeline works.
Use GET /api/v1/venafi/status to check for dead-lettered certificates. Verify credentials with the "Test Connection" button in Settings. For TPP, ensure your refresh token hasn't been revoked.
Check the full documentation in the docs/ directory on GitHub, or open an issue.