b1e78fe412
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.
124 lines
7.8 KiB
Markdown
124 lines
7.8 KiB
Markdown
# 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.
|