egressview

EgressView REST API リファレンス

English

EgressViewは、Web UIとローカル自動化向けに管理APIを提供します。現時点ではバージョン固定された公開互換APIではないため、外部連携を更新する前にリリースノートを確認してください。

ベースURLと認証

Web UIをサブパスで公開している場合も、APIは常に/api配下です。認証必須requestは従来のX-Admin-Token、同じheaderへ指定するscoped API identity token、またはHttpOnly browser session cookieを受け付けます。cookie認証による更新requestでは対応するX-CSRF-Tokenも必要です。

scoped API identityはGET / POST /api/auth/api-identitiesとPOST /api/auth/api-identities/:id/revokeで管理し、いずれもauth.adminが必要です。作成時はlabel、空でないpermission一覧、1分以上1年以下のexpiresInMsを指定します。平文のegv_... tokenを返すのは201作成responseだけで、DBにはSHA-256 hashだけを保存します。identity管理responseにはCache-Control: no-storeを付けます。

Macおよび将来のendpoint Agentは、browser/API/MCPとは別のcredential境界を使います。登録は3段階で、どの1段階も単独ではcredentialを生みません。管理者がPOST /api/agents/enrollment-tokensで英数字6文字・10分有効のcodeを発行します。AgentはPOST /api/agent/enrollment-requestsで申請し、返るのはclaim secretと承認待ちの申請であってtokenではありません。管理者がPOST /api/agents/enrollment-requests/:requestId/approveで承認した後、AgentはPOST /api/agent/enrollment-requests/claimからegva_... bearerを一度だけ受け取ります。codeは5回失敗で失効し、未承認の申請は10分で失効します。bearerはmacOS Keychainへ保存し、Hubはpepper付きhashだけを保持します。このcredentialが持つのはagent.ingestだけで、browser/admin/MCP routeには使えず、token rotation、ingest、POST /api/agent/registration/revokeだけが受け付けます。最後のrouteは、そのbearerで認証されたAgent自身だけを失効でき、別のAgentは指定できません。ingestは非圧縮JSON 512 KiB・最大200観測で、1 batchをtransaction保存し、同じAgent/batch IDの再送には元のACKを返します。上限はAgent単位30 requests/minute、Hub全体で同時4件です。Agent一覧、集約ingest metrics、管理者による失効にはauth.adminが必要です。Agent responseはcacheせず、登録codeは再表示せず、HTTPはloopback開発環境だけで許可します。

GET /api/auth/api-identities/selfは、現在認証中のscoped identity自身だけを 返し、network.readを要求します。browser sessionと従来のadmin tokenは 拒否します。remote MCP serverはこのAPIを使い、内部service identityの権限が network.readとnotes.writeだけでない場合にfail-closedで停止します。

export EGRESSVIEW_URL='https://egressview.example.net'
export EGRESSVIEW_TOKEN='replace-with-your-admin-token'

curl --fail-with-body \
  -H "X-Admin-Token: $EGRESSVIEW_TOKEN" \
  "$EGRESSVIEW_URL/api/status"

ネットワーク境界を越える場合はHTTPSまたは信頼できるVPNを使用してください。tokenをURL、ログ、ソースコードへ書かないでください。JSON request bodyの上限は64 KBです。

パスワードログイン

POST /api/auth/loginは公開APIで、UIパスワードを失効可能なsession tokenへ交換します。パスワードは最大256文字です。同じクライアントから10分間に5回失敗すると、5分間ロックされます。

curl --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{"password":"replace-with-your-password"}' \
  "$EGRESSVIEW_URL/api/auth/login"

{"success":true,"token":"session-token","expiresAt":1784304000000}

POST /api/admin/verifyも公開APIで、request body内のtokenを検証します。認証状態・方式の取得、OIDC redirect/callback、codeで保護されたPOST /api/agent/enrollment-requestsと.../claim入口、詳細情報を返さない/healthzと/readyzも公開します。それ以外は文書化したbrowser、API identity、またはAgent credentialが必要です。

