Quick Start Guide

Quick Start Guide

Get up and running with the DuoKey PQC Scanner in just a few minutes. This guide will walk you through installation, your first scan, and interpreting the results.

Applies to:

WindowsLinuxmacOSDocker

Installation

Distributed from your Cockpit, not a public release

dke-scanner-agent binaries are not published on GitHub, Homebrew, winget, or a public Docker registry, and there's no public source repository to build from. Each Cockpit tenant serves its own signed, short-TTL download link, gated by the Operations.Pki.Scanner.Agent.Download permission.

Generate an installer

In DuoKey Cockpit, go to Scanner Agents → Generate Installer and pick a platform (Windows x64, Linux x64/arm64, macOS x64/arm64). This returns a signed download link and a single-use enrollment token valid for 1 hour.

Download and place the binary

Download the binary for your platform from the link. On Linux/macOS, make it executable and place it on your $PATH: chmod +x dke-scanner-agent-* && sudo mv dke-scanner-agent-* /usr/local/bin/dke-scanner-agent.

Enroll with your Cockpit

Run enroll once to register the host and persist ~/.dke/agent.toml (mode 0600 on Unix):

dke-scanner-agent enroll --server https://cockpit.example.com --token <bundle-token>

Tip

Pass the token via the DKE_AGENT_ENROLL_TOKEN env var instead of --token to keep it out of shell history and the process list.

Your First Scan

Quick Health Check

Let's start with a simple scan of a public website:

# Scan a domain (port defaults to 443)
dke-scanner-agent domain --target example.com

Scan Local System (Host Inventory)

For a comprehensive assessment of your local machine, use inventory (the persistent agent command only connects a host to a Cockpit and sends heartbeats — it does not scan by itself):

# Run with elevated privileges for complete results
sudo dke-scanner-agent inventory --output my-system-scan.json

# View results
cat my-system-scan.json | jq '.summary'

Scan Application Directory (Filesystem Mode)

Scan your application's certificate directory:

# Scan (recursive by default; there is no --recursive flag)
dke-scanner-agent filesystem --path /opt/myapp --output app-scan.json

# View high-risk findings
cat app-scan.json | jq '.findings[] | select(.risk_assessment.severity == "HIGH")'

Scan Network Traffic (Network Mode)

Requires Privileges

Network mode requires root/admin privileges or CAP_NET_RAW capability, and a scanner built with the pcap-live feature.

# Live-capture TLS handshakes for 5 minutes (300 seconds)
sudo dke-scanner-agent network --interface eth0 --capture-duration-secs 300 --output network-scan.json

Understanding the Output

Risk Severity Levels

The scanner assigns one of four severity levels:

Severity	Score Range	Meaning	Action Required
CRITICAL	9.0-10.0	Immediate quantum threat	Urgent action
HIGH	7.0-8.9	Significant vulnerability	Plan within 3-6 months
MEDIUM	4.0-6.9	Moderate risk	Plan within 12 months
LOW	0-3.9	Minor or informational	Monitor

Algorithm Vulnerability

Common algorithms and their quantum risk:

Algorithm	Risk	Note
RSA-1024	Critical (10/10)	Ancient — replace now
RSA-2048	High (8/10)	Current standard, quantum-vulnerable
RSA-4096	Medium (5/10)	Strong now, vulnerable later
ECDSA P-256	High (8/10)	Common ECC, vulnerable
EdDSA (Ed25519)	High (7/10)	Modern but quantum-vulnerable
ML-KEM-768	Low (1/10)	Post-quantum secure

Sample Report Structure

Common Scanning Patterns

First-time assessment of your infrastructure:

#!/bin/bash
# comprehensive-assessment.sh

echo "=== DuoKey PQC Scanner - Initial Assessment ==="

# 1. Scan local system
echo "Scanning local system..."
sudo dke-scanner-agent inventory --output results/inventory-scan.json

# 2. Scan application directories
echo "Scanning application directories..."
dke-scanner-agent filesystem \
  --path /opt/applications \
  --output results/filesystem-scan.json

