Statistics & Queries

The statistics and query endpoints provide advanced analytics over the Threat Cloud dataset. Use these for dashboards, reporting, and threat research.

GET /api/stats

Returns enhanced statistics about the Threat Cloud database.

curl -X GET "https://tc.panguard.ai/api/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "totalIocs": 48923,
    "activeIocs": 12456,
    "totalSightings": 892341,
    "totalSources": 342,
    "byType": {
      "ip": 32100,
      "domain": 8923,
      "hash": 5400,
      "url": 1800,
      "email": 500,
      "cve": 200
    },
    "byCategory": {
      "bruteforce": 15200,
      "malware": 12300,
      "botnet": 8400,
      "phishing": 5600,
      "scanner": 4200,
      "c2": 2100,
      "exploit": 1123
    },
    "last24h": {
      "newIocs": 234,
      "newSightings": 4521,
      "topCategory": "bruteforce"
    },
    "updatedAt": "2026-03-07T12:00:00.000Z"
  }
}

GET /api/query/timeseries

Returns time-series data for threat activity, suitable for charting.

granularity

string

default:"day"

Time bucket size: hour, day, or week.

period

string

default:"30d"

Time range: 24h, 7d, 30d, 90d.

type

string

Filter by IoC type.

GET /api/query/geo

Returns geographic distribution of threat sources.

type

string

Filter by IoC type (primarily useful for ip).

period

string

default:"30d"

Time range: 24h, 7d, 30d, 90d.

limit

number

default:"20"

Number of countries to return.

curl -X GET "https://tc.panguard.ai/api/query/geo?period=7d&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "period": "7d",
    "countries": [
      { "code": "CN", "name": "China", "count": 8923, "percentage": 28.4 },
      { "code": "US", "name": "United States", "count": 5210, "percentage": 16.6 },
      { "code": "RU", "name": "Russia", "count": 4100, "percentage": 13.1 },
      { "code": "BR", "name": "Brazil", "count": 2890, "percentage": 9.2 },
      { "code": "VN", "name": "Vietnam", "count": 2100, "percentage": 6.7 },
      { "code": "IN", "name": "India", "count": 1850, "percentage": 5.9 },
      { "code": "KR", "name": "South Korea", "count": 1420, "percentage": 4.5 },
      { "code": "DE", "name": "Germany", "count": 1100, "percentage": 3.5 },
      { "code": "TW", "name": "Taiwan", "count": 980, "percentage": 3.1 },
      { "code": "NL", "name": "Netherlands", "count": 870, "percentage": 2.8 }
    ],
    "total": 31400
  }
}

GET /api/query/trends

Returns emerging threat trends based on IoC velocity and pattern analysis.

periodDays

number

default:"7"

Number of days to analyze for trend detection.

minChange

number

default:"10"

Minimum percentage change to qualify as a trend.

curl -X GET "https://tc.panguard.ai/api/query/trends?periodDays=7" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "periodDays": 7,
    "trends": [
      {
        "category": "bruteforce",
        "direction": "increasing",
        "changePercent": 45.2,
        "currentRate": 2100,
        "previousRate": 1446,
        "description": "SSH brute-force activity surging, primarily from CN and VN ranges"
      },
      {
        "category": "phishing",
        "direction": "increasing",
        "changePercent": 23.8,
        "currentRate": 890,
        "previousRate": 719,
        "description": "New phishing kit targeting financial services identified"
      },
      {
        "category": "scanner",
        "direction": "decreasing",
        "changePercent": -15.3,
        "currentRate": 1200,
        "previousRate": 1417,
        "description": "Port scanning activity declining after major botnet takedown"
      }
    ],
    "emergingThreats": [
      {
        "indicator": "CVE-2026-1234",
        "type": "cve",
        "firstSeen": "2026-03-05T00:00:00Z",
        "velocity": "rapid",
        "sightingsLast24h": 342
      }
    ]
  }
}

GET /api/query/mitre-heatmap

Returns a MITRE ATT&CK framework heatmap showing technique frequency across observed threats.

period

string

default:"30d"

Time range: 7d, 30d, 90d.

