Skip to content

Getting Started

Get SPOT running and analyze your first email.

Install the platform

The supported install path is the operator deployment guide, which uses the deploy repository (Traefik + Let's Encrypt + pre-built images):

Deployment guide ; the single source of truth for prerequisites, DNS, environment variables, admin bootstrap, and plugin installation.

Don't clone the core repository to install SPOT

The core repo is for platform contributors only. Production and staging deployments must use the deploy repo as documented above. See the Developer guide if you intend to work on the platform itself.

Once the stack is up and you have created an admin user, the rest of this page walks you through your first email analysis via the HTTP API.

Authenticate

Trade your admin credentials for an access token:

TOKEN=$(curl -s -X POST https://api.${DOMAIN}/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=${SPOT_ADMIN_PASSWORD}" \
  | jq -r '.access_token')

Submit an email

The example below is a textbook spear-phishing attempt ; an attacker spoofing PayPal with a lookalike domain (paypaI.com, capital I) and a credential-harvesting link:

curl -X POST https://api.${DOMAIN}/api/v1/analyze \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": {
      "headers": {
        "message_id": "<test@example.com>",
        "subject": "URGENT: Verify Your Account",
        "sender": "security@paypaI.com",
        "recipients": ["user@company.com"],
        "date": "2026-01-15T10:00:00Z"
      },
      "body_text": "Click here to verify: http://suspicious-site.com"
    },
    "workflow_id": "default-workflow"
  }'

The platform queues the analysis and returns a job id:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Email analysis job queued successfully"
}

Read the verdict

Poll the same job id until the analysis is done:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.${DOMAIN}/api/v1/analyze/550e8400-e29b-41d4-a716-446655440000

The completed verdict carries the platform's call, the indicators that drove it, and a recommended action. The full schema lives in the API reference; the fields most operators read first are:

  • threat_level ; one of safe, low, medium, high, critical.
  • confidence_score ; the platform's confidence in the verdict, 0.0–1.0.
  • threat_indicators ; the analyzer findings that drove the verdict.
  • recommended_action ; what SPOT suggests doing with the message.

Threat levels

Level Description Recommended action
safe No threats detected Allow
low Minor suspicious elements Monitor
medium Potentially harmful Review
high Likely spear-phishing Block
critical Definite spear-phishing Block + alert

What the indicators look like

Each installed analyzer contributes its own indicators when it sees something notable. The exact catalogue depends on which analyzers are installed and how the workflow is configured ; the Plugins page lists each analyzer's outputs. Common ones include:

  • Sender ; sender_spoofing, domain_mismatch, no_spf.
  • Content ; urgent_language, threatening_tone, suspicious_link, credential_request.
  • Technical ; unusual_headers, attachment_threat, encoding_anomaly.

Next steps