# 3. Scan public endpoints (comma-separated target list; no --targets-file flag)
echo "Scanning public endpoints..."
dke-scanner-agent domain \
  --target api.example.com,www.example.com \
  --output results/domain-scan.json

# 4. Generate summary report
echo "Generating summary..."
cat results/*.json | jq -s 'map(.summary) | add' > results/summary.json

echo "Assessment complete! Check results/ directory"

Next Steps

1. Analyze Results

# Get high-priority findings
jq '.findings[] | select(.risk_assessment.priority == "P0" or .risk_assessment.priority == "P1")' scan-results.json

# Count by algorithm
jq '.findings | group_by(.algorithm) | map({algorithm: .[0].algorithm, count: length})' scan-results.json

# Export to CSV for reporting
jq -r '.findings[] | [.location, .algorithm, .key_size, .risk_assessment.severity] | @csv' scan-results.json > findings.csv

2. Create a Migration Plan

Migration planning is a DuoKey CPM (Cockpit) capability that works on top of scan results — it is not a dke-scanner-agent CLI command. Upload a scan result to the Cockpit's PQC Readiness module and use the Migration tab to build a phased roadmap. See Migration Planning.

3. Set Up Dashboards

Send scan output (JSON) to your monitoring system:

# Run an inventory scan and forward the JSON result
dke-scanner-agent inventory --format json | curl -X POST http://elasticsearch:9200/pqc-scans/_doc -H 'Content-Type: application/json' -d @-

dke-scanner-agent inventory --format json | gzip | curl -X POST https://splunk:8088/services/collector \
  -H "Authorization: Splunk $SPLUNK_TOKEN" \
  --data-binary @-

Note

There is no built-in Prometheus exporter or --format prometheus; forward the JSON output to your own metrics pipeline instead.

4. Schedule Regular Scans

Establish a scanning cadence:

• Daily: Critical production systems
• Weekly: All production infrastructure
• Monthly: Complete organizational assessment
• On-Demand: Before major deployments or changes

Troubleshooting

Best Practices

Recommended Practices

Start Small

Begin with a pilot scan on a single application before expanding scope

Version Control

Save scans with timestamps and track in version control

Automate

Create wrapper scripts and schedule recurring scans

Secure Data

Encrypt sensitive scan results and restrict file permissions

Learning Resources

Architecture Overview

Technical deep dive into scanner internals

Scanning Modes

Detailed mode documentation

Risk Scoring

Understanding risk assessment

Migration Planning

Planning your PQC transition

Summary

What You've Learned

Install the PQC ScannerBinary, source, or Docker

Perform your first scanDomain, agent, and filesystem modes

Understand scan resultsSeverity levels and risk scores

Integrate with CI/CDGitHub Actions workflow

Set up monitoringDashboards and recurring scans

Follow best practicesAutomation, security, versioning

Next Recommended Steps

1. Run a comprehensive inventory scan of your systems
2. Review and categorize findings by priority
3. Create a migration roadmap for P0/P1 items
4. Set up automated weekly scans
5. Share results with your security team

Need Help?

If you encounter issues or have questions, check the CLI Reference troubleshooting section or contact support at [email protected]

Quick Reference Card

# Common Commands Cheat Sheet

# Host inventory scan (full system scan)
sudo dke-scanner-agent inventory --output inventory-scan.json

# Filesystem mode (directory scan, recursive by default)
dke-scanner-agent filesystem --path /app

# Domain mode (TLS endpoint scan)
dke-scanner-agent domain --target example.com

# Network mode (live capture, requires the pcap-live feature)
sudo dke-scanner-agent network --interface eth0 --capture-duration-secs 3600

# Batch domain scanning (comma-separated targets)
dke-scanner-agent domain --target a.example.com,b.example.com --concurrency 20

# Output formats (vary by command; see the CLI Reference for each)
--format json     # Machine-readable (default for most commands)
--format summary  # Human-readable summary
--format sarif    # CI/CD integration (`ci` command only)

# Common filesystem filters
--extensions .jks,.p12,.pem
--exclude node_modules,target
--max-depth 3

# Performance tuning
--threads 20
--timeout 30

See Also

• CLI Reference
• Data Sources
• CBOM Guide
• Architecture Overview