Entity v2 Protocol Buffer Reference

This document provides a complete reference for all entity types and their properties used in Secureworks® Taegis™ XDR's Structured Entities feature. Each entity type is organized with clear descriptions of identifiers and properties.

Overview

The Entity v2 Protocol Buffer defines the structure and properties for all entity types used in XDR. Each entity contains the following:

• Identifiers: Core information that uniquely identifies the entity
• Properties: Additional metadata and characteristics of the entity
• Perspective: Whether the entity is a source, a target, or both

Usage Notes

• Identifiers vs Properties: Identifiers are core identifying information that uniquely identifies the entity, while properties contain additional metadata and characteristics.
• Deprecated Fields: Some fields are marked as deprecated and should not be used in new implementations.
• Perspective: Each entity has a perspective indicating whether it's a source, target, or both in the context of a detection.

Entity Types

User Entity

User entities represent users in the system with detailed authentication and administrative information.

Identifiers:

• user_name: The username portion, such as "j.doe" from "SYS\j.doe@scwx.com"
• domain_name: The domain associated with a user, such as "scwx.com" from "SYS\j.doe@scwx.com"
• group: Group prefix portion, such as "SYS" from "SYS\j.doe@scwx.com"
• computer_name: Associated computer name
• host_id: Associated host identifier
• user_id: Unique user identifier, often a GUID
• auth_domain: Deprecated field, use domain_name instead

Properties:

• original_user_name: Complete original user string, such as "SYS\j.doe@scwx.com"
• user_is_admin: Boolean indicating if the user has admin privileges
• cloud_user_type: Type of cloud user, such as Regular, Application, ServicePrincipal, System, and Admin

File Entity

File entities provide comprehensive file information including paths, hashes, and metadata.

Identifiers:

• file_name: Name of the file
• file_path: Full path to the file
• host_id: Associated host identifier
• email_message_id: Associated email message ID for email attachments

Properties:

• file_type: Detected file type
• file_type_detected: File type as detected by analysis
• file_size: Size of the file in bytes
• file_owner: Owner of the file
• file_group_owner: Group owner of the file
• file_create_time: File creation timestamp
• file_modified_time: File modification timestamp
• hash_md5: MD5 hash of the file
• hash_sha1: SHA1 hash of the file
• hash_sha256: SHA256 hash of the file
• hash_sha512: SHA512 hash of the file
• email_attachment_sandbox_status: Sandbox analysis status for email attachments

Process Entity

Process entities contain detailed information about running processes and their characteristics.

Identifiers:

• process_name: Name of the process
• process_id: Process ID (PID)
• process_uuid: Unique process identifier
• process_correlation_id: Correlation ID for process tracking

Properties:

• process_image_path: Full path to the process executable
• process_is_admin: Boolean indicating if process runs with admin privileges
• process_create_time: Process creation timestamp
• host_id: Associated host identifier
• hash_md5: MD5 hash of the process executable
• hash_sha1: SHA1 hash of the process executable
• hash_sha256: SHA256 hash of the process executable
• hash_sha512: SHA512 hash of the process executable

IP Address Entity

IP address entities include geolocation data, network classification, and ASN information.

Identifiers:

• ip_address: The IP address
• host_id: Associated host identifier

Properties:

• ip_address_type: Type of IP address (IPv4/IPv6)
• ip_classification: Classification (LOCAL, PRIVATE, PUBLIC)
• is_nat_ip: Boolean indicating if IP is behind NAT
• asn: Autonomous System Number
• hostname: Associated hostname
• ip_geo_city_name: City name from geolocation
• ip_geo_country_code: Country code from geolocation
• ip_geo_continent_code: Continent code from geolocation
• ip_geo_latitude: Latitude coordinate
• ip_geo_longitude: Longitude coordinate
• ip_geo_auto_system_org: Organization from ASN data
• ip_geo_country_geoname_id: GeoNames country ID

File Hash Entity

File hash entities represent cryptographic hashes of files with their associated metadata.

Identifiers:

• hash_value: The hash value
• hash_type: Type of hash (MD5, SHA1, SHA256, SHA512)

Properties: None

Host Entity

Host entities represent computer systems and devices in the environment.

Identifiers:

• computer_name: Computer name
• host_id: Unique host identifier
• hostname: Hostname
• hostname_fqdn: Fully qualified domain name

Properties:

• mac_address: MAC address of the host
• os: Operating system
• os_arch: Operating system architecture
• sensor_id: Sensor ID associated with the host
• sensor_type: Type of sensor
• vendor_agent_device_id: Vendor-specific device ID
• vendor_agent_device_score: Vendor-specific device score

Email Entity

Email entities represent email messages and their metadata.

Identifiers:

