API Documentation

FoxIO Atlas API v0.1.0

Overview

The Vercel Sentinel API provides programmatic access to JA4+ fingerprint intelligence. Use these endpoints to ingest observations from your sensors, lookup fingerprints, and query threat campaigns.

Base URL

https://ja4-atlas.platphormnews.com

Authentication

Write endpoints require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Quick Start - Ingest Example

curl -X POST https://ja4-atlas.platphormnews.com/api/ingest/http \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "ts": 1773586478700,
    "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
    "sensor": "my-sensor",
    "env": "production",
    "path": "/api/test",
    "method": "GET",
    "ip": "203.0.113.42"
  }'

Quick Start - Lookup Example

curl "https://ja4-atlas.platphormnews.com/api/lookup?fingerprint=t13d1517h2_8daaf6152771_b0da82dd1658"

post/api/ingest/http

Ingest JA4 observation

Ingests a single JA4 fingerprint observation from a sensor. This endpoint is designed for: - Vercel Firewall middleware integration - Zeek network sensors - Custom WAF implementations - Any system that can extract JA4 fingerprints The observation will be stored and correlated with existing fingerprint data.

Example Request

From Vercel Middleware

{
  "ts": 1733260800000,
  "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
  "ja3": null,
  "sensor": "myapp-prod",
  "env": "production",
  "projectId": "prj_xxxxxxxxxxxx",
  "projectUrl": "myapp.vercel.app",
  "vercelRegion": "iad1",
  "path": "/api/users",
  "method": "GET",
  "ip": "203.0.113.42"
}

From Zeek Sensor

{
  "ts": 1733260800000,
  "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
  "ja4s": "t120300_c02b_a56c0d24d0a9",
  "sensor": "zeek-lab-1",
  "env": "lab",
  "ip": "10.0.1.50"
}

Responses

200Observation ingested successfully

401Missing or invalid authorization header

403Invalid token

500Internal server error

post/api/ingest/zeek

Ingest Zeek SSL/TLS logs

Ingest JA4 fingerprint observations from Zeek network sensors. Accepts Zeek ssl.log JSON format (either a single record or wrapped in a logs array). Timestamps may be epoch floats (Zeek native) or ISO-8601 strings.

Example Request

Zeek ssl.log batch

{
  "sensor": "zeek-prod-1",
  "log_type": "ssl",
  "logs": [
    {
      "ts": 1733260800,
      "uid": "CXKd3f1pXP5lMcHS5g",
      "id.orig_h": "192.168.1.100",
      "id.orig_p": 54321,
      "id.resp_h": "93.184.216.34",
      "id.resp_p": 443,
      "version": "TLSv13",
      "cipher": "TLS_AES_128_GCM_SHA256",
      "server_name": "example.com",
      "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
      "established": true
    }
  ]
}

Responses

200Logs ingested successfully

400Invalid payload

401Unauthorized

post/api/ingest/suricata

Ingest Suricata EVE JSON logs

Ingest JA4 fingerprint observations from Suricata IDS/IPS sensors. Accepts both standard JSON (with `events` array) and newline-delimited EVE JSON (`application/x-ndjson`). Only TLS events with JA4 data are processed.

Example Request

Suricata EVE JSON TLS event

{
  "sensor": "suricata-edge-1",
  "events": [
    {
      "timestamp": "2024-01-15T10:30:00.123456+0000",
      "event_type": "tls",
      "src_ip": "192.168.1.100",
      "src_port": 54321,
      "dest_ip": "93.184.216.34",
      "dest_port": 443,
      "tls": {
        "version": "TLS 1.3",
        "sni": "example.com",
        "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658"
      }
    }
  ]
}

Responses

200Events ingested

400Invalid payload

401Unauthorized

post/api/ingest/batch

Batch ingest observations

Ingest multiple JA4 fingerprint observations in a single request. Supports JSON, CSV, and NDJSON formats. Maximum batch size is configurable (default 1000 records). Optional deduplication flag removes duplicate fingerprints.

Example Request

JSON batch

{
  "format": "json",
  "source": "my-scanner",
  "deduplicate": true,
  "records": [
    {
      "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
      "src_ip": "192.168.1.100",
      "sensor": "lab-sensor",
      "ts": 1733260800000
    }
  ]
}

Responses

200Batch processed

400Invalid payload or batch too large

401Unauthorized

get/api/lookup

Lookup fingerprint

Lookup detailed information about a JA4 fingerprint. Returns: - Internal fingerprint data (label, severity, notes) - JA4DB enrichment (application, OS, category) - Observation statistics (total hits, first/last seen, unique IPs/sensors) - Recent observations - Associated threat campaigns

Parameters

fingerprint(query)required- JA4 fingerprint value to lookup

Responses

200Fingerprint data retrieved

400Missing fingerprint parameter

post/api/fingerprints/label

Label fingerprint

Add or update label, severity, and notes for a fingerprint.

Responses

200Fingerprint labeled successfully

get/api/stats

