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
48
docs/benchmarks/scanner/deep-dives/macos.md
Normal file
48
docs/benchmarks/scanner/deep-dives/macos.md
Normal 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 |
|
||||
@@ -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. | — |
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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
47
docs/benchmarks/scanner/deep-dives/windows.md
Normal 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 |
|
||||
Reference in New Issue
Block a user