• email_message_id: Vendor-assigned ID of the email message

Properties:

• email_message_size: Size of the email message
• email_quarantine_reason: Reason for email quarantine
• reply_to_email_address: Reply-to email address
• vendor_alert_url: Vendor-specific alert URL
• vendor_email_spam_score: Vendor-specific spam score

Email Address Entity

Email address entities represent email addresses.

Identifiers:

• email_address: The email address

Properties: None

Domain Name Entity

Domain name entities represent domain names.

Identifiers:

• domain_name: The domain name

Properties: None

URL Entity

URL entities represent web URLs with parsed components.

Identifiers:

• full_url: Complete URL

Properties:

• uri_scheme: URL scheme, such as http and https
• uri_host: Host portion of the URL
• uri_path: Path portion of the URL
• uri_query: Query string portion
• uri_fragment: Fragment portion
• uri_port: Port number
• uri_userinfo: User information portion

Certificate Entity

Certificate entities represent SSL/TLS certificates with detailed issuer and subject information.

Identifiers:

• cert_issuer: Certificate issuer
• cert_serial_number: Certificate serial number

Properties:

• cert_issuer_c: Issuer country
• cert_issuer_cn: Issuer common name
• cert_issuer_e: Issuer email
• cert_issuer_l: Issuer locality
• cert_issuer_o: Issuer organization
• cert_issuer_order: Issuer organization unit order
• cert_issuer_ou: Issuer organization unit
• cert_issuer_s: Issuer state
• cert_ja3: JA3 fingerprint
• cert_ja3s: JA3S fingerprint
• cert_subject: Certificate subject
• cert_subject_c: Subject country
• cert_subject_cn: Subject common name
• cert_subject_e: Subject email
• cert_subject_l: Subject locality
• cert_subject_o: Subject organization
• cert_subject_order: Subject organization unit order
• cert_subject_ou: Subject organization unit
• cert_subject_s: Subject state
• cert_valid_from: Certificate valid from date
• cert_valid_through: Certificate valid through date

Cloud Resource Entity

Cloud resource entities represent cloud infrastructure resources.

Identifiers:

• cloud_resource_account_id: Cloud account ID
• cloud_resource_id: Cloud resource ID
• cloud_resource_type: Type of cloud resource

Properties: None

Cloud Object Entity

Cloud object entities represent cloud storage objects.

Identifiers:

• cloud_object_bucket: Cloud storage bucket name
• cloud_object_key: Cloud storage object key
• cloud_object_prefix: Cloud storage object prefix

Properties: None

Cloud User Entity (Deprecated)

Cloud user entities represent cloud users. This entity type is deprecated in favor of the User entity.

Identifiers:

• cloud_user_id: Cloud user ID
• cloud_user_name: Cloud user name
• cloud_user_type: Type of cloud user

Properties: None

DNS Server Entity

DNS server entities represent DNS servers.

Identifiers:

• host_id: Associated host identifier
• ip_address: DNS server IP address

Properties:

• ip_address_type: Type of IP address (IPv4/IPv6)
• ip_classification: Classification (LOCAL, PRIVATE, PUBLIC)

Auth Domain Entity

Auth domain entities represent authentication domains.

Identifiers:

• auth_domain: Authentication domain name

Properties: None

Function Entity

Function entities represent functions in code.

Identifiers:

• function_name: Name of the function
• host_id: Associated host identifier

Properties: None

Registry Key Entity

Registry key entities represent Windows registry keys.

Identifiers:

• host_id: Associated host identifier
• registry_path: Registry key path

Properties: None

Scheduled Task Entity

Scheduled task entities represent scheduled tasks.

Identifiers:

• host_id: Associated host identifier
• task_name: Name of the scheduled task

Properties: None

Task Action Entity

Task action entities represent actions within scheduled tasks.

Identifiers:

• host_id: Associated host identifier
• task_action_id: Task action ID
• task_action_path: Task action path

Properties:

• task_action_args: Task action arguments
• task_action_class_id: Task action class ID
• task_action_type: Type of task action
• task_action_working_directory: Task action working directory

Service Entity

Service entities represent system services.

Identifiers:

• host_id: Associated host identifier
• service_dll: Service DLL
• service_main: Service main function
• service_name: Name of the service

Properties:

• service_start_type: Service start type
• service_type: Type of service

Script Entity

Script entities represent scripts and their metadata.

Identifiers:

• hash_value: Hash of the script
• host_id: Associated host identifier
• script_name: Name of the script

Properties:

• interpreter: Script interpreter
• is_truncated: Boolean indicating if script is truncated

Related Documentation

• Structured Entities: Main documentation for using structured entities
• Detection Details: Information about detection structure
• Advanced Search: How to search using entity properties