git.stella-ops.org/docs/modules/scanner/analyzers-go.md

# Go Analyzer (Scanner)

## What it does
- Inventories Go components from **binaries** (embedded buildinfo) and **source** (go.mod/go.sum/go.work/vendor) without executing `go`.
- Emits `pkg:golang/<module>@<version>` when a concrete version is available; otherwise emits deterministic explicit-key components (no "range-as-version" PURLs).
- Records VCS/build metadata and bounded evidence for audit/replay; remains offline-first.
- Detects security-relevant capabilities in Go source code (exec, filesystem, network, native code, etc.).

## Inputs and precedence
The analyzer processes inputs in the following order, with binary evidence taking precedence:

1. **Binary inventory (Phase 1, authoritative)**: Extract embedded build info (`runtime/debug` buildinfo blob) and emit Go modules (main + deps) with concrete versions and build settings evidence. Binary-derived components include `provenance=binary` metadata.
2. **Source inventory (Phase 2, supplementary)**: Parse `go.mod`, `go.sum`, `go.work`, and `vendor/modules.txt` to emit modules not already covered by binary evidence. Source-derived components include `provenance=source` metadata.
3. **Heuristic fallback (stripped binaries)**: When buildinfo is missing, emit deterministic `bin` components keyed by sha256 plus minimal classification evidence.

**Precedence rules:**
- Binary evidence is scanned first and takes precedence over source evidence.
- When both source and binary evidence exist for the same module path@version, only the binary-derived component is emitted.
- Main modules are tracked separately: if a binary emits `module@version`, source `module@(devel)` is suppressed.
- This ensures deterministic, non-duplicative output.

## Project discovery (modules + workspaces)
- Standalone modules are discovered by locating `go.mod` files (bounded recursion depth 10; vendor directories skipped).
- Workspaces are discovered via `go.work` at the analysis root; `use` members become additional module roots.
- Vendored dependencies are detected via `vendor/modules.txt` when present.

## Workspace replace directive propagation
`go.work` files may contain `replace` directives that apply to all workspace members:
- Workspace-level replaces are inherited by all member modules.
- Module-level replaces take precedence over workspace-level replaces for the same module path.
- Duplicate replace keys are handled deterministically (last-one-wins within each scope).

## Identity rules (PURL vs explicit key)
Concrete versions emit a PURL:
- `purl = pkg:golang/<modulePath>@<version>`

Non-concrete identities emit an explicit key:
- Used for source-only main modules (`(devel)`) and for any non-versioned module identity.
- PURL is omitted (`purl=null`) and the component is keyed deterministically via `AddFromExplicitKey`.

## Evidence and metadata

### Binary-derived components
Binary components include (when present):
- `provenance=binary`
- `go.version`
- `modulePath.main` and `build.*` settings
- VCS fields (`build.vcs*` from build settings and/or `go.dwarf` tokens)
- `moduleSum` and replacement metadata when available
- CGO signals (`cgo.enabled`, flags, compiler hints; plus adjacent native libs when detected)

### Source-derived components
Source components include:
- `provenance=source`
- `moduleSum` from `go.sum` (when present)
- vendor signals (`vendored=true`) and `vendor` evidence locators
- replacement/exclude flags with stable metadata keys
- best-effort license signals for main module and vendored modules
- `capabilities` metadata listing detected capability kinds (exec, filesystem, network, etc.)
- `capabilities.maxRisk` indicating highest risk level (critical/high/medium/low)

### Heuristic fallback components
Fallback components include:
- `type=bin`, deterministic `sha256` identity, and a classification evidence marker
- Metric `scanner_analyzer_golang_heuristic_total{indicator,version_hint}` increments per heuristic emission

## Capability scanning
The analyzer detects security-relevant capabilities in Go source code:

| Capability | Risk | Examples |
|------------|------|----------|
| Exec | Critical | `exec.Command`, `syscall.Exec`, `os.StartProcess` |
| NativeCode | Critical | `unsafe.Pointer`, `//go:linkname`, `syscall.Syscall` |
| PluginLoading | Critical | `plugin.Open` |
| Filesystem | High/Medium | `os.Remove`, `os.Chmod`, `os.WriteFile` |
| Network | Medium | `net.Dial`, `http.Get`, `http.ListenAndServe` |
| Environment | High/Medium | `os.Setenv`, `os.Getenv` |
| Database | Medium | `sql.Open`, `db.Query` |
| DynamicCode | High | `reflect.Value.Call`, `template.Execute` |
| Serialization | Medium | `gob.NewDecoder`, `xml.Unmarshal` |
| Reflection | Low/Medium | `reflect.TypeOf`, `reflect.New` |
| Crypto | Low | Hash functions, cipher operations |

Capabilities are emitted as:
- Metadata: `capabilities=exec,filesystem,network` (comma-separated list of kinds)
- Metadata: `capabilities.maxRisk=critical|high|medium|low`
- Evidence: Top 10 capability locations with pattern and line number

## IO/Memory bounds
Binary and DWARF scanning uses bounded windowed reads to limit memory usage:
- **Build info scanning**: 16 MB windows with 4 KB overlap; max file size 128 MB.
- **DWARF token scanning**: 8 MB windows with 1 KB overlap; max file size 256 MB.
- Small files (below window size) are read directly for efficiency.

## Retract semantics
Go's `retract` directive only applies to versions of the declaring module itself, not to dependencies:
- The `RetractedVersions` field in inventory results contains only versions of the main module that are retracted.
- Dependency retraction cannot be determined offline (would require fetching each module's go.mod).
- No false-positive retraction warnings are emitted for dependencies.

## Cache key correctness
Binary build info is cached using a composite key:
- File path (normalized for OS case sensitivity)
- File length
- Last modification time
- 4 KB header hash (FNV-1a)

The header hash ensures correct behavior in containerized/layered filesystem environments where files may have identical metadata but different content.

## References
- Sprint: `docs/implplan/SPRINT_0402_0001_0001_scanner_go_analyzer_gaps.md`
- Cross-analyzer contract: `docs/modules/scanner/language-analyzers-contract.md`
- Implementation: `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Go/GoLanguageAnalyzer.cs`
- Capability scanner: `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Go/Internal/GoCapabilityScanner.cs`