From f2763dccf138f97544943e7f0296e75b33ba7839 Mon Sep 17 00:00:00 2001 From: jenip13 Date: Tue, 14 Jul 2026 12:43:46 -0400 Subject: [PATCH] C33 - Events - Add docs for new V2 Events endpoints --- .../spec/firework-v4-openapi.json | 245 +++++++++++++++++- docs/docs.json | 8 +- docs/event-types-v2/invalid-credential.mdx | 9 + docs/event-types-v2/leaked-credential.mdx | 9 + docs/event-types-v2/mitigated-credential.mdx | 9 + docs/event-types-v2/overview.mdx | 5 + docs/event-types-v2/valid-credential.mdx | 9 + .../invalid_credential.mdx | 27 ++ .../leaked_credential.mdx | 31 +++ .../mitigated_credential.mdx | 28 ++ .../event_model_examples/valid_credential.mdx | 27 ++ 11 files changed, 404 insertions(+), 3 deletions(-) create mode 100644 docs/event-types-v2/invalid-credential.mdx create mode 100644 docs/event-types-v2/leaked-credential.mdx create mode 100644 docs/event-types-v2/mitigated-credential.mdx create mode 100644 docs/event-types-v2/valid-credential.mdx create mode 100644 docs/snippets/event_model_examples/invalid_credential.mdx create mode 100644 docs/snippets/event_model_examples/leaked_credential.mdx create mode 100644 docs/snippets/event_model_examples/mitigated_credential.mdx create mode 100644 docs/snippets/event_model_examples/valid_credential.mdx diff --git a/docs/api-reference/spec/firework-v4-openapi.json b/docs/api-reference/spec/firework-v4-openapi.json index 15b5b8ed..a74fbab8 100644 --- a/docs/api-reference/spec/firework-v4-openapi.json +++ b/docs/api-reference/spec/firework-v4-openapi.json @@ -417,12 +417,21 @@ { "$ref": "#/components/schemas/ForumPostEvent" }, + { + "$ref": "#/components/schemas/InvalidCredentialEvent" + }, + { + "$ref": "#/components/schemas/LeakedCredentialEvent" + }, { "$ref": "#/components/schemas/ListingEvent" }, { "$ref": "#/components/schemas/LookalikeDomainEvent" }, + { + "$ref": "#/components/schemas/MitigatedCredentialEvent" + }, { "$ref": "#/components/schemas/PasteEvent" }, @@ -434,6 +443,9 @@ }, { "$ref": "#/components/schemas/pyro__findings__stealerlogs__datamodels__StealerLogEvent" + }, + { + "$ref": "#/components/schemas/ValidCredentialEvent" } ], "discriminator": { @@ -444,12 +456,16 @@ "chat_message": "#/components/schemas/ChatMessageEvent", "cc": "#/components/schemas/FinancialEvent", "forum_post": "#/components/schemas/ForumPostEvent", + "invalid_credential": "#/components/schemas/InvalidCredentialEvent", + "leaked_credential": "#/components/schemas/LeakedCredentialEvent", "listing": "#/components/schemas/ListingEvent", "lookalike": "#/components/schemas/LookalikeDomainEvent", + "mitigated_credential": "#/components/schemas/MitigatedCredentialEvent", "paste": "#/components/schemas/PasteEvent", "ransomleak": "#/components/schemas/RansomLeakEvent", "social_media_account": "#/components/schemas/SocialMediaEvent", - "stealer_log": "#/components/schemas/pyro__findings__stealerlogs__datamodels__StealerLogEvent" + "stealer_log": "#/components/schemas/pyro__findings__stealerlogs__datamodels__StealerLogEvent", + "valid_credential": "#/components/schemas/ValidCredentialEvent" } } }, @@ -2608,6 +2624,7 @@ "driller_profile", "driller_source_code", "entity_classification", + "entity_summarization", "event", "experimental", "forum_category", @@ -4418,6 +4435,32 @@ ], "title": "CredentialActionTarget" }, + "CredentialEventData": { + "properties": { + "identity_name": { + "type": "string", + "title": "Identity Name", + "description": "The email or username associated with the credential." + }, + "credential_hash": { + "type": "string", + "title": "Credential Hash", + "description": "A hash uniquely identifying the credential." + }, + "tenant_integration_id": { + "type": "string", + "title": "Tenant Integration Id", + "description": "The UUID of the tenant's IdP integration that validated the credential." + } + }, + "type": "object", + "required": [ + "identity_name", + "credential_hash", + "tenant_integration_id" + ], + "title": "CredentialEventData" + }, "CredentialsData": { "properties": { "type": { @@ -7192,6 +7235,28 @@ ], "title": "IntelType" }, + "InvalidCredentialEvent": { + "properties": { + "event_type": { + "type": "string", + "const": "invalid_credential", + "title": "Event Type", + "default": "invalid_credential" + }, + "metadata": { + "$ref": "#/components/schemas/EventMetadata" + }, + "data": { + "$ref": "#/components/schemas/CredentialEventData" + } + }, + "type": "object", + "required": [ + "metadata", + "data" + ], + "title": "Invalid Credential" + }, "IpQuery": { "properties": { "type": { @@ -7274,6 +7339,80 @@ ], "title": "Language" }, + "LeakedCredentialEvent": { + "properties": { + "event_type": { + "type": "string", + "const": "leaked_credential", + "title": "Event Type", + "default": "leaked_credential" + }, + "metadata": { + "$ref": "#/components/schemas/EventMetadata" + }, + "data": { + "$ref": "#/components/schemas/LeakedCredentialEventData" + } + }, + "type": "object", + "required": [ + "metadata", + "data" + ], + "title": "Leaked Credential" + }, + "LeakedCredentialEventData": { + "properties": { + "identity_name": { + "type": "string", + "title": "Identity Name", + "description": "The email or username associated with the leaked credential." + }, + "imported_at": { + "type": "string", + "format": "date-time", + "title": "Imported At", + "description": "When the credential was imported into Flare." + }, + "password": { + "type": "string", + "title": "Password", + "description": "The leaked password, or its hash if not available in cleartext." + }, + "source": { + "$ref": "#/components/schemas/LeakedCredentialEventSource", + "description": "The source the credential was leaked from." + } + }, + "type": "object", + "required": [ + "identity_name", + "imported_at", + "password", + "source" + ], + "title": "LeakedCredentialEventData" + }, + "LeakedCredentialEventSource": { + "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": "LeakedCredentialEventSource" + }, "LeakedCredentialsBulkActionType": { "type": "string", "enum": [ @@ -7701,6 +7840,60 @@ ], "title": "MatchingPolicyType" }, + "MitigatedCredentialEvent": { + "properties": { + "event_type": { + "type": "string", + "const": "mitigated_credential", + "title": "Event Type", + "default": "mitigated_credential" + }, + "metadata": { + "$ref": "#/components/schemas/EventMetadata" + }, + "data": { + "$ref": "#/components/schemas/MitigatedCredentialEventData" + } + }, + "type": "object", + "required": [ + "metadata", + "data" + ], + "title": "Mitigated Credential" + }, + "MitigatedCredentialEventData": { + "properties": { + "identity_name": { + "type": "string", + "title": "Identity Name", + "description": "The email or username associated with the credential." + }, + "credential_hash": { + "type": "string", + "title": "Credential Hash", + "description": "A hash uniquely identifying the credential." + }, + "tenant_integration_id": { + "type": "string", + "title": "Tenant Integration Id", + "description": "The UUID of the tenant's IdP integration that validated the credential." + }, + "mitigation_action": { + "type": "string", + "title": "Mitigation Action", + "description": "The action the tenant's IdP integration took to mitigate the credential" + } + }, + "type": "object", + "required": [ + "identity_name", + "credential_hash", + "tenant_integration_id", + "mitigation_action" + ], + "title": "MitigatedCredentialEventData" + }, "NameData": { "properties": { "type": { @@ -9892,6 +10085,34 @@ ], "title": "SubdomainTag" }, + "Tag": { + "properties": { + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Name" + }, + "repository_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Repository Name" + } + }, + "type": "object", + "title": "Tag" + }, "TenantMetadataResponse": { "properties": { "uid": { @@ -10134,6 +10355,28 @@ ], "title": "UsernameQuery" }, + "ValidCredentialEvent": { + "properties": { + "event_type": { + "type": "string", + "const": "valid_credential", + "title": "Event Type", + "default": "valid_credential" + }, + "metadata": { + "$ref": "#/components/schemas/EventMetadata" + }, + "data": { + "$ref": "#/components/schemas/CredentialEventData" + } + }, + "type": "object", + "required": [ + "metadata", + "data" + ], + "title": "Valid Credential" + }, "ValidationError": { "properties": { "loc": { diff --git a/docs/docs.json b/docs/docs.json index 72a72c4e..41bba9d1 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -328,11 +328,15 @@ "event-types-v2/chat-message", "event-types-v2/domain", "event-types-v2/forum-post", + "event-types-v2/invalid-credential", + "event-types-v2/leaked-credential", "event-types-v2/listing", + "event-types-v2/mitigated-credential", "event-types-v2/paste", "event-types-v2/ransom-leak", "event-types-v2/social-media-account", - "event-types-v2/stealer-log" + "event-types-v2/stealer-log", + "event-types-v2/valid-credential" ] } ] @@ -622,4 +626,4 @@ "destination": "/api-reference/v2/endpoints/identifiers/get-fireworkv2assetsgroups-feed" } ] -} \ No newline at end of file +} diff --git a/docs/event-types-v2/invalid-credential.mdx b/docs/event-types-v2/invalid-credential.mdx new file mode 100644 index 00000000..83436e9e --- /dev/null +++ b/docs/event-types-v2/invalid-credential.mdx @@ -0,0 +1,9 @@ +--- +title: "Invalid Credential" +--- + +import InvalidCredentialExample from '/snippets/event_model_examples/invalid_credential.mdx' + +The `invalid_credential` type represents a leaked credential that was checked against the tenant's identity provider integration, such as Microsoft Entra ID, and confirmed to to be invalid. + + diff --git a/docs/event-types-v2/leaked-credential.mdx b/docs/event-types-v2/leaked-credential.mdx new file mode 100644 index 00000000..fba3c3b1 --- /dev/null +++ b/docs/event-types-v2/leaked-credential.mdx @@ -0,0 +1,9 @@ +--- +title: "Leaked Credential" +--- + +import LeakedCredentialExample from '/snippets/event_model_examples/leaked_credential.mdx' + +The `leaked_credential` type represents a single leaked identity and password pair, collected from sources such as breaches and combolists circulating on illicit networks. + + diff --git a/docs/event-types-v2/mitigated-credential.mdx b/docs/event-types-v2/mitigated-credential.mdx new file mode 100644 index 00000000..0302eafb --- /dev/null +++ b/docs/event-types-v2/mitigated-credential.mdx @@ -0,0 +1,9 @@ +--- +title: "Mitigated Credential" +--- + +import MitigatedCredentialExample from '/snippets/event_model_examples/mitigated_credential.mdx' + +The `mitigated_credential` type represents a compromised credential for which a mitigation action, such as disabling the account or revoking its sessions, was performed through the tenant's identity provider integration. + + diff --git a/docs/event-types-v2/overview.mdx b/docs/event-types-v2/overview.mdx index cb7613b1..65977cb8 100644 --- a/docs/event-types-v2/overview.mdx +++ b/docs/event-types-v2/overview.mdx @@ -13,10 +13,15 @@ Currently these event type models are supported on the | `blog_post` | [Blog Post ](/event-types-v2/blog-post) | | `bucket` | [Bucket ](/event-types-v2/bucket) | | `chat_message` | [Chat Message ](/event-types-v2/chat-message) | +| `credit_card` | [Chat Message ](/event-types-v2/chat-message) | | `document` | [Ransomleak (document) ](/event-types-v2/ransom-leak) | | `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) | +| `leaked_credential` | [Leaked Credential ](/event-types-v2/leaked-credential) | | `listing` | [Listing ](/event-types-v2/listing) | +| `mitigated_credential` | [Mitigated Credential ](/event-types-v2/mitigated-credential) | | `paste` | [Paste ](/event-types-v2/paste) | | `stealer_log` | [Stealer Log ](/event-types-v2/stealer-log) | | `social_media` | [Social media ](/event-types-v2/social-media-account) | +| `valid_credential` | [Valid Credential ](/event-types-v2/valid-credential) | diff --git a/docs/event-types-v2/valid-credential.mdx b/docs/event-types-v2/valid-credential.mdx new file mode 100644 index 00000000..c08ddf75 --- /dev/null +++ b/docs/event-types-v2/valid-credential.mdx @@ -0,0 +1,9 @@ +--- +title: "Valid Credential" +--- + +import ValidCredentialExample from '/snippets/event_model_examples/valid_credential.mdx' + +The `valid_credential` type represents a leaked credential that was confirmed to still be valid against the tenant's identity provider integration, such as Microsoft Entra ID. + + diff --git a/docs/snippets/event_model_examples/invalid_credential.mdx b/docs/snippets/event_model_examples/invalid_credential.mdx new file mode 100644 index 00000000..26011f71 --- /dev/null +++ b/docs/snippets/event_model_examples/invalid_credential.mdx @@ -0,0 +1,27 @@ +{/* + 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 Invalid Credential +{ + "event_type": "invalid_credential", + "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": { + "identity_name": "john.doe@example.com", + "credential_hash": "a1b2c3d4e5f67890", + "tenant_integration_id": "00000000-0000-0000-0000-000000000001" + } +} +``` diff --git a/docs/snippets/event_model_examples/leaked_credential.mdx b/docs/snippets/event_model_examples/leaked_credential.mdx new file mode 100644 index 00000000..1c4240ee --- /dev/null +++ b/docs/snippets/event_model_examples/leaked_credential.mdx @@ -0,0 +1,31 @@ +{/* + 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 Leaked Credential +{ + "event_type": "leaked_credential", + "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": { + "identity_name": "identity_name", + "imported_at": "2025-01-01T00:00:00", + "password": "password", + "source": { + "id": "url_login_pass", + "name": "URL Login Pass" + } + } +} +``` diff --git a/docs/snippets/event_model_examples/mitigated_credential.mdx b/docs/snippets/event_model_examples/mitigated_credential.mdx new file mode 100644 index 00000000..31eafe39 --- /dev/null +++ b/docs/snippets/event_model_examples/mitigated_credential.mdx @@ -0,0 +1,28 @@ +{/* + 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 Mitigated Credential +{ + "event_type": "mitigated_credential", + "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": { + "identity_name": "john.doe@example.com", + "credential_hash": "a1b2c3d4e5f67890", + "tenant_integration_id": "00000000-0000-0000-0000-000000000001", + "mitigation_action": "disable_account" + } +} +``` diff --git a/docs/snippets/event_model_examples/valid_credential.mdx b/docs/snippets/event_model_examples/valid_credential.mdx new file mode 100644 index 00000000..12f2c7d5 --- /dev/null +++ b/docs/snippets/event_model_examples/valid_credential.mdx @@ -0,0 +1,27 @@ +{/* + 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 Valid Credential +{ + "event_type": "valid_credential", + "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": { + "identity_name": "john.doe@example.com", + "credential_hash": "a1b2c3d4e5f67890", + "tenant_integration_id": "00000000-0000-0000-0000-000000000001" + } +} +```