stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

feat: Implement vulnerability token signing and verification utilities
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
- 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
2025-11-03 10:02:29 +02:00
parent bf2bf4b395
commit b1e78fe412
215 changed files with 19441 additions and 12185 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/benchmarks/scanner/README.md Normal file
View File

@@ -0,0 +1,26 @@
# Scanner Benchmarks & Coverage Dossiers
This directory aggregates competitive analyses, deep dives, and demand signals that inform the Scanner roadmap.
## Structure
- `../../scanner-feature-comparison-*.md` — high-level feature comparisons versus Trivy, Grype, Snyk.
- `deep-dives/` — ecosystem-specific implementation deep dives (languages, OS packages, secrets, macOS, Windows, etc.).
- `scanning-gaps-stella-misses-from-competitors.md` — gap analysis with scorecards, implementation plans, and backlog references.
- `windows-macos-demand.md` — demand tracker and next actions for Windows/macOS coverage.
- `windows-macos-interview-template.md` — structured questionnaire for customer discovery.
## Quick links
- macOS: `deep-dives/macos.md`, `../../modules/scanner/design/macos-analyzer.md`.
- Windows: `deep-dives/windows.md`, `../../modules/scanner/design/windows-analyzer.md`.
- Policy readiness: `../../modules/policy/secret-leak-detection-readiness.md`, `../../modules/policy/windows-package-readiness.md`.
- API dashboards: `../../api/scanner/windows-coverage.md`, `../../api/scanner/windows-macos-summary.md`.
## Maintenance tips
- When new interview signals are logged, update `windows-macos-demand.md`, the API dashboards, and cross-link relevant design docs.
- Ensure gap scorecards reflect the latest findings and backlog IDs.
- Keep feature comparison docs aligned with deep dive updates.
## Backlog references
- Engineering: see `../../modules/scanner/TASKS.md` (SCANNER-ENG-0020..0027).
- Docs: `../../docs/TASKS.md` (DOCS-SCANNER-BENCH-62-016).
- Policy: `../../modules/policy/TASKS.md` (POLICY-READINESS-0001/0002).

48
docs/benchmarks/scanner/deep-dives/macos.md Normal file
View File

@@ -0,0 +1,48 @@
# macOS Package Ecosystem — Coverage Deep Dive
## Competitor snapshot
- **Trivy**: Official coverage tables list only Linux distributions (Alpine/Wolfi, Debian/Ubuntu, RHEL family, SUSE, Photon, Amazon, Bottlerocket). No analyzer exists for Homebrew, Mac App Store receipts, or `.app` bundles.
- **Grype**: Mirrors Syft catalogers that target Linux package managers; no matchers for Homebrew formulae, pkgutil receipts, or macOS frameworks.
- **Snyk CLI**: Container and open-source scans are routed through the SaaS backend; macOS host package analysis is not advertised or documented.
## Proposed StellaOps roadmap
See also: `../../modules/scanner/design/macos-analyzer.md` for the in-depth design brief.
1. **Homebrew cellar collector**
- Parse `/usr/local/Cellar` and `/opt/homebrew/Cellar` manifest files plus taps metadata to enumerate installed formulae/casks.
- Normalize tap origin, version, revision, and bottle source; map to `pkg:brew/{tap}/{name}@{version}` PURLs.
2. **System receipt inventory**
- Use `pkgutil --pkgs --pkg-info-plist` style parsing against `/var/db/receipts/*.bom` to capture Apple installer packages and third-party pkg receipts.
- Record CFBundleIdentifier, install timestamps, and BOM file hashes to feed deterministic provenance.
3. **Application bundle inspection**
- Scan `/Applications`, `/System/Applications`, and `/Users/*/Applications` for `.app` bundles.
- Extract Info.plist data (bundle id/version), embedded frameworks, entitlements, and code signing certificates.
4. **Policy alignment**
- Emit capability hints (network, TCC categories) for Policy Engine gating.
- Provide allow lists for signed Apple system components versus third-party apps.
5. **Offline parity**
- Mirror Homebrew tap metadata snapshots and entitlements schema inside Offline Kit.
- Package notarization certificate bundles and CRL/OCSP cache guidance for air-gapped verification.
## Detection technique comparison
| Technique | Artifacts | Merge strategy | Notes |
| --- | --- | --- | --- |
| Homebrew cellar parsing | Cellar manifests, `INSTALL_RECEIPT.json`, tap metadata | Produce per-formula component records keyed by tap + version; merge duplicates by canonical tap origin; attach bottle SHA256 for provenance. | Requires tap snapshot to ensure deterministic version resolution. |
| pkgutil receipt parsing | `/var/db/receipts/*.plist` + `.bom` files | Build component entries for Apple/third-party installer packages; merge with bundle evidence when matching CFBundleIdentifier. | Provides authoritative install-time metadata including install source. |
| `.app` bundle inspection | Info.plist, CodeResources, entitlements, embedded frameworks | Emit capability records (e.g., `tcc.camera`, `network.client`); merge with receipts when bundle id matches. | Must preserve signing chain and team identifier; store hash of CodeDirectory. |
| Launch daemon/service mapping | `/Library/LaunchDaemons`, `/Library/LaunchAgents`, `launchctl print` exports | (Planned) Attach runtime usage hints for Policy Engine and EntryTrace cross-module alignment. | Helps differentiate dormant apps from active services. |
| Competitor baseline | — | No competitor evidence to merge; Trivy/Grype/Snyk lack macOS analyzers. | Presents differentiation opportunity once demand justifies investment. |
## Backlog / coordination
- Keep demand capture in `docs/benchmarks/scanner/windows-macos-demand.md` up to date; once thresholds are met, open:
- `SCANNER-ENG-00xx` (macOS cellar/receipt analyzer design spike).
- `DOCS-SCANNER-BENCH-62-002` (this doc’s parent task) — exit criteria: demand summary + design scope recommendation.
- Policy task to define macOS capability predicates (entitlements, notarization state).
- Align with Offline Kit guild on notarization/CRL packaging and tap mirroring strategy.
## Open design questions
| Topic | Question | Owner |
| --- | --- | --- |
| Notarization verification | Should scanner verify Apple notarization tickets or delegate to Policy Engine? | Security Guild |
| Entitlement taxonomy | How granular should capability predicates be (per entitlement vs grouped categories)? | Policy Guild |
| User-space scope | Do we scan per-user Homebrew installs and sandboxed app containers? | Scanner Guild |
| Performance | Do we cache receipts/bundle metadata between scans given large `.app` trees? | Scanner + Surface Guilds |