curl -X GET "https://tc.panguard.ai/api/query/mitre-heatmap?period=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "period": "30d",
    "techniques": [
      {
        "id": "T1110",
        "name": "Brute Force",
        "tactic": "Credential Access",
        "count": 15200,
        "intensity": "critical"
      },
      {
        "id": "T1059",
        "name": "Command and Scripting Interpreter",
        "tactic": "Execution",
        "count": 8900,
        "intensity": "high"
      },
      {
        "id": "T1078",
        "name": "Valid Accounts",
        "tactic": "Persistence",
        "count": 5400,
        "intensity": "high"
      },
      {
        "id": "T1566",
        "name": "Phishing",
        "tactic": "Initial Access",
        "count": 3200,
        "intensity": "medium"
      },
      {
        "id": "T1204",
        "name": "User Execution",
        "tactic": "Execution",
        "count": 2100,
        "intensity": "medium"
      }
    ],
    "tactics": {
      "Initial Access": 5300,
      "Execution": 11000,
      "Persistence": 5400,
      "Credential Access": 15200,
      "Discovery": 3800,
      "Lateral Movement": 1200,
      "Collection": 800,
      "Command and Control": 2100,
      "Exfiltration": 400,
      "Impact": 1500
    }
  }
}

POST /api/sightings

Records a new sighting of an existing IoC. Sightings increase the reputation score weight of an indicator.

value

string

required

The IoC value that was observed.

source

string

required

Source of the sighting (e.g., guard-agent, honeypot).

context

object

Additional context about the sighting.

curl -X POST "https://tc.panguard.ai/api/sightings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "198.51.100.42",
    "source": "guard-agent",
    "context": {
      "agentId": "agent-a1b2c3d4",
      "detectionType": "brute_force",
      "targetPort": 22
    }
  }'

{
  "ok": true,
  "data": {
    "sightingId": "sig_x1y2z3",
    "iocValue": "198.51.100.42",
    "totalSightings": 48,
    "reputationChange": -2
  }
}

GET /api/sightings

Queries sighting records for a specific IoC.

value

string

required

The IoC value to query sightings for.

limit

number

default:"50"

Maximum results.

curl -X GET "https://tc.panguard.ai/api/sightings?value=198.51.100.42&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": [
    {
      "id": "sig_x1y2z3",
      "value": "198.51.100.42",
      "source": "guard-agent",
      "context": {
        "agentId": "agent-a1b2c3d4",
        "detectionType": "brute_force"
      },
      "timestamp": "2026-03-07T08:15:00.000Z"
    }
  ],
  "pagination": {
    "total": 48,
    "page": 1,
    "limit": 5,
    "pages": 10
  }
}

GET /api/audit-log

Returns the audit log of API operations performed against the Threat Cloud. Useful for compliance and debugging.

action

string

Filter by action type: create, update, delete, query.

since

string

ISO 8601 timestamp for log start.

limit

number

default:"50"

Maximum results (max 200).

curl -X GET "https://tc.panguard.ai/api/audit-log?action=create&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": [
    {
      "id": "audit_001",
      "action": "create",
      "resource": "ioc",
      "details": "Added 3 IoCs (2 new, 1 updated)",
      "apiKey": "key_...redacted",
      "ip": "203.0.113.10",
      "timestamp": "2026-03-07T08:15:00.000Z"
    },
    {
      "id": "audit_002",
      "action": "create",
      "resource": "sighting",
      "details": "Recorded sighting for 198.51.100.42",
      "apiKey": "key_...redacted",
      "ip": "203.0.113.10",
      "timestamp": "2026-03-07T08:14:00.000Z"
    }
  ],
  "pagination": {
    "total": 1234,
    "page": 1,
    "limit": 10,
    "pages": 124
  }
}

API key values are partially redacted in audit log responses. Only the first 4 and last 4 characters are shown.

API Reference

Threat Cloud API

GET /api/stats

GET /api/query/timeseries

GET /api/query/geo

GET /api/query/trends

GET /api/query/mitre-heatmap

POST /api/sightings

GET /api/sightings

GET /api/audit-log

​GET /api/stats

​GET /api/query/timeseries

​GET /api/query/geo

​GET /api/query/trends

​GET /api/query/mitre-heatmap

​POST /api/sightings

​GET /api/sightings

​GET /api/audit-log

GET /api/stats

GET /api/query/timeseries

GET /api/query/geo

GET /api/query/trends

GET /api/query/mitre-heatmap

POST /api/sightings

GET /api/sightings

GET /api/audit-log