Add unit tests for RabbitMq and Udp transport servers and clients
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented comprehensive unit tests for RabbitMqTransportServer, covering constructor, disposal, connection management, event handlers, and exception handling. - Added configuration tests for RabbitMqTransportServer to validate SSL, durable queues, auto-recovery, and custom virtual host options. - Created unit tests for UdpFrameProtocol, including frame parsing and serialization, header size validation, and round-trip data preservation. - Developed tests for UdpTransportClient, focusing on connection handling, event subscriptions, and exception scenarios. - Established tests for UdpTransportServer, ensuring proper start/stop behavior, connection state management, and event handling. - Included tests for UdpTransportOptions to verify default values and modification capabilities. - Enhanced service registration tests for Udp transport services in the dependency injection container.
This commit is contained in:
master
282
docs/contracts/scanner-surface.md
Normal file
282
docs/contracts/scanner-surface.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user