TEDS Reference

The TEDS reference documentation establishes a standardized data schema aimed at creating a unified framework to support seamless collaboration between security teams and tools. It promotes consistent data formats and schemas, particularly within Swimlane's products, enhancing the detection, analysis, and response capabilities for security incidents. This standardization also simplifies the integration process for various cybersecurity tools, reducing complexity and minimizing integration effort.

TEDS schemas are integrated throughout Swimlane Turbine in several key areas:

The SOC Solutions Bundle uses TEDS schemas extensively for security operations workflows:

TEDS schemas are implemented through Turbine Solutions Interfaces, which provide standardized input and output formats for components. When building components in Turbine Canvas, you can apply interfaces that use TEDS schemas, such as:

These interfaces ensure components can work together seamlessly because they all use the same TEDS-based data structures.

When building applications in Swimlane Turbine, you can follow TEDS naming conventions for your field keys to ensure compatibility with TEDS-based workflows and integrations. This is especially important when:

TEDS schemas can be applied to playbook actions through Input Schema References. When configuring record actions (Create, Update/Create, Search), you can reference TEDS-based schemas to ensure your playbooks accept and process data in standardized formats.

For customers who prefer to develop their own solutions, data management can present a significant challenge. Standard data fields and naming conventions become essential for maintaining consistency and avoiding data loss or errors.

For instance, in scenarios where customers use a database like MongoDB Atlas Event Manager, even though Swimlane doesn't provide a direct solution for this specific database, the data still needs to be accurately saved to the database or application. A schema with consistent naming conventions is crucial; mismatches between field names can lead to lost or mishandled records. For customers unfamiliar with TEDS references, it's important to ensure that their applications adhere to correct naming conventions to avoid any data errors and ensure reliable data management across systems.

When building applications that will work with TEDS-based data:

When building playbooks that process TEDS-formatted data:

Here's an example of how TEDS is used in an Alert Triage workflow:

This standardized approach ensures that data flows seamlessly between different components and systems, regardless of the underlying technology or vendor.

The following examples show real-world TEDS-formatted data structures used in the SOC Solutions Bundle. These examples demonstrate how TEDS schemas are implemented in practice.

Here's a complete Alert object following TEDS conventions:

Here's a complete Email object following TEDS conventions:

Here's a complete Observable object with enrichment data:

This example shows how raw data from a SIEM system is transformed into TEDS format:

Raw Splunk Alert:

Transformed to TEDS Alert:

Key Transformation Steps:

Understanding what not to do is just as important as following best practices. The following examples show common mistakes and how to correct them.

Problem: Using camelCase or mixed case instead of snake_case.

❌ WRONG:

✅ CORRECT:

Why it fails: Field names are case-sensitive. Components expecting alert_uid will not find alertUid, causing data to be lost or validation errors.

Problem: Using strings for array fields or incorrect data types.

❌ WRONG:

✅ CORRECT:

Why it fails: Array fields must be arrays, not comma-separated strings. Integer fields must be numbers, not strings. Type mismatches cause validation errors and prevent proper data processing.

Problem: Omitting required fields from TEDS objects.

❌ WRONG:

✅ CORRECT:

Why it fails: Required fields (alert_uid and raw_alert for Alert objects) must always be present. Missing required fields cause schema validation failures and prevent data ingestion.

Problem: Not following the correct structure for nested objects like observables or enrichments.

❌ WRONG:

✅ CORRECT:

Why it fails: observables must be an array, even for a single observable. Using an object instead of an array causes type validation errors.

Problem: Using invalid values for observable_type field.

❌ WRONG:

✅ CORRECT:

Why it fails: observable_type must use exact TEDS values: ipv4_public, ipv4_private, ipv6_public, ipv6_private, url, domain, email, sha256, sha1, md5, or file. Invalid types cause validation errors and prevent observable processing.

Problem: Using incorrect date/time formats.

❌ WRONG:

✅ CORRECT:

Why it fails: All datetime fields must use ISO 8601 format with UTC timezone (Z suffix). Incorrect formats cause parsing errors and time-based queries to fail.

Problem: Inconsistent naming within the same object.

❌ WRONG:

✅ CORRECT:

Why it fails: All fields must consistently use snake_case. Mixing conventions causes some fields to be unrecognized and data to be lost.

Problem: Data ingested via TEDS schemas isn't appearing in your application records.

Solutions:

Problem: Playbook actions fail with schema validation errors.

Solutions:

Problem: Components or connectors aren't working together as expected.

Solutions:

Problem: Observable enrichments are not being applied or are missing from results.

Solutions:

Problem: Timestamp fields are not being recognized or parsed correctly.

Solutions:

Problem: Data appears as a single value when it should be an array, or vice versa.

Solutions:

Problem: Nested objects like observables, enrichments, or detection rules are not structured correctly.

Solutions:

Problem: Fields are not being recognized due to typos or case mismatches.

Solutions:

Problem: The raw_alert or raw_email field is missing or incorrectly formatted.

Solutions:

The event schema categorizes attributes into three levels: Core, Optional, and Reserved.

The Open Cybersecurity Schema Framework allows for extensions through additional attributes, objects, and event classes.

To extend the schema:

Here is a list of objects and their corresponding inputs:

A SIEM (Security Information and Event Management) or XDR (Extended Detection and Response) alert serves as an early warning system for potential security incidents within an organization's IT environment. By aggregating and analyzing log data, network activity, endpoint behaviors, and user actions, a SIEM or XDR platform can detect suspicious or malicious activities and generate alerts for security teams to investigate and respond.

This solution is designed to ingest alerts from various alerting tools, such as SIEM, EDR, and AV systems. It enriches the alerts with data from third-party services like VirusTotal, URLHaus, and Recorded Future, then creates cases for analysts to review, collaborate on, and resolve. The goal is to automate the SOC team's handling of the constant stream of alerts, driving incidents to remediation or closing invalid ones. This results in faster remediation, reduced costs in human resources, and an overall more secure environment.

The attack object defines the specific techniques and corresponding tactics involved in an attack. It provides detailed information about the methods used and references the relevant version of the ATT&CK Matrix™

Monitor the network data for uncommon data flows. Processes utilizing the network do not normally have network communication or have never been seen before are suspicious.

Cloud Storage Query Input is a feature that enables users to perform customized searches for files within a cloud storage provider's system. By inputting specific parameters or keywords, users can filter files based on attributes like file name, type, date, and other metadata. This query input functionality is essential for quickly locating files within vast repositories, optimizing access times, and improving data management efficiency, especially in enterprise environments such as TEDS

File-like content, attachment, or bytearray

Detection Rule is a configurable rule designed to trigger alerts when specific conditions or anomalies are detected within a system. It includes attributes such as a unique ID, name, description, and type, allowing organizations to categorize and describe the rule’s purpose and scope, enabling more effective monitoring and response to potential threats.

The Email object represents essential metadata related to an email, including details about the sender, recipients, and email's direction. It contains fields for tracking various email components such as BCC, CC, subject, body, timestamps, headers, and observables, enabling comprehensive analysis and record-keeping of email communications.

The Enrichment object adds valuable context to event attributes, providing metadata such as the provider, type, timestamp, raw data, and a link to the original source. It also includes a reputation verdict (example, benign, malicious, suspicious, or unknown) to quickly assess the nature of the enriched data and aid in detailed event analysis.

The Error object captures details about errors encountered during processing, including essential information to aid in troubleshooting. It includes fields like the error provider, which specifies the tool, service, or software source of the error; error result, offering a description of the error; and error status, indicating the current status of the error, allowing for efficient identification and resolution of issues.