3
docs/benchmarks/scanner/deep-dives/matrix.md
View File

@@ -13,7 +13,8 @@
| Rust | Binary heuristics | StellaOps | Fingerprint coverage incomplete for niche toolchains. | Unmatched binaries ignored; no fallback crates. | No fallback for binaries lacking Cargo metadata; depends on Syft crate data. | No Rust/Cargo support in CLI plugins. | Execute Rust fingerprint plan (`scanning-gaps-stella-misses-from-competitors.md`) and update analyzer backlog. | [rust.md](rust.md) |
| OS packages | Linux distro coverage & provenance | Tie (StellaOps / Grype) | Requires RustFS/object store deployment for full replay; Windows packaging still out of scope. | No per-layer fragment storage; provenance limited; Windows support likewise minimal. | No per-layer provenance; shares Syft catalog and Anchore DB only. | Snyk Container scanning depends on SaaS API; no per-layer provenance. | Document RustFS dependency & offline alternatives in ops backlog; evaluate Windows pkg roadmap. | [os-packages.md](os-packages.md) |
| OS packages | Linux flavor support (Alpine/Wolfi/Chainguard, Debian/Ubuntu, RHEL/Alma/Rocky, SUSE, Amazon/Bottlerocket) | Tie (Trivy / Snyk) | Windows/macOS package ecosystems still pending. | Coverage relies on package DB adapters; per-distro nuances (e.g., Chainguard signatures) not attested. | Supports major Linux feeds but no Windows/macOS package analyzers. | Supports documented distro list via Snyk Container but requires cloud connectivity. | Track demand for non-Linux package analyzers; document distro mapping in os-packages deep dive. | [os-packages.md](os-packages.md) |
| OS packages | Windows/macOS coverage | — | No Windows/macOS analyzer; backlog item for offline parity. | Coverage docs enumerate Linux distributions only; Windows/macOS packages unsupported. | Syft matchers focus on Linux ecosystems; Windows/macOS packages unsupported. | Coverage depends on Snyk’s SaaS service; no offline assurance for Windows/macOS packages. | Capture demand for Windows/macOS analyzers (see `docs/benchmarks/scanner/windows-macos-demand.md`) and scope feasibility. | [os-packages.md](os-packages.md) |
| macOS packages | Coverage & provenance | StellaOps (future) | macOS analyzer not implemented yet; design captured in deep dive. | No macOS analyzers (Linux only). | No macOS analyzers (Linux only). | No macOS host scanning; SaaS container focus only. | Advance demand capture (`windows-macos-demand.md`); open macOS design spike once threshold met. | [macos.md](macos.md) |
| Windows packages | Coverage & provenance | StellaOps (future) | Windows analyzer family not yet implemented; design brief in progress. | No Windows coverage beyond containers. | Syft/Grype lack Windows collectors; Anchore feeds Linux-only. | SaaS host scanning only; no offline or deterministic evidence. | Capture demand signals; scope Windows analyzer spike when thresholds met. | [windows.md](windows.md) |
| Secrets | Handling posture | StellaOps | No leak scanning by design; Surface.Secrets manages retrieval/rotation with tenant scopes. | Leak detections lack governance hooks; operators must track rule updates. | No secret management abstraction; credentials configured manually. | Requires SaaS backend for secret scanning; no offline posture or secret storage guidance. | Document governance patterns for Surface.Secrets users and recommended companion tooling. | [secrets.md](secrets.md) |
| Secrets | Detection technique | Trivy | No content scanning; relies on Surface.Secrets integrations. | Regex/entropy detectors with configurable allow/deny lists across files/bytecode. | No detector available; Syft/Grype skip leak scanning entirely. | Snyk Code/Snyk secrets require uploading code to SaaS; offline detection unavailable. | Execute secrets leak detection plan (`scanning-gaps-stella-misses-from-competitors.md`) and plan policy templates. | [secrets.md](secrets.md) |
| EntryTrace | Runtime command resolution | StellaOps | Shell/language launcher coverage needs continuous tuning. | Not supported. | Not available. | Not available. | Maintain EntryTrace plan (`scanning-gaps-stella-misses-from-competitors.md`) and backlog cadence. | — |

8
docs/benchmarks/scanner/deep-dives/os-packages.md
View File

