Skip to content

Publish unstable STIX ingestion API #4119

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

Open
api-clients-generation-pipeline wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Publish unstable STIX ingestion API #4119

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
333 changes: 333 additions & 0 deletions .generator/schemas/v2/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86174,6 +86174,229 @@ components:
example: "report_id"
type: string
type: object
STIXBundleRequest:
additionalProperties: {}
description: A STIX 2.1 bundle containing threat intelligence indicator objects.
properties:
id:
description: The STIX bundle identifier.
example: bundle--11111111-1111-4111-8111-111111111111
type: string
objects:
description: The indicator objects included in the bundle.
example:
- created: "2026-07-22T12:00:00Z"
id: indicator--22222222-2222-4222-8222-222222222222
modified: "2026-07-22T12:00:00Z"
pattern: "[ipv4-addr:value = '198.51.100.42']"
pattern_type: stix
spec_version: "2.1"
type: indicator
valid_from: "2026-07-22T12:00:00Z"
items:
$ref: "#/components/schemas/STIXIndicatorObject"
type: array
spec_version:
$ref: "#/components/schemas/STIXSpecVersion"
type:
$ref: "#/components/schemas/STIXBundleType"
required:
- type
- id
- objects
type: object
STIXBundleType:
description: The STIX object type for a bundle.
enum:
- bundle
example: bundle
type: string
x-enum-varnames:
- BUNDLE
STIXContentEncoding:
description: The content encoding applied to the request body.
enum:
- gzip
example: gzip
type: string
x-enum-varnames:
- GZIP
STIXIndicatorObject:
additionalProperties: {}
description: A STIX 2.1 indicator object.
properties:
confidence:
description: The confidence in the correctness of the indicator, from 0 through 100.
example: 80
format: int32
maximum: 100
minimum: 0
type: integer
created:
description: The time when the indicator was created.
example: "2026-07-22T12:00:00Z"
format: date-time
type: string
external_references:
description: Optional external reference metadata preserved with the indicator but not interpreted during ingestion.
items:
$ref: "#/components/schemas/STIXMetadataObject"
type: array
id:
description: The STIX indicator identifier.
example: indicator--22222222-2222-4222-8222-222222222222
type: string
indicator_types:
description: The open vocabulary terms that categorize the indicator.
example:
- malicious-activity
items:
type: string
type: array
kill_chain_phases:
description: Optional kill chain metadata preserved with the indicator but not interpreted during ingestion.
items:
$ref: "#/components/schemas/STIXMetadataObject"
type: array
labels:
description: Labels associated with the indicator.
example:
- synthetic
items:
type: string
type: array
modified:
description: The time when the indicator was last modified.
example: "2026-07-22T12:00:00Z"
format: date-time
type: string
object_marking_refs:
description: References to marking definition objects that apply to the indicator.
example:
- marking-definition--33333333-3333-4333-8333-333333333333
items:
type: string
type: array
pattern:
description: The STIX pattern that identifies the observable.
example: "[ipv4-addr:value = '198.51.100.42']"
type: string
pattern_type:
$ref: "#/components/schemas/STIXPatternType"
revoked:
description: Whether the indicator has been revoked.
example: false
type: boolean
spec_version:
$ref: "#/components/schemas/STIXSpecVersion"
type:
$ref: "#/components/schemas/STIXIndicatorType"
valid_from:
description: The time from which the indicator is considered valid.
example: "2026-07-22T12:00:00Z"
format: date-time
type: string
valid_until:
description: The time until which the indicator is considered valid.
example: "2027-07-22T12:00:00Z"
format: date-time
type: string
required:
- type
- id
- spec_version
- created
- modified
- pattern
- pattern_type
- valid_from
type: object
STIXIndicatorType:
description: The STIX object type for an indicator.
enum:
- indicator
example: indicator
type: string
x-enum-varnames:
- INDICATOR
STIXIngestResponse:
description: The response from a completed STIX ingestion request.
properties:
data:
$ref: "#/components/schemas/STIXIngestResponseData"
required:
- data
type: object
STIXIngestResponseAttributes:
description: Counters describing the result of the STIX ingestion request.
properties:
added:
description: The number of supported indicators added.
example: 1
format: int64
minimum: 0
type: integer
invalid:
description: The number of indicators with patterns that could not be parsed.
example: 0
format: int64
minimum: 0
type: integer
unsupported:
description: The number of unsupported objects or patterns.
example: 0
format: int64
minimum: 0
type: integer
required:
- added
- unsupported
- invalid
type: object
STIXIngestResponseData:
description: The JSON:API resource describing the completed STIX ingestion request.
properties:
attributes:
$ref: "#/components/schemas/STIXIngestResponseAttributes"
id:
description: The normalized vendor identifier.
example: acme
type: string
type:
$ref: "#/components/schemas/STIXIngestResponseType"
required:
- type
- id
- attributes
type: object
STIXIngestResponseType:
description: The STIX ingestion resource type.
enum:
- threat-intel-stix-ingest
example: threat-intel-stix-ingest
type: string
x-enum-varnames:
- THREAT_INTEL_STIX_INGEST
STIXMetadataObject:
additionalProperties: {}
description: An opaque STIX metadata object.
type: object
STIXPatternType:
description: The supported STIX pattern language.
enum:
- stix
example: stix
type: string
x-enum-varnames:
- STIX
STIXSpecVersion:
description: The supported STIX specification version.
enum:
- "2.1"
example: "2.1"
type: string
x-enum-varnames:
- VERSION_2_1
SalesforceIncidentsOrganizationResponseAttributes:
description: Attributes of a Salesforce organization connected to the Datadog Salesforce integration.
properties:
Expand Down Expand Up @@ -181627,6 +181850,114 @@ paths:
operator: OR
permissions:
- security_monitoring_notification_profiles_write
/api/v2/security/threat-intel/stix:
post:
description: |-
Ingest a STIX 2.1 bundle containing threat intelligence indicators. Only indicator objects are supported. Supported indicator patterns contain IPv4 addresses, IPv6 addresses, domain names, or SHA-256 file hashes.

