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

```csharp
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

```csharp
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

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

---

## Policy Signals

### Surface Signal Keys

```csharp
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

```csharp
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

```csharp
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

```json
{
  "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

```csharp
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 |