Get dashboard statistics

Returns overall platform statistics for the dashboard.

Responses

200Statistics retrieved

get/api/observations

List observations

Returns paginated list of raw observations from all sensors.

Parameters

page(query)- Page number (1-indexed)

limit(query)- Results per page

sensor(query)- Filter by sensor name

ja4(query)- Filter by JA4 fingerprint

Responses

200Observations retrieved

get/api/campaigns

List campaigns

Returns all threat campaigns with their associated fingerprints.

Responses

200Campaigns retrieved

get/api/infrastructure

List infrastructure

Returns tracked infrastructure (IPs, domains, ASNs, etc.).

Parameters

kind(query)- Filter by infrastructure type

Responses

200Infrastructure retrieved

get/api/health

Health check

Returns system health status including database connectivity.

Responses

200System healthy

503System unhealthy

get/api/projects

List projects

Returns all monitored Vercel projects with real-time statistics. Each project includes: - Total observations and unique fingerprints - Activity metrics (24h, 1h) - Threat indicators (critical, high counts) - Last seen timestamp

Responses

200Projects retrieved successfully

post/api/projects

Add project

Add a new Vercel project to monitor for JA4 fingerprint observations. The project_id must be a valid Vercel project ID (starts with 'prj_'). Once added, all observations from this project will be automatically correlated.

Responses

201Project created successfully

400Invalid request

409Project ID already exists

get/api/projects/{id}

Get project details

Returns detailed statistics for a specific project.

Parameters

id(path)required- Project database ID

Responses

200Project retrieved

404Project not found

patch/api/projects/{id}

Update project

Update project name, description, environment, or status.

Parameters

id(path)required- Project database ID

Responses

200Project updated

404Project not found

delete/api/projects/{id}

Delete project

Remove a project from monitoring. Observations are not deleted.

Parameters

id(path)required- Project database ID

Responses

200Project deleted

404Project not found

post/api/projects/validate

Validate project ID

Validate Vercel project ID format before adding.

Responses

200Validation result

get/api/sensors

List sensors

Returns all registered sensors with their last-seen timestamps and observation counts.

Responses

200Sensors retrieved

get/api/alerts

List alerts

Returns security alerts with optional filtering by status and severity.

Parameters

status(query)- Filter by alert status

severity(query)- Filter by severity

limit(query)- Maximum number of alerts to return

Responses

200Alerts retrieved

post/api/alerts

Create alert

Create a new security alert.

Responses

201Alert created

401Unauthorized

get/api/alerts/feed

Real-time alert feed

Returns the latest alerts for real-time dashboard display, sorted by creation time descending.

Responses

200Alert feed retrieved

get/api/actors

List threat actors

Returns all tracked threat actors with associated campaigns and fingerprints.

Responses

200Actors retrieved

post/api/actors

Create threat actor

Add a new threat actor to track.

Responses

201Actor created

401Unauthorized

get/api/actors/{id}

Get actor details

Returns detailed information about a specific threat actor including linked campaigns.

Parameters

id(path)required- Actor ID

Responses

200Actor retrieved

404Actor not found

get/api/firewall/rules

List firewall rules

Returns all configured firewall rules for automated blocking based on JA4 fingerprints.

Responses

200Firewall rules retrieved

post/api/firewall/rules

Create firewall rule

Create a new rule to block or flag traffic matching a JA4 fingerprint pattern.

Responses

201Rule created

401Unauthorized

curl -X POST https://ja4-atlas.platphormnews.com/api/ingest/http \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "ts": 1773586478700, "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658", "sensor": "my-sensor", "env": "production", "path": "/api/test", "method": "GET", "ip": "203.0.113.42" }'

{ "ts": 1733260800000, "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658", "ja3": null, "sensor": "myapp-prod", "env": "production", "projectId": "prj_xxxxxxxxxxxx", "projectUrl": "myapp.vercel.app", "vercelRegion": "iad1", "path": "/api/users", "method": "GET", "ip": "203.0.113.42" }

{ "sensor": "zeek-prod-1", "log_type": "ssl", "logs": [ { "ts": 1733260800, "uid": "CXKd3f1pXP5lMcHS5g", "id.orig_h": "192.168.1.100", "id.orig_p": 54321, "id.resp_h": "93.184.216.34", "id.resp_p": 443, "version": "TLSv13", "cipher": "TLS_AES_128_GCM_SHA256", "server_name": "example.com", "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658", "established": true } ] }

{ "sensor": "suricata-edge-1", "events": [ { "timestamp": "2024-01-15T10:30:00.123456+0000", "event_type": "tls", "src_ip": "192.168.1.100", "src_port": 54321, "dest_ip": "93.184.216.34", "dest_port": 443, "tls": { "version": "TLS 1.3", "sni": "example.com", "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658" } } ] }

{ "format": "json", "source": "my-scanner", "deduplicate": true, "records": [ { "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658", "src_ip": "192.168.1.100", "sensor": "lab-sensor", "ts": 1733260800000 } ] }