Getting Started with PQC Scanner

Getting Started with PQC Scanner

Install the scanner and run your first quantum readiness assessment

Applies to:

Windows 10+LinuxmacOSDocker

Prerequisites

Prerequisites

• Supported Operating System (Windows 10+, Linux, macOS)
• Administrator/root access for agent scans and Windows Certificate Store
• Network connectivity to your DuoKey Cockpit tenant (for the installer download and enrollment) and to scan targets (port 443/TCP for domain scans)
• 4GB RAM minimum (8GB recommended)
• 5GB free disk space

Installation

Distributed from your Cockpit, not a public release

dke-scanner-agent binaries are not published on GitHub or a public Docker registry. 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 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. If your Cockpit release published a binary hash, add --expected-sha256 <hex> and enrollment refuses to proceed on a mismatch.

Quick Start: Your First Scans

Available Scanning Modes

filesystemScan directories for certificates, keystores, and keys

domainAnalyze remote TLS/SSL endpoints

inventoryFull system-wide cryptographic inventory

source-codeStatic analysis for crypto patterns in code

1. Filesystem Scan

Scan a directory for certificates, keystores, and private keys:

# Scan current directory (default: recursive, max-depth 10)
dke-scanner-agent filesystem

# Scan specific directory with output
dke-scanner-agent filesystem --path /etc/ssl/certs --output scan.json

# Scan with specific extensions and thread count
dke-scanner-agent filesystem \
  --path /opt/app \
  --extensions .pem,.crt,.p12,.jks \
  --exclude node_modules,.git,target \
  --threads 8 \
  --output report.json

# Include Windows Certificate Store scanning
dke-scanner-agent filesystem --scan-windows-certstore

2. Domain Scan

Analyze remote TLS endpoints and extract certificate chains. This runs a classic SSL/TLS audit by default; add --pqc for the Post-Quantum readiness report and Quantum Risk Score:

# Basic domain scan
dke-scanner-agent domain --target example.com

# Custom port(s) with timeout
dke-scanner-agent domain --target api.example.com --ports 8443 --timeout 30

# Post-Quantum readiness scan with a jurisdiction-specific scoring profile
dke-scanner-agent domain --target example.com --pqc --jurisdiction eu

Note

The classic (non---pqc) audit reports certificate, cipher-suite, protocol and vulnerability information. Only domain --pqc drives the live key-exchange probe and produces the PQC readiness report and Quantum Risk Score.

3. Host Inventory Scan

agent is a separate, persistent command that connects a host to a DuoKey Cockpit server and sends heartbeats — it does not scan anything by itself. For a comprehensive, one-shot system-wide cryptographic inventory, use inventory:

# Full host inventory (elevated privileges recommended for complete results)
sudo dke-scanner-agent inventory

# Skip the SSH key sweep for faster results
sudo dke-scanner-agent inventory --no-ssh

# Save results
sudo dke-scanner-agent inventory --output system-scan.json --format json

Note

Run enroll once to register a host with a cockpit, then agent to keep it continuously connected for fleet visibility. See Agent Mode.

4. Source Code Scan

Static analysis of source code for cryptographic usage patterns across 8 languages with 150+ detection rules:

# Scan local directory
dke-scanner-agent source-code --path /path/to/code

# Scan GitHub repository
dke-scanner-agent source-code \
  --github-repo owner/repo \
  --github-token $GITHUB_TOKEN \
  --branch main

# Scan GitLab project
dke-scanner-agent source-code \
  --gitlab-project group/project \
  --gitlab-token $GITLAB_TOKEN

# Scan Azure DevOps repository
dke-scanner-agent source-code \
  --azdo-org myorg \
  --azdo-project myproject \
  --azdo-repo myrepo \
  --azdo-token $AZDO_TOKEN

5. CI/CD Mode

Integrate scanning into your CI/CD pipeline with SARIF output and fail-on-severity thresholds:

# Scan with SARIF output for GitHub/GitLab security tabs
dke-scanner-agent ci --source-path . --format sarif --output results.sarif

# Fail build on high severity findings
dke-scanner-agent ci --source-path ./src --fail-on high --output ci-scan.json

# Fail only on critical
dke-scanner-agent ci --fail-on critical

Post-Scan Workflows

Generate CBOM

Export findings as a CycloneDX 1.7 Cryptographic Bill of Materials:

# Run scan first
dke-scanner-agent filesystem --path /app --output scan.json

# Generate CBOM
dke-scanner-agent cbom \
  --input scan.json \
  --app-name "Payment Gateway" \
  --app-version "2.5.1" \
  --output payment-gateway-cbom.json

Check Compliance

Note

Compliance-framework checking against NIST, PCI DSS, HIPAA, SOC 2 and the other frameworks runs against a saved scan result inside DuoKey CPM (the Cockpit) — it is not a standalone dke-scanner-agent CLI command. Upload scan.json from the Cockpit's PQC Readiness module.

Publish to ServiceNow

Note

ServiceNow publishing is configured and run server-side in DuoKey CPM against a saved scan result — see ServiceNow Integration. It is not a dke-scanner-agent CLI command.

View the Web Dashboard

The interactive dashboard is the PQC Readiness module inside DuoKey Cockpit. Upload or push a scan result there to view it — dke-scanner-agent itself has no built-in web server.

Understanding Results

Risk Severity Levels

Severity	Score Range	Priority	Action
Critical	9.0-10.0	P0	Immediate action - RSA <2048, DSA, 3DES, RC4
High	7.0-8.9	P1	Within 3 months - RSA-2048, ECDSA, EdDSA
Medium	5.0-6.9	P2	Within 6 months - RSA-3072
Low	3.0-4.9	P3	Within 12 months - RSA-4096
Info	0-2.9	P4	Monitor - PQC algorithms (ML-KEM, ML-DSA, SLH-DSA)

Scan Result Structure

Configuration

# Git provider tokens (for source-code scanning; --git-url falls back to GIT_TOKEN first)
export GIT_TOKEN="xxxxxxxxxxxx"
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"
export AZDO_TOKEN="xxxxxxxxxxxx"

# Cockpit enrollment (keeps the token out of shell history / ps)
export DKE_AGENT_ENROLL_TOKEN="<bundle-token-from-generate-installer>"

# Logging verbosity
export RUST_LOG=info # debug, info, warn, error, trace

Note

ServiceNow, compliance-framework checking, and the web dashboard are configured and run inside DuoKey CPM (the Cockpit) against a saved scan result — they have no corresponding dke-scanner-agent environment variables. See ServiceNow Integration.

Troubleshooting

Tip

Start with a single filesystem or domain scan to familiarize yourself with the output format before running comprehensive infrastructure assessments.

CLI Reference

Complete command documentation

Understanding Results

Deep dive into risk scores and findings

Migration Planning

Create your PQC migration roadmap

Integrations

ServiceNow CMDB and incident sync