Skip to content

Add bucket object and leak event docs #237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jenip13 merged 1 commit into from
Jul 21, 2026
Merged

Add bucket object and leak event docs #237

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 168 additions & 0 deletions docs/api-reference/spec/firework-v4-openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -408,6 +408,9 @@
{
"$ref": "#/components/schemas/BucketEvent"
},
{
"$ref": "#/components/schemas/BucketObjectEvent"
},
{
"$ref": "#/components/schemas/ChatMessageEvent"
},
Expand All @@ -426,6 +429,9 @@
{
"$ref": "#/components/schemas/InvalidCredentialEvent"
},
{
"$ref": "#/components/schemas/LeakEvent"
},
{
"$ref": "#/components/schemas/LeakedCredentialEvent"
},
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down
2 changes: 2 additions & 0 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
10 changes: 10 additions & 0 deletions docs/event-types-v2/bucket-object.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).

<BucketObjectExample />
14 changes: 14 additions & 0 deletions docs/event-types-v2/leak.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<LeakExample />
2 changes: 2 additions & 0 deletions docs/event-types-v2/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Currently these event type models are supported on the
| -------------- | ----------------------------------------------------------------------------------- |
| `blog_post` | [Blog Post <Icon icon="book" size={16} />](/event-types-v2/blog-post) |
| `bucket` | [Bucket <Icon icon="book" size={16} />](/event-types-v2/bucket) |
| `bucket_object` | [Bucket Object <Icon icon="book" size={16} />](/event-types-v2/bucket-object) |
| `chat_message` | [Chat Message <Icon icon="book" size={16} />](/event-types-v2/chat-message) |
| `credit_card` | [Chat Message <Icon icon="book" size={16} />](/event-types-v2/chat-message) |
| `docker_repository`| [Docker Repository <Icon icon="book" size={16} />](/event-types-v2/docker-repository) |
Expand All @@ -20,6 +21,7 @@ Currently these event type models are supported on the
| `domain` | [Lookalike Domain (domain) <Icon icon="book" size={16} />](/event-types-v2/domain) |
| `forum_post` | [Forum Post & Topic <Icon icon="book" size={16} />](/event-types-v2/forum-post) |
| `invalid_credential` | [Invalid Credential <Icon icon="book" size={16} />](/event-types-v2/invalid-credential) |
| `leak` | [Leak <Icon icon="book" size={16} />](/event-types-v2/leak) |
| `leaked_credential` | [Leaked Credential <Icon icon="book" size={16} />](/event-types-v2/leaked-credential) |
| `listing` | [Listing <Icon icon="book" size={16} />](/event-types-v2/listing) |
| `mitigated_credential` | [Mitigated Credential <Icon icon="book" size={16} />](/event-types-v2/mitigated-credential) |
Expand Down
29 changes: 29 additions & 0 deletions docs/snippets/event_model_examples/bucket_object.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
```
36 changes: 36 additions & 0 deletions docs/snippets/event_model_examples/leak.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
```
Loading