Box Enterprise Event: APIとPython
Enterprise Eventでは、アプリケーションがサブスクライブできる、企業のBoxインスタンス内の任意のユーザーまたはコンテンツに関連したイベントストリームを提供します。
このストリームにアクセスできるようにするには、新しいレポートを実行したり、既存のレポートにアクセスしたりするための管理者権限のセキュリティコンテキストがアプリケーションに必要です。
User Eventと同様に、Enterprise Eventでは、以下の2つの異なるストリームを提供します。
admin_logs— 最大1年分の履歴の照会を実行するadmin_logs_streaming— ほぼリアルタイムでイベントをサブスクライブする
前回の記事では、User Eventについて説明しました。前回の記事については以下を参照してください。
Enterprise Event
履歴の照会
Boxでは、Enterprise Eventが最大1年間保持されます。
そのためには、ストリームタイプをadmin_logsに設定する必要があります。
アプリケーションでは、イベントタイプ、日付、ストリーム位置でこれらのイベントを照会できます。例として、2023年7月10日 (太平洋標準時) 以降の最初の5回のログインを見てみましょう。
curl --location 'https://api.box.com/2.0/events?stream_type=admin_logs&limit=5&event_type=LOGIN&created_after=2023-07-10T00%3A00%3A00-08%3A00' \
--header 'Authorization: Bearer gm...yK'{
"chunk_size": 1,
"next_stream_position": "1152923193681168215",
"entries": [
{
"source": {
"type": "user",
"id": "18622116055",
"name": "Rui Barbosa",
"login": "..."
},
"created_by": {
...
},
"action_by": null,
"created_at": "2023-07-11T04:18:41-07:00",
"event_id": "9fad413f-5385-4e2c-a046-1fdfccb46702",
"event_type": "LOGIN",
"ip_address": "89.x.x.246",
"type": "event",
}
]
}JWT認証を使用するPythonの例では、次のようになります。
def main():
"""
Simple script to demonstrate the use of events
"""
auth = JWTAuth.from_settings_file("./.jwt.config.json")
auth.authenticate_instance()
client = Client(auth)
events = client.events().get_admin_events(
limit=5,
stream_position=0,
created_after="2023-07-10T00:00:00-08:00",
created_before=None,
event_types=[
"LOGIN",
],
)
for event in events["entries"]:
print(
event.created_at,
event.event_id,
event.event_type,
event.ip_address,
event.source.name,
)2023-07-11T04:18:41-07:00 9fad413f-5385-4e2c-a046-1fdfccb46702 LOGIN 89.x.x.246 Rui Barbosaライブで監視
ストリームをポーリングして最近のイベントを取得するには、admin_logs_streamingタイプを使用します。
このストリームタイプでは、速度やレイテンシの低さを重視します。イベントは、時系列に関係なく、複数回返される場合があります。ただし、アプリでevent_idを使用すると重複を識別できます。
User Eventとは異なり、Enterprise EventではLong pollingを使用できません。中断した場所からポーリングを続行するには、stream_positionを使用する必要があります。
例を以下に示します。
curl --location 'https://api.box.com/2.0/events?stream_type=admin_logs_streaming&event_type=LOGIN&created_after=2023-07-10T00%3A00%3A00-08%3A00' \
--header 'Authorization: Bearer gm..tyK'{
"entries": [
{
...
"created_at": "2023-06-26T08:50:13-07:00",
"event_id": "97163786-b9ca-4a7d-add3-ec6d11f62144",
"event_type": "LOGIN",
...
},
...
{
...
"created_at": "2023-07-11T04:18:41-07:00",
"event_id": "9fad413f-5385-4e2c-a046-1fdfccb46702",
"event_type": "LOGIN",
...
},
{
...
"created_at": "2023-07-11T04:39:57-07:00",
"event_id": "1f6093ec-68c0-48c5-bd4d-5baa1f1c9d6b",
"event_type": "LOGIN",
"ip_address": "89.x.x.246",
...
}
],
"chunk_size": 8,
"next_stream_position": 564639031499837
}履歴の照会よりもかなり短い期間のイベントだけを取得することに注意してください。
この時点から続行するには、アプリで上記のstream_positionパラメータを使用します。
curl --location 'https://api.box.com/2.0/events?stream_type=admin_logs_streaming&stream_position=564639031499837&event_type=LOGIN&created_after=2023-07-10T00%3A00%3A00-08%3A00' \
--header 'Authorization: Bearer gm...ttyK'{
"entries": [
{
"source": {
"type": "user",
"id": "22240405099",
"name": "Wealth User",
"login": "..."
},
"created_by": {
"type": "user",
"id": "22240405099",
"name": "Wealth User",
"login": "..."
},
"action_by": null,
"created_at": "2023-07-11T05:30:08-07:00",
"event_id": "8fc0e1db-4d61-41f7-bd0b-17aa09d22b50",
"event_type": "LOGIN",
"ip_address": "89.x.x.246",
"type": "event",
"session_id": null,
"additional_details": null
}
],
"chunk_size": 1,
"next_stream_position": 564639032046787
}Pythonを使用した例は次のとおりです。
def main():
"""
Simple script to demonstrate the use of events
"""
auth = JWTAuth.from_settings_file("./.jwt.config.json")
auth.authenticate_instance()
client = Client(auth)
events = client.events().get_admin_events_streaming(
stream_position=0,
event_types=[
"LOGIN",
],
)
for event in events["entries"]:
print(
event.created_at,
event.event_id,
event.event_type,
event.ip_address,
event.source.name,
)結果は次のとおりです。
2023-06-26T08:50:13-07:00 97...144 LOGIN 76.x.x.13 Rui Barbosa
2023-06-29T06:40:00-07:00 6d...dc9 LOGIN 76.x.x.13 Rui Barbosa
2023-06-30T12:58:32-07:00 bd...844 LOGIN 76.x.x.13 Rui Barbosa
2023-07-04T12:42:02-07:00 28...827 LOGIN 76.x.x.13 Rui Barbosa
2023-07-11T04:18:41-07:00 9f...702 LOGIN 89.x.x.246 Rui Barbosa
2023-07-11T04:39:57-07:00 1f...d6b LOGIN 89.x.x.246 Investment User
2023-07-11T05:30:08-07:00 8f...b50 LOGIN 89.x.x.246 Wealth Userイベントタイプ
イベントタイプは多数あり、User Eventよりもはるかに多くのタイプをカバーしています。
一覧については、こちらのドキュメントを参照してください。
ユースケース
Enterprise Eventは、Boxインスタンスの管理者にとって非常に便利です。
Boxでは特定の機能をいくつか提供していますが、以下にいくつかのケースを紹介します。
セキュリティとコンプライアンスの監視: Admin Logs APIを利用すると、セキュリティとコンプライアンスを監視するカスタムソリューションを構築できます。ユーザー管理、ファイルアクセス、共有、権限変更など、管理者のアクティビティを監視することで、不審または不正な操作を事前に特定できます。これは、データの整合性の確保、内部の脅威の検出、規制順守の維持に役立ちます。
監査証跡とレポート: Admin Logs APIを使用すると、Box.comアカウントの包括的な監査証跡とレポートを生成できます。ログから関連情報を抽出することで、ユーザーのアクティビティ、アカウントの変更、システムイベントを示すカスタマイズされたレポートを作成できます。これらのレポートは、コンプライアンス監査、内部分析、意思決定のプロセスに役立つ場合があります。
ほぼリアルタイムの通知とアラート: Admin Logs Streaming APIを使用すると、管理イベントが発生したときにそのイベントに関するリアルタイムの通知を受け取ることができます。特定のイベントタイプまたはフィルタに対してサブスクライブすることで、Box.comアカウント内の重要なアクティビティに関する最新情報を常に入手することができます。例えば、異常なログインパターン、機密ファイルに対する権限の変更、ユーザーによる大量の操作に関するアラートを設定できるため、すぐに対応して、潜在的なリスクを軽減できます。
ユーザーの行動の分析: 管理ログを分析することで、ユーザーの行動パターンと傾向についてインサイトを得ることができます。これは、組織がBox.comをどのように利用しているかを把握して、改善点を特定し、ワークフローを最適化するのに役立ちます。例えば、ユーザーのコラボレーションパターンの分析、特定の機能の採用率の測定、サードパーティの統合の使用状況の評価を行うことができます。
セキュリティ情報およびイベント管理 (SIEM) システムとの統合: Admin Logs APIをSIEMシステムやセキュリティオーケストレーションプラットフォームと統合すると、セキュリティイベントの管理を一元化し、インシデント対応を効率化できます。Box.comの管理ログをSIEMに取り込むことにより、Box.comのイベントを他のソースのイベントと関連付けて、高度な脅威検出を実行し、レスポンスのワークフローを自動化できます。
この記事を楽しんでいただけたら、ぜひ [Clap] をクリックしてください。
質問がある場合は、この記事のコメント欄またはBoxのforum.box.com (英語のみ) に投稿してください。
上記の例は、こちらのGitHubリポジトリを使用して簡単に複製できます。
Box Platformの使用を開始する場合は、こちらのGitHubリポジトリにあるPythonアプリのテンプレートをご確認ください。
