Discovery Agent

Three Products in One

"Discovery agent" undersells it. One binary, one scan, three genuinely distinct capabilities — most vendors sell these as separate products.

Quick Start

Real, working downloads — no account or API key required to get the binary. For the full walkthrough — every run mode, the complete configuration reference, appliance scanning, offline mode, and troubleshooting — see the Complete Guide →

curl -sSL https://api.pqcrypta.com/stream/downloads/discovery-agent/install.sh | bash

🔐 Not blind curl | bash. The installer fails closed: it verifies the binary's Ed25519 signature (key pinned in the script) and SHA-256 checksum before making it executable. Every release is hybrid-signed — classical Ed25519 and post-quantum ML-DSA-65 (NIST FIPS 204), both over a signed SHA256SUMS manifest and verifiable entirely offline (no CA). We sign our own supply chain with the same hybrid transition we recommend to you. Full verification steps: Verify Your Download →

# Linux x86_64 (~30.2 MB)
curl -o pqcrypta-discovery https://api.pqcrypta.com/stream/downloads/discovery-agent/linux

# Windows x86_64 (~18.0 MB)
# https://api.pqcrypta.com/stream/downloads/discovery-agent/windows

# macOS Apple Silicon / arm64 (~18.9 MB)
curl -o pqcrypta-discovery https://api.pqcrypta.com/stream/downloads/discovery-agent/macos

# macOS Intel / x86_64 (~19.9 MB)
# curl -o pqcrypta-discovery https://api.pqcrypta.com/stream/downloads/discovery-agent/macos-intel

chmod +x pqcrypta-discovery

./pqcrypta-discovery \
  --api-url https://api.pqcrypta.com \
  --api-key YOUR_API_KEY \
  --deep-scan

What It Captures

Platform Support

Comprehensive Scan Coverage

The built-in per-OS defaults (used when you run with no --config) cover these categories out of the box — each a real, tested path pattern, not aspirational. Every one of these paths lives in the downloadable reference-{linux,windows,macos}.toml config, so you can trim this list down or extend it: run with --config and your file's scan_paths are exactly what gets scanned.

Measured Performance

Real numbers from real machines, not estimates. Every figure below was measured on v1.0.45 — the same binary published on this page — using /usr/bin/time -v on Linux and polled process counters on Windows. Linux rows are the median of three runs; Windows is a single run of each mode. Your numbers will differ with disk speed and how much of the filesystem your scan_paths cover, so treat these as the shape of the cost rather than a guarantee.

Cost on the scanned host

• It fits on a 1 GB VM. Peak memory tracks the largest single artifact parsed, not the number of assets — the 339-asset mail server used 32 MB, and the 6,479-asset desktop used 129 MB.
• Most of the wall clock is I/O, not CPU. The 2,047-asset scan spent 58 s wall for 15 s of CPU: about a quarter of one core on a 4-core box, with the rest waiting on the filesystem.
• The offline bundle is not slower. It does strictly more work — compliance scoring, CycloneDX CBOM, a self-contained HTML report — yet finishes sooner, because it never waits on API round trips.
• Windows costs far more per asset — roughly 70 ms of CPU each against 7 ms on Linux. It walks the native CryptoAPI stores, a deep Program Files tree and thousands of DLLs for the compiled-in crypto library surface. Budget minutes on Windows, seconds on a Linux server.

Cost on an agentless appliance

Agentless means nothing is installed on the device — not that the device does no work. It still authenticates, enumerates its certificate store and serialises the reply, so both sides are measured: the scanning host, and the appliance itself. Appliance CPU and memory were sampled every 0.5 s while idle and again throughout the scan; without the idle baseline a percentage means nothing.

• The F5 saw about +2.4% average CPU for three seconds and no measurable memory change. The NetScaler stayed inside its own noise floor.
• The scanning host spends 0.13 s of CPU and 17 MB to inventory both devices, so appliance discovery can run from any host without deploying anything to the appliances.
• Honest caveat: these are lab appliances holding 9 and 7 certificates, and a scan short enough that only a handful of samples land inside it. A production device with hundreds of certificates does more work enumerating its store — the store walk is the part that scales, not the connection.

Air-Gap / Offline Mode

The agent runs a complete assessment entirely on-host, with zero network access — no API key, no callback, nothing leaves the machine. One flag produces a self-contained bundle you carry out on removable media:

• --offline-report ./assessment — scan, classify, and report locally in one step
• report.html — a single self-contained compliance report (all styling inlined, no external requests) safe to open on an isolated host: post-quantum readiness, risk breakdown, remediation ownership, and the full inventory
• cbom.json — a CycloneDX 1.6 Cryptographic Bill of Materials
• inventory.json — every asset with full detail and its assessment

