Structured Entities

The Structured Entities feature represents a significant enhancement to how entities are handled in Secureworks® Taegis™ XDR. Unlike traditional string-based entities, structured entities are represented as objects that can carry rich metadata and properties, enabling more sophisticated analysis, searching, and pivoting capabilities.

Overview

Structured entities have the following benefits:

• Carry rich metadata: Entities now include detailed properties beyond simple string values.
• Enable advanced searching: You can search on specific entity properties using advanced search syntax.
• Support complex pivoting: You can pivot on multiple entity properties for precise identification.
• Integrate with Entity Graph: Structured entities use the same types as the Entity Graph for consistency.

Entity Structure

Structured entities are found in the source_entities and target_entities properties of detections, depending on their perspective. Each entity contains:

• 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

For complete technical details about all entity types and their properties, see Entity v2 Protocol Buffer Reference.

Common Entity Types and Examples

This section contains common entity types with examples and properties. For the full list of entity types, see Entity v2 Protocol Buffer Reference.

User Entities

User entities are now broken down into structured components, allowing for more granular analysis and searching. For example, a user foo@bar.com is represented as:

• user.user_name = "foo"
• user.domain_name = "bar.com"
• user.original_user_name = "foo@bar.com"

The following are available properties:

• user_name: The username portion
• domain_name: The domain portion
• original_user_name: The complete original user string
• 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
• group: Group prefix, such as "SYS" from "SYS\j.doe@scwx.com"
• computer_name: Associated computer name
• host_id: Associated host identifier
• user_id: Unique user identifier

File Entities

File entities provide comprehensive file information including paths, hashes, and metadata. For example, a file /usr/bin/malware.exe is represented as:

• file.file_name = "malware.exe"
• file.file_path = "/usr/bin/malware.exe"
• file.file_type = "application/pdf"
• file.hash_sha256 = "a1b2c3d4e5f6..."

The following are available properties:

• file_name: Name of the file
• file_path: Full path to the file
• 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
• host_id: Associated host identifier
• email_attachment_sandbox_status: Sandbox analysis status for email attachments

Process Entities

Process entities contain detailed information about running processes and their characteristics. For example, a process notepad.exe running as admin is represented as:

• process.process_name = "notepad.exe"
• process.process_id = "1234"
• process.process_is_admin = true
• process.process_image_path = "C:\\Windows\\System32\\notepad.exe"

The following are available properties:

• process_name: Name of the process
• process_id: Process ID (PID)
• process_uuid: Unique process identifier
• process_correlation_id: Correlation ID for process tracking
• 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 Entities

IP address entities include geolocation data, network classification, and ASN information. For example, an IP address 192.168.1.100 is represented as:

• ip_address.ip_address = "192.168.1.100"
• ip_address.ip_classification = "PRIVATE"
• ip_address.asn = 12345
• ip_address.ip_geo_country_code = "US"

The following are available properties:

• ip_address: The IP address
• 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
• host_id: Associated host identifier
• 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 Entities

File hash entities represent cryptographic hashes of files with their associated metadata. For example, a SHA256 hash is represented as:

• filehash.hash_value = "a1b2c3d4e5f6789..."
• filehash.hash_type = "SHA256"

The following are available properties:

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

Advanced Search Examples

Structured entities enable powerful Advanced Search capabilities using specific entity properties.

Basic Property Searches

-- Search for detections with admin users
from detection where source_entities.user.user_is_admin = true

-- Search for processes running with admin privileges
from detection where source_entities.process.process_is_admin = true

-- Find detections with specific IP classifications
from detection where source_entities.ip_address.ip_classification = 'PUBLIC'

Geolocation Searches

-- Search for detections from specific countries
from detection where source_entities.ip_address.ip_geo_country_code = 'CN'

-- Find detections from specific cities
from detection where source_entities.ip_address.ip_geo_city_name = 'Beijing'

-- Search for detections from specific ASNs
from detection where source_entities.ip_address.asn = 12345

