git.stella-ops.org/docs/contracts/scanner-surface.md

CONTRACT-SCANNER-SURFACE-014: Scanner Surface Analysis Framework

Status: Published Version: 1.0.0 Published: 2025-12-05 Owners: Scanner Guild Unblocks: SCANNER-SURFACE-01

Overview

This contract defines the Scanner Surface analysis framework scope, providing the task definition and contract required for implementing comprehensive attack surface analysis across scanner modules.

Scope

SCANNER-SURFACE-01 establishes the foundational surface analysis patterns that integrate:

• Entry point discovery across language analyzers
• Attack surface enumeration and classification
• Policy signal emission for surface findings
• Integration with Surface.FS, Surface.Env, and Surface.Secrets

---

Surface Analysis Model

Surface Types

Type	Description	Detection Method
Network	Exposed ports, listeners, endpoints	EntryTrace, config analysis
File	Sensitive file access, path traversal	VFS analysis, permission checks
Process	Command execution, subprocess spawn	Call graph, runtime trace
Crypto	Key/secret handling, weak algorithms	Pattern matching, API usage
Auth	Authentication bypass, session handling	Framework detection, config
Input	User input handling, injection points	Data flow analysis

Surface Entry

public record SurfaceEntry
{
    public string Id { get; init; }  // SHA256(type|path|context)
    public SurfaceType Type { get; init; }
    public string Path { get; init; }  // File path or endpoint
    public string Context { get; init; }  // Function/method context
    public ConfidenceLevel Confidence { get; init; }
    public IReadOnlyList<string> Tags { get; init; }
    public SurfaceEvidence Evidence { get; init; }
}

public enum SurfaceType
{
    NetworkEndpoint,
    FileOperation,
    ProcessExecution,
    CryptoOperation,
    AuthenticationPoint,
    InputHandling,
    SecretAccess,
    ExternalCall
}

---

Integration Points

Surface.FS Integration

public interface ISurfaceManifestWriter
{
    Task WriteSurfaceEntriesAsync(
        string scanId,
        IEnumerable<SurfaceEntry> entries,
        CancellationToken ct);
}

Surface.Env Integration

Environment configuration for surface analysis:

STELLA_SURFACE_ENABLED=true
STELLA_SURFACE_DEPTH=3          # Call graph depth
STELLA_SURFACE_CONFIDENCE=0.7   # Minimum confidence threshold
STELLA_SURFACE_CACHE_ROOT=/var/cache/stella/surface

Surface.Secrets Integration

public interface ISurfaceSecretScanner
{
    IAsyncEnumerable<SecretFinding> ScanAsync(
        IPhysicalFileProvider files,
        SecretScanOptions options,
        CancellationToken ct);
}

---

Policy Signals

Surface Signal Keys

public static class SurfaceSignalKeys
{
    public const string NetworkEndpoints = "surface.network.endpoints";
    public const string ExposedPorts = "surface.network.ports";
    public const string FileOperations = "surface.file.operations";
    public const string ProcessSpawns = "surface.process.spawns";
    public const string CryptoUsage = "surface.crypto.usage";
    public const string AuthPoints = "surface.auth.points";
    public const string InputHandlers = "surface.input.handlers";
    public const string SecretAccess = "surface.secrets.access";
    public const string TotalSurfaceArea = "surface.total.area";
}

Signal Emission

public interface ISurfaceSignalEmitter
{
    Task EmitAsync(
        string scanId,
        IDictionary<string, object> signals,
        CancellationToken ct);
}

---

Entry Point Discovery

Language Analyzer Integration

Each language analyzer contributes surface entries:

Analyzer	Entry Points
.NET	Controllers, Minimal APIs, SignalR hubs
Java	Servlets, JAX-RS resources, Spring MVC
Node	Express routes, Fastify handlers
Python	Flask/Django views, FastAPI endpoints
Go	HTTP handlers, gRPC services
PHP	Routes, controller actions
Deno	HTTP handlers, permissions

Entry Point Model

public record EntryPoint
{
    public string Id { get; init; }
    public string Language { get; init; }
    public string Framework { get; init; }
    public string Path { get; init; }  // URL path or route
    public string Method { get; init; }  // HTTP method or RPC
    public string Handler { get; init; }  // Function/method name
    public string File { get; init; }
    public int Line { get; init; }
    public IReadOnlyList<string> Parameters { get; init; }
    public IReadOnlyList<string> Middlewares { get; init; }
}

---

Output Schema

Surface Analysis Result

{
  "scanId": "scan-abc123",
  "timestamp": "2025-12-05T12:00:00Z",
  "summary": {
    "totalEntries": 42,
    "byType": {
      "NetworkEndpoint": 15,
      "FileOperation": 10,
      "ProcessExecution": 5,
      "CryptoOperation": 8,
      "SecretAccess": 4
    },
    "riskScore": 0.65
  },
  "entries": [
    {
      "id": "sha256:...",
      "type": "NetworkEndpoint",
      "path": "/api/users",
      "context": "UserController.GetUsers",
      "confidence": 0.95,
      "evidence": {
        "file": "src/Controllers/UserController.cs",
        "line": 42,
        "hash": "sha256:..."
      }
    }
  ]
}

Analysis Store Key

public const string SurfaceAnalysisKey = "scanner.surface.analysis";

---

Determinism Requirements

1. Stable IDs: Entry IDs computed as SHA256(type|path|context)
2. Sorted Output: Entries sorted by ID
3. Reproducible Hashes: Content hashes use BLAKE3
4. Canonical JSON: Output serialized with sorted keys

---

Implementation Phases

Phase 1: Core Framework

• Define SurfaceEntry model
• Implement entry point collector registry
• Add Surface.FS manifest writer integration
• Basic policy signal emission

Phase 2: Language Integration

• Wire .NET entry point discovery
• Wire Java entry point discovery
• Wire Node entry point discovery
• Wire Python entry point discovery

Phase 3: Advanced Analysis

• Data flow tracking
• Secret pattern detection
• Crypto usage analysis
• Attack path enumeration

---

Project Structure

src/Scanner/__Libraries/StellaOps.Scanner.Surface/
├── StellaOps.Scanner.Surface.csproj
├── Models/
│   ├── SurfaceEntry.cs
│   ├── SurfaceType.cs
│   └── EntryPoint.cs
├── Discovery/
│   ├── ISurfaceEntryCollector.cs
│   └── SurfaceEntryRegistry.cs
├── Signals/
│   └── SurfaceSignalEmitter.cs
├── Output/
│   └── SurfaceAnalysisWriter.cs
└── README.md

---

Dependencies

• StellaOps.Scanner.Surface.FS - Manifest storage
• StellaOps.Scanner.Surface.Env - Environment configuration
• StellaOps.Scanner.Surface.Secrets - Secret detection
• StellaOps.Scanner.EntryTrace - Entry point tracing

---

Changelog

Version	Date	Author	Changes
1.0.0	2025-12-05	Scanner Guild	Initial contract