Post-quantum scoring, risk rating, remediation-ownership classification, and CBOM assembly are all computed on the agent — the same logic the platform runs server-side — so an air-gapped report is identical to an online one. There is no SaaS tether: the same single binary that scans a cloud host also runs unattended inside a classified enclave and hands back a complete, standards-based assessment. Verified by running under a network namespace with no interfaces at all.

Self-Hosted / On-Premises Platform

Three ways to run PQCrypta, so the deployment fits your data-sovereignty posture — not the other way around:

• Hosted (SaaS): agents submit to our dashboard with --api-url. Nothing to operate.
• Offline / air-gap: one binary, one flag, a complete on-host assessment — the mode above.
• Self-hosted platform: run the entire platform — API, PostgreSQL, and the Compliance Dashboard — inside your own network. Agents point at your API; no inventory, CBOM, or telemetry ever leaves your environment.

The self-hosted tier ships as a docker compose stack (database + API + dashboard) with a connected installer and a fully air-gapped bundle — container images, schema, and signed agent artifacts staged into a single tarball that installs on a disconnected host with zero registry pulls. Point agents at it with nothing more than --api-url http://your-host:3003; the dashboard, its CSP, and every download link follow the same local base URL.

It runs behind a license that is post-quantum signed with ML-DSA (Dilithium3, NIST FIPS 204) and verified entirely offline at startup — no phone-home, so it works in classified enclaves. A tampered license fails closed; an expired one keeps you running in grace mode. It's the same hybrid post-quantum transition we sign our own supply chain with, applied to entitlement.

Appliance Lab Validation

The F5/NetScaler integration isn't tested against mocks — it's validated against a live, licensed F5 BIG-IP Virtual Edition 17.5 (TMOS) running on KVM, scanned exactly the way a customer would run it: agentlessly, from a separate jump host, over iControl REST, using a least-privilege Auditor-role account.

• Deliberate certificate matrix: RSA-2048, RSA-4096, ECDSA P-256, an already-expired certificate, and a spare certificate never bound to any virtual server — every one discovered with correct algorithm, key size, subject, and expiry
• The unbound-certificate claim, proven: the spare cert is invisible to live TLS scanning of the appliance's endpoints (nothing serves it), but the management-API inventory surfaces it — the core reason this scan mode exists
• Factory-vs-customer split verified: TMOS's shipped certificates (ca-bundle, f5-irule, default) classify as hardware-vendor remediation; every certificate we installed classifies as internal — yours to rotate
• Device facts cross-checked: the reported TMOS version, Virtual Edition platform, CPU/memory, management IP, and interface MACs all matched the known VM configuration exactly
• Operationally honest: re-scans are idempotent (no duplicate assets), one unreachable appliance never aborts the rest of the scan, and read-only credentials are sufficient end-to-end — including the TMOS quirk that newly created accounts start password-expired, which is documented in the setup guidance
• End-to-end, not endpoint-deep: the validated path runs appliance → agent → API → inventory → Compliance Dashboard → CycloneDX 1.6 CBOM export

The Citrix NetScaler/ADC integration is validated the same way, against live NetScaler 14.1 firmware (NetScaler CPX) over the NITRO API: the same certificate matrix, correct handling of NITRO's expired-certificate semantics (the true not-after date is preserved even when daystoexpiration has hit zero), factory certificates (ns-server-certificate, ns-sftrust-certificate) classified as hardware-vendor remediation, and device facts — build version, platform, management IP, interfaces — collected from the device's own nsversion/nshardware/nsip endpoints.

CBOM: Weak Cryptography in Source Code

Every other scan type finds crypto material at rest — a cert file, a live TLS endpoint, a database column. CBOM (Cryptographic Bill of Materials) is different in kind: it looks for calls into known-weak cryptographic primitives inside your own application source code. A codebase can have a spotless certificate inventory and still call hashlib.md5() for something security-sensitive — nothing else in this tool can see that.

Scope, stated plainly: this is known-weak call-site detection via pattern matching against real per-ecosystem API idioms — not full static analysis. It does not follow data flow, so a weak primitive reached through a wrapper function or a variable-selected cipher name is out of scope by design. That trade keeps findings high-confidence: what it flags is a literal call into a broken primitive at a specific file and line.

# Off by default. Point it at your source trees:
code_scan_paths = ["/opt/myapp/src", "/opt/myapp/internal"]

OS & Security Metadata Collection