-- Find detections from specific geographic regions
from detection where source_entities.ip_address.ip_geo_continent_code = 'AS'

Hash-based Searches

-- Search for specific file hashes
from detection where source_entities.file.hash_sha256 = 'a1b2c3d4e5f6789...'

-- Search for process executables with specific hashes
from detection where source_entities.process.hash_sha256 = 'b2c3d4e5f6789a1...'

User Domain Searches

-- Search for users from specific domains
from detection where source_entities.user.domain_name = 'company.com'

-- Find admin users connecting to specific domains
from detection where target_entities.user.domain_name = 'company.com' and source_entities.user.user_is_admin = true

-- Search for specific usernames across domains
from detection where source_entities.user.user_name = 'admin'

Complex Multi-Property Searches

-- Find detections with admin processes to specific countries
from detection where source_entities.process.process_is_admin = true and target_entities.ip_address.ip_geo_country_code = 'RU'

-- Find detections involving specific file paths and admin processes
from detection where target_entities.file.file_path contains 'C:\\Windows\\System32' and source_entities.process.process_is_admin = true

Cybersecurity Use Cases

Threat Hunting

Hunting for Privilege Escalation:

-- Find processes running with admin privileges
from detection where source_entities.process.process_is_admin = true

Tracking Lateral Movement:

-- Find authentication events from external IPs
from detection where source_entities.ip_address.ip_classification = 'PUBLIC' and target_entities.user.user_name is not null

Incident Response

Geographic Analysis:

-- Identify detections from specific geographic regions
from detection where source_entities.ip_address.ip_geo_country_code in ('CN', 'RU', 'IR', 'KP')

ASN-based Investigation:

-- Find detections from specific ASNs (e.g., known malicious hosting providers)
from detection where source_entities.ip_address.asn in (12345, 67890, 11111)

File Hash Correlation:

-- Search for known malicious file hashes
from detection where target_entities.file.hash_sha256 in ('hash1', 'hash2', 'hash3')

Compliance and Auditing

Admin Activity Monitoring:

-- Monitor all admin user activity
from detection where source_entities.user.user_is_admin = true or target_entities.user.user_is_admin = true

Network Segmentation Verification:

-- Verify no cross-segment communication
from detection where source_entities.ip_address.ip_classification = 'PRIVATE' and target_entities.ip_address.ip_classification = 'PUBLIC'

Pivoting on Structured Entities

You can pivot on structured entities by clicking the Magnifying Glass icon next to them in detection details. The pivot functionality uses multiple entity properties to uniquely identify the entity.

Pivot Examples

User Pivot:

A user foo@bar.com can be identified by:

• user.user_name = 'foo' AND user.domain_name = 'bar.com'

You can relax the search criteria in advanced search to search only for user.user_name = 'foo'

File Pivot:

A file can be identified by:

• file.file_name = 'malware.exe' AND file.host_id = host123

Process Pivot:

A process can be identified by:

• process.process_id = '1234' AND process.host_id = 'host123'

IP Address Pivot:

A local IP address can be identified by:

• ip_address.ip_address = '127.0.0.1 AND ip_address.host_id = 'host123'

Integration with Entity Graph

Structured entities use the same entity types as Entity Graph, ensuring consistency across XDR. This provides the following benefits:

• Entity relationships are preserved
• Entity properties are consistent
• Pivoting works seamlessly between detections and the entity graph
• Search capabilities are unified across the platform

Best Practices

1. Use specific properties: When searching, use the most specific properties available to reduce false positives.
2. Combine multiple criteria: Use multiple entity properties to create more precise searches.
3. Leverage geolocation data: Use IP geolocation properties for geographic threat hunting.
4. Monitor admin activity: Regularly search for admin user and process activity.
5. Track file hashes: Use file hash properties to correlate with threat intelligence.
6. Relax search criteria: When pivoting, you can remove some criteria in advanced search to broaden results.

Related Topics

• Detection Details
• Advanced Search
• Entity Graph
• Threat Hunting
• Entity v2 Protocol Buffer Reference