docs consolidation
This commit is contained in:
StellaOps Bot
@@ -1,15 +0,0 @@
|
||||
# EntryTrace Heuristics Maintenance — Draft Skeleton (2025-12-05 UTC)
|
||||
|
||||
Status: draft placeholder. Inputs pending: replay hooks (RPRC0101).
|
||||
|
||||
## Purpose
|
||||
- Explain EntryTrace heuristics and maintenance cycles.
|
||||
|
||||
## Heuristic Catalog
|
||||
- Placeholder for rules with owners and review cadence.
|
||||
|
||||
## Operations
|
||||
- How to update heuristics safely; replay/validation steps.
|
||||
|
||||
## Open TODOs
|
||||
- Add concrete heuristics and replay examples when hooks arrive.
|
||||
@@ -1,12 +0,0 @@
|
||||
# Go Stripped Binaries — Draft Skeleton (2025-12-05 UTC)
|
||||
|
||||
Status: draft placeholder. Inputs pending: Go analyzer results.
|
||||
|
||||
## Fallback Enrichment
|
||||
- Techniques to enrich stripped Go binaries (to fill).
|
||||
|
||||
## Policy Guidance
|
||||
- When to accept fallback; how to flag low-confidence matches.
|
||||
|
||||
## Open TODOs
|
||||
- Add enrichment recipes and examples once analyzer outputs land.
|
||||
@@ -1,15 +0,0 @@
|
||||
# Java Lockfile Ingestion — Draft Skeleton (2025-12-05 UTC)
|
||||
|
||||
Status: draft placeholder. Inputs pending: Java analyzer notes.
|
||||
|
||||
## Lockfile Types
|
||||
- Maven/Gradle variants (to fill).
|
||||
|
||||
## Ingestion Guidance
|
||||
- Normalization, version conflict handling.
|
||||
|
||||
## Policy Templates
|
||||
- Sample allow/deny templates (placeholder).
|
||||
|
||||
## Open TODOs
|
||||
- Add concrete examples and ingestion steps from analyzer notes.
|
||||
@@ -1,12 +0,0 @@
|
||||
# Python Lockfiles & Editable Installs — Draft Skeleton (2025-12-05 UTC)
|
||||
|
||||
Status: draft placeholder. Depends on outcomes from Windows/macOS coverage (task 3) and Python analyzer guidance.
|
||||
|
||||
## Lockfile Handling
|
||||
- Pip/Poetry/UV constraints; editable installs; markers (to fill).
|
||||
|
||||
## Policy Guidance
|
||||
- What to enforce/allow; sample policy snippets.
|
||||
|
||||
## Open TODOs
|
||||
- Insert concrete lockfile examples and policies once inputs arrive.
|
||||
@@ -1,15 +0,0 @@
|
||||
# Rust Fingerprint Enrichment — Draft Skeleton (2025-12-05 UTC)
|
||||
|
||||
Status: draft placeholder. Inputs pending: SCSA0601 updated benchmarks.
|
||||
|
||||
## Fingerprint Sources
|
||||
- Cargo metadata, debug info, symbol hashes (to fill).
|
||||
|
||||
## Enrichment Steps
|
||||
- Mapping fingerprints to crates/versions; confidence scoring.
|
||||
|
||||
## Policy Examples
|
||||
- Sample allow/deny/waiver patterns (placeholder).
|
||||
|
||||
## Open TODOs
|
||||
- Add concrete examples from updated benchmarks.
|
||||
@@ -1,12 +0,0 @@
|
||||
# SAST Integration — Draft Skeleton (2025-12-05 UTC)
|
||||
|
||||
Status: draft placeholder. Inputs pending: CLI samples (132_CLCI0110).
|
||||
|
||||
## Connector Framework
|
||||
- How SAST connectors plug into scanner pipeline (to fill).
|
||||
|
||||
## Policy Templates
|
||||
- Placeholder for SAST-specific policy examples.
|
||||
|
||||
## Open TODOs
|
||||
- Add sample configs and flows once CLI samples are available.
|
||||
@@ -1,15 +0,0 @@
|
||||
# Windows/macOS Analyzer Coverage — Draft Skeleton (2025-12-05 UTC)
|
||||
|
||||
Status: draft placeholder. Inputs pending: SCSA0301 customer demand signals.
|
||||
|
||||
## Demand Signals
|
||||
- Customers requesting Windows/macOS analyzer coverage (to fill with SCSA0301 data).
|
||||
|
||||
## Coverage Plan
|
||||
- Supported OS versions/builds; exclusions; offline posture.
|
||||
|
||||
## Rollout & Monitoring
|
||||
- Enablement steps; metrics to watch.
|
||||
|
||||
## Open TODOs
|
||||
- Add quantified demand, target milestones, and acceptance criteria once inputs land.
|
||||
@@ -1,30 +1,38 @@
|
||||
# Field Engagement Playbook — Windows & macOS Coverage
|
||||
# Field Engagement Playbook: Windows and macOS Coverage
|
||||
|
||||
> Audience: Field SEs, Product Specialists • Status: Draft
|
||||
This playbook helps field teams answer Windows/macOS coverage questions without drifting into speculative promises.
|
||||
|
||||
## Purpose
|
||||
Provide quick-reference guidance when prospects or customers ask about Windows/macOS coverage.
|
||||
## 1) Current scope (baseline)
|
||||
- Scanner targets deterministic container-image workflows first (Linux-focused).
|
||||
- Windows and macOS analyzers are design-tracked and should be discussed as "in discovery/design" unless a specific sprint/feature flag says otherwise.
|
||||
|
||||
## Key talking points
|
||||
- **Current scope**: Scanner supports deterministic Linux coverage; Windows/macOS analyzers are in design.
|
||||
- **Roadmap**: macOS design (brew/pkgutil/.app) at `../design/macos-analyzer.md`; Windows design (MSI/WinSxS/Chocolatey) at `../design/windows-analyzer.md`.
|
||||
- **Demand tracking**: All signals captured in `../../benchmarks/scanner/windows-macos-demand.md` using the interview template.
|
||||
- **Policy readiness**: Secret leak detection briefing (`../../policy/secret-leak-detection-readiness.md`) and Windows package readiness (`../../policy/windows-package-readiness.md`).
|
||||
- **Backlog IDs**: MacOS (SCANNER-ENG-0020..0023), Windows (SCANNER-ENG-0024..0027), policy follow-ups (POLICY-READINESS-0001/0002).
|
||||
## 2) Operator talking points
|
||||
- Determinism and offline parity are non-negotiable: any Windows/macOS expansion must keep fixtures, ordering, hashing, and Offline Kit flows reproducible.
|
||||
- Coverage work is split into:
|
||||
- Scanner analyzers (collection and parsing),
|
||||
- Policy predicates (trust/verification rules),
|
||||
- Offline Kit packaging (feeds, certificates, mirrors, and deterministic indexes).
|
||||
|
||||
## SE workflow
|
||||
1. Use the interview template to capture customer needs.
|
||||
2. Append structured summary to `windows-macos-demand.md` and update the API dashboards (`docs/api/scanner/windows-macos-summary.md`, `docs/api/scanner/windows-coverage.md`).
|
||||
3. Notify Product/Scanner guild during weekly sync; flag blockers in Jira.
|
||||
4. Add highlight to the “Recent updates” section in `docs/api/scanner/windows-macos-summary.md`.
|
||||
5. Track upcoming milestones (FinSecure decision 2025-11-07, Northwind demo 2025-11-10) and ensure readiness tasks reflect outcomes.
|
||||
## 3) Where to point people
|
||||
- Design briefs:
|
||||
- `docs/modules/scanner/design/windows-analyzer.md`
|
||||
- `docs/modules/scanner/design/macos-analyzer.md`
|
||||
- Deep dives and research notes:
|
||||
- `docs/benchmarks/scanner/deep-dives/windows.md`
|
||||
- `docs/benchmarks/scanner/deep-dives/macos.md`
|
||||
- Demand capture: `docs/benchmarks/scanner/windows-macos-demand.md`
|
||||
- Policy readiness notes:
|
||||
- `docs/modules/policy/windows-package-readiness.md`
|
||||
- `docs/modules/policy/secret-leak-detection-readiness.md`
|
||||
|
||||
## FAQ snippets
|
||||
- *When will Windows/macOS analyzers be GA?* — Pending demand threshold; design complete, awaiting prioritisation.
|
||||
- *Can we run scans offline?* — Offline parity is a requirement; Offline Kit packaging detailed in design briefs.
|
||||
- *Do we cover Authenticode/notarization?* — Planned via Policy Engine predicates as part of readiness tasks.
|
||||
## 4) Signal capture workflow
|
||||
1. Capture requirements using `docs/benchmarks/scanner/windows-macos-interview-template.md`.
|
||||
2. Append a structured summary to `docs/benchmarks/scanner/windows-macos-demand.md`.
|
||||
3. If the signal implies policy/security decisions (signature verification, trust roots, masking/telemetry), update the relevant readiness notes and reference the demand entry.
|
||||
4. Share the updated demand entry with the Scanner and Policy guilds in the next sync.
|
||||
|
||||
## 5) FAQ snippets
|
||||
- When will Windows/macOS be GA? Demand- and evidence-driven; avoid date promises. Use the design briefs and deep dives for the current state.
|
||||
- Can we run scans offline? Offline parity is required; any OS expansion must include an Offline Kit story (feeds, trust roots, deterministic indexes).
|
||||
- Do we cover Authenticode/notarization? Treat as a policy/security decision captured in readiness notes, not an implicit feature promise.
|
||||
|
||||
## Contacts
|
||||
- Product lead: TBD (record in demand log when assigned)
|
||||
- Scanner guild rep: TBD
|
||||
- Policy guild rep: TBD
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
# Scanner Analyzers PREP Notes — 2025-11-20
|
||||
|
||||
Owner: Scanner EPDR Guild · Signals Guild · SBOM Service Guild · Native Analyzer Guild
|
||||
Scope: Prep deliverables for PREP-SCANNER-ANALYZERS-LANG-11-003-DEPENDS-ON, PREP-SCANNER-ANALYZERS-LANG-11-004-DEPENDS-ON, and PREP-SCANNER-ANALYZERS-NATIVE-20-002-AWAIT-DE.
|
||||
|
||||
## 1) LANG-11-003 runtime evidence ingest (dependent on 11-002)
|
||||
- Required upstream: static analyzer outputs from 11-002 (AssemblyRef/ModuleRef/PInvoke/reflection edges with reason codes/confidence).
|
||||
- Runtime harness spec (draft):
|
||||
- Listener surfaces `AssemblyLoad`, `Resolving`, `FirstChanceException` events; optional OS-specific providers gated by feature flag `scanner:analyzers:dotnet:runtime-capture` (default off).
|
||||
- Output shape fed into merger: `runtime_edges[]` with fields `{from_entrypoint, to_identity, reason_code, confidence, evidence}`; `evidence` captures event type, payload fragment, timestamp (UTC ISO-8601), and source provider.
|
||||
- Merge rules: prefer static edges; runtime edges only add new edges or upgrade confidence; no removals.
|
||||
- Test plan stub: targeted harness tests under `StellaOps.Scanner.Analyzers.Lang.DotNet.Tests` using recorded ETW/EventListener traces; determinism enforced via sorted edges and normalized timestamps.
|
||||
|
||||
## 2) LANG-11-004 normalized observation export (dependent on 11-003)
|
||||
- Export contract (AOC compliant) to Scanner writer:
|
||||
- `entrypoints[]` with `{id, assembly_name, mvid, tfm, rid, kind}`.
|
||||
- `dependency_edges[]` with `{from_entrypoint, to_component, reason_code, confidence, source={static|runtime|declared}, evidence_ref}`.
|
||||
- `environment_profiles[]` capturing loader configuration (search paths, probing settings) without host-specific absolute paths; deterministic ordering.
|
||||
- Integration expectations:
|
||||
- Writer API endpoint path: `scanner/writer/analyzers/dotnet/runtime-static-fusion` (to be aligned with writer team).
|
||||
- SBOM tagging: entrypoints annotated with export IDs; avoid adding derived severity.
|
||||
- Testing hook: golden JSON exports under `src/Scanner/__Tests/Fixtures/lang11/export/*.json`, referenced by `ObservationExportTests` once 11-003 is ready.
|
||||
|
||||
## 3) NATIVE-20-002 declared-dependency writer (await declared-dependency contract)
|
||||
- Scope: emit declared dependencies from ELF dynamic sections with `reason_code=elf-dtneeded`, include `rpath/runpath` and symbol version needs when present.
|
||||
- Contract expectations:
|
||||
- Writer record fields: `{binary_id, needed_soname, search_path_hint[], runpath[], build_id, interpreter, version_need[]}`; all ordered deterministically.
|
||||
- Input parser must normalize duplicate `DT_NEEDED` entries and preserve order of appearance.
|
||||
- Dependencies: needs finalized declared-dependency writer interface from Scanner writer team; block remains until contract lands, but this prep defines expected payload shape and ordering.
|
||||
- Test stub guidance: place fixtures under `src/Scanner/__Tests/Fixtures/native/elf-dtneeded/*` with baseline YAML/JSON; benchmark target <25ms per binary on baseline fixtures.
|
||||
|
||||
## Handoff
|
||||
- This document is the published prep artefact requested by the above PREP tasks. Implementation tasks should cite this file until upstream contracts arrive.
|
||||
@@ -1,26 +0,0 @@
|
||||
# Java Analyzer Prep — SCANNER-ANALYZERS-JAVA-21-005 (PREP)
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Java Analyzer Guild
|
||||
Scope: Capture prerequisites and fixture expectations to unblock SCANNER-ANALYZERS-JAVA-21-005 once upstream build issues clear.
|
||||
|
||||
## Blocking issues observed
|
||||
- Repository build fails in Concelier due to missing `CoreLinksets` Mongo interfaces; prevents running targeted Java analyzer tests.
|
||||
- Targeted `dotnet test` stalls during restore/build on shared runner; needs clean CI slot or scoped solution.
|
||||
|
||||
## Required upstream artifacts
|
||||
- Concelier/CoreLinksets packages or mocks to let Java analyzer tests restore/build.
|
||||
- CI job or local script to run Java analyzer tests in isolation (`StellaOps.Scanner.Analyzers.Lang.Java.Tests.csproj`) without full solution restore.
|
||||
|
||||
## Expected outputs once unblocked
|
||||
- Framework config extraction evidence covering Spring Boot imports, app/bootstrap configs, web.xml/fragments, JPA/CDI/JAXB configs, logging files, Graal native-image configs.
|
||||
- JNI/native hint detection: System.load/Library literals, bundled native libs, Graal JNI configs with component metadata.
|
||||
- Deterministic hashing of config evidence (SHA-256) with stable ordering.
|
||||
|
||||
## Test/fixture plan
|
||||
- Fixtures under `src/Scanner/__Tests/Fixtures/java/21-005/*` capturing the above configs.
|
||||
- Regression tests in `StellaOps.Scanner.Analyzers.Lang.Java.Tests/FrameworkConfigTests.cs` asserting evidence presence and hashes.
|
||||
- Add CI note: prefer `dotnet test ...Java.Tests.csproj --filter Category=FrameworkConfig` once solutions restore cleanly.
|
||||
|
||||
## Handoff
|
||||
Use this document as the published prep artefact for PREP-SCANNER-ANALYZERS-JAVA-21-005-TESTS-BLOC. Update once Concelier/CoreLinksets dependency is resolved or CI isolation is available.
|
||||
@@ -1,26 +0,0 @@
|
||||
# Java Analyzer Prep — SCANNER-ANALYZERS-JAVA-21-008
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Java Analyzer Guild
|
||||
Scope: Resolver + AOC writer emitting entrypoints/components/edges with reason codes/confidence; depends on 21-007 outputs.
|
||||
|
||||
## Dependencies
|
||||
- 21-007 manifest metadata collector outputs (signers, manifest attributes) required to seed resolver inputs.
|
||||
- CoreLinksets/Concelier build health to allow Java analyzer test runs.
|
||||
|
||||
## Proposed resolver outputs
|
||||
- `entrypoints[]`: `{id, path, manifest_main_class?, agent_class?, start_class?, module}`.
|
||||
- `components[]`: modules/JARs with `{purl?, sha256, module_name?, signed?, signer_ids[]}`.
|
||||
- `edges[]`: `{from_entrypoint, to_component, reason_code (jpms|cp|spi|reflect|jni|runtime), confidence, evidence}`.
|
||||
- Deterministic ordering: sort edges by (from_entrypoint, to_component, reason_code).
|
||||
|
||||
## Tests/fixtures
|
||||
- Place fixtures under `src/Scanner/__Tests/Fixtures/java/21-008/*` covering jpms, classpath, SPI, reflection, JNI cases.
|
||||
- Regression tests: `ResolverOutputs_AreDeterministic` and `EdgesIncludeReasonAndConfidence`.
|
||||
|
||||
## Open decisions
|
||||
- Exact confidence scale (0–1 vs categorical) to align with downstream Surface.
|
||||
- Whether to emit runtime edges in this task vs deferring to 21-010.
|
||||
|
||||
## Handoff
|
||||
Use this doc as the PREP artefact for 21-008; update once 21-007 outputs and confidence scale are finalized.
|
||||
@@ -1,28 +0,0 @@
|
||||
# .NET Lang Analyzer Prep — SCANNER-ANALYZERS-LANG-11-001
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Scanner EPDR Guild · Language Analyzer Guild
|
||||
Scope: Entrypoint resolver mapping project/publish artifacts to deterministic entrypoint identities; PREP covers test isolation and hang debugging.
|
||||
|
||||
## Blocking issues
|
||||
- `dotnet test` hangs/returns empty output on shared runner; high restore/build fan-out.
|
||||
- Concelier/CoreLinksets build errors encountered during prior attempts.
|
||||
|
||||
## Proposed mitigation
|
||||
- Add CI job to run `dotnet test src/Scanner/__Tests/StellaOps.Scanner.Analyzers.Lang.DotNet.Tests/StellaOps.Scanner.Analyzers.Lang.DotNet.Tests.csproj --filter Category=Entrypoints --blame-hang-timeout 45s` on clean agent.
|
||||
- Provide scoped solution `StellaOps.Scanner.Analyzers.Lang.DotNet.slnf` to limit restore.
|
||||
|
||||
## Expected outputs
|
||||
- Entrypoints array: `{id, assembly_name, mvid, tfm, rid, kind}` with deterministic ID hashing (`sha256` over path+tfm+rid).
|
||||
- Environment profiles: loader/probing settings minus host absolute paths.
|
||||
|
||||
## Test/fixtures
|
||||
- Fixtures under `src/Scanner/__Tests/Fixtures/dotnet/entrypoints/*` for framework-dependent, self-contained, NativeAOT, multi-RID, single-file, trimmed builds.
|
||||
- Golden outputs sorted by entrypoint id; verify hash stability across OS.
|
||||
|
||||
## Open decisions
|
||||
- Hash input shape for `id` (include project GUID?): to confirm with Signals guild.
|
||||
- Whether to allow RID inference from runtimeconfig vs RID graph; requires Signals sign-off.
|
||||
|
||||
## Handoff
|
||||
Treat this as the PREP artefact for PREP-SCANNER-ANALYZERS-LANG-11-001; update once CI isolation and hash rules are confirmed.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Scanner PREP — Node Analyzer Isolated Runner (22-001)
|
||||
Date: 2025-11-20
|
||||
Owner: Node Analyzer Guild
|
||||
Scope: Requirements and plan to provide an isolated/scoped runner so targeted Node analyzer tests complete without whole-solution fan‑out.
|
||||
|
||||
## Goals
|
||||
- Enable `StellaOps.Scanner.Analyzers.Lang.Node.Tests` to run deterministically without restoring/building the entire solution.
|
||||
- Reduce CI/local runtime (<5 min) and contention during restores.
|
||||
- Keep offline/air-gap posture: rely only on `local-nugets/` + repo fixtures; no external fetches.
|
||||
|
||||
## Proposed approach
|
||||
1) **Scoped solution file**
|
||||
- Create `src/Scanner/StellaOps.Scanner.Analyzers.Node.slnf` including only Node analyzer projects + their direct deps (`StellaOps.Scanner.Analyzers.Lang.Node`, tests, shared test utilities).
|
||||
- CI job uses `dotnet test --solution St...Node.slnf --no-restore --no-build` after targeted restore.
|
||||
2) **Isolated restore cache**
|
||||
- Pre-populate `local-nugets/` via existing offline feed; add msbuild property `RestorePackagesPath=$(RepoRoot)/offline/packages` to avoid global cache churn.
|
||||
3) **Test shim**
|
||||
- Add runsettings to disable collectors that trigger solution-wide discovery; set `RunConfiguration.DisableAppDomain=true` for determinism.
|
||||
4) **Tarball/pnpm/Yarn PnP fixtures**
|
||||
- Move heavy fixtures under `src/Scanner/__Tests/Fixtures/node/` and reference via deterministic VFS layer; no temp extraction outside repo.
|
||||
5) **Entry point**
|
||||
- New `scripts/scanner/node-tests-isolated.sh` wrapper: restore scoped solution, then run `dotnet test` with `/m:1` and explicit test filters as needed.
|
||||
|
||||
## Deliverables for implementation task
|
||||
- Add `.slnf`, runsettings, and wrapper script as above.
|
||||
- Update CI pipeline (Scanner) to include isolated target; keep full solution tests separate.
|
||||
- Document usage in `src/Scanner/__Tests/README.md`.
|
||||
|
||||
## Blocking items
|
||||
- Upstream Concelier projects in solution filter currently do not build (`StellaOps.Concelier.Storage.Mongo` duplicate `AdvisoryObservationSourceDocument` definition and missing `NatsJSContext` type), so `dotnet test` fails before Node analyzer tests execute. Needs Concelier fix or temporary exclusion to validate runner.
|
||||
- 2025-11-20 follow-up: deduplication + JetStream package added in Concelier.Storage.Mongo and Scanner tests now set `UseConcelierTestInfra=false`, but the shared Directory.Build.props still injects Concelier connectors into the restore/build graph; Node tests remain blocked until Concelier test infra is fully detachable or those projects are excluded from the filter.
|
||||
|
||||
This note satisfies PREP-SCANNER-ANALYZERS-NODE-22-001-NEEDS-ISOL by defining the isolated runner plan and artefact locations.
|
||||
@@ -1,16 +0,0 @@
|
||||
# Scanner Record Payloads Prep — PREP-SCANNER-RECORDS
|
||||
|
||||
Status: Draft (2025-11-21)
|
||||
Owners: Scanner Guild · Policy Guild
|
||||
Scope: Stabilize record/observation payload schema for scanner workers so downstream policy/graph pipelines can rely on consistent envelopes.
|
||||
|
||||
Needs
|
||||
- Confirm per-language analyzer output fields (package coordinates, vuln refs, evidence hashes) and common envelope keys.
|
||||
- Decide deterministic ordering for findings within a record to support replay/air-gap.
|
||||
- Define maximum payload size, chunking rules, and checksum strategy (SHA256 over canonical JSON).
|
||||
- Align timestamp format (UTC, RFC3339) and monotonic sequencing for job-level ordering.
|
||||
|
||||
Next actions
|
||||
- Pull latest analyzer outputs from scanner worker prototypes and normalize into a shared JSON Schema.
|
||||
- Share sample NDJSON record set for Policy/Graph consumers.
|
||||
- Publish links into relevant sprints once schema draft is frozen.
|
||||
@@ -1,282 +0,0 @@
|
||||
# Bun Analyzer Design — PREP-SCANNER-BUN-001-DESIGN-DOC
|
||||
|
||||
Status: Draft (2025-12-06)
|
||||
Owners: Bun Analyzer Guild · Scanner Guild
|
||||
Scope: Bun package manager analyzer for npm-ecosystem vulnerability scanning in container filesystems.
|
||||
|
||||
## Overview
|
||||
|
||||
The Bun analyzer extracts npm-ecosystem package inventory from Bun-managed JavaScript/TypeScript projects. Bun uses npm-compatible package.json and produces packages in `node_modules`, making it similar to the Node analyzer but with distinct lockfile formats and installation structures.
|
||||
|
||||
## Supported Artifacts
|
||||
|
||||
### Lockfile Formats
|
||||
|
||||
| Format | Extension | Status | Notes |
|
||||
|--------|-----------|--------|-------|
|
||||
| Text lockfile | `bun.lock` | Supported | JSONC format with package metadata |
|
||||
| Binary lockfile | `bun.lockb` | Unsupported | Undocumented binary format; emit migration guidance |
|
||||
|
||||
### Installation Structures
|
||||
|
||||
| Structure | Discovery Pattern | Notes |
|
||||
|-----------|-------------------|-------|
|
||||
| Default (hoisted) | `node_modules/**/package.json` | Standard flat structure |
|
||||
| Isolated linker | `node_modules/.bun/**/package.json` | Symlink-heavy, requires safe traversal |
|
||||
|
||||
## Discovery Heuristics
|
||||
|
||||
### Project Root Detection
|
||||
|
||||
A directory is considered a Bun project root when:
|
||||
|
||||
1. `package.json` exists, AND
|
||||
2. One or more of:
|
||||
- `bun.lock` exists (text lockfile)
|
||||
- `bun.lockb` exists (binary lockfile — triggers unsupported message)
|
||||
- `bunfig.toml` exists (Bun configuration)
|
||||
- `node_modules/.bun/` exists (isolated linker marker)
|
||||
|
||||
### Input Classification
|
||||
|
||||
```
|
||||
BunInputNormalizer classifies each root:
|
||||
├── InstalledPath: node_modules exists → traverse installed packages
|
||||
├── LockfilePath: bun.lock only (no node_modules) → parse lockfile
|
||||
└── Unsupported: bun.lockb only → emit remediation finding
|
||||
```
|
||||
|
||||
## Lockfile Schema (`bun.lock`)
|
||||
|
||||
The `bun.lock` text format is a JSONC variant (JSON with comments and trailing commas):
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"lockfileVersion": 1,
|
||||
"workspaces": {
|
||||
"": {
|
||||
"name": "my-app",
|
||||
"dependencies": {
|
||||
"lodash": "^4.17.21"
|
||||
}
|
||||
}
|
||||
},
|
||||
"packages": {
|
||||
"lodash@4.17.21": {
|
||||
"resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
|
||||
"integrity": "sha512-v2kDEe57...",
|
||||
"dependencies": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Extracted Fields
|
||||
|
||||
| Field | Source | Usage |
|
||||
|-------|--------|-------|
|
||||
| name | packages key (before `@version`) | PURL name component |
|
||||
| version | packages key (after `@`) | PURL version component |
|
||||
| resolved | packages[].resolved | Evidence locator |
|
||||
| integrity | packages[].integrity | Evidence hash (sha512/sha256) |
|
||||
|
||||
## Evidence Model
|
||||
|
||||
### LanguageComponentEvidence Structure
|
||||
|
||||
```csharp
|
||||
record BunPackageEvidence(
|
||||
LanguageEvidenceKind Kind, // File | Metadata | Lockfile
|
||||
string Source, // "node_modules" | "bun.lock"
|
||||
string Locator, // File path or registry URL
|
||||
string? Content, // package.json content (if File)
|
||||
string? Sha256); // Content hash
|
||||
```
|
||||
|
||||
### Evidence Collection Matrix
|
||||
|
||||
| Source | Kind | Locator | Content | Hash |
|
||||
|--------|------|---------|---------|------|
|
||||
| `node_modules/**/package.json` | File | Relative path | JSON content | sha256 of content |
|
||||
| `bun.lock` | Lockfile | `bun.lock:packages[name@version]` | null | null |
|
||||
| Registry resolution | Metadata | resolved URL | null | integrity value |
|
||||
|
||||
## PURL Generation
|
||||
|
||||
Bun packages are npm packages with `bun` package manager qualifier:
|
||||
|
||||
```
|
||||
pkg:npm/<name>@<version>?package_manager=bun
|
||||
```
|
||||
|
||||
### Scoped Package Encoding
|
||||
|
||||
| Raw Name | Encoded PURL |
|
||||
|----------|--------------|
|
||||
| `lodash` | `pkg:npm/lodash@4.17.21?package_manager=bun` |
|
||||
| `@types/node` | `pkg:npm/%40types/node@20.10.0?package_manager=bun` |
|
||||
| `@org/pkg` | `pkg:npm/%40org/pkg@1.0.0?package_manager=bun` |
|
||||
|
||||
## Symlink Safety
|
||||
|
||||
Bun's isolated linker creates symlink-heavy structures. Safety requirements:
|
||||
|
||||
1. **Prefix Containment**: Only follow symlinks that resolve within root path
|
||||
2. **Cycle Detection**: Maintain visited inode/realpath set
|
||||
3. **Path Recording**: Record both logical path (symlink) and real path (target)
|
||||
4. **Depth Limit**: Cap symlink depth at 32 levels (configurable)
|
||||
|
||||
```csharp
|
||||
record SymlinkSafetyContext(
|
||||
string RootPrefix,
|
||||
HashSet<(long Inode, long Device)> VisitedInodes,
|
||||
int MaxDepth = 32);
|
||||
```
|
||||
|
||||
## Performance Guards
|
||||
|
||||
| Guard | Default | Rationale |
|
||||
|-------|---------|-----------|
|
||||
| max-files-per-root | 50,000 | Prevent full image traversal |
|
||||
| max-symlink-depth | 32 | Avoid infinite loops in malformed structures |
|
||||
| prefix-pruning | enabled | Skip paths outside expected locations |
|
||||
| timeout-per-root | 60s | Bound analysis time per project |
|
||||
|
||||
## CLI Contract
|
||||
|
||||
### `stellaops-cli bun inspect`
|
||||
|
||||
Display Bun package inventory for local root or scan ID:
|
||||
|
||||
```bash
|
||||
# Local analysis
|
||||
stellaops-cli bun inspect /path/to/project
|
||||
|
||||
# Remote scan lookup
|
||||
stellaops-cli bun inspect --scan-id abc123
|
||||
```
|
||||
|
||||
Output formats: `--output json|table|ndjson`
|
||||
|
||||
### `stellaops-cli bun resolve`
|
||||
|
||||
Resolve Bun packages by scan ID, digest, or image reference:
|
||||
|
||||
```bash
|
||||
stellaops-cli bun resolve --scan-id abc123 --package lodash
|
||||
stellaops-cli bun resolve --digest sha256:abc... --format json
|
||||
```
|
||||
|
||||
## WebService Contract
|
||||
|
||||
### `GET /api/scans/{scanId}/bun-packages`
|
||||
|
||||
Returns inventory of Bun packages for a completed scan.
|
||||
|
||||
Query parameters:
|
||||
- `page`, `pageSize`: Pagination
|
||||
- `name`: Filter by package name (prefix match)
|
||||
- `scope`: Filter by npm scope
|
||||
|
||||
Response schema:
|
||||
```json
|
||||
{
|
||||
"scanId": "abc123",
|
||||
"analyzer": "bun",
|
||||
"packages": [
|
||||
{
|
||||
"name": "lodash",
|
||||
"version": "4.17.21",
|
||||
"purl": "pkg:npm/lodash@4.17.21?package_manager=bun",
|
||||
"evidence": [
|
||||
{
|
||||
"kind": "File",
|
||||
"source": "node_modules",
|
||||
"locator": "node_modules/lodash/package.json",
|
||||
"sha256": "abc..."
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"total": 150,
|
||||
"page": 1,
|
||||
"pageSize": 50
|
||||
}
|
||||
```
|
||||
|
||||
## Unsupported Artifact Handling
|
||||
|
||||
### Binary Lockfile (`bun.lockb`)
|
||||
|
||||
When only `bun.lockb` is present (no `bun.lock` or `node_modules`):
|
||||
|
||||
1. Emit remediation finding with severity `Info`
|
||||
2. Provide migration command: `bun install --save-text-lockfile`
|
||||
3. Skip package enumeration (no false negatives from partial binary parse)
|
||||
|
||||
```csharp
|
||||
record BunLockbUnsupportedFinding(
|
||||
string Path,
|
||||
string RemediationCommand = "bun install --save-text-lockfile",
|
||||
string Reason = "Binary lockfile format is undocumented and unstable");
|
||||
```
|
||||
|
||||
## Test Fixtures
|
||||
|
||||
| Fixture | Purpose | Validation |
|
||||
|---------|---------|------------|
|
||||
| `hoisted-install` | Standard Bun install with `node_modules` + `bun.lock` | Installed inventory path |
|
||||
| `isolated-linker` | `bun install --linker isolated` structure | `.bun/` traversal |
|
||||
| `lockfile-only` | No `node_modules`, only `bun.lock` | Lockfile inventory, dev/prod filtering |
|
||||
| `binary-lockfile-only` | Only `bun.lockb` present | Unsupported remediation message |
|
||||
| `monorepo-workspaces` | Multiple `package.json` under single lock | Workspace member handling |
|
||||
| `symlink-cycles` | Malformed structure with cycles | Cycle detection, no infinite loops |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `STELLAOPS_BUN_MAX_FILES` | 50000 | Max files per root |
|
||||
| `STELLAOPS_BUN_MAX_SYMLINK_DEPTH` | 32 | Max symlink traversal depth |
|
||||
| `STELLAOPS_BUN_INCLUDE_DEV` | true | Include dev dependencies |
|
||||
| `STELLAOPS_BUN_TIMEOUT_SECONDS` | 60 | Per-root analysis timeout |
|
||||
|
||||
### appsettings.json
|
||||
|
||||
```json
|
||||
{
|
||||
"Scanner": {
|
||||
"Analyzers": {
|
||||
"Bun": {
|
||||
"MaxFilesPerRoot": 50000,
|
||||
"MaxSymlinkDepth": 32,
|
||||
"IncludeDevDependencies": true,
|
||||
"TimeoutSeconds": 60
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Determinism Requirements
|
||||
|
||||
1. **Sorted Output**: Packages ordered by `(name, version)` tuple
|
||||
2. **Stable IDs**: Component keys computed as `sha256(analyzerId + purl)`
|
||||
3. **Reproducible Evidence**: Evidence ordered by `(kind, source, locator)`
|
||||
4. **No Timestamps**: Evidence does not include file modification times
|
||||
5. **Canonical Paths**: All paths normalized (forward slashes, no trailing slash)
|
||||
|
||||
## Open Decisions
|
||||
|
||||
1. **Dev Dependency Default**: Currently `include_dev: true` for lockfile-only scans — confirm with Policy Guild
|
||||
2. **Workspace Handling**: Whether to emit separate inventory per workspace or merged — await monorepo fixture results
|
||||
3. **PURL Qualifier**: Using `?package_manager=bun` vs no qualifier — coordinate with Concelier linkset resolution
|
||||
|
||||
## Handoff
|
||||
|
||||
This document serves as the PREP artifact for PREP-SCANNER-BUN-001-DESIGN-DOC. Update upon:
|
||||
- Policy Guild confirmation of dev dependency defaults
|
||||
- Concelier Guild decision on PURL qualifier handling
|
||||
- Fixture suite completion revealing edge cases
|
||||
@@ -1,24 +0,0 @@
|
||||
# Scanner Engine Surface FS/Env/Secrets — Draft Skeleton (2025-12-05 UTC)
|
||||
|
||||
Status: draft placeholder. Inputs pending: SCANNER-SURFACE-04 emit notes, Zastava/Scheduler bindings, Ops runbook hooks.
|
||||
|
||||
## Workflow Overview
|
||||
- Surface.FS, Surface.Env, Surface.Secrets capture points.
|
||||
- How Scanner orchestrates surface capture across jobs.
|
||||
|
||||
## Data Flow
|
||||
- Scanner -> Zastava (signals/alerts pipeline).
|
||||
- Scanner -> Scheduler (job orchestration, retries, back-pressure).
|
||||
- Storage/retention expectations.
|
||||
|
||||
## Policies & Safety Rails
|
||||
- Redaction rules, scope boundaries, tenant isolation.
|
||||
- Determinism/offline posture considerations.
|
||||
|
||||
## Operations
|
||||
- How to enable/disable surface capture per tenant/workspace.
|
||||
- Observability: metrics, logs, traces to watch.
|
||||
|
||||
## Open TODOs
|
||||
- Insert concrete emit schemas and example payloads when SCANNER-SURFACE-04 lands.
|
||||
- Add sequencing diagrams per module dossier once available.
|
||||
Reference in New Issue
Block a user