The File object provides comprehensive details about files, folders, links, and mounts, including relevant metadata and potential reputation information for security analysis. Key attributes include the file's content, access times (created, accessed, and modified), file name and encoding, unique file hashes for identification, MIME type, file size, and any observable indicators of compromise, supporting robust file tracking and management across systems.

The File Hash object provides a unique digital fingerprint for a file, allowing verification of its integrity and authenticity. It includes the hash algorithm name, specifying which hashing method (example, MD5, SHA-256) was used, and the hash value, which is the unique code generated by the hash function, ensuring files can be consistently identified and monitored for changes.

The Header object represents key-value pairs within HTTP or Email headers, containing essential metadata for communication protocols. It includes the header key, which specifies the name of the header (example, "Content-Type" for HTTP or "Subject" for Email), and the header value, which holds the corresponding information, such as the content type, sender, or other protocol-specific data, facilitating structured data transmission and analysis.

The MIME Part object represents a single, non-multipart section of a MIME-encoded email, containing data such as text, images, or attachments. It includes fields like content, which stores the actual data of the MIME part; file name, which is derived from the content-disposition if available; is attachment, indicating whether the MIME part is an attachment or inline content; and mime type, defining the media type (example, "text/plain" or "image/jpeg") for proper handling by email clients.

The Observable object serves as a key reference element, capturing related data that appears across multiple points in an event, making it central for linking information and context. Key fields include observable enrichments, which is an array of enrichment data applied to the observable; observable metadata, used if the observable is composite (example, a file); primary context details from the main enrichment source, such as provider name, timestamp, and reputation verdict; observable type, defining the kind (example, URL, file, email); and observable value, which contains either a simple identifier (example, IP address) or a unique string for complex observables (example, SHA256 hash for files).

The Phishing Email Report object captures comprehensive details about a suspected phishing email, providing critical information for investigation and security response. It includes fields like report description for incident details, reporter information, and essential email components such as sender, recipients (To, CC, BCC), delivery timestamp, subject, and content (both HTML and text), along with observables for any compromise indicators, and raw email data as received by the server to support thorough analysis.

The Phishing Triage Email Ingestion process defines the parameters for processing and assessing incoming phishing emails, supporting proactive threat response. Key inputs include the organization field, specifying the affected organization, and start time, which determines how far back to search for relevant phishing reports, allowing for focused and time-sensitive analysis of potential phishing threats.

The Simple Observable object acts as a key reference point within an event, containing data that is often repeated across multiple parts of the event. It includes fields such as observable metadata, populated when the observable is a complex type (like a file), observable type, which defines the kind of data (example, domain, email, IP), and observable value, which provides a unique identifier or value, like an IP address for simple observables or a SHA256 hash for composite ones.

The Status object provides detailed information about the current state of a tool, software, or service, capturing both the outcome and descriptive details for troubleshooting or logging. Key fields include status messages, an array of log-like messages, status provider, identifying the source of the status, status raw, containing the unprocessed status in JSON format, status description, which summarizes the status, and status success, indicating whether the status reflects success or an error.

The Tactic object identifies specific tactics linked to an attack technique, as outlined by the ATT&CK Matrix™, providing a standardized approach to describing adversarial behaviors. It includes the name of the tactic, giving a descriptive label, and a unique ID (UID), which serves as a standardized identifier for the tactic, enabling precise tracking and categorization of tactics used in cybersecurity threat analysis.

The Technique object represents a specific ATT&CK Matrix™ technique used in an attack, detailing how adversaries may achieve certain objectives. It includes fields like name, which gives the descriptive label of the technique (example, "Drive-by Compromise"), and unique ID (UID), a standardized identifier (example, "T1189"), which allows for consistent referencing and analysis of attack methods.

The User object represents a user account with identifying information for secure and personalized interactions within a system. It includes key attributes such as user email address, providing the user’s email for contact and identification, user ID, a unique identifier for distinguishing each user account, and user name, the username associated with the account, supporting authentication and user-specific activity tracking.