@@ -29,6 +29,14 @@
- **Metadata depth**: StellaOps records extensive vendor metadata and file evidence for replay; Trivy, Snyk, and Grype focus on match-relevant fields from their feeds.
- **Provenance**: StellaOps’ outputs integrate directly with attestation/diff pipelines, while Trivy, Snyk, and Grype assume downstream tools consume package lists without replay requirements.
### Detection technique comparison
| Tool | Detection technique(s) | Merge / result handling | Notes |
| --- | --- | --- | --- |
| **StellaOps** | Deterministic DB parsing via `StellaOps.Scanner.Analyzers.OS.(Apk|Dpkg|Rpm)`; fragment mapping via `OsComponentMapper`; provenance persisted in Surface.FS. | Analyzer outputs become `LayerComponentFragment`s stored in `ScanAnalysisStore`; SBOM assembly composes inventory/usage views while preserving layer digests and metadata for diffs + attestations. | Supports offline replay, DSSE binding, and policy joins with Concelier advisories. |
| **Trivy** | Layer walkers + distro parsers in `pkg/fanal/analyzer/pkg/*`; optional manifest enrichment using vendor feeds. | Packages aggregated per artifact; provenance/layer context not persisted, leaving downstream tooling to interpret results. | Coverage matrix enumerated in `docs/docs/coverage/os/*.md`. |
| **Grype** | Syft catalogers + matchers in `grype/matcher/{apk,dpkg,rpm}` leveraging Anchore feeds. | Matchers run against Syft inventory and Anchore DB; no layer fragments retained. | Determinism depends on feed snapshots. |
| **Snyk** | Container scans upload image metadata to SaaS for analysis. | Results surfaced via SaaS dashboards/API; no local merge or provenance data. | Requires network connectivity; offline unsupported. |
### References
- [t1] `/tmp/trivy-src/docs/docs/coverage/os/index.md`
- [s1] `/tmp/snyk-cli/README.md`

10
docs/benchmarks/scanner/deep-dives/secrets.md
View File

@@ -1,6 +1,7 @@
# Secret Handling
## StellaOps approach
- Detailed Policy/Security briefing: `../../modules/policy/secret-leak-detection-readiness.md`.
- Secrets treated as operational inputs delivered through Surface.Secrets (`src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets` and documented in `docs/modules/scanner/design/surface-secrets.md`).
- Providers support Kubernetes Secrets, file-based bundles, and inline definitions; configuration resolved via Surface.Env with validation gates from Surface.Validation.
- Secret placeholders (`secret://type/name`) are resolved before analyzers execute, with results wrapped in secure handles and rotation metadata checked at startup.
@@ -26,6 +27,15 @@
- **Workflow**: StellaOps’ secret lifecycle is pre-scan configuration; Trivy and Snyk analyse content at scan time (Snyk requiring SaaS connectivity), and Grype requires external tooling for leak detection.
- **Determinism**: StellaOps avoids non-deterministic leak scans; Trivy and Snyk’s detectors may evolve with rule updates; Grype remains deterministic by not attempting secret discovery.
### Detection technique comparison
| Tool | Detection technique(s) | Merge / result handling | Notes |
| --- | --- | --- | --- |
| **StellaOps (current)** | `Surface.Secrets` providers fetch credentials at runtime; no leak scanning today. | Secrets resolve to opaque handles stored in scan metadata; no SBOM entries emitted. | Deterministic and explainable; avoids exposing payloads. |
| **StellaOps (planned)** | `StellaOps.Scanner.Analyzers.Secrets` plug-in executing signed rule bundles. | Findings inserted into `ScanAnalysisStore` as `secret.leak` evidence; Policy Engine merges with component context and lattice scores. | Rules packaged offline; CLI/reporting masks payloads while surfacing rule IDs. |
| **Trivy** | Regex + entropy detectors under `pkg/fanal/secret` (configurable via `trivy-secret.yaml`). | Detectors aggregate per file; results exported alongside vulnerability findings without provenance binding. | Ships built-in rule sets; users can add allow/block lists. |
| **Snyk** | Snyk Code SaaS classifiers invoked by CLI plugin (`src/lib/plugins/sast`). | Source uploaded to SaaS; issues returned with severity + remediation; no offline merge with SBOM data. | Requires authenticated cloud access; rules evolve server-side. |
| **Grype** | None (focuses on vulnerability matching). | — | Operators must integrate separate tooling for leak detection. |
### References
- [s1] `/tmp/snyk-cli/src/lib/plugins/sast`
- [s2] `/tmp/snyk-cli/README.md`

47
docs/benchmarks/scanner/deep-dives/windows.md Normal file
View File