共通仕様

通信履歴

通信履歴一覧

GET /api/connections

Query 内容
from, to 任意のepoch millisecond期間。
limit, offset ページング。limitは最大1,000。互換用の未ページング形式は最大50,000行でtruncatedを返し、グラフは/api/connections/summaryを使用します。
sort lastSeen, src, dst, dport, proto, country, org。既定値はlastSeen。
sortDir ascまたはdesc。既定値はdesc。
fSrc, fDst, fDport, fProto, fCountry, fOrg Server-side filter。末尾にModeを付け、contains, startsWith, endsWith, exactを指定できます。
fSrcMac 送信元MACの完全一致。
fThreat safe, warn, danger。 
curl --fail-with-body \
  -H "X-Admin-Token: $EGRESSVIEW_TOKEN" \
  "$EGRESSVIEW_URL/api/connections?from=1784217600000&limit=100&sort=lastSeen&sortDir=desc"

Responseにはconnections, total, limit, offset, serverTimeが含まれます。各connectionには端末情報、接続先の付加情報、firstSeen, lastSeen, 互換用source, 観測したrouter IDのobservedBy、任意のthreatが含まれます。

集計・セキュリティ表示

CSV / JSON export

GET /api/connections/exportではformat=csv|jsonとfromが必須で、to省略時は現在時刻です。

curl --fail-with-body \
  -H "X-Admin-Token: $EGRESSVIEW_TOKEN" \
  "$EGRESSVIEW_URL/api/connections/export?format=csv&from=1784217600000" \
  -o connections.csv

1,000行単位でstreamし、最大50,000行、timeoutは60秒です。X-Export-Total, X-Export-Count, X-Export-Truncatedを確認してください。CSVはUTF-8 BOM付きでspreadsheet formula injectionを防ぎます。JSONはmetaとconnectionsを返します。

Router

EgressViewには、Yamaha/Ciscoを混在して最大10台登録できます。

作成・検出bodyではkind（yamahaまたはcisco）、displayName, ip, user, pass, enabledを使います。Yamahaはnat、Ciscoは任意のenablePassも使用します。更新時にpasswordを省略すると保存済みの値を維持します。

端末とメモ

Backupとrestore

プロセスhealth

AIプロバイダー設定

AI洞察はローカル集計を常時表示し、利用者が明示的に実行した場合だけ、通信先IP・ホスト名・端末名・MACと接続の集計情報を設定済みのAI providerへ送信します。パスワード等の認証情報は送信しません。

providerは初期状態で無効です。Anthropic/OpenAIは固定の公式API endpointを使い、任意HTTP(S) endpointを設定できるのはOllamaだけです。BedrockはリージョンとConverse APIを使い、認証はAWS SDKのdefault credential chainに委譲します（キー入力・保存なし）。Bedrock対応は通常依存（@aws-sdk/client-bedrock-runtimeと@aws-sdk/client-bedrock）として同梱され、追加インストールは不要です。詳細はdocs/setup-bedrock.ja.mdを参照してください。

Restoreはfail-closedです。復元元の検査、安全backup成功の確認、restore、全DB利用者の再接続、復元後検査を行い、失敗時はrollbackします。成功後は既存のbrowser sessionを失効します。

Endpoint一覧

実装済みHTTP endpoint 101本の全一覧です。公開以外は従来またはscopedのX-Admin-Token credential、browserのHttpOnly session cookie、または明記されたAgent bearerが必要です。cookie認証による更新要求ではX-CSRF-Tokenも必要です。

