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.

string

default:"day"

Time bucket size: hour, day, or week.

string

default:"30d"

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

string

Filter by IoC type.

string

Filter by threat category.

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

{
  "ok": true,
  "data": {
    "granularity": "day",
    "period": "7d",
    "series": [
      { "timestamp": "2026-03-01T00:00:00Z", "newIocs": 198, "sightings": 4200 },
      { "timestamp": "2026-03-02T00:00:00Z", "newIocs": 215, "sightings": 4510 },
      { "timestamp": "2026-03-03T00:00:00Z", "newIocs": 187, "sightings": 3980 },
      { "timestamp": "2026-03-04T00:00:00Z", "newIocs": 234, "sightings": 5120 },
      { "timestamp": "2026-03-05T00:00:00Z", "newIocs": 201, "sightings": 4350 },
      { "timestamp": "2026-03-06T00:00:00Z", "newIocs": 256, "sightings": 5890 },
      { "timestamp": "2026-03-07T00:00:00Z", "newIocs": 142, "sightings": 3100 }
    ]
  }
}

GET /api/query/geo

Returns geographic distribution of threat sources.

string

Filter by IoC type (primarily useful for ip).

string

default:"30d"

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

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.

number

default:"7"

Number of days to analyze for trend detection.

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.

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.

string

required

The IoC value that was observed.

string

required

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

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.

string

required

The IoC value to query sightings for.

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.

string

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

string

ISO 8601 timestamp for log start.

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