pqscan 0.4.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. pqscan-0.4.1/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
  2. pqscan-0.4.1/.github/ISSUE_TEMPLATE/config.yml +8 -0
  3. pqscan-0.4.1/.github/ISSUE_TEMPLATE/feature_request.yml +19 -0
  4. pqscan-0.4.1/.github/ISSUE_TEMPLATE/rule_correction.yml +31 -0
  5. pqscan-0.4.1/.github/PULL_REQUEST_TEMPLATE.md +18 -0
  6. pqscan-0.4.1/.github/dependabot.yml +9 -0
  7. pqscan-0.4.1/.github/workflows/ci.yml +82 -0
  8. pqscan-0.4.1/.github/workflows/release.yml +53 -0
  9. pqscan-0.4.1/.gitignore +36 -0
  10. pqscan-0.4.1/CHANGELOG.md +135 -0
  11. pqscan-0.4.1/CODE_OF_CONDUCT.md +31 -0
  12. pqscan-0.4.1/CONTRIBUTING.md +72 -0
  13. pqscan-0.4.1/LICENSE +201 -0
  14. pqscan-0.4.1/Makefile +10 -0
  15. pqscan-0.4.1/NOTICE +25 -0
  16. pqscan-0.4.1/PKG-INFO +216 -0
  17. pqscan-0.4.1/README.md +176 -0
  18. pqscan-0.4.1/RELEASE_CHECKLIST.md +71 -0
  19. pqscan-0.4.1/SECURITY.md +50 -0
  20. pqscan-0.4.1/docs/architecture.md +143 -0
  21. pqscan-0.4.1/docs/ci.md +107 -0
  22. pqscan-0.4.1/docs/faq.md +72 -0
  23. pqscan-0.4.1/docs/getting-started.md +93 -0
  24. pqscan-0.4.1/docs/ism-coverage.md +135 -0
  25. pqscan-0.4.1/docs/outputs.md +93 -0
  26. pqscan-0.4.1/docs/scanning.md +130 -0
  27. pqscan-0.4.1/docs/scoring.md +138 -0
  28. pqscan-0.4.1/examples/hosts.csv +16 -0
  29. pqscan-0.4.1/examples/testbed.csv +47 -0
  30. pqscan-0.4.1/pqc +58 -0
  31. pqscan-0.4.1/pqc_scan/cbom.py +199 -0
  32. pqscan-0.4.1/pqc_scan/checks.py +568 -0
  33. pqscan-0.4.1/pqc_scan/cli.py +770 -0
  34. pqscan-0.4.1/pqc_scan/collectors.py +462 -0
  35. pqscan-0.4.1/pqc_scan/discovery.py +85 -0
  36. pqscan-0.4.1/pqc_scan/domain_probe.py +306 -0
  37. pqscan-0.4.1/pqc_scan/exporters.py +221 -0
  38. pqscan-0.4.1/pqc_scan/ike_probe.py +349 -0
  39. pqscan-0.4.1/pqc_scan/models.py +100 -0
  40. pqscan-0.4.1/pqc_scan/netutil.py +29 -0
  41. pqscan-0.4.1/pqc_scan/parsers.py +196 -0
  42. pqscan-0.4.1/pqc_scan/probes.py +485 -0
  43. pqscan-0.4.1/pqc_scan/remediation.py +106 -0
  44. pqscan-0.4.1/pqc_scan/report_template.py +376 -0
  45. pqscan-0.4.1/pqc_scan/reporters.py +561 -0
  46. pqscan-0.4.1/pqc_scan/rules/__init__.py +1 -0
  47. pqscan-0.4.1/pqc_scan/rules/asd_ism.yaml +617 -0
  48. pqscan-0.4.1/pqc_scan/rules/ism_controls.txt +1345 -0
  49. pqscan-0.4.1/pqc_scan/rules/port_map.yaml +31 -0
  50. pqscan-0.4.1/pqc_scan/rules/scoring.yaml +190 -0
  51. pqscan-0.4.1/pqc_scan/rules/selftest.yaml +229 -0
  52. pqscan-0.4.1/pqc_scan/scoring.py +553 -0
  53. pqscan-0.4.1/pqc_scan/selftest.py +182 -0
  54. pqscan-0.4.1/pqc_scan/ssh_probe.py +187 -0
  55. pqscan-0.4.1/pqc_scan/tls_probe.py +471 -0
  56. pqscan-0.4.1/pqc_scan/verify.py +381 -0
  57. pqscan-0.4.1/pyproject.toml +111 -0
  58. pqscan-0.4.1/tests/fixtures/openssl/expired.txt +1 -0
  59. pqscan-0.4.1/tests/fixtures/openssl/self-signed.txt +1 -0
  60. pqscan-0.4.1/tests/fixtures/openssl/sha1-intermediate.txt +1 -0
  61. pqscan-0.4.1/tests/fixtures/openssl/tls12-ecdsa-chain.txt +1 -0
  62. pqscan-0.4.1/tests/fixtures/openssl/tls13-classical.txt +1 -0
  63. pqscan-0.4.1/tests/fixtures/openssl/tls13-hybrid.txt +1 -0
  64. pqscan-0.4.1/tests/test_cli.py +159 -0
  65. pqscan-0.4.1/tests/test_collector.py +289 -0
  66. pqscan-0.4.1/tests/test_discovery.py +88 -0
  67. pqscan-0.4.1/tests/test_domain.py +206 -0
  68. pqscan-0.4.1/tests/test_exporters.py +102 -0
  69. pqscan-0.4.1/tests/test_hostile_input.py +144 -0
  70. pqscan-0.4.1/tests/test_hostile_server.py +154 -0
  71. pqscan-0.4.1/tests/test_ipsec.py +225 -0
  72. pqscan-0.4.1/tests/test_network.py +14 -0
  73. pqscan-0.4.1/tests/test_parser.py +107 -0
  74. pqscan-0.4.1/tests/test_readiness_band.py +106 -0
  75. pqscan-0.4.1/tests/test_reporters.py +181 -0
  76. pqscan-0.4.1/tests/test_scoring.py +384 -0
  77. pqscan-0.4.1/tests/test_selftest.py +87 -0
  78. pqscan-0.4.1/tests/test_verify.py +105 -0
  79. pqscan-0.4.1/tests/test_weak_and_autodetect.py +196 -0
  80. pqscan-0.4.1/tools/capture_fixtures.sh +18 -0
  81. pqscan-0.4.1/tools/refresh_ism_controls.py +59 -0
  82. pqscan-0.4.1/tools/verify_openssl.py +6 -0
  83. pqscan-0.4.1/uv.lock +929 -0