分類 Methodとpath Access
認証 POST /api/auth/login 公開
認証 POST /api/admin/verify 公開
認証 GET /api/auth/status 公開
認証 GET /api/auth/methods 公開
認証 GET /api/auth/oidc/start 公開
認証 GET /api/auth/oidc/callback 公開
認証 POST /api/auth/logout 認証必須
認証 GET /api/auth/sessions 認証必須
認証 POST /api/auth/sessions/:id/revoke 認証必須
認証 POST /api/auth/sessions/revoke-all 認証必須
認証 POST /api/auth/change-password 認証必須
認証 POST /api/admin/regenerate-token 認証必須
認証 GET /api/auth/security-config 認証必須
認証 POST /api/auth/security-config 認証必須
認証 POST /api/auth/oidc/test 認証必須
認証 GET /api/auth/api-identities 認証必須
認証 POST /api/auth/api-identities 認証必須
認証 POST /api/auth/api-identities/:id/revoke 認証必須
認証 GET /api/auth/audit-events 認証必須
Agent POST /api/agents/enrollment-tokens auth.admin必須。登録codeを一度だけ返す
Agent POST /api/agent/enrollment-requests 公開。6文字codeで申請する。tokenは返らない
Agent POST /api/agent/enrollment-requests/claim 公開。承認後にtokenを一度だけ受け取る
Agent GET /api/agents/transport auth.admin必須。暗号化の有無と、平文の場合に露出する内容を返す
Agent POST /api/agents/transport auth.admin必須。平文通信の承諾を記録する
Agent GET /api/agents/enrollment-requests auth.admin必須。承認待ち一覧
Agent POST /api/agents/enrollment-requests/:requestId/approve auth.admin必須。承認してtokenを発行する
Agent POST /api/agents/enrollment-requests/:requestId/reject auth.admin必須。申請を却下する
Agent GET /api/agents auth.admin必須。credential hashは返さない
Agent GET /api/agents/ingest-metrics auth.admin必須。集約counterと上限だけを返す
Agent POST /api/agents/:agentId/revoke auth.admin必須
Agent POST /api/agent/token/rotate Agent bearerのagent.ingestだけ
Agent POST /api/agent/registration/revoke Agent bearer。認証されたAgent自身だけを失効
Agent POST /api/agent/ingest Agent bearerのagent.ingest。最大200観測・非圧縮JSON 512 KiB
Agent GET /api/agent/capabilities Agent bearerのagent.ingest。受理するschema versionとbatch上限を返し、Agentが双方の話せるversionを選べるようにする
Agent GET /api/agent/geo-cache Agent bearerのagent.ingest。位置キャッシュを全件返す。Agentは宛先を送らない — 絞り込みは「どの宛先に関心があるか」を伝えることになるため。ETag/304に対応
Agent GET /api/agent/threat-intel Agent bearerのagent.ingest。脅威指標を全件返す。Agentは宛先を送らない — 「危ないか」を尋ねるために宛先を送ると、何を気にしているかを相手に伝えることになるため。フィード未設定のHubではavailable: falseを返し、Agentはこれを「脅威が無い」と読んではならない。ETag/304に対応
Router初期設定 POST /api/nonce 認証必須
Router初期設定 POST /api/yamaha/detect 認証必須
Router初期設定 POST /api/cisco/detect 認証必須
Router初期設定 POST /api/login 認証必須、旧setup flow
Router GET /api/routers 認証必須
Router POST /api/routers/detect 認証必須
Router POST /api/routers 認証必須
Router PUT /api/routers/:id 認証必須
Router DELETE /api/routers/:id 認証必須
通信 GET /api/connections 認証必須
通信 GET /api/connections/memory 認証必須
通信 GET /api/connections/summary 認証必須
通信 GET /api/connections/new-nodes 認証必須
通信 GET /api/connections/threat-connections 認証必須
通信 GET /api/connections/threat-counts 認証必須
通信 GET /api/connections/export 認証必須
端末 GET /api/devices 認証必須
端末 GET /api/devices/merge-candidates 認証必須
端末 POST /api/devices/merge 認証必須
端末 POST /api/devices/reject 認証必須
端末 POST /api/devices/archive 認証必須
端末 POST /api/devices/unarchive 認証必須
メモ GET /api/notes 認証必須
メモ POST /api/notes 認証必須
メモ POST /api/notes/draft 認証必須
Backup GET /api/backup/list 認証必須
Backup POST /api/backup/create 認証必須
Backup GET /api/backup/download/:name 認証必須
Backup POST /api/backup/restore 認証必須
Backup POST /api/backup/upload 認証必須
Backup POST /api/backup/config 認証必須
Backup POST /api/backup/prune 認証必須
Backup GET /api/backup/prune/:jobId 認証必須
Backup DELETE /api/backup/prune/:jobId 認証必須
Process health GET /healthz 認証不要。最小livenessのみ
Process health GET /readyz 認証不要。最小readinessのみ
全般設定 GET /api/status 認証必須
全般設定 POST /api/config/general 認証必須
Data source GET /api/config/datasources 認証必須
Data source POST /api/config/datasources 認証必須
Slack GET /api/config/slack 認証必須
Slack POST /api/config/slack 認証必須
通知 GET /api/config/detection-notifications 認証必須
通知 POST /api/config/detection-notifications 認証必須
手動脅威調査 GET /api/config/manual-threat 認証必須。APIキー値は返さず設定済みかだけ返す
手動脅威調査 POST /api/config/manual-threat 認証必須。APIキー、cache、provider別cooldownを保存
手動脅威調査 POST /api/threat/manual-lookup 認証必須。明示操作で公開IP 1件を選択providerへ送信
AI設定 GET /api/config/ai 認証必須。APIキー値は返さず設定済みかだけ返す
AI設定 POST /api/config/ai 認証必須。provider、model、endpoint、cloud APIキーを保存
AI設定 POST /api/ai/models 認証必須。推論せずBedrockのモデル・推論プロファイルIDを取得
AI設定 POST /api/ai/pricing/check 認証必須。providerへ接続せず内蔵料金表の対応を確認
AI設定 POST /api/ai/guardrails 認証必須。推論せずBedrockのGuardrailを取得（fail-open）
AI設定 POST /api/ai/test 認証必須。通信データを送らずモデルIDを取得
AI洞察 GET /api/ai/facts 認証必須。local factsと直前期間比較のみ
AI洞察 GET /api/ai/usage/monthly 認証必須。現地暦の今月・先月token使用量とUSD概算
AI洞察 GET /api/ai/pricing/diagnostics 認証必須。選択model状態と未価格usageのmodel別診断
AI洞察 POST /api/ai/analyze 認証必須。通信先IP・ホスト名・端末名・MACと接続集計を選択providerで手動分析。cloudは二重同意必須
AI通知 GET /api/ai/notification-config 認証必須。schedule、発火条件、通知先、実行状態を返す
AI通知 POST /api/ai/notification-config 認証必須。検証済みscheduleと自動実行同意を保存
AI通知 GET /api/ai/notification-events 認証必須。append-only通知履歴を最大200件返す
AI通知 POST /api/ai/notification-test 認証必須。AIを呼ばずUI/Slack通知をテスト
AI通知 POST /api/ai/notification-run-now 認証必須。設定済み期間のAI分析を明示実行
AI対話 POST /api/ai/chat 認証必須。質問を先に追記し、回答または失敗行をappend-only保存
AI対話 GET /api/ai/conversations 認証必須。会話一覧と保存量
AI対話 GET /api/ai/conversations/:id 認証必須。再起動後も残るメッセージ履歴
AI対話 DELETE /api/ai/conversations/:id 認証必須。会話単位の明示削除
Slack POST /api/slack/test 認証必須
Slack POST /api/slack/verify 認証必須
Slack POST /api/slack/lookup-user 認証必須
検出ログ GET /api/notification-log 認証必須
Beacon GET /api/beacons 認証必須
Beacon GET /api/beacons/config 認証必須
Beacon POST /api/beacons/config 認証必須
Beacon POST /api/beacons/:id/dismiss 認証必須
This site is open source. Improve this page.