@@ -0,0 +1,47 @@
# Windows Package Ecosystem — Coverage Deep Dive
## Competitor snapshot
- **Trivy**: No analyzers for Windows Installer (MSI), WinSxS manifests, or Chocolatey feeds. Official coverage tables enumerate Linux distributions only.
- **Grype**: Syft catalogers focus on Linux ecosystems; no Windows package collectors or matchers are available.
- **Snyk CLI**: Container/open-source scans rely on SaaS services; Windows host-level package scanning is not advertised. Snyk AppRisk references depend on SaaS integrations rather than offline collectors.
## Proposed StellaOps roadmap
In-depth design detail lives in `../../modules/scanner/design/windows-analyzer.md`.
1. **MSI/WinSxS collector**
- Traverse `Windows/WinSxS/Manifests` and `Windows/Installer` to harvest component manifests, linking to installed products via the installer database.
- Parse MSI tables (Product, Component, File) to emit authoritative component records with product codes, upgrade codes, and install context.
2. **Chocolatey/NuGet-based packages**
- Inspect `ProgramData/Chocolatey/lib` and `ProgramData/Chocolatey/packages.config` for package metadata, including embedded nuspec files and checksums.
- Resolve package sources and cache feed metadata to support offline replay.
3. **Registry-backed inventory**
- Query `HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall` and equivalent Wow6432Node path to capture legacy installers (EXE/PDB) with version/signature hints.
- Record install source, publisher, and install location for cross-reference with filesystem collectors.
4. **Capability signals**
- Detect installed services (`System32/config/SYSTEM` registry hive), scheduled tasks, and driver packages to feed Policy Engine capability predicates.
- Capture Authenticode signatures and catalog (.cat) references to support trust enforcement.
5. **Offline parity**
- Package MSI schema definitions, Chocolatey feed snapshots, and Windows update catalog indexes into Offline Kit bundles.
- Provide hashing guidance for large binaries to avoid excessive Offline Kit growth (use external CAS references where possible).
## Detection technique comparison
| Technique | Artifacts | Merge strategy | Notes |
| --- | --- | --- | --- |
| MSI database parsing | `Windows/Installer/*.msi` database tables (Product, Component, File) | Emit component records keyed by ProductCode/ComponentCode; merge with WinSxS manifests using file hashes. | Requires custom MSI reader (Jet/COM-free) compatible with offline bundles. |
| WinSxS manifest enumeration | `Windows/WinSxS/Manifests/*.manifest` | Map assemblies to catalog signatures and MSP patches; merge with MSI output for provenance. | Provides side-by-side assembly version info and language resources. |
| Chocolatey package inspection | `ProgramData/Chocolatey/lib/*/tools` & nuspec metadata | Produce package records with source feed URL, checksum, install scripts. | Feed metadata snapshot required to resolve dependencies offline. |
| Registry uninstall keys | `HKLM/HKCU ... /Uninstall/*` | Fill gaps for legacy installers (non-MSI); merge by install path and display name with file system evidence. | Use hive exports during scan to avoid registry API dependencies. |
| Service/driver mapping | `System32/config/SYSTEM` hive, `System32/DriverStore/FileRepository` | Generate capability overlays (services, drivers) for Policy Engine gating. | Helps differentiate drivers requiring elevated scrutiny (e.g., kernel-mode). |
| Competitor baseline | — | No competitor tool offers deterministic Windows package coverage with offline support. | Opportunity to differentiate once demand justifies scope. |
## Backlog / coordination
- Follow demand capture in `docs/benchmarks/scanner/windows-macos-demand.md`. Once Windows signals meet thresholds, open engineering backlog (see proposed IDs below).
- Coordinate with Offline Kit guild on distributing MSI schema, Chocolatey feed snapshots, and driver catalog signatures.
- Engage Policy guild on required predicates (Authenticode trust, driver risk classes, service start modes).
## Open design questions
| Topic | Question | Owner |
| --- | --- | --- |
| MSI parsing library | Build custom reader or embed open-source MSI parser? Must be AGPL-compatible and offline-ready. | Scanner Guild |
| Driver risk classification | Should Policy Engine treat kernel-mode drivers differently by default? | Policy Guild |
| Authenticodes & catalogs | Where do we verify signature/certificate revocation (scanner vs policy)? | Security Guild |
| Registry access | Will scanner access registry hives directly or require pre-extracted exports? | Scanner + Ops Guild |

136
docs/benchmarks/scanner/scanning-gaps-stella-misses-from-competitors.md
View File

