Developer Documentation

# Include the key in every request
curl https://app.surge.security/api/v1/ping \
  -H "X-API-Key: surge_a1b2c3d4e5f6..."

# Create a webhook subscription
curl -X POST https://app.surge.security/settings/webhooks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["investigation.completed", "finding.signal"]
  }'

{
  "id": "7",
  "url": "https://your-server.com/webhook",
  "events": ["investigation.completed", "finding.signal"],
  "secret": "a1b2c3d4...your_webhook_secret...e5f6",
  "created_at": "2025-06-15T12:00:00+00:00"
}

{
  "event": "investigation.completed",
  "timestamp": "2025-06-15T10:45:22+00:00",
  "delivery_id": "d4e5f6a7-b8c9-1234-5678-abcdef012345",
  "data": {
    "investigation_id": "1234",
    "hostname": "WORKSTATION-01",
    "verdict": "malicious",
    "severity": "HIGH",
    "confidence": "high",
    "mitre_techniques": ["T1059.001", "T1053.005"]
  }
}

// data payload
{
  investigation_id: string;
  hostname: string;
  operating_system: string;
  verdict: "malicious" | "review" | "benign";
  severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
  confidence: "high" | "medium" | "low";
  maliciousness_score: number;       // 0-100
  triage_priority: string;           // P1, P2, P3, P4
  mitre_techniques: string[];        // e.g. ["T1059.001"]
  signal_count: number;
  noise_count: number;
  analysis_duration_formatted: string;
}

// data payload
{
  investigation_id: string;
  hostname: string;
  finding_title: string;
  description: string;
  outcome: "signal";
  severity: string;
  mitre_techniques: string[];
  evidence: string[];
}

// data payload
{
  endpoint_id: string;
  hostname: string;
  operating_system: string;
  created_at: string;              // ISO-8601
}

// data payload
{
  scan_id: string;
  endpoint_id: string;
  hostname: string;
  status: "completed" | "drift_detected";
  drift_summary?: string;
}

import hmac
import hashlib
from datetime import datetime, timezone, timedelta

def verify_surge_webhook(body: bytes, headers: dict, secret: str) -> bool:
    """Verify a SURGE webhook signature."""
    signature = headers.get("X-Surge-Signature", "")
    timestamp = headers.get("X-Surge-Timestamp", "")

    if not signature.startswith("sha256="):
        return False

    # Check timestamp freshness (prevent replay attacks)
    try:
        ts = datetime.fromisoformat(timestamp)
        if abs((datetime.now(timezone.utc) - ts).total_seconds()) > 300:
            return False
    except ValueError:
        return False

    # Reconstruct the signing payload
    sign_payload = f"{timestamp}.{body.decode('utf-8')}".encode()
    expected = hmac.new(
        secret.encode("utf-8"),
        sign_payload,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)

const crypto = require('crypto');

function verifySurgeWebhook(rawBody, headers, secret) {
  const signature = headers['x-surge-signature'] || '';
  const timestamp = headers['x-surge-timestamp'] || '';

  if (!signature.startsWith('sha256=')) return false;

  // Check timestamp freshness
  const ts = new Date(timestamp);
  if (Math.abs(Date.now() - ts.getTime()) > 300_000) return false;

  // Reconstruct the signing payload
  const signPayload = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

// Express.js example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySurgeWebhook(req.body, req.headers, process.env.SURGE_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  console.log('Verified event:', event.event, event.data);
  res.status(200).send('OK');
});

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"math"
	"net/http"
	"strings"
	"time"
)

func verifySurgeWebhook(body []byte, r *http.Request, secret string) bool {
	signature := r.Header.Get("X-Surge-Signature")
	timestamp := r.Header.Get("X-Surge-Timestamp")

	if !strings.HasPrefix(signature, "sha256=") {
		return false
	}

	// Check timestamp freshness
	ts, err := time.Parse(time.RFC3339, timestamp)
	if err != nil {
		return false
	}
	if math.Abs(time.Since(ts).Seconds()) > 300 {
		return false
	}

	// Reconstruct the signing payload
	signPayload := fmt.Sprintf("%s.%s", timestamp, string(body))
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(signPayload))
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

	return hmac.Equal([]byte(expected), []byte(signature))
}

import requests
from datetime import datetime, timezone

SURGE_API = "https://app.surge.security/api/v1"
API_KEY = "surge_your_key_here"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Track your last poll timestamp
last_poll = "2025-06-01T00:00:00Z"

# Poll for new findings since last sync
response = requests.post(
    f"{SURGE_API}/findings",
    headers=HEADERS,
    json={
        "created_after": last_poll,
        "per_page": 200,
    },
)
data = response.json()
for finding in data["findings"]:
    # Ingest into your SIEM
    print(f"[{finding['severity']}] {finding['hostname']}: {finding['title']}")

# Update last_poll for next iteration
last_poll = datetime.now(timezone.utc).isoformat()

# Get CEF-formatted findings for a specific investigation
curl -s "https://app.surge.security/api/v1/investigations/1234/findings?format=cef" \
  -H "X-API-Key: surge_your_key_here"

CEF:0|SURGE|SecurityForensics|1.1.0|finding|PowerShell Encoded Command|7|src=WORKSTATION-01 cs1=1234 cs1Label=InvestigationID cs2=signal cs2Label=Outcome cs3=confirmed cs3Label=Status cs4=T1059.001 T1027 cs4Label=MitreTechniques msg=Encoded PowerShell command detected...

{
  "detail": "Scope 'read' required"
}