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

Scanner Analyzer Prep · Sprint 0132

This note captures the unblockers promised in PREP tasks for Sprint 0132. Each subsection gives the artifact location, assumption set, and the handoff needed by downstream implementation tasks.

SCANNER-ANALYZERS-LANG-11-003 (runtime fusion)

• Objective: Define the runtime evidence ingest contract to merge AssemblyLoad/Resolving/PInvoke signals with static edges from 11-002.
• Inputs required:
  • Static edge export format from 11-002 (AssemblyRef/ModuleRef/PInvoke with reason codes).
  • Event listener tap points: AssemblyLoadContext.Resolving, AssemblyLoad, NativeLibrary.SetDllImportResolver, DynamicDependency attributes, and optional ETW provider Microsoft-Windows-DotNETRuntime (keyword 0x8, task AssemblyLoad).
• Runtime evidence envelope (AOC-aligned):

  {
    "runtime_observation_id": "uuid",
    "assembly_name": "System.Text.Json",
    "kind": "assembly-load|p-invoke|dynamic-dependency",
    "source": "Resolving|AssemblyLoad|NativeLibrary|ETW",
    "details": {
      "requested_name": "System.Text.Json",
      "resolved_path": "<normalized absolute path>",
      "assembly_version": "8.0.0.0",
      "culture": "neutral",
      "package_purl": "pkg:nuget/system.text.json@8.0.0",
      "confidence": 0.72,
      "reason_code": "runtime-resolve"
    },
    "timestamp_utc": "2025-11-20T00:00:00Z"
  }
  

• Merge rules for downstream 11-003 implementation:
  • De-dup edges by (assembly_name, resolved_path, kind).
  • Prefer static edge confidence when present; runtime adds confidence_bonus = +0.1 but never exceeds 1.0.
  • Keep provenance: edge.provenance = { "static": bool, "runtime": bool }.
• Publication: This doc section is the frozen location for the runtime ingest contract; downstream tasks should reference this path.

SCANNER-ANALYZERS-LANG-11-004 (observation export → writer/SBOM)

• Objective: Define the observation payload emitted to Scanner writer and SBOM entrypoint tagging.
• Export envelope (AOC-compliant):

  {
    "entrypoints": [
      {
        "label": "app",
        "rids": ["win-x64","linux-x64"],
        "tfms": ["net8.0","net8.0-windows"],
        "command": "dotnet ./bin/app.dll",
        "sources": ["src/App/Program.cs"],
        "rank": 1
      }
    ],
    "dependency_edges": [
      {
        "from": "app",
        "to": "pkg:nuget/system.text.json@8.0.0",
        "reason_code": "assembly-ref",
        "confidence": 0.86,
        "provenance": {"static": true, "runtime": false}
      }
    ],
    "environment_profiles": {
      "tfm": "net8.0",
      "rid": "linux-x64",
      "host_policy": "portable",
      "features": ["singlefile:false","trimmed:false","nativeaot:false"]
    }
  }
  

• Writer handoff:
  • Serialize as deterministic JSON (sorted keys) to the Scanner writer contract writer/observations/lang/dotnet.
  • Attach sbom_entrypoint_tags derived from entrypoint labels to feed SBOM Service tagging.
• Publication: Payload shape and field meanings fixed here for Sprint 0132 downstream work.

SCANNER-ANALYZERS-LANG-11-005 (fixtures & benchmarks)

• Objective: Provide fixture plan so QA can start without waiting on further design.
• Fixture matrix:
  • Framework-dependent: net8.0, net9.0-preview sample apps (console + web minimal API).
  • Self-contained: linux-x64 trimmed vs non-trimmed.
  • Single-file: win-x64 single-file publish, include native hosting bundle.
  • NativeAOT: linux-x64 HelloWorld + P/Invoke stub.
  • Multi-RID: RID graph linux-x64, linux-arm64, win-x64 with RID fallback expectations.
• Locations: place fixtures under src/Scanner/__Tests/Fixtures/DotNet/11-005/*; store expected observation JSON in __Tests/Fixtures/DotNet/11-005/expected/*.json with sorted keys.
• Bench envelopes:
  • Target <150 ms p95 per project scan on dev laptop, <25 MB heap delta; capture via BenchmarkDotNet and report to __Benchmarks/11-005.md.
• Determinism: lock timestamps to 1970-01-01T00:00:00Z in serialized outputs; stable ordering by (entrypoint label, dependency to PURL, reason_code).

SCANNER-ANALYZERS-NATIVE-20-002 (ELF declared-dependency writer contract)

• Objective: Unblock writer schema so native analyzer can emit DT_NEEDED/DT_RPATH/DT_RUNPATH data.
• Edge record (per ELF binary):

  {
    "image": "libssl.so.3",
    "build_id": "cafef00d",
    "rpath": ["$ORIGIN/lib","/usr/lib"],
    "runpath": ["$ORIGIN","/opt/openssl"],
    "needed": [
      {"name": "libcrypto.so.3", "slot": 0, "version": "OPENSSL_3.0", "reason_code": "elf-dtneeded"},
      {"name": "libpthread.so.0", "slot": 1, "version": null, "reason_code": "elf-dtneeded"}
    ],
    "interpreter": "/lib64/ld-linux-x86-64.so.2",
    "origin": "virtual-fs",
    "confidence": 0.82
  }
  

• Writer path: writer/observations/native/elf-declared-deps (append-only NDJSON; sorted by image name then slot).
• Redaction: no host absolute paths; resolve $ORIGIN using virtual image root only.
• Publication: schema above is the agreed baseline for downstream tasks; time-boxed to Sprint 0132.

SCANNER-ANALYZERS-NODE-22-001 (isolated runner / scoped build graph)

• Objective: Provide a deterministic way to run Node analyzer tests without fanning out the whole solution.
• Approach:
  • Add target solution filter: src/Scanner/StellaOps.Scanner.Analyzers.Lang.Node.slnf including only Node projects + shared test utilities.
  • Introduce Directory.Build.props override for Lang.Node tests to disable cross-solution restore (DisableTransitiveProjectReferences=true).
  • Test command for CI + local: dotnet test src/Scanner/StellaOps.Scanner.Analyzers.Lang.Node.Tests/StellaOps.Scanner.Analyzers.Lang.Node.Tests.csproj /p:DisableTransitiveProjectReferences=true --no-restore --logger:"console;verbosity=minimal".
  • Cache seeds: copy pnpm/Yarn fixtures into obj/fixtures-cache during test init; deterministic zip timestamps set to 1980-01-01.
• Publication: This runbook unblocks execution while broader solution build contention is resolved; downstream tasks should adopt this invocation until Sprint 131 completes.

---

Owners: Scanner EPDR Guild (DotNet), SBOM Service Guild, Native Analyzer Guild, Node Analyzer Guild.
Status: All PREP artifacts published 2025-11-20.