@@ -232,12 +232,108 @@
- **Policy considerations**: Policies would need repository allowlists, signing requirements, and OS-specific mitigations; defer concrete templates until design spike completes.
- **Next actions**: Execute tasks DOCS-SCANNER-BENCH-62-002/003/004/005/006 as demand signals accrue; only open engineering backlog after demand review approves scope expansion.
### Implementation details
- **StellaOps**:
- Linux analyzers live under `StellaOps.Scanner.Analyzers.OS.(Apk|Dpkg|Rpm)` and inherit from `OsPackageAnalyzerBase`, which normalises package metadata, file evidence, and vendor fields before persisting content-addressed fragments via Surface.FS.
- Analyzer results are converted to `LayerComponentFragment`s by `OsComponentMapper` and cached inside the worker `ScanAnalysisStore`; downstream SBOM assembly keeps layer digests and provenance so usage/inventory views can be replayed deterministically.
- Export Center binds OS fragments to DSSE attestations through Signer/Attestor so operators can prove provenance for every package list in offline bundles.
- **Trivy**:
- Package analyzers under `pkg/fanal/analyzer/pkg/(apk|dpkg|rpm)` walk layer file systems and emit `types.Package` results; the upstream coverage matrix in `docs/docs/coverage/os/*.md` drives which distro manifests and feeds ship with Trivy releases.
- Results are flattened per artifact, leaving layer attribution to Syft-style catalog walks; provenance and diffing are delegated to downstream tooling.
- **Grype**:
- Delegates cataloguing to Syft, then applies matchers in `grype/matcher/{apk,dpkg,rpm}` that resolve distro namespaces and fix statuses using Anchore feeds.
- Evidence is matched at scan time without long-lived fragments, so reproducibility depends on feed snapshots rather than packaged artifacts.
- **Snyk**:
- `snyk container test` uploads image metadata to Snyk SaaS; coverage is dictated by the hosted service and cannot run offline.
- No layer-aware evidence is returned; operators rely on SaaS reports for package presence and risk.
### Detection techniques
| Technique | Artifacts | Analyzer / Module | Merge strategy |
|-----------|-----------|-------------------|----------------|
| Layer package DB parsing | apk, dpkg, rpm status/databases per layer | StellaOps.Scanner.Analyzers.OS.* with RustFS CAS | Produces per-layer fragments keyed by layer digest; composed into inventory/usage SBOM with provenance pointers. |
| Manifest + attestation binding | Distro manifest attestations, vendor signatures | Export Center + Signer/Attestor hand-off | Binds package fragments to DSSE attestations; policy consumes provenance metadata for trust weighting. |
| External SBOM import (interim) | Third-party SBOMs for Windows/macOS | Scanner SBOM import API (planned) | Imports produce declared-only entries flagged for policy review until native analyzers exist. |
| Layer package DB parsing | apk, dpkg, rpm status/databases per layer | `StellaOps.Scanner.Analyzers.OS.(Apk|Dpkg|Rpm)` + Surface.FS | Emits `OSPackageRecord` fragments tagged with layer digest; `OsComponentMapper` writes `LayerComponentFragment`s that SBOM assembly uses to build inventory/usage views with provenance. |
| Manifest + attestation binding | Distro manifest attestations, vendor signatures | Export Center + Signer/Attestor hand-off | Couples OS fragments with DSSE/Rekor proofs; Policy Engine verifies signatures before promotion gates. |
| Linux distro enrichment | Vendor advisory feeds, package-to-CVE mapping | Concelier + Policy Engine | Concelier ingests advisory metadata; Policy joins advisories with package fragments to produce lattice-scored findings. |
| External SBOM import (interim) | Third-party SBOMs for Windows/macOS | Scanner SBOM import API (planned) | Declared-only entries are merged with runtime evidence; policy downgrades unmatched declarations until native analyzers exist. |
## macOS package coverage (Trivy, Grype, Snyk)
### Scorecard
| Dimension | Score (1-5) | Notes |
|-----------|-------------|-------|
| Customer demand | 2 | macOS coverage requests surface intermittently; demand capture ongoing via `windows-macos-demand.md`. |
| Competitive risk | 2 | Competitors lack macOS analyzers today, but roadmap announcements could erode differentiation quickly. |
| Engineering effort | 4 | Requires new collectors (Homebrew, pkgutil receipts, `.app` bundles) plus Offline Kit tap mirroring. |
| Policy/config impact | 4 | Policies must reason over entitlements, notarization, and signed bundle provenance. |
| Offline/air-gap impact | 4 | Tap metadata, notarization caches, and entitlement schemas must ship offline. |
- **Competitor capability**: None of Trivy, Grype, or Snyk provide macOS host/package coverage; their documentation lists Linux-only ecosystems.
- **StellaOps gap**: No macOS analyzers exist; design work is captured in `docs/benchmarks/scanner/deep-dives/macos.md` but implementation/backlog stories are not yet opened.
- **Proposed plan**:
1. Finalise demand assessment (DOCS-SCANNER-BENCH-62-002) using customer interviews, sales telemetry, and support tags.
2. Scope macOS analyzer design spike covering Homebrew cellar parsing, pkgutil receipt ingestion, and `.app` bundle inspection; include entitlements/notarization strategy.
3. Define Policy Engine predicates for entitlements, notarization status, bundle signing chain, and tenant allow lists.
4. Coordinate with Offline Kit guild on mirroring tap metadata, notarization caches, and CRL/OCSP content for air-gapped operation.
- **Milestones**: Northwind Health Services demo (2025-11-10) doubles as POLICY-READINESS-0001 workshop to finalise masking/telemetry defaults before spike approval.
- **Policy considerations**: Need predicates for `macos.entitlement`, `macos.notarized`, `macos.bundle.teamId`, and severity rules for unsigned or unnotarized software; waivers should bind to bundle hash + signer.
- **Next actions**: Keep `windows-macos-demand.md` updated, prepare design brief once threshold met, and log engineering backlog items (SCANNER-ENG-00xx) for macOS collectors and policy integration.
### Implementation details
- **Design references**: `docs/benchmarks/scanner/deep-dives/macos.md` captures proposed collectors (Homebrew, receipts, bundles) and open questions for Security/Policy guilds.
- **Collector outline**:
- Homebrew collector enumerates Cellar manifests under `/usr/local/Cellar` and `/opt/homebrew/Cellar`, mapping taps to PURLs and retaining bottle SHA256 for provenance.
- pkgutil collector parses `/var/db/receipts/*.plist` and `.bom` files to record installer package metadata with deterministic hashes.
- Bundle inspector walks `.app` directories, extracting Info.plist, entitlements, embedded frameworks, and code signing chains.
- **Merge strategy**: Collectors will emit component fragments keyed by bundle/tap identifiers; planned aggregator merges receipts and cellular data where identifiers match, tagging capabilities for Policy Engine.
- **Offline requirements**: Bundle signed rule packs (tap metadata snapshots, entitlements schema) with Offline Kit; ensure notarization cache instructions are documented.
### Detection techniques
| Technique | Artifacts | Analyzer / Module | Merge strategy |
|-----------|-----------|-------------------|----------------|
| Homebrew cellar parsing (planned) | Cellar manifests, `INSTALL_RECEIPT.json`, tap metadata | Planned `StellaOps.Scanner.Analyzers.OS.Mac.Homebrew` | Emits component records keyed by tap + version; merges duplicates and attaches bottle hashes for provenance. |
| pkgutil receipt parsing (planned) | `/var/db/receipts/*.plist` and `.bom` | Planned `StellaOps.Scanner.Analyzers.OS.Mac.Receipts` | Records installer packages with bundle identifiers; merges with bundle evidence when identifiers align. |
| `.app` bundle inspection (planned) | Info.plist, CodeResources, entitlements, signing certs | Planned `StellaOps.Scanner.Analyzers.OS.Mac.Bundles` | Produces capability evidence (entitlements, hardened runtime) and links to receipts/Homebrew entries via bundle id. |
| Launch agent/daemon analysis (planned) | `/Library/Launch*` manifests, `launchctl` exports | Planned runtime usage mapper | Augments EntryTrace usage hints to distinguish active services. |
| Competitor baseline | — | Trivy/Grype/Snyk | No macOS host analyzers; coverage limited to Linux/container contexts. |
## Windows package coverage (Trivy, Grype, Snyk)
### Scorecard
| Dimension | Score (1-5) | Notes |
|-----------|-------------|-------|
| Customer demand | 3 | Windows Server/container adopters continue to request evidence parity; demand captured via `windows-macos-demand.md`. |
| Competitive risk | 2 | Competitors lack Windows analyzers today but could narrow the gap with roadmap announcements. |
| Engineering effort | 5 | Requires MSI/WinSxS parsers, registry collectors, Chocolatey handling, and extensive Offline Kit work. |
| Policy/config impact | 4 | Policies must interpret Authenticode trust, driver/service posture, and legacy installer artefacts. |
| Offline/air-gap impact | 5 | Need to package MSI schemas, feed snapshots, and certificate bundles; storage overhead is significant. |
- **Competitor capability**: Trivy, Grype, and Snyk do not ship Windows host analyzers; tooling focuses on Linux ecosystems and SaaS flows.
- **StellaOps gap**: No Windows analyzers exist yet; design outline under `docs/benchmarks/scanner/deep-dives/windows.md`.
- **Proposed plan**:
1. Complete demand validation and prioritisation (DOCS-SCANNER-BENCH-62-002) alongside macOS signals.
2. Execute engineering spike covering MSI/WinSxS parsing, Chocolatey inventory, and registry-based fallbacks.
3. Define Policy Engine predicates for Authenticode, driver risk, service start mode, and Chocolatey provenance.
4. Coordinate Offline Kit packaging strategy for MSI schemas, feed snapshots, and certificate revocation caches.
- **Policy considerations**: Introduce predicates such as `windows.package.signed(teamId?)`, `windows.driver.kernelMode`, `windows.service.startType`, and waivers tied to product code + signature thumbprint.
- **Next actions**: Maintain demand tracker, execute DOCS-SCANNER-BENCH-62-016, refine `docs/modules/scanner/design/windows-analyzer.md`, and open SCANNER-ENG-0024..0027 backlog tickets for collector and policy work once demand threshold is confirmed.
- **Milestones**: POLICY-READINESS-0002 Authenticode/feed decision due 2025-11-07 (FinSecure PCI blocker) gates Windows analyzer spikes.
### Implementation details
- **Design references**: `docs/benchmarks/scanner/deep-dives/windows.md`, `docs/modules/scanner/design/windows-analyzer.md`, `docs/api/scanner/windows-coverage.md`.
- **Policy readiness**: see `docs/modules/policy/windows-package-readiness.md` for predicate requirements, waiver model, and offline guidance.
- **Collector outline**:
- MSI/WinSxS collector to parse installer databases/manifests and correlate via file hashes.
- Chocolatey collector to read nuspec metadata and install scripts, retaining feed provenance.
- Registry collector to harvest uninstall/service keys, linking to filesystem artefacts and signatures.
- **Merge strategy**: Planned `WindowsComponentMapper` merges MSI, WinSxS, Chocolatey, and registry evidence into unified fragments with provenance metadata; capability overlays capture services/drivers.
- **Offline requirements**: Bundle MSI schema definitions, Chocolatey feed snapshots, Windows Update catalog hashes, and certificate chains; document cache priming steps for air-gapped environments.
### Detection techniques
| Technique | Artifacts | Analyzer / Module | Merge strategy |
|-----------|-----------|-------------------|----------------|
| MSI database parsing (planned) | `Windows/Installer/*.msi` Product/Component/File tables | Planned `StellaOps.Scanner.Analyzers.OS.Windows.Msi` | Emits component records keyed by product/component codes; merges with WinSxS manifests via file hashes. |
| WinSxS manifest parsing (planned) | `Windows/WinSxS/Manifests/*.manifest`, catalog files | Planned `StellaOps.Scanner.Analyzers.OS.Windows.WinSxS` | Maps assemblies to catalogs and MSP patches; merges with MSI output for provenance. |
| Chocolatey package parsing (planned) | `ProgramData/Chocolatey/lib/*`, nuspec metadata | Planned `StellaOps.Scanner.Analyzers.OS.Windows.Choco` | Records package evidence with feed provenance; merges with registry uninstall data. |
| Registry fallback (planned) | Exported uninstall/service hives | Planned `StellaOps.Scanner.Analyzers.OS.Windows.Registry` | Fills gaps for legacy installers and services; merges evidence by install path/signature. |
| Service/driver capability mapping (planned) | SYSTEM hive, DriverStore manifest | Planned capability overlay | Emits runtime capability records (drivers/services) for Policy Engine gating. |
| Competitor baseline | — | Trivy/Grype/Snyk | No Windows host analyzers; operators depend on external tooling. |
## Secrets leak detection (Trivy, Snyk)
### Scorecard
@@ -258,14 +354,29 @@
4. Offer CLI verb (`stella secrets scan`) and integration into existing scan workflows behind an opt-in flag.
5. Expose explain traces detailing rule IDs, masked snippets, and remediation guidance while upholding privacy constraints.
- **Policy considerations**: Deliver policy templates for severity gating, rule packs per tenant, and privacy controls; lattice logic should discount low-confidence matches.
- **Next actions**: open analyzer/CLI backlog work, coordinate with Docs Guild on policy templates, and bundle signed rule packs for Offline Kit distribution.
- **Next actions**: Track execution via SCANNER-ENG-0007 (design/implementation) and DOCS-SCANNER-BENCH-62-007 (policy/docs); bundle signed rule packs for Offline Kit distribution once analyzer stories land.
### Implementation details
- **StellaOps**:
- Operational secret retrieval flows through `Surface.Secrets` providers (Kubernetes, file bundle, inline) with validation policies enforced by `Surface.Validation`; handles remain opaque to analyzers.
- Planned `StellaOps.Scanner.Analyzers.Secrets` plug-in will execute deterministic rule bundles signed by the Export Center signing stack; findings land in `ScanAnalysisStore` alongside component fragments.
- Policy Engine will ingest `secret.leak` evidence with lattice hints (`confidence`, `rule.id`, `masking.applied`) so tenants can tune severities and approvals.
- **Trivy**:
- Secret detection is implemented in `pkg/fanal/secret` with detectors combining regex and entropy heuristics; rules merge into `Result` objects per file with severity weighting.
- Configuration is provided via `trivy-secret.yaml`, enabling per-rule enable/disable and allow lists.
- **Snyk**:
- CLI delegates to Snyk Code (`src/lib/plugins/sast`) which uploads source or image contents to SaaS for analysis; results stream back as issue JSON with remediation tips.
- Offline execution is unsupported; rule updates ship server-side.
- **Grype**:
- No leak detection analyzer; secrets are only used for registry authentication options.
### Detection techniques
| Technique | Artifacts | Analyzer / Module | Merge strategy |
|-----------|-----------|-------------------|----------------|
| Operational secret retrieval | secret:// references resolved via Surface.Secrets providers | Surface.Secrets, Surface.Validation | Injects secrets at runtime; no SBOM entry created; policy ensures provenance of retrieved credentials. |
| Deterministic leak detection (planned) | File content, archives, bytecode | StellaOps.Scanner.Analyzers.Secrets (planned) | Emits secret.leak evidence with masked snippets; Policy Engine merges with package evidence using VEX gating. |
| Competitor leak scanning | Regex/entropy rulesets (Trivy pkg/fanal/secret), Snyk Code SaaS service | Trivy secret analyzer, Snyk Code API | Findings remain separate from SBOM data; StellaOps will map to policy evidence types once analyzer ships. |
| Operational secret retrieval | `secret://` references resolved via `Surface.Secrets` providers | Surface.Secrets, Surface.Validation | Injects handles at runtime only; provenance recorded in scan metadata, nothing added to SBOM inventory. |
| Deterministic leak detection (planned) | File contents, archives, bytecode, container layers | `StellaOps.Scanner.Analyzers.Secrets` plug-in | Produces `secret.leak` records stored in `ScanAnalysisStore`; Policy Engine correlates with component metadata for context-aware enforcement. |
| Policy gating and reporting | Secret evidence + policy templates | Policy Engine, CLI/Export Center | Lattice scores combine confidence + severity; CLI/report output masks payloads while referencing rule IDs for explainability. |
| Competitor leak scanning | Regex/entropy rule sets, SaaS classifiers | Trivy `pkg/fanal/secret`; Snyk Code service | Trivy merges detectors per file; Snyk relies on SaaS analysis; neither binds results to SBOM evidence or deterministic attestations. |
## EntryTrace runtime command resolution (Trivy, Grype, Snyk)
### Scorecard
@@ -314,12 +425,23 @@
- **Policy considerations**: Provide policy predicates for attestation presence, Rekor inclusion, and proof expiry to enforce promotion gates.
- **Next actions**: Track via DOCS-SCANNER-BENCH-62-015 and SCANNER-ENG-0015 for playbook plus tooling updates.
### Implementation details
- **StellaOps**:
- `StellaOps.Signer` generates DSSE envelopes for SBOMs/reports using PoE-scoped keys and forwards them to `StellaOps.Attestor`, which handles Rekor v2 submissions with retries and proof caching.
- Export Center profiles bundle DSSE payloads, Rekor inclusion proofs, and any external attestations into offline-ready archives; CLI and Policy Engine verify proofs before release.
- Notify + Scanner.WebService emit attestation health telemetry so operators can quickly spot and remediate failed Rekor submissions.
- **Trivy / Grype / Snyk**:
- Trivy supports optional Cosign signing but leaves Rekor submission manual; proofs are not bundled with scanner outputs.
- Grype leans on Syft for SBOM export and does not sign outputs.
- Snyk Container/Snyk CLI rely on SaaS-managed signing and do not expose DSSE workflows or offline proof packaging.
### Detection techniques
| Technique | Artifacts | Analyzer / Module | Merge strategy |
|-----------|-----------|-------------------|----------------|
| SBOM emission | CycloneDX/SPDX payloads per scan | Scanner emit pipelines | Generates inventory/usage BOMs stored with CAS hashes for attestation. |
| DSSE signing | DSSE bundles, signing keys | StellaOps.Signer + StellaOps.Attestor | Signs SBOM/report metadata, forwards to Rekor v2, records proof identifiers. |
| Rekor proof packaging | Rekor inclusion proofs, bundle metadata | Export Center attestation packager | Bundles proofs into Offline Kit/export artifacts; Policy verifies before release. |
| Policy enforcement | Attestation & proof evidence | Policy Engine, Scheduler gates | Policies require successful DSSE/Rekor entries before promotion; Scheduler blocks exports lacking proofs. |
| Competitor approach | CLI or SaaS-managed signing | Trivy Cosign integration, Snyk SaaS, Grype none | Operators must integrate manually; no default policy enforcement. |
## Ruby analyzer parity (Trivy, Grype, Snyk)

