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 capture, you'll also need access to a SPAN port, mirror port, or network TAP. For PCAP-only analysis, no special network access is needed.
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/YOUR-ORG/cipherflag/main/scripts/install.sh | sh
cipherflag setupgit clone https://github.com/YOUR-ORG/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 "[email protected]"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.