QU.I.R.K. — v5.27.0

Quantum Infrastructure Readiness Kit is a consulting-grade cryptographic inventory and quantum-readiness assessment tool.

QU.I.R.K. is an agentless scanner that finds the cryptography running in an environment: TLS and SSH services, identity infrastructure (SAML, Kerberos, AD CS, JWT/OIDC), mail and message brokers, container images, source code, databases, cloud key management (AWS, Azure, GCP, HashiCorp Vault, Kubernetes), and network and OT/ICS hardware. QU.I.R.K. is dashboard-first and CLI-complete. Run a scan, review the results and download the deliverable in the browser, or script the same scans from the command line for automation, scheduling, sensors and repeat engagements.

It produces three things:

• a Cryptography Bill of Materials (CBOM) in CycloneDX JSON and XML;
• a 0–100 quantum-readiness score with six subscores;
• a prioritized migration roadmap, in client-ready PDF, DOCX and HTML reports.

The executive summary for a scan of the bundled chaos lab, which is deliberately weak. The score is capped at 20 because six CRITICAL findings are open, even though the computed score is 78. It shows the harvest-now-decrypt-later verdict, the first three remediation steps, and the six subscores.

For your role

For the security consultant. QU.I.R.K. produces the deliverable:

• a CycloneDX CBOM;
• a 0–100 quantum-readiness score with six subscores (Hygiene, Modern TLS, Identity, Agility, Data at Rest, Data in Motion);
• a written executive narrative;
• a prioritized remediation roadmap, in PDF, DOCX and HTML.

Nothing is installed on the systems being scanned.

For the IT generalist. Start with the simple question: what crypto do we even have running? QU.I.R.K. lists the TLS endpoints, SSH hosts, certificates, container images and cloud KMS keys it finds, and marks the quantum-vulnerable algorithms among them. Browse the results in the dashboard before committing to any remediation work.

For the compliance officer. QU.I.R.K. assigns network hardware a CNSA 2.0 remediation tier, maps its findings to FIPS 140-3 / CMVP, PCI-DSS 4.0.1, HIPAA, ISO 27001:2022 and SOC2 CC (the Trust Services Criteria), and tracks the US federal PQC transition deadlines (EO 14412). Each mapping is dated and re-verified on a CI-enforced review cadence. The output (CBOM JSON/XML, PDF reports) can be attached to an audit response.

Quick Start

Install into a virtual environment. This is recommended on every platform and required on Debian 12, Kali and other distributions that mark their system Python as externally managed (see the note below).

python3 -m venv .venv && source .venv/bin/activate
pip install 'quirk-scanner[all]'
quirk serve                    # opens the dashboard at http://127.0.0.1:8512

Then click New Scan in the sidebar, enter your targets and start the scan. Results appear in the dashboard when it finishes.

Prefer a script? Every scan also runs from the command line:

quirk init                     # writes a starter config.yaml — edit the targets
quirk --config config.yaml     # run the scan

Use a venv. Debian 12, Kali and other distributions that mark their system Python as "externally managed" (PEP 668) reject a bare pip install into the system Python with error: externally-managed-environment. Keep the quotes around 'quirk-scanner[all]': zsh, the default shell on macOS 10.15 and later and on Kali's desktop images, otherwise treats [all] as a glob and fails with no matches found. Full walkthrough: Installation → Parrot OS / Kali / Debian.

The dashboard has no login by default and is meant for local use. To require one, run quirk token generate --config config.yaml, then start quirk serve from the same directory; see Configuration → dashboard authentication. For a walkthrough of each step, follow the Getting Started guide.

What QU.I.R.K. Scans

Always on. Every scan does these against its targets:

• TLS / HTTPS: certificate metadata and chain, cipher suites, protocol versions, and PQC-hybrid key exchange detection (X25519MLKEM768; needs a host openssl with ML-KEM).
• SSH: host key, key exchange, MAC and cipher algorithms, read by the ssh-audit binary. ssh-audit is not installed with QU.I.R.K.; without it on PATH, the scan records only each SSH server's banner.
• Hardware fingerprinting: for each SSH host, vendor, model and CNSA 2.0 remediation tier, from its SSH banner, its HTTP management page and, when neither identifies the vendor, an SNMP v2c public query (sent without --enable-snmp when the [hw] extra is installed). Firmware CVEs and end-of-life dates are matched against built-in offline tables.

On by default in the standard and deep scan profiles (the default profile is standard; quick leaves them off, and enable_email: false or enable_broker: false turns them off):

