feat: Implement vulnerability token signing and verification utilities
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Added VulnTokenSigner for signing JWT tokens with specified algorithms and keys. - Introduced VulnTokenUtilities for resolving tenant and subject claims, and sanitizing context dictionaries. - Created VulnTokenVerificationUtilities for parsing tokens, verifying signatures, and deserializing payloads. - Developed VulnWorkflowAntiForgeryTokenIssuer for issuing anti-forgery tokens with configurable options. - Implemented VulnWorkflowAntiForgeryTokenVerifier for verifying anti-forgery tokens and validating payloads. - Added AuthorityVulnerabilityExplorerOptions to manage configuration for vulnerability explorer features. - Included tests for FilesystemPackRunDispatcher to ensure proper job handling under egress policy restrictions.
This commit is contained in:
92
docs/modules/policy/windows-package-readiness.md
Normal file
92
docs/modules/policy/windows-package-readiness.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Windows Package Coverage — Policy & Security Readiness Brief
|
||||
|
||||
> Audience: Policy Guild, Security Guild, Offline Kit Guild
|
||||
> Related engineering backlog (proposed): SCANNER-ENG-0024..0027
|
||||
> Docs linkage: DOCS-SCANNER-BENCH-62-016
|
||||
|
||||
## 1. Goal
|
||||
- Prepare policy and security guidance ahead of Windows analyzer implementation (MSI, WinSxS, Chocolatey, registry).
|
||||
- Define evidence handling, predicates, waiver expectations, and offline prerequisites so engineering can align during spike execution.
|
||||
|
||||
## 2. Evidence pipeline snapshot (from `design/windows-analyzer.md`)
|
||||
1. **Collection**
|
||||
- MSI database parsing → component records keyed by ProductCode/ComponentCode.
|
||||
- WinSxS manifests → assembly identities, catalog signatures.
|
||||
- Chocolatey packages → nuspec metadata, feed provenance, script hashes.
|
||||
- Registry exports → uninstall/service entries, legacy installers.
|
||||
- Driver/service mapper → capability overlays (kernel-mode, auto-start).
|
||||
2. **Storage**
|
||||
- Results persisted as `LayerComponentFragment`s plus capability overlays (`ScanAnalysisKeys.capability.windows`).
|
||||
- Provenance metadata includes signature thumbprint, catalog hash, feed URL, install context.
|
||||
3. **Downstream**
|
||||
- Policy Engine consumes component + capability evidence; Export Center bundles MSI manifests, nuspec metadata, catalog hashes.
|
||||
|
||||
## 3. Policy predicate requirements
|
||||
| Predicate | Description | Initial default |
|
||||
| --- | --- | --- |
|
||||
| `windows.package.signed(thumbprint?)` | True when Authenticode signature/cert matches allowlist. | Warn on missing signature, fail on mismatched thumbprint for kernel drivers. |
|
||||
| `windows.package.sourceAllowed(sourceId)` | Validates Chocolatey/nuget feed against tenant allowlist. | Fail if feed not in tenant policy. |
|
||||
| `windows.driver.kernelMode()` | Flags kernel-mode drivers for extra scrutiny. | Fail when unsigned; warn otherwise. |
|
||||
| `windows.driver.signedBy(publisher)` | Checks driver publisher matches allowlist. | Warn on unknown publisher. |
|
||||
| `windows.service.autoStart(name)` | Identifies auto-start services. | Warn if unsigned binary or service not in allowlist. |
|
||||
| `windows.package.legacyInstaller()` | Legacy EXE-only installers detected via registry. | Warn by default; escalate if binary unsigned. |
|
||||
|
||||
Additional considerations:
|
||||
- Map KB references (from WinSxS/MSP metadata) to vulnerability posture once Policy Engine supports patch layering.
|
||||
- Provide predicates to waive specific ProductCodes or AssemblyIdentities with expiration.
|
||||
|
||||
## 4. Waiver & governance model
|
||||
- Waiver key: `{productCode, version, signatureThumbprint}` or for drivers `{driverName, serviceName, signatureThumbprint}`.
|
||||
- Required metadata: remediation ticket, justification, expiry date.
|
||||
- Automated re-evaluation when version or signature changes.
|
||||
- Tenants maintain allow lists for Chocolatey feeds and driver publishers via policy configuration.
|
||||
|
||||
## 5. Masking & privacy
|
||||
- Findings should not include raw script contents; provide SHA256 hash and limited excerpt (first/last 8 chars).
|
||||
- Registry values (install paths, command lines) must be truncated if they contain secrets; rely on Surface.Secrets to manage environment variables referenced during install scripts.
|
||||
|
||||
## 6. Offline kit guidance
|
||||
- Bundle:
|
||||
- MSI parser binary + schema definitions.
|
||||
- Chocolatey feed snapshot(s) (nupkg files) with hash manifest.
|
||||
- Microsoft root/intermediate certificate bundles; optional CRL/OCSP cache instructions.
|
||||
- Operators must export registry hives (`SOFTWARE`, `SYSTEM`) during image extraction; document PowerShell script and required access.
|
||||
- Provide checksum manifest to verify feed snapshot integrity.
|
||||
|
||||
## 7. Telemetry expectations
|
||||
- Metrics:
|
||||
- `scanner.windows.package_total{tenant,signed}` — count packages per signature state.
|
||||
- `scanner.windows.driver_unsigned_total{tenant}`.
|
||||
- `scanner.windows.choco_feed_total{tenant,feed}`.
|
||||
- Logs:
|
||||
- Include product code, version, signature thumbprint, feed ID (no file paths unless sanitized).
|
||||
- Traces:
|
||||
- Annotate collector spans (`collector.windows.msi`, `collector.windows.winsxs`, etc.) with component counts and parsing duration.
|
||||
|
||||
## 8. Open questions
|
||||
| Topic | Question | Owner | Target decision |
|
||||
| --- | --- | --- | --- |
|
||||
| Signature verification locus | Scanner vs Policy: where to verify Authenticode signatures + revocation? | Security Guild | Sprint 133 |
|
||||
| Feed mirroring scope | Default set of Chocolatey feeds to mirror (official/community). | Product + Security Guild | Sprint 133 |
|
||||
| Legacy installers | Should we block unsigned EXE installers by default or allow warn-only posture? | Policy Guild | Sprint 134 |
|
||||
| Driver taxonomy | Define high-risk driver categories (kernel-mode, filter drivers) for policy severity. | Policy Guild | Sprint 134 |
|
||||
|
||||
### Decision tracker
|
||||
| Decision | Owner(s) | Target date | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| Authenticode verification locus (Scanner vs Policy) | Security Guild | 2025-11-07 | Pending — blocker for FinSecure |
|
||||
| Chocolatey feed mirroring scope | Product + Security Guild | 2025-11-07 | Draft proposal circulating |
|
||||
| Legacy installer posture (warn vs fail) | Policy Guild | 2025-11-14 | Not started |
|
||||
| Driver risk taxonomy | Policy Guild | 2025-11-14 | Not started |
|
||||
|
||||
## 9. Next steps
|
||||
1. Policy Guild drafts predicate specs + policy templates; align with DOCS-SCANNER-BENCH-62-016.
|
||||
2. Security Guild evaluates signature verification approach and revocation handling (online vs offline CRL cache).
|
||||
3. Offline Kit Guild scopes snapshot size and update cadence for Chocolatey feeds and certificate bundles.
|
||||
4. Docs Guild prepares policy/user guidance updates once predicates are finalised.
|
||||
5. Security Guild to report decision for FinSecure Corp (POLICY-READINESS-0002) by 2025-11-07; feed outcome into dashboards.
|
||||
|
||||
## Coordination
|
||||
- Sync demand signals via `docs/benchmarks/scanner/windows-macos-demand.md`.
|
||||
- Log policy readiness status in `docs/api/scanner/windows-coverage.md`.
|
||||
- Update Windows/macOS metrics dashboard when decisions change (`docs/api/scanner/windows-macos-summary.md`).
|
||||
Reference in New Issue
Block a user