Unsupported objects and patterns increment the `unsupported` counter. Patterns that cannot be parsed increment the `invalid` counter. Processing is best effort, so valid supported indicators in the same bundle are still added.

A successful response means ingestion has completed. Reference-table materialization and enrichment happen asynchronously. Requests are limited to 50 MB and 10 requests per second per API key. Gzip-compressed request bodies are supported.
operationId: IngestStixThreatIntel
parameters:
- description: >-
Vendor identifier for the feed. The value must not exceed 10 characters. Datadog normalizes the accepted value to lowercase, converts non-alphanumeric characters to underscores, and trims leading and trailing underscores.
example: acme
in: header
name: ti_vendor
required: true
schema:
maxLength: 10
minLength: 1
type: string
- description: Content encoding for the request body. Use gzip for a compressed STIX bundle.
in: header
name: Content-Encoding
required: false
schema:
$ref: "#/components/schemas/STIXContentEncoding"
requestBody:
content:
application/json:
examples:
default:
value:
id: bundle--11111111-1111-4111-8111-111111111111
objects:
- created: "2026-07-22T12:00:00Z"
id: indicator--22222222-2222-4222-8222-222222222222
modified: "2026-07-22T12:00:00Z"
pattern: "[ipv4-addr:value = '198.51.100.42']"
pattern_type: stix
spec_version: "2.1"
type: indicator
valid_from: "2026-07-22T12:00:00Z"
spec_version: "2.1"
type: bundle
schema:
$ref: "#/components/schemas/STIXBundleRequest"
description: >-
A STIX 2.1 bundle containing indicator objects. The maximum request size is 50 MB. When `Content-Encoding: gzip` is used, the limit applies to the compressed bytes received.
required: true
responses:
"200":
content:
application/json:
examples:
default:
value:
data:
attributes:
added: 1
invalid: 0
unsupported: 0
id: acme
type: threat-intel-stix-ingest
schema:
$ref: "#/components/schemas/STIXIngestResponse"
description: OK
"400":
$ref: "#/components/responses/BadRequestResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"413":
content:
application/json:
schema:
$ref: "#/components/schemas/APIErrorResponse"
description: Payload Too Large
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
"502":
content:
application/json:
schema:
$ref: "#/components/schemas/APIErrorResponse"
description: Bad Gateway
"503":
content:
application/json:
schema:
$ref: "#/components/schemas/APIErrorResponse"
description: Service Unavailable
security:
- apiKeyAuth: []
appKeyAuth: []
- AuthZ:
- reference_tables_write
summary: Ingest STIX threat intelligence
tags:
- Threat Intelligence
x-codegen-request-body-name: body
x-permission:
operator: OR
permissions:
- reference_tables_write
x-unstable: |-
**Note**: This endpoint is in preview and is subject to change.
If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
/api/v2/security/vulnerabilities:
get:
deprecated: true
Expand Down Expand Up @@ -204776,6 +205107,8 @@ tags:
- description: |-
Search and manage flaky tests through Test Optimization. See the [Test Optimization page](https://docs.datadoghq.com/tests/) for more information.
name: Test Optimization
- description: Ingest and manage threat intelligence data for security enrichment and investigation.
name: Threat Intelligence
- description: |-
The usage metering API allows you to get hourly, daily, and
monthly usage across multiple facets of Datadog.
Expand Down
Loading
Loading