• Email: TLS / STARTTLS on the SMTP, submission, IMAP and POP3 ports of each host the TLS phase scanned. The dashboard flags STARTTLS-stripping risk on SMTP port 25.
• Message brokers: Kafka, RabbitMQ (AMQPS and management API) and Redis TLS on the same hosts and any broker_targets, plus the Azure Service Bus namespaces and AWS SQS regions you list.

Opt-in. Each of these is enabled with a config key or flag:

[all] covers the cloud, database, broker, email, AD CS, report and dashboard dependencies. It deliberately leaves out [hw] (SNMP, Modbus, BACnet), [api] (REST fuzzing) and [identity] (Kerberos). Install those explicitly, e.g. pip install 'quirk-scanner[all,hw]'. The Configuration Reference documents every key.

Output

• Quantum-readiness score (0–100) with six subscores: Hygiene, Modern TLS, Identity, Agility, Data at Rest, Data in Motion. The headline score (in the report and on the dashboard's Executive page) is capped while CRITICAL findings remain open; trend and sensor-merge scores do not apply that cap. No score reaches 100 unless a hybrid post-quantum key exchange is observed.
• CBOM in CycloneDX JSON and XML. Hardware is modelled as DEVICE components with FIRMWARE children.
• Reports in PDF, DOCX and HTML, plus CLI markdown. The HTML report (which the PDF prints), the DOCX report and the CLI executive summary take their executive content from one shared content model, and each carries a written executive narrative and a NOW / NEXT / LATER migration roadmap. The CLI also writes the roadmap on its own as roadmap-*.md. The PDF needs Playwright and its Chromium browser; without them the scan skips the PDF and still writes the HTML report.
• Web dashboard (quirk serve) with these views: executive summary, findings with a per-finding storyline, identity, data in motion, data at rest, certificates, hardware inventory, CBOM viewer, migration roadmap, quantum exposure map (endpoints linked by a shared key or a shared issuing CA), trends, scan history, scan comparison, schedules, sensors and QRAMM assessment, plus a New Scan page that starts a scan from the browser. Light and dark themes are included.
• Distributed mode: on-prem sensors scan isolated network segments and push their results to a central console. quirk sensor merge builds one CBOM and score from them, but it currently keeps only one endpoint per sensor (a known defect). A Windows sensor build ships as a GitHub Release asset.
• Integrations: notifications for scheduled scans and hardware lifecycle changes, SIEM CEF export, and Jira / ServiceNow ticket creation.

Four sample CBOMs live in examples/cbom/: TLS-only, identity, data at rest and data in motion. They are built from synthesized chaos-lab endpoints, not from a live scan.

Documentation

What's New in v5.27

v5.27.0 is the first release since v5.25.0, so it carries both the v5.26 accessibility work and the v5.27 launch-readiness work. There are no score-model changes (SCORING_VERSION stays 3.0), so v5.27 scores are comparable with v5.25 scores.

• Score gauges no longer draw mirrored. A score of 20 out of 100 used to draw an arc that looked about 90% full.
• Accessibility. More dashboard badges meet WCAG AA contrast, and a dashboard table too wide or too tall for its space is a single Tab stop that the keyboard can scroll.
• A brand identity. The logo appears in this README, the report colophon, the PDF footer, the favicon and the dashboard sidebar, and the dashboard accent is now Ink-violet.
• Every user-facing doc was reviewed claim by claim, and the README hero image was retaken.
• Security hardening of configuration loading, URL fetching and sensor enrollment.
• Upgrade notes. quirk serve exits with an error when its config file exists but cannot be read, and protected API routes answer 503 in that state. quirk sensor enroll and quirk sensor push require an https:// console URL for non-loopback hosts unless --allow-insecure-console is given, so re-enroll existing sensors that use an http:// console.

The full per-release history is in CHANGELOG.md.

Install

• PyPI: pip install 'quirk-scanner[all]' (see Quick Start). Releases are published through PyPI Trusted Publishers with Sigstore attestations; verify them as described in Release Process.
• Windows sensor: a zip with the frozen quirk.exe and PowerShell install and uninstall scripts is attached to each GitHub Release from v5.12.0 onward. The installer registers a daily Scheduled Task.

No curl | bash installer. This is deliberate. Piping HTTP into a shell bypasses the integrity guarantees of Sigstore attestations and Trusted Publishers. See docs/release-process.md.

git clone https://github.com/0xD1g5/QU.I.R.K
cd QU.I.R.K
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dashboard]'
playwright install chromium
quirk --help

License

MIT. See LICENSE.