7.2 KiB
Findings remediation plan
Pending remediation batches for the open items in FINDINGS.md.
Every batch of the 2026-09-20 audit is complete and summarized in
Documentation/RELEASE_NOTES_1.0.md;
their plans, validation and benchmarks are in git history. When a batch is
fixed, remove it and its assessment rows from this file, remove its findings
from FINDINGS.md, and summarize the change in the next release notes.
Classification and priority
The findings index still calls its classification column Severity, but its
values are types. This plan preserves those types and assigns proposed
severity independently. Severity estimates assume the affected feature is
used; deployment exposure can change the estimate. They are not CVSS scores.
| Severity | Meaning for this library | Priority |
|---|---|---|
| CRITICAL | Untrusted input can bypass certificate issuance policy at a trust boundary | P0: address first |
| HIGH | Authentication/trust protection fails, a normal feature hangs/crashes, or concurrent use can stop a process | P1: next remediation cycle |
| MEDIUM | A supported operation fails under particular inputs/configuration, or reliability/performance is materially impaired | P2: scheduled remediation |
| LOW | Limited interoperability, metadata, documentation, or tooling impact | P3: follow-up |
Importance = severity first, then type. For a sortable score, assign
severity CRITICAL=4, HIGH=3, MEDIUM=2, LOW=1 and type security=6, bug=5,
race=4, correctness=3, performance=2, docs=1. Score = 10 × severity + type;
higher scores go first. Thus HIGH/correctness (33) precedes MEDIUM/security
(26), and HIGH/security (36) precedes HIGH/bug (35). This makes the combination
explicit without letting a cosmetic security-related item outrank an outage.
A batch inherits its highest item score; lower-priority companions do not acquire a higher severity. Break ties by production exposure, dependencies, then smaller reviewable scope. Regression risk below describes the change, not the severity of the existing defect.
Every implementation batch has one package owner. Scripts, workflow, and build configuration have separate non-Go owners. Multi-package findings are split into linked portions; an ID is complete only after all portions are complete. The suffixes in this plan are scope labels, not replacement IDs.
Decision means the existing FINDINGS compatibility decision must be resolved
before implementing the changed contract. It does not block test design,
reproduction, or this plan. Do not silently change public APIs to make an
implementation easier; record larger contract work in ROADMAP.md.
Batch queue
No open batches. New findings get a batch here with the columns below when they are recorded in FINDINGS.md:
| Batch | Owner | Findings (package portion where split) | Priority / score | Regression risk | Decision |
|---|
Conventions that carry over to the next batches:
- For a fixture-dependent test, gate with
internal/testenv(RequireTCP, orRequireFilefor a fixture file such as the SoftHSM config); the Makefile exportsXPKI_INTEGRATION=required, so a missing fixture failsmake test/covtestand CI while a local run without the fixture skips. Keep unit tests fixture-free withinmemcryptoandtestca. - Prove the pre-fix failure (a
git worktreeof HEAD, or the new test against the old code) before changing the implementation, and record only verified claims. - The coverage gate in CI is
MIN_TESTCOV=90with a strict>comparison (.github/workflows/unittest.yml);make lintruns in CI and must stay clean.
Benchmark and race-test protocol
No open batch needs a before-fix benchmark.
Performance fixes require an existing-behavior reproduction plus a baseline
before optimization. Use generated fixtures and local/fake HTTP/KMS services;
keep service latency controlled. Compare the same scenarios/toolchain/machine
before and after, for example go test ./<package> -run '^$' -bench <name> -benchmem -count=5 -cpu=1,4,8. For pool/network work, request/resource counts
and bounded completion are acceptance criteria alongside timing.
Do not run a known racy map or hanging pool unbounded to obtain a baseline. Use a safe serial baseline or isolated, time-bounded reproduction, then measure the concurrent implementation once it is correct. Record that limitation. Run race detection separately from timing; race-instrumented timings are not comparable production-performance measurements.
For every shared-state fix, add a test with overlapping reads and writes
(barriers/channels, not merely t.Parallel on independent objects), assert
results, and run make test RACE=true with required fixtures provisioned.
Keep testca defaults, entity fields and option data immutable
during concurrent generation and use a signer supporting concurrent calls. Passing the
existing mostly serial race suite is insufficient evidence that these races
are fixed.
Completion and validation
For each batch:
- Reproduce the finding or correct its premise first. Write the missing behavioral assertions before changing the implementation; update existing characterization tests in the same batch. Do not close a finding solely because statement coverage is high.
- Resolve the listed contract decisions with concrete API/config examples. Preserve the existing Needs Approval statuses until those decisions exist. Security/outage fixes in independent batches can proceed meanwhile.
- Run the owning package's targeted tests and affected consumers, with local servers/generated fixtures wherever possible. Perform the required benchmark comparison and concurrency validation for that batch.
- Run required integration checks using the established SoftHSM and local-kms
fixtures. Use
make lint; shared-state changes also requiremake test RACE=true. Overlapping CLI coverage and race runs need separate output files. Preserve the actual CI coverage gate and exclusions; adding skips must not hide integration execution in CI. - In the same change, remove the fixed finding from
FINDINGS.mdand its batch and assessment rows from this plan, and summarize the fix, its compatibility impact and the client changes it needs in the nextDocumentation/RELEASE_NOTES_<version>.md. Keep both files synchronized, even whenPLAN.mdis ignored by Git. Remove a finding only when every linked package portion is complete; otherwise record partial progress and remaining work. Never reuse IDs, and state any validation limitations in the commit or PR. - Update the codemap for changed APIs, ownership, locking, formats, algorithms, fixture conventions, and compatibility decisions. Put larger API designs/migrations in ROADMAP and keep examples compiling.