@@ -0,0 +1,42 @@
1
+ name: Bug report
2
+ description: Something measured wrong, crashed, or reported a finding you believe is incorrect
3
+ labels: [bug]
4
+ body:
5
+ - type: markdown
6
+ attributes:
7
+ value: |
8
+ A wrong measurement is the most serious kind of bug this tool can have, so thank you
9
+ for reporting it. If you believe a finding is incorrect, `--explain` output is the
10
+ single most useful thing you can include.
11
+ - type: textarea
12
+ id: what
13
+ attributes:
14
+ label: What happened
15
+ description: What did the tool report, and what did you expect?
16
+ validations: {required: true}
17
+ - type: textarea
18
+ id: command
19
+ attributes:
20
+ label: The command and its output
21
+ description: Include `--explain` if a score or finding looks wrong. Redact hostnames if they are not public.
22
+ render: shell
23
+ validations: {required: true}
24
+ - type: input
25
+ id: version
26
+ attributes:
27
+ label: Version
28
+ description: Output of `pqc doctor` (first two lines are enough)
29
+ validations: {required: true}
30
+ - type: input
31
+ id: platform
32
+ attributes:
33
+ label: OS and Python
34
+ placeholder: macOS 15.2, Python 3.13.1
35
+ validations: {required: true}
36
+ - type: checkboxes
37
+ id: selftest
38
+ attributes:
39
+ label: Before submitting
40
+ options:
41
+ - label: I ran `pqc selftest --offline` and included the result if it failed
42
+ - label: The endpoint is one I am authorised to scan, or is a public test endpoint
@@ -0,0 +1,8 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Security vulnerability
4
+ url: https://github.com/NFH26/pqscan/security/advisories/new
5
+ about: Please report privately rather than opening an issue. See SECURITY.md.
6
+ - name: Question
7
+ url: https://github.com/NFH26/pqscan/discussions
8
+ about: Ask about usage, ISM interpretation, or readiness assessment generally.
@@ -0,0 +1,19 @@
1
+ name: Feature request
2
+ description: A protocol, control, output format or workflow that is missing
3
+ labels: [enhancement]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: What are you trying to do
9
+ description: The problem, not the solution — it often has a cheaper answer.
10
+ validations: {required: true}
11
+ - type: textarea
12
+ id: proposal
13
+ attributes:
14
+ label: What you have in mind
15
+ - type: input
16
+ id: control
17
+ attributes:
18
+ label: Related ISM control, if any
19
+ description: A proposal tied to a control is much easier to accept.
@@ -0,0 +1,31 @@
1
+ name: Rule or ISM mapping correction
2
+ description: A control is cited wrongly, an algorithm is classified wrongly, or the ISM changed
3
+ labels: [rules]
4
+ body:
5
+ - type: markdown
6
+ attributes:
7
+ value: |
8
+ The rule profile is a reading of the ISM, and readings can be wrong. Corrections with a
9
+ citation are the most valuable contributions this project can receive.
10
+ - type: input
11
+ id: control
12
+ attributes:
13
+ label: ISM control
14
+ placeholder: ISM-1995
15
+ - type: textarea
16
+ id: current
17
+ attributes:
18
+ label: What the tool does now
19
+ description: Quote the relevant line from `pqc_scan/rules/asd_ism.yaml` if you can.
20
+ validations: {required: true}
21
+ - type: textarea
22
+ id: correct
23
+ attributes:
24
+ label: What it should do, and why
25
+ description: Please quote the ISM wording you are relying on.
26
+ validations: {required: true}
27
+ - type: input
28
+ id: ism
29
+ attributes:
30
+ label: ISM version
31
+ placeholder: September 2026 / OSCAL 2026.09.4
@@ -0,0 +1,18 @@
1
+ ## What this changes
2
+
3
+ <!-- One or two sentences. If it fixes an issue, "Fixes #123". -->
4
+
5
+ ## Why
6
+
7
+ <!-- The reasoning belongs here and, for anything non-obvious, in a comment in the code.
8
+ This project's commits explain *why*; a diff already shows *what*. -->
9
+
10
+ ## Checklist
11
+
12
+ - [ ] `pqc test` passes
13
+ - [ ] `pqc selftest --offline` passes
14
+ - [ ] New behaviour has a test that would fail without the change
15
+ - [ ] A rule or classification change cites the ISM control it is based on
16
+ - [ ] A new protocol is registered in `PROBES`, given a port in `port_map.yaml`, and has a
17
+ case in `selftest.yaml`
18
+ - [ ] No measurement can now fail silently — a failure is reported, never assumed compliant
@@ -0,0 +1,9 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: "pip"
4
+ directory: "/"
5
+ schedule: {interval: "monthly"}
6
+ open-pull-requests-limit: 5
7
+ - package-ecosystem: "github-actions"
8
+ directory: "/"
9
+ schedule: {interval: "monthly"}
@@ -0,0 +1,82 @@
1
+ name: ci
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ workflow_dispatch:
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ concurrency:
13
+ group: ci-${{ github.ref }}
14
+ cancel-in-progress: true
15
+
16
+ jobs:
17
+ test:
18
+ name: test (py${{ matrix.python }} on ${{ matrix.os }})
19
+ runs-on: ${{ matrix.os }}
20
+ strategy:
21
+ fail-fast: false
22
+ matrix:
23
+ os: [ubuntu-latest, macos-latest, windows-latest]
24
+ python: ["3.11", "3.13"]
25
+ steps:
26
+ - uses: actions/checkout@v7
27
+ - uses: astral-sh/setup-uv@v10.2.0
28
+ with:
29
+ enable-cache: true
30
+ - run: uv sync --extra dev --python ${{ matrix.python }}
31
+ - name: Unit tests
32
+ run: uv run pytest -q
33
+ - name: Rules, scoring and output checks
34
+ # No network, so it runs everywhere. Catches a rule profile that no longer
35
+ # matches ASD's catalog, which a unit test cannot see.
36
+ run: uv run pqc selftest --offline
37
+
38
+ lint:
39
+ runs-on: ubuntu-latest
40
+ steps:
41
+ - uses: actions/checkout@v7
42
+ - uses: astral-sh/setup-uv@v10.2.0
43
+ with:
44
+ enable-cache: true
45
+ - run: uv sync --extra dev
46
+ - run: uv run ruff check .
47
+ # Both of these pass. A gate that is allowed to fail is not a gate, and a step that
48
+ # always reports a failure nobody acts on is the reason people stop reading CI.
49
+ - run: uv run mypy pqc_scan/
50
+
51
+ build:
52
+ name: build and verify the package
53
+ runs-on: ubuntu-latest
54
+ steps:
55
+ - uses: actions/checkout@v7
56
+ - uses: astral-sh/setup-uv@v10.2.0
57
+ - run: uv build
58
+ - run: uvx twine check dist/*
59
+ - name: Install the wheel and run it
60
+ # A package that builds but does not run is a package that fails on someone
61
+ # else's machine instead of ours.
62
+ run: |
63
+ uv venv /tmp/fresh
64
+ VIRTUAL_ENV=/tmp/fresh uv pip install dist/*.whl
65
+ /tmp/fresh/bin/pqc doctor
66
+ /tmp/fresh/bin/pqc selftest --offline
67
+ - uses: actions/upload-artifact@v7
68
+ with:
69
+ name: dist
70
+ path: dist/
71
+
72
+ live:
73
+ name: live protocol self-test
74
+ runs-on: ubuntu-latest
75
+ # Reaches public endpoints, so it is not run on forks or on every pull request.
76
+ if: github.event_name != 'pull_request'
77
+ continue-on-error: true
78
+ steps:
79
+ - uses: actions/checkout@v7
80
+ - uses: astral-sh/setup-uv@v10.2.0
81
+ - run: uv sync --extra dev
82
+ - run: uv run pqc selftest
@@ -0,0 +1,53 @@
1
+ name: release
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ permissions:
8
+ contents: write
9
+
10
+ jobs:
11
+ build:
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v7
15
+ - uses: astral-sh/setup-uv@v10.2.0
16
+ - run: uv build
17
+ - name: Check the tag matches the packaged version
18
+ # A release tagged v0.4.0 that ships 0.3.0 is a support problem forever.
19
+ run: |
20
+ tag="${GITHUB_REF_NAME#v}"
21
+ built=$(ls dist/*.whl | sed -E 's/.*-([0-9][^-]*)-py3.*/\1/')
22
+ test "$tag" = "$built" || { echo "tag $tag != version $built"; exit 1; }
23
+ - run: uvx twine check dist/*
24
+ - uses: actions/upload-artifact@v7
25
+ with: {name: dist, path: dist/}
26
+
27
+ pypi:
28
+ # Trusted publishing: no token stored in the repo. Register the publisher once at
29
+ # https://pypi.org/manage/account/publishing/ (project pqscan, owner NFH26,
30
+ # repository pqscan, workflow release.yml, environment pypi).
31
+ needs: build
32
+ runs-on: ubuntu-latest
33
+ environment: pypi
34
+ permissions:
35
+ id-token: write
36
+ steps:
37
+ - uses: actions/download-artifact@v8
38
+ with: {name: dist, path: dist}
39
+ - uses: pypa/gh-action-pypi-publish@release/v1
40
+
41
+ github-release:
42
+ needs: build
43
+ runs-on: ubuntu-latest
44
+ steps:
45
+ - uses: actions/checkout@v7
46
+ - uses: actions/download-artifact@v8
47
+ with: {name: dist, path: dist}
48
+ - uses: softprops/action-gh-release@v3
49
+ with:
50
+ files: dist/*
51
+ generate_release_notes: true
52
+ body: |
53
+ See [CHANGELOG.md](https://github.com/NFH26/pqscan/blob/main/CHANGELOG.md).
@@ -0,0 +1,36 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .venv/
8
+ venv/
9
+
10
+ # Tooling
11
+ .pytest_cache/
12
+ .mypy_cache/
13
+ .ruff_cache/
14
+ .coverage
15
+ htmlcov/
16
+
17
+ # Scan output and local state
18
+ reports/
19
+ .pqc_cache/
20
+
21
+ # Reference material that is not ours to redistribute. The ASD ISM is Commonwealth
22
+ # copyright; the tool reads control numbers from the OSCAL catalog instead, which ASD
23
+ # publishes under CC BY 4.0 (see pqc_scan/rules/ism_controls.txt).
24
+ Ref/
25
+
26
+ # OS
27
+ .DS_Store
28
+ Thumbs.db
29
+
30
+ # Superseded by pyproject.toml; kept out of the repo so there is one source of truth.
31
+ requirements.txt
32
+
33
+ # Drafts and local working files that are not part of the tool.
34
+ LINKEDIN-POST.md
35
+ test-plan/
36
+ *outputs/
@@ -0,0 +1,135 @@
1
+ # Changelog
2
+
3
+ Notable changes to PQScan. Format based on [Keep a Changelog](https://keepachangelog.com/),
4
+ versioning follows [Semantic Versioning](https://semver.org/).
5
+
6
+ Rule-profile changes are called out separately, because a new rules version can change a score
7
+ without any code changing.
8
+
9
+ ## [0.4.1] - unreleased
10
+
11
+ ### Changed
12
+
13
+ - **Published on PyPI as `pqscan`.** `pipx install pqscan` replaces the clone-and-setup step.
14
+ The name `pqc-scan` on PyPI belongs to an unrelated project. The `pqc` command is unchanged;
15
+ the long alias is now `pqscan` instead of `pqc-scan`.
16
+ - The release workflow publishes to PyPI through trusted publishing, with no stored token.
17
+
18
+ ## [0.4.0] - 2026-09-21
19
+
20
+ First public release.
21
+
22
+ ### Added
23
+
24
+ - **Service-specific recommendations.** Every recommendation names the endpoints it applies to
25
+ and the service each one runs (`vpn-a.example:500 (ipsec)`), in the terminal, the Markdown
26
+ export and the HTML report, where each endpoint links to its own measurements. An estate with
27
+ several VPNs or a dozen SSH hosts needs to know which box to change, not how many.
28
+ - **IPsec / IKEv2 probe.** One unauthenticated, plaintext `IKE_SA_INIT` answers ISM-1233, 1771,
29
+ 1772, 0998 and 0999. Handles the RFC 7296 cookie challenge, which any gateway under load
30
+ issues — and which a probe that ignores it measures nothing against.
31
+ - **Domain controls.** SPF (ISM-0574), hard-fail SPF (ISM-1183), DMARC reject (ISM-1540),
32
+ MTA-STS enforcing (ISM-1589) and HSTS (ISM-1424), via a hand-rolled DNS resolver so the
33
+ install stays one command.
34
+ - **Service discovery** (`--discover`). Given a hostname, finds which of 24 ISM-relevant ports
35
+ are live, identifies each from its greeting, and measures them all.
36
+ - **Cipher suite enumeration** (`--deep`). Reading one ServerHello only reveals a server's
37
+ favourite suite. `badssl.com` leads with AES-GCM and still accepts 3DES and static RSA key
38
+ transport — the suite a downgrade attack asks for.
39
+ - **CBOM export.** CycloneDX 1.6, built from observed negotiation rather than declared
40
+ dependencies, citing ISM-2082 and ISM-2083.
41
+ - **SARIF and Markdown exports**, alongside HTML, CSV and JSON. One `-o` directory, `-f` to
42
+ narrow. Each run lands in its own dated folder.
43
+ - **`pqc selftest`.** A real scan of every protocol against endpoints with a known answer, plus
44
+ offline checks of the rule profile, the scoring invariants and every output format — including
45
+ that every cited ISM control number still exists in ASD's catalog.
46
+ - **Readiness band, 0-5.** Band 3, *PQ capable but not negotiating*, is the one that matters: an
47
+ endpoint that cannot do post-quantum and one that can but does not are both classical, and
48
+ only the second is a configuration line from compliant.
49
+ - DNS over TLS (ISM-2017) and SIP over TLS (ISM-0548) via the port map.
50
+ - `--protocol` for a single target, `--flat`, and a per-host time budget.
51
+
52
+ ### Fixed
53
+
54
+ - **Ed25519 and Ed448 certificates no longer raise.** Both key types carry no `key_size`
55
+ attribute, so reading one raised `AttributeError` on any endpoint presenting an EdDSA
56
+ certificate. Both curves are fixed size and are now reported as such.
57
+ - **mypy now actually runs.** It was aborting on a module-path collision before checking a
58
+ single file, so the type gate had never caught anything. The findings it surfaced once it ran
59
+ are fixed in this release.
60
+ - **The scanner crashed on a machine with no OpenSSL binary** — the configuration the README
61
+ promises and `doctor` reports as fine.
62
+ - **A file descriptor leaked on every exception path** in the main TLS connection, which is the
63
+ weak-crypto path, so scanning a legacy estate exhausted descriptors.
64
+ - **Hosts that only speak 3DES, RC4 or NULL were unmeasurable.** Current OpenSSL builds do not
65
+ offer those suites, so the `ssl` module cannot reach such a host; PQScan now builds its own
66
+ ClientHello and measures them.
67
+ - **Network failures were reported as ISM breaches.** A DNS timeout on `_dmarc` was
68
+ indistinguishable from a domain publishing no DMARC.
69
+ - **IKEv2 transforms were read from a fixed offset**, ignoring the declared SPI size, producing
70
+ plausible but wrong algorithm names.
71
+ - **A YAML null silently disabled the NULL-cipher check**, letting an unencrypted endpoint score
72
+ better than a 3DES one.
73
+ - TLS below 1.3 reported as UNKNOWN rather than definitively classical.
74
+ - Ports treated as contracts rather than guesses — SSH on 443 is now detected and measured.
75
+ - Teardown could hang forever against a peer that went silent mid-handshake.
76
+ - `--require-hybrid-kex` failed on every domain row.
77
+ - An SSH server's `SSH_MSG_DISCONNECT` reason is quoted instead of reported as a parse error.
78
+
79
+ ### Changed
80
+
81
+ - **Dependency floors raised to the versions actually tested**: jinja2 3.1.6 (a security fix),
82
+ pydantic 2.13.5, typer 0.27.2, pytest-asyncio 1.4.0 and ruff 0.16.8. The lockfile already
83
+ held these; the declared minimums had not moved since the first commit.
84
+ - **GitHub Actions updated**: checkout v7, upload-artifact v7, download-artifact v8, setup-uv
85
+ v10 and action-gh-release v3.
86
+
87
+ - **The coverage page listed four IPsec controls as measured that the rule profile itself
88
+ declares unobservable** (ISM-0494, 0496, 0498, 1000). They are settled in `IKE_AUTH` or
89
+ `CREATE_CHILD_SA`, which an unauthenticated probe never reaches. Removed, and the offline
90
+ check now refuses to let an unobservable control be listed as measured. The documented count
91
+ is 44.
92
+ - **ASD's deadlines, all three.** The docs led with 2030 alone. ASD's first milestone is a
93
+ refined transition plan by the end of 2026, then commencement by 2028, then completion by
94
+ 2030; the profile carries all three as data.
95
+
96
+ - **`pqc report` uses the same writers as `pqc scan --out`.** It carried its own thinner JSON
97
+ and CBOM writers, so `report --format cbom` and `scan -f cbom` produced different documents.
98
+ It now takes the same format names as `scan` and writes the same files. The `rich` and
99
+ `jsonl` format names are gone; `rich` was the terminal output, which prints anyway.
100
+ - **The status legend lists only the bands on screen.** A six-band legend under a table holding
101
+ one band is definitions for something the reader is not looking at.
102
+ - **A one-host scan drops the fleet summary.** "Hosts scanned 1" and "PQ readiness HYBRID 1"
103
+ both restated the single row underneath them.
104
+ - **`pqc scan` no longer warns about an old OpenSSL.** Scanning never uses the binary, so the
105
+ notice was a warning that trains people to ignore warnings. `pqc doctor` reports the
106
+ capability and `pqc verify` enforces the version.
107
+ - **`pqc doctor` ends by showing how to start a scan** rather than with a scoring legend that
108
+ belongs next to a score.
109
+ - **The summary counts endpoints, not hosts.** After `--discover` finds seven services on one
110
+ host, "Hosts scanned 7" was simply wrong; it now reads "Endpoints 7 on 1 host(s)" and adds a
111
+ breakdown by service when more than one kind was measured.
112
+ - **Every row names its service.** Four SSH listeners on one host differ only by port, and a
113
+ table showing the port alone read as the same row four times.
114
+ - **Recommendations list every affected endpoint.** "+2 more" hid exactly the VPN or SSH host
115
+ the reader was looking for.
116
+ - **Removed the PQCMM claim.** Checked against the published model: the PKI Consortium's PQC
117
+ Maturity Model rates a named product as shipped, on evidence a handshake cannot see. PQScan
118
+ reports its own band and says plainly why a scan can contribute evidence to a PQCMM assessment
119
+ but cannot be one.
120
+ - **Python 3.11 and newer**, down from 3.13.
121
+ - The summary says only what is true at the scale scanned; a distribution over one host repeated
122
+ the row below it.
123
+ - One `Status` column instead of separate Ready and Band columns, which said the same thing
124
+ twice.
125
+ - Three export flags became `-o` and `-f`. The old flags still work.
126
+
127
+ ### Rules
128
+
129
+ - `asd_ism` rules version `2026.09.1`, control identifiers verified against ASD OSCAL catalog
130
+ `2026.09.4`.
131
+ - SSH tables now classify ML-KEM hybrids over NIST curves and ML-DSA host keys. ML-DSA-44 is
132
+ classified unapproved: ISM-1991 lists only ML-DSA-65 and ML-DSA-87.
133
+ - NULL and EXPORT ciphers scored separately from weak-but-real ciphers, at the cap.
134
+
135
+ [0.4.0]: https://github.com/NFH26/pqscan/releases/tag/v0.4.0
@@ -0,0 +1,31 @@
1
+ # Code of conduct
2
+
3
+ ## The short version
4
+
5
+ Be straight with people and assume they are being straight with you. Disagree about the
6
+ technical substance as sharply as you like; do not make it about the person.
7
+
8
+ ## Expected
9
+
10
+ - Engage with what someone actually said or wrote.
11
+ - Say when you are unsure, and say when you were wrong. This project has a running record of
12
+ bugs found by people who took a second look, and that record is an asset.
13
+ - Accept that a rule reading can be contested. Bring the ISM wording and argue the reading.
14
+
15
+ ## Not acceptable
16
+
17
+ Harassment, personal attacks, discriminatory language, publishing private information, or
18
+ sustained disruption of discussion.
19
+
20
+ ## Reporting
21
+
22
+ Contact the maintainer privately through
23
+ [GitHub Security Advisories](https://github.com/NFH26/pqscan/security/advisories/new),
24
+ which is private, or by an issue if the matter is not sensitive. Reports are handled discreetly.
25
+ The maintainer may edit, remove or reject contributions and comments that are not consistent
26
+ with this document, and may ban a contributor for sustained or serious breaches.
27
+
28
+ ## Scope
29
+
30
+ Applies in this repository, its issues, pull requests and discussions, and anywhere someone is
31
+ representing the project.
@@ -0,0 +1,72 @@
1
+ # Contributing
2
+
3
+ Thank you for looking. This is a compliance tool, which shapes what a good contribution looks
4
+ like: a wrong measurement presented confidently is worse than no measurement at all, so the bar
5
+ is less about style and more about not being quietly wrong.
6
+
7
+ ## Getting set up
8
+
9
+ ```bash
10
+ git clone https://github.com/NFH26/pqscan.git
11
+ cd pqscan
12
+ ./pqc setup
13
+ pqc test
14
+ ```
15
+
16
+ Python 3.11 or newer. No other system dependency.
17
+
18
+ ## Before you open a pull request
19
+
20
+ ```bash
21
+ pqc test # unit tests, no network, about ten seconds
22
+ pqc selftest --offline # rules, scoring invariants, output formats
23
+ pqc selftest # live, every protocol (needs network)
24
+ ./pqc lint
25
+ ```
26
+
27
+ ## The rules this project is strict about
28
+
29
+ Each came from a real bug and each has a test pinning it. The full list, with the defect behind
30
+ each rule, is in [docs/architecture.md](docs/architecture.md#design-rules-that-are-load-bearing).
31
+ Read it before your first change. The two that reviewers raise most often:
32
+
33
+ **Unmeasured is never compliant.** An endpoint that could not be reached gets no score, no band
34
+ and no pass, and must never satisfy a policy gate.
35
+
36
+ **Rules are data.** Classifications live in `pqc_scan/rules/*.yaml` next to the ISM control that
37
+ sets them. A classification change is a YAML edit and should cite its control.
38
+
39
+ **Comments explain why.** The code shows what it does. A comment earns its place by explaining
40
+ the reasoning, the constraint, or the bug that made the code look like this. Commit messages
41
+ follow the same rule.
42
+
43
+ ## Adding a protocol
44
+
45
+ See [docs/architecture.md](docs/architecture.md#adding-a-protocol). Briefly: write a probe that
46
+ returns a `HostFinding`, register it in `PROBES`, give it a port in `port_map.yaml`, add its
47
+ classifications to the rule profile with their control numbers, and add a case to
48
+ `selftest.yaml`.
49
+
50
+ ## Changing a rule or a classification
51
+
52
+ Please include the ISM wording you are relying on. The profile is a *reading* of the ISM and
53
+ readings can be wrong; two positions are already marked `verify:` for exactly that reason.
54
+
55
+ If a new ISM has been published, run `python tools/refresh_ism_controls.py` and include the
56
+ updated control list in the same pull request.
57
+
58
+ ## Tests
59
+
60
+ - Unit tests live in `tests/` and must not touch the network.
61
+ - A live protocol case belongs in `pqc_scan/rules/selftest.yaml`, not in a unit test.
62
+ - Every parser reads attacker-controlled bytes. New parsing code needs a case in
63
+ `tests/test_hostile_input.py`, and new connection handling needs one in
64
+ `tests/test_hostile_server.py`.
65
+
66
+ ## Reporting a security issue
67
+
68
+ Please do not open a public issue — see [SECURITY.md](SECURITY.md).
69
+
70
+ ## Licence
71
+
72
+ Contributions are accepted under Apache-2.0, the licence of this project.