Semantic Entrypoint Schema

Part of Sprint 0411 - Semantic Entrypoint Engine (Task 23)

This document defines the schema for semantic entrypoint analysis, which enriches container scan results with application-level intent, capabilities, and threat modeling.

Current composition (verified 2026-07-19): The schema, analyzers, and in-memory temporal diff are library capabilities. The production Scanner Worker registers AddEntryTraceAnalyzer(), not AddSemanticEntryTraceAnalyzer(), and does not persist or emit semantic or temporal results. The CLI, SBOM, and RichGraph sections below describe the intended integration contract, not a currently reachable production path.

Overview

The Semantic Entrypoint Engine analyzes container entrypoints to infer:

1. Application Intent - What kind of application is running (web server, worker, CLI, etc.)
2. Capabilities - What system resources the application accesses (network, filesystem, database, etc.)
3. Attack Surface - Potential security threat vectors based on capabilities
4. Data Boundaries - Data flow boundaries with sensitivity classification

This semantic layer enables more precise vulnerability prioritization by understanding which code paths are actually reachable from the entrypoint.

Schema Definitions

SemanticEntrypoint

The root type representing semantic analysis of an entrypoint.

interface SemanticEntrypoint {
  id: string;                        // Unique identifier for this analysis
  specification: EntrypointSpecification;
  intent: ApplicationIntent;
  capabilities: CapabilityClass;     // Bitmask of detected capabilities
  attackSurface: ThreatVector[];
  dataBoundaries: DataFlowBoundary[];
  confidence: SemanticConfidence;
  language?: string;                 // Primary language (python, java, node, dotnet, go)
  framework?: string;                // Detected framework (django, spring-boot, express, etc.)
  frameworkVersion?: string;
  runtimeVersion?: string;
  analyzedAt: string;                // ISO-8601 timestamp
}

ApplicationIntent

Enumeration of application types.

CapabilityClass (Bitmask)

Flags indicating detected capabilities. Multiple flags can be combined.

ThreatVector

Represents a potential attack vector.

interface ThreatVector {
  type: ThreatVectorType;
  confidence: number;                // 0.0 to 1.0
  contributingCapabilities: CapabilityClass;
  evidence: string[];
  cweId?: number;                    // CWE identifier
  owaspCategory?: string;            // OWASP category
}

ThreatVectorType

DataFlowBoundary

Represents a data flow boundary crossing.

interface DataFlowBoundary {
  type: DataFlowBoundaryType;
  direction: DataFlowDirection;      // Inbound | Outbound | Bidirectional
  sensitivity: DataSensitivity;      // Public | Internal | Confidential | Restricted
  confidence: number;
  port?: number;                     // For network boundaries
  protocol?: string;                 // http, grpc, amqp, etc.
  evidence: string[];
}

DataFlowBoundaryType

SemanticConfidence

Confidence scoring for semantic analysis.

interface SemanticConfidence {
  score: number;                     // 0.0 to 1.0
  tier: ConfidenceTier;
  reasons: string[];
}

enum ConfidenceTier {
  Unknown = 0,
  Low = 1,
  Medium = 2,
  High = 3,
  Definitive = 4
}

SBOM Property Extensions

When semantic data is included in CycloneDX or SPDX SBOMs, the following property namespace is used:

stellaops:semantic.*

Property Names

RichGraph Integration

Semantic data is attached to richgraph-v1 nodes via the Attributes dictionary:

Language Adapter Support

The following language-specific adapters are available:

Configuration

Semantic analysis is configured via the Scanner:EntryTrace:Semantic configuration section:

Scanner:
  EntryTrace:
    Semantic:
      Enabled: true
      ThreatConfidenceThreshold: 0.3
      MaxThreatVectors: 50
      IncludeLowConfidenceCapabilities: false
      EnabledLanguages: []  # Empty = all languages

Determinism Guarantees

All semantic analysis outputs are deterministic:

1. Entrypoint identity - SHA-256 over language, working directory, ENTRYPOINT, and CMD; image digest is deliberately excluded so the same logical entrypoint retains its identity across image versions.
2. Capability ordering - Flags are ordered by value (bitmask position)
3. Threat vector ordering - Ordered by ThreatVectorType enum value
4. Data boundary ordering - Ordered by (Type, Direction) tuple
5. Evidence ordering - Alphabetically sorted within each element
6. JSON serialization - Uses camelCase naming, consistent formatting

This enables reliable diffing of semantic analysis results across scan runs.

CLI Usage

Semantic analysis can be enabled via the CLI --semantic flag:

stella scan --semantic docker.io/library/python:3.12

Output includes semantic summary when enabled:

Semantic Analysis:
  Intent: WebServer
  Framework: flask (v3.0.0)
  Capabilities: NetworkListen, DatabaseSql, FileRead
  Threat Vectors: 2 (SqlInjection, Ssrf)
  Risk Score: 0.72
  Confidence: High (0.85)

References

• OWASP Top 10 2021
• CWE/SANS Top 25
• CycloneDX Property Extensions
• SPDX 3.0 External Identifiers