stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
afa23fc504c8c82b3aaf694e37a0df9d9f6e087c
git.stella-ops.org/src/Unknowns/AGENTS.md

4.4 KiB
Raw Blame History

Unknowns Module - Agent Guidelines

Module Overview

The Unknowns module tracks ambiguities discovered during vulnerability scanning that cannot be definitively resolved. It uses bitemporal semantics to enable point-in-time compliance queries and full audit trails.

Key Concepts

Bitemporal Data Model

The module uses two time dimensions:

  • Valid time (valid_from, valid_to): When the unknown was relevant in the real world
  • System time (sys_from, sys_to): When the system recorded/knew about the unknown

This enables queries like:

  • "What unknowns existed on January 1st?" (valid time query)
  • "What did we know about unknowns on January 1st, as of January 15th?" (bitemporal query)

Unknown Types

Kind Description
MissingSbom SBOM is missing for a component
AmbiguousPackage Package reference is ambiguous
MissingFeed No vulnerability feed covers this component
UnresolvedEdge Dependency edge cannot be resolved
NoVersionInfo No version information available
UnknownEcosystem Ecosystem is not recognized
PartialMatch Only partial match found
VersionRangeUnbounded Version range is unbounded
UnsupportedFormat Format is not supported
TransitiveGap Gap in transitive dependency chain

Resolution Types

Type Description
FeedUpdated Vulnerability feed was updated to cover the component
SbomProvided SBOM was provided for the component
ManualMapping Manual mapping was created
Superseded Superseded by another unknown or finding
FalsePositive Determined to be a false positive
WontFix Acknowledged but not going to be fixed

Directory Structure

src/Unknowns/
????????? __Libraries/
???   ????????? StellaOps.Unknowns.Core/
???   ???   ????????? Models/
???   ???   ???   ????????? Unknown.cs           # Domain model and enums
???   ???   ????????? Repositories/
???   ???       ????????? IUnknownRepository.cs # Repository interface
???   ????????? StellaOps.Unknowns.Storage.Postgres/
???       ????????? Migrations/
???       ???   ????????? 001_initial_schema.sql  # Bitemporal schema
???       ????????? Repositories/
???           ????????? PostgresUnknownRepository.cs
????????? __Tests/
    ????????? StellaOps.Unknowns.Storage.Postgres.Tests/
        ????????? PostgresUnknownRepositoryTests.cs

Database Schema

Key Tables

  • unknowns.unknown - Main bitemporal table with RLS
  • Views: unknowns.current, unknowns.resolved
  • Functions: unknowns.as_of(), unknowns.count_by_kind(), unknowns.count_by_severity()

Row-Level Security

The module uses RLS for tenant isolation:

SELECT set_config('app.tenant_id', 'my-tenant', false);
SELECT * FROM unknowns.unknown; -- Only returns rows for my-tenant

Coding Guidelines

Creating Unknowns

var unknown = await repository.CreateAsync(
    tenantId: "my-tenant",
    subjectType: UnknownSubjectType.Package,
    subjectRef: "pkg:npm/lodash@4.17.21",
    kind: UnknownKind.MissingFeed,
    severity: UnknownSeverity.Medium,
    context: """{"ecosystem": "npm"}""",
    sourceScanId: scanId,
    sourceGraphId: null,
    sourceSbomDigest: null,
    createdBy: "scanner",
    cancellationToken);

Resolving Unknowns

var resolved = await repository.ResolveAsync(
    tenantId,
    unknownId,
    ResolutionType.FeedUpdated,
    resolutionRef: "nvd-feed-2025-01",
    resolutionNotes: "NVD now covers this package",
    resolvedBy: "feed-sync",
    cancellationToken);

Point-in-Time Queries

// What unknowns existed on a specific date?
var historicalUnknowns = await repository.AsOfAsync(
    tenantId,
    validAt: new DateTimeOffset(2025, 1, 1, 0, 0, 0, TimeSpan.Zero),
    cancellationToken: ct);

Testing

Run tests with:

dotnet test src/Unknowns/__Tests/StellaOps.Unknowns.Storage.Postgres.Tests

Tests use Testcontainers for PostgreSQL integration testing.

Related Documentation

  • docs/operations/postgresql-patterns-runbook.md - Operational guide
  • docs-archived/implplan/SPRINT_3420_0001_0001_bitemporal_unknowns_schema.md - Sprint spec
  • devops/database/postgres/validation/001_validate_rls.sql - RLS validation

Service Endpoints