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:
master
123
docs/modules/scanner/design/macos-analyzer.md
Normal file
123
docs/modules/scanner/design/macos-analyzer.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# macOS Analyzer Design Brief (Draft)
|
||||
|
||||
> Owners: Scanner Guild, Policy Guild, Offline Kit Guild
|
||||
> Related backlog (proposed): SCANNER-ENG-0020..0023, DOCS-SCANNER-BENCH-62-002
|
||||
> Status: Draft pending demand validation (see `docs/benchmarks/scanner/windows-macos-demand.md`)
|
||||
|
||||
## 1. Scope & objectives
|
||||
- Deliver deterministic inventory coverage for macOS container and VM images, focusing on Homebrew, Apple/pkgutil receipts, and `.app` bundles.
|
||||
- Preserve StellaOps principles: per-layer provenance, offline parity, policy explainability, and signed evidence pipelines.
|
||||
- Provide capability signals (entitlements, hardened runtime, launch agents) to enable Policy Engine gating.
|
||||
|
||||
Out of scope (Phase 1):
|
||||
- Dynamic runtime tracing of macOS services (deferred to Zastava/EntryTrace).
|
||||
- iOS/tvOS/visionOS package formats (will reuse bundle inspection where feasible).
|
||||
- Direct notarization ticket validation (delegated to Policy Engine unless otherwise decided).
|
||||
|
||||
## 2. High-level architecture
|
||||
```
|
||||
Scanner.Worker (macOS profile)
|
||||
├─ Surface.Validation (enforce allowlists, bundle size limits)
|
||||
├─ Surface.FS (layer/materialized filesystem)
|
||||
├─ HomebrewCollector (new) -> LayerComponentFragment (brew)
|
||||
├─ PkgutilCollector (new) -> LayerComponentFragment (pkgutil)
|
||||
├─ BundleInspector (new) -> Capability records + component fragments
|
||||
├─ LaunchAgentMapper (optional) -> Usage hints
|
||||
└─ MacOsAggregator (new) -> merges fragments, emits ComponentGraph & capability overlays
|
||||
```
|
||||
|
||||
- Each collector runs deterministically against the mounted filesystem; results persist in `ScanAnalysisStore` under dedicated keys before being normalized by `MacOsComponentMapper`.
|
||||
- Layer digests follow existing `LayerComponentFragment` semantics to maintain diff/replay parity.
|
||||
|
||||
## 3. Collectors & data sources
|
||||
### 3.1 Homebrew collector
|
||||
- Scan `/usr/local/Cellar/**` and `/opt/homebrew/Cellar/**` for `INSTALL_RECEIPT.json` and `*.rb` formula metadata.
|
||||
- Output fields: `tap`, `formula`, `version`, `revision`, `poured_from_bottle`, `installed_with`: [].
|
||||
- Store `bottle.sha256`, `source.url`, and `tapped_from` metadata for provenance.
|
||||
- Map to PURL: `pkg:brew/<tap>/<formula>@<version>?revision=<revision>`.
|
||||
- Guardrails: limit traversal depth, ignore caches (`/Caskroom` optional), enforce 200MB per formula cap (configurable).
|
||||
|
||||
### 3.2 pkgutil receipt collector
|
||||
- Parse `/var/db/receipts/*.plist` for pkg identifiers, version, install time, volume, installer domain.
|
||||
- Use `.bom` files to enumerate installed files; capture path hashes via `osx.BomParser`.
|
||||
- Emit `ComponentRecord`s keyed by `pkgutil:<identifier>` with metadata: `bundleIdentifier`, `installTimeUtc`, `volume`.
|
||||
- Provide dependency mapping between pkg receipts and Homebrew formulae when overlapping file hashes exist (optional Phase 2).
|
||||
|
||||
### 3.3 Bundle inspector
|
||||
- Traverse `/Applications`, `/System/Applications`, `/Users/*/Applications`, `/Library/Application Support`.
|
||||
- For each `.app`:
|
||||
- Read `Info.plist` (bundle id, version, short version, minimum system).
|
||||
- Extract code signing metadata via `codesign --display --xml` style parsing (Team ID, certificate chain, hardened runtime flag).
|
||||
- Parse entitlements (`archived-entitlements.xcent`) and map to capability taxonomy (network, camera, automation, etc.).
|
||||
- Hash `CodeResources` manifest to support provenance comparisons.
|
||||
- Link `.app` bundles to receipts and Homebrew formulae using bundle id or install path heuristics.
|
||||
- Emit capability overlays (e.g., `macos.entitlement("com.apple.security.network.server") == true`).
|
||||
|
||||
### 3.4 Launch agent mapper (optional Phase 1 extension)
|
||||
- Inspect `/Library/Launch{Agents,Daemons}` and user equivalents.
|
||||
- Parse `plist` for program arguments, run conditions, sockets, environment.
|
||||
- Feed derived runtime hints into EntryTrace (`UsageHints`) to mark active binaries vs dormant installations.
|
||||
|
||||
## 4. Aggregation & output
|
||||
- `MacOsComponentMapper` converts collector results into:
|
||||
- `LayerComponentFragment` arrays keyed by synthetic digests (`sha256:stellaops-os-macbrew`, etc.).
|
||||
- `ComponentMetadata` entries capturing tap origin, Team ID, entitlements, notarization flag (when available).
|
||||
- Capability overlays stored under `ScanAnalysisKeys.capability.macOS`.
|
||||
- Export Center enhancements:
|
||||
- Include Homebrew metadata manifests and CodeResources hashes in attested bundles.
|
||||
- Provide optional notarization proof attachments if Policy Engine later requires them.
|
||||
|
||||
## 5. Policy & governance integration
|
||||
- Predicates to introduce:
|
||||
- `macos.bundle.signed(teamId?, hardenedRuntime?)`
|
||||
- `macos.entitlement(name)`
|
||||
- `macos.pkg.receipt(identifier, version?)`
|
||||
- `macos.notarized` (pending Security decision).
|
||||
- Lattice guidance:
|
||||
- Unsigned/unnotarized third-party apps default to `warn`.
|
||||
- High-risk entitlements (camera, screen capture) escalate severity unless whitelisted.
|
||||
- Waiver model similar to existing EntryTrace/Secrets: require bundle hash + Team ID to avoid broad exceptions.
|
||||
|
||||
## 6. Offline kit considerations
|
||||
- Mirror required Homebrew taps (`homebrew/core`, `homebrew/cask`) and freeze metadata per release.
|
||||
- Bundle notarization cache instructions (CRL/OCSP) so operators can prefetch without Apple connectivity.
|
||||
- Package Apple certificate chain updates (WWDR) and provide verification script to ensure validity.
|
||||
- Document disk space impacts (Homebrew cellar snapshots ~500MB per tap snapshot).
|
||||
|
||||
## 7. Testing strategy
|
||||
- Unit tests with fixture directories:
|
||||
- Sample Cellar tree with multiple formulas (bottled vs source builds).
|
||||
- Synthetic pkg receipts + BOM files.
|
||||
- `.app` bundles with varying signing states (signed/notarized/unsigned).
|
||||
- Integration tests:
|
||||
- Build macOS rootfs tarballs via CI job (runner requiring macOS) that mimic layered container conversion.
|
||||
- Verify deterministic output by re-running collectors and diffing results (CI gating).
|
||||
- Offline compliance tests:
|
||||
- Ensure rule bundles and caches load without network by running integration suite in sealed environment.
|
||||
|
||||
## 8. Dependencies & open items
|
||||
| Item | Description | Owner | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| Demand threshold | Need ≥3 qualified customer asks to justify engineering investment | Product Guild | Active (DOCS-SCANNER-BENCH-62-002) |
|
||||
| macOS rootfs fixtures | Require automation to produce macOS layer tarballs for tests | Scanner Guild | Pending design |
|
||||
| Notarization validation | Decide whether scanner performs `spctl --assess` or defers | Security Guild | TBD |
|
||||
| Entitlement taxonomy | Finalize capability grouping for Policy Engine | Policy Guild | TBD |
|
||||
|
||||
## 9. Proposed backlog entries
|
||||
| ID (proposed) | Title | Summary |
|
||||
| --- | --- | --- |
|
||||
| SCANNER-ENG-0020 | Implement Homebrew collector and fragment mapper | Parse cellar manifests, emit brew component records, integrate with Surface.FS/Validation. |
|
||||
| SCANNER-ENG-0021 | Implement pkgutil receipt collector | Parse receipts/BOM, output installer component records with provenance. |
|
||||
| SCANNER-ENG-0022 | Implement macOS bundle inspector & capability overlays | Extract plist/signing/entitlements, produce capability evidence and merge with receipts. |
|
||||
| SCANNER-ENG-0023 | Policy & Offline integration for macOS | Define predicates, CLI toggles, Offline Kit packaging, and documentation. |
|
||||
|
||||
## 10. References
|
||||
- `docs/benchmarks/scanner/deep-dives/macos.md` — competitor snapshot and roadmap summary.
|
||||
- `docs/benchmarks/scanner/windows-macos-demand.md` — demand capture log.
|
||||
- `docs/modules/scanner/design/surface-secrets.md`, `surface-fs.md`, `surface-validation.md` — surface contracts leveraged by collectors.
|
||||
|
||||
Further reading: `../../api/scanner/windows-coverage.md` (summary) and `../../api/scanner/windows-macos-summary.md` (metrics dashboard).
|
||||
|
||||
Policy readiness alignment: see `../policy/secret-leak-detection-readiness.md` (POLICY-READINESS-0001).
|
||||
|
||||
Upcoming milestone: Northwind Health Services demo on 2025-11-10 to validate notarization/entitlement outputs before final policy sign-off.
|
||||
Reference in New Issue
Block a user