From 691ca2c7ebdbb1d85a4c01bb03dbbffe4eed7de8 Mon Sep 17 00:00:00 2001 From: Maxime Goyette Date: Thu, 26 Sep 2024 14:58:02 -0400 Subject: [PATCH] Add new guide to fetch tenant events. --- ...get-activities-.mdx => get-activities.mdx} | 1 + docs/guides/tenant-events-api-v4.mdx | 77 +++++++++++++++++++ docs/mint.json | 13 +--- 3 files changed, 82 insertions(+), 9 deletions(-) rename docs/api-reference/v2/endpoints/activities/{get-activities-.mdx => get-activities.mdx} (77%) create mode 100644 docs/guides/tenant-events-api-v4.mdx diff --git a/docs/api-reference/v2/endpoints/activities/get-activities-.mdx b/docs/api-reference/v2/endpoints/activities/get-activities.mdx similarity index 77% rename from docs/api-reference/v2/endpoints/activities/get-activities-.mdx rename to docs/api-reference/v2/endpoints/activities/get-activities.mdx index b2903a1..77bebef 100644 --- a/docs/api-reference/v2/endpoints/activities/get-activities-.mdx +++ b/docs/api-reference/v2/endpoints/activities/get-activities.mdx @@ -1,3 +1,4 @@ --- openapi: firework-v2-openapi get /activities/{index}/{source}/{id} +title: Retrieve Event --- \ No newline at end of file diff --git a/docs/guides/tenant-events-api-v4.mdx b/docs/guides/tenant-events-api-v4.mdx new file mode 100644 index 0000000..511e758 --- /dev/null +++ b/docs/guides/tenant-events-api-v4.mdx @@ -0,0 +1,77 @@ +--- +title: 'List Events Within a Tenant' +--- + +Browsing events within a tenant is exposed through the +[/events/tenant/_search ](#) +API. + +This guide explains how to use the tenant feed API perform a full export +of all results. + +## Paging + +The tenant feed endpoint uses parameters that match the +[Flare standard paging pattern ](/concepts/paging). + +## Fetching new results in future executions + +It is possible to save the `next` in a database and use it to resume fetching new results in the future. +However, it is important that future requests use **exactly** the same parameters for everything else but `next`. + +## Getting the full data of results + +For performance reasons, feed results only contain the bear minimum. +To get the full data, an API call must be made per result to the [/activities/:index/:source/:id ](/api-reference/v2/endpoints/activities/get-activities) endpoint. + + + + +```python +import os +import time + +from flareio import FlareApiClient + + +api_key: str | None = os.environ.get("FLARE_API_KEY") +if not api_key: + raise Exception("Please provide an API key") + +api_client = FlareApiClient(api_key=api_key) + +last_from: str | None = None +fetched_pages: int = 0 + +for resp in api_client.scroll( + method="POST", + url="/firework/v4/events/tenant/_search", + json={ + "from": last_from, + } +): + # Rate limiting. + time.sleep(1) + + resp_data: dict = resp.json() + + fetched_pages += 1 + num_results: int = len(resp_data["items"]) + print(f"Fetched page {fetched_pages} with {num_results} results...") + + # Save the last "next" value. + last_from = resp_data.get("next") or last_from + + # Get the full data + for item in resp_data["items"]: + # Rate limiting. + time.sleep(1) + + item_uid: str = item["metadata"]["uid"] + response = api_client.get(f"/firework/v2/activities/{item_uid}") + full_data = response.json() + print(f"Here is the full data of the event: {full_data}") +``` + + + diff --git a/docs/mint.json b/docs/mint.json index ce3744b..0392275 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -49,8 +49,8 @@ } ], "topAnchor": { - "name": "API Documentation", - "icon": "code" + "name": "API Documentation", + "icon": "code" }, "anchors": [ { @@ -164,7 +164,6 @@ "api-reference/v2/endpoints/identifiers/put-assets", "api-reference/v3/endpoints/identifiers/get-identifiers-1", "api-reference/v2/endpoints/identifiers/delete-assets", - "api-reference/v2/endpoints/identifiers/post-assets-toggle" ] }, @@ -180,6 +179,7 @@ { "group": "Events", "pages": [ + "api-reference/v2/endpoints/activities/get-activities", "api-reference/v2/endpoints/activities/get-activities--ai_assistance" ] }, @@ -199,7 +199,6 @@ "api-reference/v2/endpoints/identifiers/post-assets-alerts", "api-reference/v2/endpoints/identifiers/put-assets-alerts", "api-reference/v2/endpoints/identifiers/delete-assets-alerts", - "api-reference/v2/endpoints/identifiers/get-assetsgroups-alerts", "api-reference/v2/endpoints/identifiers/post-assetsgroups-alerts", "api-reference/v2/endpoints/identifiers/put-assetsgroups-alerts", @@ -221,12 +220,9 @@ "api-reference/v2/endpoints/organizations/post-organizations-members", "api-reference/v2/endpoints/organizations/get-organizations-members-1", "api-reference/v2/endpoints/organizations/put-organizations-members", - "api-reference/v2/endpoints/organizations/post-organizations-members-enable", "api-reference/v2/endpoints/organizations/post-organizations-members-disable", - "api-reference/v2/endpoints/organizations/get-organizations-members-tenants", - "api-reference/v2/endpoints/organizations/post-organizations-members-permissions" ] }, @@ -257,7 +253,6 @@ "api-reference/v2/endpoints/tenants/get-tenants", "api-reference/v2/endpoints/tenants/put-tenants", "api-reference/v2/endpoints/tenants/post-tenants-archive", - "api-reference/v2/endpoints/tenants/get-tenants-users", "api-reference/v2/endpoints/tenants/post-tenants-users", "api-reference/v2/endpoints/tenants/delete-tenants-users" @@ -272,4 +267,4 @@ "github": "https://github.com/flared", "youtube": "https://www.youtube.com/@flarecybersecurity" } -} +} \ No newline at end of file