checkId: check.scanner.witness.graph plugin: stellaops.doctor.scanner severity: warn tags: [scanner, witness, graph, reachability, evidence]

Witness Graph Health

This Doctor check watches the Scanner’s witness graph construction – the evidence artifacts that record exactly how a reachability verdict was reached, from application entry point to vulnerable function. It is aimed at operators and security engineers who need intact, consistent witness graphs so that reachability findings carry verifiable provenance and stand up to audit.

What It Checks

Queries the Scanner service at /api/v1/witness/stats and evaluates witness graph construction health:

Evidence collected: total_constructed, construction_failures, failure_rate, incomplete_graphs, avg_nodes_per_graph, avg_edges_per_graph, avg_completeness, consistency_errors.

The check requires Scanner:Url or Services:Scanner:Url to be configured.

Why It Matters

Witness graphs are the evidence artifacts that prove how a vulnerability reachability verdict was reached. They record the call chain from application entry point to vulnerable function. Without intact witness graphs, reachability findings lack provenance, attestation of scan results is weakened, and auditors cannot verify that “unreachable” verdicts are legitimate. Incomplete or inconsistent graphs can cause incorrect reachability conclusions.

Common Causes

How to Fix

Docker Compose

# View recent construction failures
docker compose -f docker-compose.stella-ops.yml logs scanner | grep -i "witness.*fail\|graph.*error"

# Rebuild failed graphs
stella scanner witness rebuild --failed

# Check SBOM pipeline health (witness graphs depend on SBOMs)
stella doctor run --check check.scanner.sbom

Tune graph construction limits in docker-compose.stella-ops.yml:

services:
  scanner:
    environment:
      Scanner__WitnessGraph__MaxDepth: "50"
      Scanner__WitnessGraph__TimeoutMs: "30000"
      Scanner__WitnessGraph__ConsistencyCheckEnabled: "true"

Bare Metal / systemd

# View construction errors
sudo journalctl -u stellaops-scanner --since "1 hour ago" | grep -i witness

# Rebuild failed graphs
stella scanner witness rebuild --failed

# View graph statistics
stella scanner witness stats

Edit /etc/stellaops/scanner/appsettings.json:

{
  "WitnessGraph": {
    "MaxDepth": 50,
    "TimeoutMs": 30000,
    "ConsistencyCheckEnabled": true
  }
}

Kubernetes / Helm

# Check scanner logs for witness graph issues
kubectl logs -l app=stellaops-scanner --tail=200 | grep -i witness

# Rebuild failed graphs
kubectl exec -it <scanner-pod> -- stella scanner witness rebuild --failed

Set in Helm values.yaml:

scanner:
  witnessGraph:
    maxDepth: 50
    timeoutMs: 30000
    consistencyCheckEnabled: true

Verification

stella doctor run --check check.scanner.witness.graph