16
docs/benchmarks/scanner/windows-macos-demand.md
View File

@@ -10,8 +10,24 @@
2. **Sales & SE feedback loop** – capture any RFP items referencing Windows/macOS scanning and log them in the Scanner guild tracker (SCANNER-ANALYZERS-OS-*).
3. **Support telemetry** – review ticket tags for “windows”, “macos”, “dotnet framework” to quantify inbound demand.
4. **Community landscape** – monitor Trivy/Grype/Snyk release notes for Windows/macOS announcements; update this note and the feature matrix when competitors change posture.
5. **Interview discipline** – use the structured questionnaire in `windows-macos-interview-template.md` to ensure consistent scoring and capture follow-up actions.
## Signals log — macOS
| Date (YYYY-MM-DD) | Source / Account | Use case | Demand strength (1-5) | Notes / follow-up |
|-------------------|------------------|----------|------------------------|-------------------|
| 2025-11-03 | Northwind Health Services (NA) | macOS CI runners require notarization evidence for release sign-off | 4 | Demo deterministic bundle inspection w/ Product on 2025-11-10; capture entitlements policy requirements. |
## Signals log — Windows
| Date (YYYY-MM-DD) | Source / Account | Use case | Demand strength (1-5) | Notes / follow-up |
|-------------------|------------------|----------|------------------------|-------------------|
| 2025-11-03 | FinSecure Corp (NA) | Windows Server 2019 images need MSI/WinSxS SBOM + signed driver attestations for PCI audit | 5 | Blocking go-live; Security guild to confirm Authenticode posture (POLICY-READINESS-0002) by 2025-11-07. |
## Next actions
- Coordinate with Product Marketing to add Windows/macOS discovery prompts into upcoming customer advisory sessions (target: Sprint 132 intake).
- Instrument the scanner roadmap intake form with explicit checkboxes for Windows/macOS package ecosystems.
- If three or more qualified customers flag Windows/macOS coverage as a blocking requirement, open a design spike under the Scanner Analyzer Guild with scope/time estimates and Offline Kit considerations.
- Keep the macOS deep dive (`docs/benchmarks/scanner/deep-dives/macos.md`) in sync with demand findings so engineering can move from design sketch to formal backlog when thresholds are met.
- Update the Windows deep dive (`docs/benchmarks/scanner/deep-dives/windows.md`) and associated design briefs (`docs/modules/scanner/design/windows-analyzer.md`) as new signals arrive.
- Refresh API dashboards (`docs/api/scanner/windows-macos-summary.md`, `docs/api/scanner/windows-coverage.md`) after each update to keep Product and Field teams aligned.
- Drive POLICY-READINESS-0002 Authenticode/feed decision by 2025-11-07 (FinSecure PCI blocker); log outcome in dashboards and design briefs.
- Prepare POLICY-READINESS-0001 workshop aligned with Northwind demo on 2025-11-10, updating policy briefs with masking/telemetry decisions.

