35 lines
5.1 KiB
Markdown
35 lines
5.1 KiB
Markdown
# Protected scanner import contracts
|
|
|
|
User decision, 2026-10-09: working scanner imports are ASSESSOR crown jewels. This is a Core compatibility boundary in Phase 13A, not another engine or another worker.
|
|
|
|
## Release gate
|
|
|
|
Run `npm run test:imports` for every importer, shared helper, dependency or Platform change. `npm test` runs it before the complete suite; `npm run build` runs it through `prebuild` before either production build. Any failure blocks release. Direct build commands are not a substitute for this gate.
|
|
|
|
The gate runs Vitest in CI mode, without an update option. Changed and missing snapshots fail. It includes all importer and scoring tests and the Node runtime, worker, base64, batch HTTP and server API tests, plus GPO/GPP server ingestion, Registry.pol, security templates, preferences, advanced audit, ADMX and domain ingestion tests. The existing tests for invalid input, safety limits, native score priority and safe fallback stay required.
|
|
|
|
## Registered reference inputs
|
|
|
|
`tests/importers/import-contracts.json` is the additive format register. Each entry names a tool, format, exact synthetic fixture, variant, filename/MIME, expected approved Work-record count and SHA-256 of UTF-8 fixture text with CRLF normalized to LF. Excel is generated from the protected CSV using the existing XLSX library; it is checked through both runtime paths.
|
|
|
|
Initial coverage: 18 variants across all five registered import profiles, using every existing synthetic scanner fixture plus a synthetic Maester multi-tenant fixture. PingCastle HTML/XML; CIS-CAT HTML details, future control sections and summary/outcomes; Purple Knight HTML, JSON and summary CSV; Maester CSV, Excel, legacy HTML, static object literal, current JSON-script declaration, bare JSON-script data, const/let/var and multi-tenant HTML; generic CSV.
|
|
|
|
For each reference the test exercises file selection/import, recognition, non-error preview, explicit confirmation of mappings and canonical batch creation in both browser and Node backend. Both paths must produce identical protected results. Committed snapshots retain finding identity, original and normalized values, source locations, field roles, status/outcome/execution state, severity, score, evidence and its finding association, source tables, scanner report sections and environment observations. The scoring projection is protected too. Generated IDs/links, import timestamps, processing versions and mapping-confidence explanations are not application findings and are excluded where applicable; original source objects are never recursively scrubbed.
|
|
|
|
The registry test rejects removal of an initial contract and requires a reference for every registered profile and every `.synthetic.` fixture. Baselines are inspectable output, not hashes of opaque canonical objects. Existing structural and semantic assertion tests remain in the gate to avoid accepting an incorrect initial baseline by snapshot alone.
|
|
|
|
## Extending and maintaining contracts
|
|
|
|
1. Use only invented Dummy data. Build a fixture for the exact report structure; retain original-value edge cases and provenance. Do not read customer reports or copy customer values into a fixture.
|
|
2. Add a uniquely named register entry and its normalized fixture checksum. Keep existing entries and fixtures. Add exact assertions for the new behavior, including the scoring declaration required by the project guidance.
|
|
3. Generate only the new case's initial snapshot using a narrowly selected test, inspect its fields and approved count, and run the complete gate without update mode. Never blanket-update existing snapshots to resolve a regression.
|
|
4. Run the full tests and both builds, and record coverage/limits in the implementation plan. Do not claim support for a vendor format solely because it is listed by the vendor.
|
|
|
|
Changes to established expected behavior, removal of a contract or replacement of a reference require the user's explicit agreement for that exact change and current Core consent for affected areas. A failing test must normally be fixed by restoring compatibility or adding another input variant. Test suppression, hash replacement and baseline regeneration are not repairs.
|
|
|
|
## Limits and current gaps
|
|
|
|
This protects registered examples and existing behavioral suites, not unknown future vendor formats or all possible report values. An exploratory raw Maester JSON object produced the generic profile rather than Maester recognition; that shape has not been promoted to a supported Maester contract or changed in this protection batch. Additional supported structures should be registered incrementally; unsupported structures need a separate additive implementation and regression tests. No external CI provider is configured in this repository; a future CI pipeline must invoke the same mandatory `npm test`/`npm run build` entry points.
|
|
|
|
The protection is executable for normal test/build commands and binding for agents and reviewers through AGENTS.md. It cannot prevent someone with repository write access from intentionally changing the gate itself; such a change is Governance/Platform work and remains subject to Core consent and review.
|