From 8658fecaf762cabff707fcc534bc7ab8375b59d5 Mon Sep 17 00:00:00 2001 From: Antoine Parent Date: Tue, 21 Jul 2026 12:39:01 -0400 Subject: [PATCH] Add bucket object and leak event docs Add some documentation for bucket object and leak events as part of the MCP changes --- .../spec/firework-v4-openapi.json | 168 ++++++++++++++++++ docs/docs.json | 2 + docs/event-types-v2/bucket-object.mdx | 10 ++ docs/event-types-v2/leak.mdx | 14 ++ docs/event-types-v2/overview.mdx | 2 + .../event_model_examples/bucket_object.mdx | 29 +++ docs/snippets/event_model_examples/leak.mdx | 36 ++++ 7 files changed, 261 insertions(+) create mode 100644 docs/event-types-v2/bucket-object.mdx create mode 100644 docs/event-types-v2/leak.mdx create mode 100644 docs/snippets/event_model_examples/bucket_object.mdx create mode 100644 docs/snippets/event_model_examples/leak.mdx diff --git a/docs/api-reference/spec/firework-v4-openapi.json b/docs/api-reference/spec/firework-v4-openapi.json index b60ffd8..aa270ae 100644 --- a/docs/api-reference/spec/firework-v4-openapi.json +++ b/docs/api-reference/spec/firework-v4-openapi.json @@ -408,6 +408,9 @@ { "$ref": "#/components/schemas/BucketEvent" }, + { + "$ref": "#/components/schemas/BucketObjectEvent" + }, { "$ref": "#/components/schemas/ChatMessageEvent" }, @@ -426,6 +429,9 @@ { "$ref": "#/components/schemas/InvalidCredentialEvent" }, + { + "$ref": "#/components/schemas/LeakEvent" + }, { "$ref": "#/components/schemas/LeakedCredentialEvent" }, @@ -462,12 +468,14 @@ "mapping": { "blog_post": "#/components/schemas/BlogPostEvent", "bucket": "#/components/schemas/BucketEvent", + "bucket_object": "#/components/schemas/BucketObjectEvent", "chat_message": "#/components/schemas/ChatMessageEvent", "cc": "#/components/schemas/FinancialEvent", "docker_image": "#/components/schemas/DockerImageEvent", "docker_repository": "#/components/schemas/DockerRepositoryEvent", "forum_post": "#/components/schemas/ForumPostEvent", "invalid_credential": "#/components/schemas/InvalidCredentialEvent", + "leak": "#/components/schemas/LeakEvent", "leaked_credential": "#/components/schemas/LeakedCredentialEvent", "listing": "#/components/schemas/ListingEvent", "lookalike": "#/components/schemas/LookalikeDomainEvent", @@ -3772,6 +3780,53 @@ ], "title": "BucketEventData" }, + "BucketObjectEvent": { + "properties": { + "event_type": { + "type": "string", + "const": "bucket_object", + "title": "Event Type", + "default": "bucket_object" + }, + "metadata": { + "$ref": "#/components/schemas/EventMetadata" + }, + "data": { + "$ref": "#/components/schemas/BucketObjectEventData" + } + }, + "type": "object", + "required": [ + "metadata", + "data" + ], + "title": "Bucket Object" + }, + "BucketObjectEventData": { + "properties": { + "url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Url", + "description": "The URL to the bucket object." + }, + "bucket": { + "$ref": "#/components/schemas/BucketData" + } + }, + "type": "object", + "required": [ + "url", + "bucket" + ], + "title": "BucketObjectEventData" + }, "CCBinData": { "properties": { "type": { @@ -7577,6 +7632,119 @@ ], "title": "Language" }, + "LeakEvent": { + "properties": { + "event_type": { + "type": "string", + "const": "leak", + "title": "Event Type", + "default": "leak" + }, + "metadata": { + "$ref": "#/components/schemas/EventMetadata" + }, + "data": { + "$ref": "#/components/schemas/LeakEventData" + } + }, + "type": "object", + "required": [ + "metadata", + "data" + ], + "title": "Leak" + }, + "LeakEventData": { + "properties": { + "term": { + "type": "string", + "title": "Term", + "description": "The search term that matched this leak." + }, + "site_url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Site Url", + "description": "The URL of the site the leak originated from." + }, + "leaked_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Leaked At", + "description": "When the leak occurred." + }, + "breached_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Breached At", + "description": "When the breach was disclosed." + }, + "leaked_credential_count": { + "type": "integer", + "title": "Leaked Credential Count", + "description": "Number of credentials contained in this leak." + }, + "pii_tags": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Pii Tags", + "description": "PII categories present in this leak." + }, + "source": { + "$ref": "#/components/schemas/LeakEventSource", + "description": "The source of the leak." + } + }, + "type": "object", + "required": [ + "term", + "leaked_credential_count", + "source" + ], + "title": "LeakEventData" + }, + "LeakEventSource": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "The identifier of the leak source category." + }, + "name": { + "type": "string", + "title": "Name", + "description": "The name of the leak source category." + } + }, + "type": "object", + "required": [ + "id", + "name" + ], + "title": "LeakEventSource" + }, "LeakedCredentialEvent": { "properties": { "event_type": { diff --git a/docs/docs.json b/docs/docs.json index 7c79f06..b1381eb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -325,10 +325,12 @@ "event-types-v2/overview", "event-types-v2/blog-post", "event-types-v2/bucket", + "event-types-v2/bucket-object", "event-types-v2/chat-message", "event-types-v2/domain", "event-types-v2/forum-post", "event-types-v2/invalid-credential", + "event-types-v2/leak", "event-types-v2/leaked-credential", "event-types-v2/docker-image", "event-types-v2/docker-repository", diff --git a/docs/event-types-v2/bucket-object.mdx b/docs/event-types-v2/bucket-object.mdx new file mode 100644 index 0000000..3ed8577 --- /dev/null +++ b/docs/event-types-v2/bucket-object.mdx @@ -0,0 +1,10 @@ +--- +title: "Bucket Object" +--- + +import BucketObjectExample from '/snippets/event_model_examples/bucket_object.mdx' + +The `bucket_object` type represents individual files (objects) discovered within a publicly exposed cloud storage bucket, such as Amazon S3, Azure Blob Storage, or Google Cloud Storage. +Each record identifies a single accessible object and includes the bucket it was found in (host and provider). + + diff --git a/docs/event-types-v2/leak.mdx b/docs/event-types-v2/leak.mdx new file mode 100644 index 0000000..e49de9d --- /dev/null +++ b/docs/event-types-v2/leak.mdx @@ -0,0 +1,14 @@ +--- +title: "Leak" +--- + +import LeakExample from '/snippets/event_model_examples/leak.mdx' + +The `leak` type represents a discrete data leak, such as a batch of credentials or PII published on a leak site. + +Each record corresponds to a single leak and may include: +- The search term that matched the leak and the site it originated from. +- Timing details: when the leak occurred and when the breach was disclosed. +- The number of leaked credentials and the categories of PII exposed. + + diff --git a/docs/event-types-v2/overview.mdx b/docs/event-types-v2/overview.mdx index 9e32b3c..ca4d967 100644 --- a/docs/event-types-v2/overview.mdx +++ b/docs/event-types-v2/overview.mdx @@ -12,6 +12,7 @@ Currently these event type models are supported on the | -------------- | ----------------------------------------------------------------------------------- | | `blog_post` | [Blog Post ](/event-types-v2/blog-post) | | `bucket` | [Bucket ](/event-types-v2/bucket) | +| `bucket_object` | [Bucket Object ](/event-types-v2/bucket-object) | | `chat_message` | [Chat Message ](/event-types-v2/chat-message) | | `credit_card` | [Chat Message ](/event-types-v2/chat-message) | | `docker_repository`| [Docker Repository ](/event-types-v2/docker-repository) | @@ -20,6 +21,7 @@ Currently these event type models are supported on the | `domain` | [Lookalike Domain (domain) ](/event-types-v2/domain) | | `forum_post` | [Forum Post & Topic ](/event-types-v2/forum-post) | | `invalid_credential` | [Invalid Credential ](/event-types-v2/invalid-credential) | +| `leak` | [Leak ](/event-types-v2/leak) | | `leaked_credential` | [Leaked Credential ](/event-types-v2/leaked-credential) | | `listing` | [Listing ](/event-types-v2/listing) | | `mitigated_credential` | [Mitigated Credential ](/event-types-v2/mitigated-credential) | diff --git a/docs/snippets/event_model_examples/bucket_object.mdx b/docs/snippets/event_model_examples/bucket_object.mdx new file mode 100644 index 0000000..8b4f034 --- /dev/null +++ b/docs/snippets/event_model_examples/bucket_object.mdx @@ -0,0 +1,29 @@ +{/* + If you are in pyro: + - If this file changes, you should also modify the API docs. + - https://github.com/flared/docs-api/ + + If you are in mintlify: + - Don't edit this directly, edit the generator in pyro. + - pyro/pyro/mintlify/test_firework_event_models.py +*/} + +```json Bucket Object +{ + "event_type": "bucket_object", + "metadata": { + "estimated_created_at": "2025-01-01T00:00:00", + "flare_url": "https://app.flare.io/#/uid", + "matched_at": null, + "severity": "info", + "uid": "index/source/id" + }, + "data": { + "url": "https://bucket.public.com/file.txt", + "bucket": { + "host": "bucket.public.com", + "provider": "s3" + } + } +} +``` diff --git a/docs/snippets/event_model_examples/leak.mdx b/docs/snippets/event_model_examples/leak.mdx new file mode 100644 index 0000000..7321ef0 --- /dev/null +++ b/docs/snippets/event_model_examples/leak.mdx @@ -0,0 +1,36 @@ +{/* + If you are in pyro: + - If this file changes, you should also modify the API docs. + - https://github.com/flared/docs-api/ + + If you are in mintlify: + - Don't edit this directly, edit the generator in pyro. + - pyro/pyro/mintlify/test_firework_event_models.py +*/} + +```json Leak +{ + "event_type": "leak", + "metadata": { + "estimated_created_at": "2025-01-01T00:00:00", + "flare_url": "https://app.flare.io/#/uid", + "matched_at": null, + "severity": "info", + "uid": "index/source/id" + }, + "data": { + "term": "leakforum", + "site_url": "leakforum.com", + "leaked_at": "2024-01-10T00:00:00", + "breached_at": "2024-01-10T00:00:00", + "leaked_credential_count": 2, + "pii_tags": [ + "Emails" + ], + "source": { + "id": "leak_forum", + "name": "Leak Forum" + } + } +} +```