git.stella-ops.org/docs/modules/scanner/design/macos-analyzer.md

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 ComponentRecords 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.