50
docs/benchmarks/scanner/windows-macos-interview-template.md Normal file
View File

@@ -0,0 +1,50 @@
# Windows / macOS Analyzer Demand — Interview Template
Use this template during customer interviews, SE discovery calls, or product advisory meetings. Copy the table into your meeting notes and fill in the responses. Summaries should be pushed back into `windows-macos-demand.md`.
## Interview metadata
| Field | Notes |
| --- | --- |
| Date | `YYYY-MM-DD` |
| Interviewer(s) | |
| Customer / Account | |
| Participant roles | (e.g., platform lead, security architect) |
| Workload context | (container images, VMs, desktop fleets, CI pipelines, etc.) |
## Current state
1. **Operating systems in scope**
- Which Windows or macOS versions/images are mission critical?
- Container vs VM vs bare-metal distribution?
2. **Existing tooling**
- What scanners or inventory tools are used today (e.g., SCCM, Tanium, Trivy, Snyk, custom scripts)?
- Pain points / gaps they experience (offline support, provenance, coverage, explainability).
3. **Regulatory / compliance drivers**
- Any specific frameworks (PCI, FedRAMP, DISA, internal policies) mandating Windows/macOS SBOM or attestation?
## Desired capabilities (score 1–5 per feature)
| Capability | Score | Notes |
| --- | --- | --- |
| MSI / WinSxS package inventory | | |
| Chocolatey / third-party feed tracking | | |
| macOS Homebrew / pkgutil receipts | | |
| `.app` bundle inspection (signing, entitlements) | | |
| Driver / service posture | | |
| Authenticode / notarization verification | | |
| Offline/air-gap parity | | |
| Policy integration (e.g., block unsigned driver) | | |
## Operational requirements
- **Offline expectations**: Do they require artefact mirroring? Which feeds?
- **Performance**: Time budget for scans? Incremental vs full?
- **Evidence formats**: Preferred SBOM types, attestation needs, API endpoints.
- **Secrets / credentials**: Any constraints for registry/hive exports or feed mirrors?
## Success metrics
- How will the customer judge success? (e.g., number of workloads covered, audit findings reduced, ability to prove provenance).
- Timeline expectations for pilot vs GA?
## Follow-up actions
- What next steps were promised (POC, roadmap update, integration with other guilds)?
- Owners + due dates.
> After the interview: convert highlights into a concise row in `windows-macos-demand.md` and, if needed, create Jira/backlog items for SCANNER-ENG-0020..0027 or DOCS-SCANNER-BENCH-62-016 with the captured context.