Semantic Entrypoint Analysis

The Semantic Entrypoint Engine is the layer that runs after entry-point resolution: once EntryTrace has identified the program a container actually runs, the semantic engine infers what that program does and how it is exposed. This guide is the reference for its schema, language adapters, and integration points. Audience: engineers consuming semantic fields (in SBOM/RichGraph output) or extending the engine with new adapters and capabilities.

Current composition (verified 2026-07-19): This post-resolution pipeline is implemented and tested as a library but is not called by the production Scanner Worker. The Worker registers the base EntryTrace analyzer only; it does not persist temporal snapshots or emit semantic fields in scan reports. The integration and CLI examples below are target contracts until that production composition is implemented.

Overview

The Semantic Entrypoint Engine provides a deeper understanding of container entrypoints by inferring:

• Application intent — what the application is designed to do (web server, CLI tool, worker, etc.).
• Capabilities — which system resources and external services the application uses.
• Attack surface — potential security weaknesses implied by the detected patterns.
• Data boundaries — the I/O edges where data enters or leaves the application.

This semantic layer feeds more accurate vulnerability prioritization, reachability analysis, and policy decisioning. It builds on the resolved entry point produced by the static and dynamic reducers.

Schema Definition

SemanticEntrypoint Record

The core output of semantic analysis:

public sealed record SemanticEntrypoint
{
    public required string Id { get; init; }
    public required EntrypointSpecification Specification { get; init; }
    public required ApplicationIntent Intent { get; init; }
    public required CapabilityClass Capabilities { get; init; }
    public required ImmutableArray<ThreatVector> AttackSurface { get; init; }
    public required ImmutableArray<DataFlowBoundary> DataBoundaries { get; init; }
    public required SemanticConfidence Confidence { get; init; }
    public string? Language { get; init; }
    public string? Framework { get; init; }
    public string? FrameworkVersion { get; init; }
    public string? RuntimeVersion { get; init; }
    public ImmutableDictionary<string, string>? Metadata { get; init; }
}

Application Intent

Enumeration of recognized application types:

Capability Classes

Flags enum representing detected capabilities:

Threat Vectors

Inferred security threats:

Data Flow Boundaries

I/O edges for data flow analysis:

Confidence Scoring

All inferences include confidence scores:

public sealed record SemanticConfidence
{
    public double Score { get; init; }           // 0.0-1.0
    public ConfidenceTier Tier { get; init; }    // Unknown, Low, Medium, High, Definitive
    public ImmutableArray<string> ReasoningChain { get; init; }
}

Language Adapters

Semantic analysis uses language-specific adapters:

Python Adapter

• Django: Detects manage.py, INSTALLED_APPS, migrations
• Flask/FastAPI: Detects Flask(__name__), FastAPI() patterns
• Celery: Detects Celery() app, @task decorators
• Click/Typer: Detects CLI decorators
• Lambda: Detects lambda_handler pattern

Java Adapter

• Spring Boot: Detects @SpringBootApplication, starter dependencies
• Quarkus: Detects io.quarkus packages
• Kafka Streams: Detects kafka-streams dependency
• Main-Class: Falls back to manifest analysis

Node Adapter

• Express: Detects express() + listen()
• NestJS: Detects @nestjs/core dependency
• Fastify: Detects fastify() patterns
• CLI bin: Detects bin field in package.json

.NET Adapter

• ASP.NET Core: Detects Microsoft.AspNetCore references
• Worker Service: Detects BackgroundService inheritance
• Console: Detects OutputType=Exe without web deps

Go Adapter

• net/http: Detects http.ListenAndServe patterns
• Cobra: Detects github.com/spf13/cobra import
• gRPC: Detects google.golang.org/grpc import

Integration Points

Entry Trace Pipeline

Semantic analysis integrates after entry trace resolution:

Container Image
     ↓
EntryTraceAnalyzer.ResolveAsync()
     ↓
EntryTraceGraph (nodes, edges, terminals)
     ↓
SemanticEntrypointOrchestrator.AnalyzeAsync()
     ↓
SemanticEntrypoint (intent, capabilities, threats)

SBOM Output

Semantic data appears in CycloneDX properties:

{
  "properties": [
    { "name": "stellaops:semantic.intent", "value": "WebServer" },
    { "name": "stellaops:semantic.capabilities", "value": "NetworkListen,DatabaseSql" },
    { "name": "stellaops:semantic.threats", "value": "[{\"type\":\"SqlInjection\",\"confidence\":0.7}]" },
    { "name": "stellaops:semantic.risk.score", "value": "0.7" },
    { "name": "stellaops:semantic.framework", "value": "django" }
  ]
}

RichGraph Output

Semantic attributes on entrypoint nodes:

{
  "kind": "entrypoint",
  "attributes": {
    "semantic_intent": "WebServer",
    "semantic_capabilities": "NetworkListen,DatabaseSql,UserInput",
    "semantic_threats": "SqlInjection,Xss",
    "semantic_risk_score": "0.7",
    "semantic_confidence": "0.85",
    "semantic_confidence_tier": "High"
  }
}

Usage Examples

CLI Usage

# Scan with semantic analysis
stella scan myimage:latest --semantic

# Output includes semantic fields
stella scan myimage:latest --format json | jq '.semantic'

Programmatic Usage

// Create orchestrator
var orchestrator = new SemanticEntrypointOrchestrator();

// Create context from entry trace result
var context = orchestrator.CreateContext(entryTraceResult, fileSystem, containerMetadata);

// Run analysis
var result = await orchestrator.AnalyzeAsync(context);

if (result.Success && result.Entrypoint is not null)
{
    Console.WriteLine($"Intent: {result.Entrypoint.Intent}");
    Console.WriteLine($"Capabilities: {result.Entrypoint.Capabilities}");
    Console.WriteLine($"Risk Score: {result.Entrypoint.AttackSurface.Max(t => t.Confidence)}");
}

Extending the Engine

Adding a New Language Adapter

1. Implement ISemanticEntrypointAnalyzer:

public sealed class RubySemanticAdapter : ISemanticEntrypointAnalyzer
{
    public IReadOnlyList<string> SupportedLanguages => new[] { "ruby" };
    public int Priority => 100;

    public ValueTask<SemanticEntrypoint> AnalyzeAsync(
        SemanticAnalysisContext context,
        CancellationToken cancellationToken)
    {
        // Detect Rails, Sinatra, Sidekiq, etc.
    }
}

2. Register in SemanticEntrypointOrchestrator.CreateDefaultAdapters().

Adding a New Capability

1. Add to CapabilityClass flags enum
2. Update CapabilityDetector with detection patterns
3. Update ThreatVectorInferrer if capability contributes to threats
4. Update DataBoundaryMapper if capability implies I/O boundaries

Related Documentation

• Entry-point detection index
• Entry-point problem & architecture
• Static analysis approach
• Language-specific guides (Python example)
• Reachability evidence