Collected once per scan and attached to every submission — this is what powers the Discovered Systems page in the dashboard (security score, TPM/Secure Boot indicators, hardware).

Command Line Options

Configuration File

The agent is fully config-driven — there is no hidden hardcoded path list. Run it with --config yourfile.toml and that file's scan_paths are authoritative: the agent scans exactly what you list and nothing else. Run it with no --config and it falls back to a built-in per-OS default set — which is literally the same reference-{linux,windows,macos}.toml file you can download and edit (256 paths on Linux, 67 on Windows, 64 on macOS). There are three modes, not two: config alone replaces the catalog, no config uses the catalog, and --config … --with-defaults scans both. Keystores (.jks/.p12/.pfx/…) are opened and their certificates inventoried wherever scan_paths point, so widening keystore coverage just means adding a path. Every field below is real and currently supported. Start from a ready-made preset in the dashboard's Download Discovery Agent section (role presets, or full per-OS catalogs with every path active) — all at /stream/downloads/discovery-agent/config/<name>.toml.

# API endpoint configuration
api_url = "https://api.pqcrypta.com"
api_key = "your-api-key-here"

# Filesystem paths to scan for certificates, keys, SSH keys, and keystores
# (.jks/.p12/.pfx found here are opened and their certs inventoried too).
# When this file is passed via --config, these paths are AUTHORITATIVE — the
# agent scans exactly this list. ~, $VAR, ${VAR} and %VAR% are expanded.
# For the complete built-in set, start from reference-linux.toml (or the
# Windows/macOS catalogs) instead.
scan_paths = [
    "/etc/ssl/certs",
    "/etc/pki",
    "/root/.ssh",
    "/opt/tomcat/conf",   # e.g. keystore.jks — parsed into individual certs
]

# Enable deep scanning (slower but more thorough)
deep_scan = false

# Filter for specific algorithms (comma-separated). Leave empty/commented to scan
# for all algorithms.
# algorithms_filter = ["RSA", "ECC"]

# Read executables and shared objects for the crypto library compiled into them.
# On by default; the only surface that sees inside a closed-source vendor binary,
# and the only one whose cost scales with installed software rather than deployed
# cryptography. Set false where that budget does not exist — coverage then reports
# it as not configured rather than clean.
binary_scan = true

# Paths to exclude from scanning. Your config is authoritative: listing this key
# replaces the built-in exclusions rather than adding to them, so keep the
# pseudo-filesystems if you override it. With NO config at all, the built-in
# catalog for the platform already excludes /proc, /sys, /dev, /run and the temp
# dirs (WinSxS, Temp and the recycle bin on Windows).
excluded_paths = ["/proc", "/sys", "/dev", "/run", "/tmp", "/var/tmp"]

# Source-code trees to scan for weak-crypto API calls (CBOM). Off by default.
code_scan_paths = []

# Keystore passwords for locked PKCS#12/PFX/JKS containers. The built-in defaults
# (empty / changeit / password) are always tried first; these are added after.
# There is no lockout on a local keystore, so the list is tried first-match-wins
# with no need to map a password to a specific store. Used LOCALLY only — never
# submitted, never logged. Four sources, merged in order (all opt-in):
# keystore_passwords = ["s3cret", "corp-export-pw"]         # inline
# keystore_passwords_file = "/etc/pqcrypta/keystore-pw.txt" # newline-separated file
# (env) PQCRYPTA_KEYSTORE_PASSWORDS="pw1\npw2"              # environment variable
# keystore_passwords_command = "vault kv get -field=pw secret/keystores"  # any secrets
#   manager via its CLI — aws secretsmanager get-secret-value, op read, gpg -d, etc.

# Database connections to scan (optional). Reads real column values matching
# %cert%/%key%/%pem% and parses them; never stores the raw value. Dispatch is by
# DSN scheme (postgres/mysql/sqlite/mssql/oracle all functional). Oracle needs
# Instant Client installed on the scanning host itself — skipped gracefully if not.
# [[database_connections]]
# name = "Production PostgreSQL"
# db_type = "postgres"
# dsn = "postgres://user:password@localhost/dbname"
# [[database_connections]]
# name = "Legacy SQL Server"
# db_type = "mssql"
# dsn = "mssql://user:password@localhost:1433/dbname"
# [[database_connections]]
# name = "Oracle Prod"
# db_type = "oracle"
# dsn = "oracle://user:password@host:1521/ORCL"

database_connections = []

