Skip to main content

​
POST /api/agents/:id/events

提交由代理偵測到的一個或多個威脅事件。這是 Guard 偵測到的威脅的主要接收端點。
​
id
string
required
回報威脅的代理 ID。
​
events
object[]
required
威脅事件物件陣列。
​
events[].type
string
required
威脅類型（例如 brute_force、port_scan、malware_detected、suspicious_process、file_integrity、privilege_escalation）。
​
events[].severity
string
required
嚴重程度：low、medium、high 或 critical。
​
events[].details
object
required
威脅特定的詳細資訊（來源 IP、檔案路徑、程序名稱等）。
​
events[].timestamp
string
ISO 8601 時間戳。如果省略，預設為伺服器接收時間。
​
events[].sigmaRuleId
string
觸發此偵測的 Sigma 規則 ID。
​
events[].confidence
number
AI 信心分數（0.0—1.0）。
curl -X POST https://localhost:8443/api/agents/agent-a1b2c3d4/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "brute_force",
        "severity": "high",
        "confidence": 0.92,
        "details": {
          "sourceIp": "198.51.100.42",
          "attempts": 150,
          "targetService": "sshd",
          "timeWindow": "300s"
        },
        "sigmaRuleId": "sigma-bf-001"
      }
    ]
  }'

{
  "ok": true,
  "data": {
    "received": 1,
    "eventIds": ["evt_x1y2z3"]
  }
}

​
GET /api/threats

查詢整個機群的最近威脅事件。
​
since
string
ISO 8601 時間戳。僅回傳此時間之後的事件。
​
org_id
string
依組織 ID 篩選。
​
severity
string
依嚴重程度篩選：low、medium、high、critical。
​
type
string
依威脅類型篩選。
​
limit
number
default:"50"
最大結果數（最大 200）。
curl -X GET "https://localhost:8443/api/threats?since=2026-03-07T00:00:00Z&severity=high" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "ok": true,
  "data": [
    {
      "id": "evt_x1y2z3",
      "agentId": "agent-a1b2c3d4",
      "hostname": "web-server-1",
      "type": "brute_force",
      "severity": "high",
      "confidence": 0.92,
      "details": {
        "sourceIp": "198.51.100.42",
        "attempts": 150,
        "targetService": "sshd"
      },
      "timestamp": "2026-03-07T08:15:00.000Z"
    }
  ]
}

​
GET /api/threats/summary

回傳整個機群的威脅彙總摘要。
​
period
string
default:"24h"
時間區間：1h、6h、24h、7d、30d。
​
org_id
string
依組織 ID 篩選。
curl -X GET "https://localhost:8443/api/threats/summary?period=24h" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "ok": true,
  "data": {
    "period": "24h",
    "total": 47,
    "bySeverity": {
      "critical": 2,
      "high": 8,
      "medium": 15,
      "low": 22
    },
    "byType": {
      "brute_force": 12,
      "port_scan": 8,
      "suspicious_process": 15,
      "file_integrity": 7,
      "malware_detected": 3,
      "privilege_escalation": 2
    },
    "topAgents": [
      { "agentId": "agent-a1b2c3d4", "hostname": "web-server-1", "count": 18 },
      { "agentId": "agent-e5f6g7h8", "hostname": "db-server-1", "count": 12 }
    ],
    "topSourceIps": [
      { "ip": "198.51.100.42", "count": 25 },
      { "ip": "203.0.113.99", "count": 14 }
    ]
  }
}

​
GET /api/events/stream

開啟 Server-Sent Events (SSE) 串流用於即時事件通知。連線保持開啟，並在事件發生時推送。 
curl -N -X GET https://localhost:8443/api/events/stream \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream"

​
事件類型

事件類型說明酬載
connected初始連線確認{ message: "Connected to event stream" }
agent_online代理發送了第一次心跳{ agentId, hostname, ip }
agent_offline代理超過心跳逾時{ agentId, hostname, lastSeen }
threats_reported新的威脅事件已提交{ agentId, hostname, count, maxSeverity }
policy_created新策略已建立並廣播{ policyId, version, ruleCount }

​
SSE 輸出範例

event: connected
data: {"message":"Connected to event stream"}

event: agent_online
data: {"agentId":"agent-a1b2c3d4","hostname":"web-server-1","ip":"203.0.113.10"}

event: threats_reported
data: {"agentId":"agent-a1b2c3d4","hostname":"web-server-1","count":3,"maxSeverity":"high"}

event: policy_created
data: {"policyId":"pol_abc123","version":"v3","ruleCount":5}
SSE 串流每 30 秒發送一次心跳註解（: keepalive）以維持連線。如果連線中斷，客戶端應實作帶有指數退避的自動重連。