快速開始
在應用程式的 Wire → API 金鑰建立金鑰,即可在任何地方呼叫 API。回應為 JSON,時間為 ISO-8601 UTC。
curl -H "Authorization: Bearer rr_live_…" \
https://realityradar-7h6.pages.dev/api/v1/public/alerts?limit=5const res = await fetch('https://realityradar-7h6.pages.dev/api/v1/public/entities', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.RADAR_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ entityType: 'software_version', displayName: 'Node.js', modelOrVersion: '18.20.0',
identifiers: { eolProduct: 'nodejs' }, relationship: 'used' }),
});
console.log(res.status, await res.json());import os, requests
r = requests.get("https://realityradar-7h6.pages.dev/api/v1/public/events", params={"type": "product_recall", "limit": 20},
headers={"Authorization": f"Bearer {os.environ['RADAR_KEY']}"}, timeout=10)
r.raise_for_status()
for e in r.json()["items"]:
print(e["firstSeenAt"], e["title"], e["sourceUrl"])驗證
以 Bearer 權杖傳送金鑰。金鑰只顯示一次,僅以雜湊儲存,可設定 30、90 或 365 天後到期,並可在 24 小時重疊期內輪替。
Authorization: Bearer rr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX權限範圍
每把金鑰只帶有你選擇的權限範圍。超出範圍的請求會回傳 403 insufficient_scope,因此唯讀金鑰無法新增項目或管理 Webhook。
| 權限範圍 | 端點 |
|---|---|
read:signals | GET /public/eventsGET /public/events/{id} |
read:entities | GET /public/entities |
write:entities | POST /public/entities |
read:alerts | GET /public/alerts |
manage:webhooks | GET /public/webhooksPOST /public/webhooksDELETE /public/webhooks/{id}GET /public/webhooks/{id}/deliveriesPOST /public/webhooks/{id}/deliveries/{deliveryId}/replay |
速率限制
標準金鑰每分鐘 60 次,高額度金鑰每分鐘 300 次。收到 429 時請稍候再試;每把金鑰與端點的用量可在 Wire 查看。
分頁
清單端點回傳 items 與 nextCursor。持續傳回 cursor 直到它為 null;游標不透明,翻頁期間保持穩定。
cursor = None
while True:
page = requests.get(f"https://realityradar-7h6.pages.dev/api/v1/public/events", headers=H, params={"limit": 100, "cursor": cursor}).json()
handle(page["items"])
cursor = page["nextCursor"]
if not cursor:
break錯誤
錯誤使用一致的格式與固定的機器代碼。5xx 與 429 可依退避策略重試,4xx 表示請求有問題。
{ "error": { "code": "insufficient_scope", "message": "This key lacks the \"write:entities\" scope" } }invalid_api_key | 401 | 缺少金鑰、格式錯誤或已撤銷 |
api_key_expired | 401 | 已超過有效期限或輪替寬限期 |
insufficient_scope | 403 | 金鑰缺少此端點所需的權限範圍 |
not_found | 404 | 不存在,或此工作區無法看見 |
plan_limit | 409 | 已達免費方案的項目上限 |
ssrf_blocked | 422 | URL 指向私有或內部位址 |
rate_limited | 429 | 請求過多 — 請稍後再試 |
Webhook
當達到你設定等級的警示產生時,以 POST 傳送 JSON 事件。傳送紀錄保留 30 天,含狀態與延遲,並可一鍵重送。
POST /your/endpoint
Content-Type: application/json
User-Agent: RealityRadar-Webhook/1.0
X-Radar-Signature: t=1761112800,v1=5f2b…a91c,v1=03de…77b0
{"type":"alert.created","alert":{"impactLevel":"critical","matchType":"exact",…},"event":{…}}驗證簽章
以密鑰對 t、句點與原始內容計算 HMAC-SHA256,以常數時間與任一 v1 比較,並拒絕超過五分鐘的時間戳記。輪替密鑰後的 24 小時內會收到兩個 v1。
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody: the exact bytes you received (do not re-serialize JSON)
export function verifyRadar(header, rawBody, secret) {
const parts = header.split(',').map((p) => p.split('='));
const t = Number(parts.find(([k]) => k === 't')?.[1]);
const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
const mac = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return sigs.some((v) => v.length === mac.length && timingSafeEqual(Buffer.from(v), Buffer.from(mac)));
}import hmac, hashlib, time
def verify_radar(header: str, raw_body: bytes, secret: str) -> bool:
parts = [p.split("=", 1) for p in header.split(",")]
t = next((int(v) for k, v in parts if k == "t"), None)
sigs = [v for k, v in parts if k == "v1"]
if t is None or abs(time.time() - t) > 300:
return False
mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(mac, s) for s in sigs)func VerifyRadar(header string, rawBody []byte, secret string) bool {
var t int64 = -1
var sigs []string
for _, p := range strings.Split(header, ",") {
k, v, ok := strings.Cut(p, "=")
if !ok { continue }
if k == "t" { t, _ = strconv.ParseInt(v, 10, 64) }
if k == "v1" { sigs = append(sigs, v) }
}
if t < 0 || math.Abs(float64(time.Now().Unix()-t)) > 300 { return false }
m := hmac.New(sha256.New, []byte(secret))
fmt.Fprintf(m, "%d.", t)
m.Write(rawBody)
want := hex.EncodeToString(m.Sum(nil))
for _, s := range sigs {
if hmac.Equal([]byte(want), []byte(s)) { return true }
}
return false
}# Replay a delivery (fresh timestamp + signature)
curl -X POST -H "Authorization: Bearer rr_live_…" \
https://realityradar-7h6.pages.dev/api/v1/public/webhooks/WEBHOOK_ID/deliveries/DELIVERY_ID/replay相依套件與 OSV
以 pkg:npm/lodash 這類 purl 與確切版本追蹤套件。系統會查詢 OSV.dev,若你的版本在受影響清單中即標示為完全符合。鎖定檔或 SBOM 可在應用程式的匯入上傳。
curl -X POST -H "Authorization: Bearer rr_live_…" -H "Content-Type: application/json" \
-d '{"entityType":"software_version","displayName":"lodash","modelOrVersion":"4.17.20","identifiers":{"purl":"pkg:npm/lodash"},"relationship":"used"}' \
https://realityradar-7h6.pages.dev/api/v1/public/entities詞彙表
回應中會出現的詞彙。
- Signal(訊號)
- 從官方來源偵測到的變化事件,附有證據與時間。
- Beacon(信標)
- 資料來源。A 級為官方主管機關或廠商,B 級為經整理的資料庫。
- 符合類型
- exact、strong、probable、weak — 事件與你項目相關的確定程度。只有 exact 與 strong 會被表述為確定。
- 相關性、可信度、嚴重性
- 分開計算的三個 0–100 分數:是否與你有關、證據有多可信、變化有多嚴重。
- purl
- 套件 URL,例如 pkg:npm/lodash,是 OSV 比對使用的標準識別碼。
- 證據帳本
- 所存每筆證據組成的防竄改雜湊鏈,任何人都能驗證。