# Live network/TLS endpoints to inspect — reflects what's actually being
# served right now, not just files sitting in a cert store. STARTTLS ports
# (SMTP 25/587, IMAP 143, POP3 110) are upgraded automatically; implicit-TLS
# ports (443/465/993/995) handshake directly.
[[network_targets]]
host = "example.com"
port = 443

# F5 BIG-IP / Citrix NetScaler certificate stores, via management API.
# [[appliance_targets]]
# name = "F5 Prod LB"
# appliance_type = "f5"          # or "netscaler"
# mgmt_url = "https://your-f5-mgmt-host"
# username = "readonly-api-user"
# password = "..."
# verify_tls = true

API Integration

{
  "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_hostname": "server-01.example.com",
  "agent_version": "1.0.38",
  "agent_platform": "linux",
  "os_metadata": {
    "os_name": "Ubuntu", "os_version": "24.04",
    "tpm_available": true, "secure_boot_enabled": false,
    "cpu_model": "AMD EPYC-Milan Processor", "cpu_cores": 4
  },
  "assets": [
    {
      "location": "/etc/ssl/certs/server.crt",
      "location_type": "filesystem",
      "asset_type": "certificate",
      "algorithm": "RSA",
      "key_size": 2048,
      "subject_cn": "server.example.com",
      "issuer_cn": "Let's Encrypt Authority X3",
      "not_after": "2026-06-01T00:00:00Z",
      "sha256_fingerprint": "..."
    }
  ],
  "scan_duration_ms": 45320,
  "errors": [],
  "batch_number": 1,
  "total_batches": 12
}

{
  "success": true,
  "message": "Stored 10 of 10 assets",
  "assets_processed": 10,
  "assets_compliant": 1,
  "assets_legacy": 9,
  "violations": [ /* one per non-compliant asset */ ]
}

GET /crypto-assets/report
    ?remediation_owner=internal          # any inventory filter: compliance_status,
    &expires_after=2026-07-06T00:00:00Z  #   risk_level, asset_type, environment,
    &discovered_by_hostname=web-01       #   application, search, date bounds, device
    &columns=device,location,hosted_on_hostname,hosted_at_locations,algorithm,valid_until,compliance_status
    &group_by=device                     # orders rows by hosting device for sectioned output
    &format=csv                          # csv | json (default csv)
    &limit=10000                         # row cap, max 50000 (json summary still counts the full match)

Compliance Assessment

Classification is based on the actual NIST-registered OIDs for post-quantum algorithms, not string matching.

A weak signature hash is judged separately from a weak key. MD2/MD5/SHA-1 in a certificate's signatureAlgorithm is Forbidden where the signature is actually verified during chain building — that is, on any certificate that is not self-signed. On a self-signed root it is recorded but not flagged: trust in a root comes from its presence in a trust store, never from verifying its own signature, which is why NIST SP 800-131A Rev. 2 and the CA/Browser Forum Baseline Requirements both scope the SHA-1 prohibition to verified signatures, and why several hundred SHA-1 self-signed roots legitimately ship in every OS trust store. Flagging those would bury the certificates where a weak signature genuinely is a finding.

Remediation Ownership

A flat inventory tells you what's wrong. Ownership classification tells you who can actually fix it — the difference between an inventory and a to-do list. Classification is layered: operator-defined location rules match first (first match by priority wins, editable without a deploy), then a semantic classifier reasons from what the asset is — holding a private key means the key material is yours; a certificate whose CN/SAN matches one of your own scanned domains is yours (or your public CA's, if one issued it); a locally-minted self-signed certificate is yours; a code-signing or timestamping certificate belongs to the software vendor that shipped it; and any other CA certificate is a trust anchor owned by the issuing CA. A final content-aware pass then corrects for what location alone cannot see: a copy of a public CA certificate is still the CA's wherever it sits on disk, so roots are matched by SHA-256 against the known trust anchors and intermediates by whether they chain to one. That pass only ever moves work off your list — it never marks something actionable that the earlier layers did not. Only what survives every layer lands in Unknown for human review.

Technical Stack

Use Cases

Using the Compliance Dashboard

Every scan submission lands here. The Compliance Dashboard is one page with everything scoped consistently — pick a device once, and every table on the page narrows to it.

Three ways to run it, and none of them are mandatory

“We cannot send our cryptographic inventory to a third party” is a reasonable position, and it is not one you have to argue us out of. Pick the row that matches your constraint — the agent and the assessment are identical in all three.

Security Characteristics

Database Safety Profile

Column scanning is the one capability a DBA is entitled to interrogate before allowing it near a production instance, so here is the whole of it. Every row below is a property of the code, not an intention.

Frequently Asked Questions