Surface Drift Detection¶

Captures point-in-time snapshots of an application's attack surface and compares them to detect changes: new endpoints, removed pages, modified headers, technology updates, and certificate changes.

What a snapshot captures¶

Each snapshot records:

Endpoints: all URLs discovered during the engagement (from app-map.json and discovery output)
Headers: security-relevant response headers (CSP, HSTS, CORS, X-Frame-Options, ...)
Technologies: detected tech stack (frameworks, servers, languages)
Certificates: TLS certificate details (issuer, expiry, SANs)

The snapshot is stored in the database with an endpoint count and timestamp.

API endpoints¶

Create snapshot¶

POST /api/v1/surface/engagements/{engagement_name}/snapshot

Reads the engagement directory, builds a snapshot from current data, and stores it. Returns the snapshot metadata.

Response (SurfaceSnapshotResponse):

{
  "id": 12,
  "engagement_ref": "acme-2026-q1",
  "snapshot_type": "full",
  "endpoint_count": 247,
  "created_at": "2026-03-15T14:30:00Z"
}

List snapshots¶

GET /api/v1/surface/engagements/{engagement_name}/snapshots

Returns all snapshots for an engagement, newest first.

Compare two snapshots¶

GET /api/v1/surface/diff?old_snapshot_id=10&new_snapshot_id=12

Response (SurfaceDiffResult):

{
  "old_snapshot_id": 10,
  "new_snapshot_id": 12,
  "old_date": "2026-01-15T10:00:00Z",
  "new_date": "2026-03-15T14:30:00Z",
  "total_changes": 7,
  "endpoints_added": 3,
  "endpoints_removed": 1,
  "headers_changed": 2,
  "tech_changed": 1,
  "changes": [
    {
      "change_type": "added",
      "category": "endpoint",
      "item": "/api/v2/users/export",
      "old_value": null,
      "new_value": "GET 200"
    },
    {
      "change_type": "modified",
      "category": "header",
      "item": "Content-Security-Policy",
      "old_value": "default-src 'self'",
      "new_value": "default-src 'self' cdn.example.com"
    }
  ]
}

Compare across engagements¶

GET /api/v1/surface/diff/engagements?old_engagement=acme-2025-q4&new_engagement=acme-2026-q1

Compares the latest snapshot from each engagement. Useful for quarterly retest comparisons.

Change categories¶

Category	What it tracks	Why it matters
`endpoint`	Added/removed URLs	New endpoints = new attack surface
`header`	Security header changes	Weakened CSP = potential XSS
`cert`	Certificate changes	Expiry, new SANs, issuer change
`tech`	Technology stack changes	Framework upgrade may fix or introduce vulns

CLI equivalent¶

The /surface-scan skill performs a lightweight Phase 0 + 0.5 and creates a snapshot for drift detection without running a full engagement.

Connections to other features¶

Continuous Monitoring: the monitoring scheduler can trigger periodic surface scans. When a change is detected, it creates a new snapshot and fires a surface_changed webhook event
Webhooks: surface changes trigger the surface_changed event, which can notify teams via Slack, Teams, or SIEM that the attack surface has shifted
Compliance Mapping: a surface drift that removes a security header may create a new compliance gap on the next assessment