Signal schema reference

The signal schema is the fixed field set every signal carries, the shape a detection writes when its conditions match.

A deployed detection materializes its signals into a continuous table at signals.<detection>, one row per match, and every row has this shape. The query fills the fields it can from the events it read, and the platform injects event.id. Because the field set is fixed, a signal from Okta and a signal from CloudTrail carry the same field names, and a detection reading another detection's signals correlates on them. The entity families (users, hosts, sources, destinations, and the rest) are arrays, because one signal can involve several of each. extra is the one place a query can add fields the schema does not define.

Notation

• [] marks an array of structs. The fields listed under it are the fields of one element.
• The schema marks only timestamp, message, and labels as required, so every other field is optional.
• unknown is the type the schema itself reports for sources[].geo.location and threat.enrichments[].indicator.geo.location, so neither field has a concrete type to document.

Top-level fields

Field	Type	Description
timestamp	timestamp	Time when the detection fired or the primary event occurred.
message	string	Human-readable summary of the signal, for display in the app.
labels	map<string, string>	Key-value map carrying the signal's most important context. Shaped for a language model to parse.
tags	array<string>	String tags for categorization and filtering.
event	struct	Event metadata describing the time window and classification of the detected activity.
signal	struct	Severity, confidence, risk assessment, and MITRE ATT&CK mapping for the signal.
detection	struct	Context about the rule that fired: authorship, references, known false positives, MITRE ATT&CK mapping, and methodology.
hosts	array<struct>	Hosts and systems involved.
users	array<struct>	Users and identities involved.
sources	array<struct>	Source endpoints involved, such as attacking IPs and originating systems.
destinations	array<struct>	Destination endpoints involved, such as target systems and accessed resources.
processes	array<struct>	Processes involved.
files	array<struct>	Files involved.
network_flows	array<struct>	Network flow information associated with the detected activity.
registry_entries	array<struct>	Windows registry entries involved.
cloud	struct	Cloud environment context for the detected activity.
urls	array<struct>	URLs involved.
threat	struct	Threat intelligence context and enrichments.
related	struct	Related signals and events involved in the detected activity.
extra	struct	Custom fields container. Fields a query writes under extra do not fail schema validation.

event

Field	Type	Description
event.start	timestamp	Start of the detected activity or observation window.
event.end	timestamp	End of the detected activity or observation window.
event.duration	int	Duration of the detected activity in nanoseconds, event.end minus event.start.
event.kind	string	Event kind. Always signal for detections.
event.id	string	Deterministic identifier for this signal instance. The platform injects it at deploy time.
event.action	string	The action captured by the event.
event.outcome	string	Outcome of the event. Valid values success, failure, unknown.

signal

The signal's identifier is event.id. The signal struct has no id field.

Field	Type	Description
signal.severity	string	Severity of the signal. Valid values critical, high, medium, low, informational.
signal.confidence	string	Detection confidence level. Valid values high, medium, low.
signal.risk_score	int	Base risk score for the detection, 0 to 100. Bands are 0-30 low, 31-60 medium, 61-85 high, and 86-100 critical.
signal.observed_count	int	Number of events that contributed to this detection.
signal.skip_alert	boolean	When true, Perpetual stores the signal and does not create an alert, even when the detection has alerting enabled. false, null, or an absent field leaves alerting unchanged.
signal.risk_factors	array<string>	Risk factors that contributed to the score.
signal.risk_summary	string	Human-readable risk explanation.
signal.mitre_tactics	array<string>	MITRE ATT&CK tactic names.
signal.mitre_techniques	array<string>	MITRE ATT&CK technique IDs.
signal.mitre_subtechniques	array<string>	MITRE ATT&CK sub-technique IDs.

detection

Field	Type	Description
detection.description	string	Detailed explanation of what the rule detects.
detection.author	string	Author or team that created the rule.
detection.references	array<string>	URLs to documentation, threat intel, or research.
detection.false_positives	array<string>	Known false positive scenarios.
detection.tags	array<string>	Searchable tags for categorization.
detection.mitre_tactics	array<string>	MITRE ATT&CK tactic names.
detection.mitre_techniques	array<string>	MITRE ATT&CK technique IDs.
detection.mitre_subtechniques	array<string>	MITRE ATT&CK sub-technique IDs.
detection.method	string	Detection methodology. Valid values signature, anomaly, correlation, behavioral, statistical, machine_learning.

TODO ‼️

Could not verify how detection.mitre_tactics, detection.mitre_techniques, and detection.mitre_subtechniques differ from the identically named fields on signal, or how detection.tags differs from the top-level tags. The schema gives each pair the same description and does not say which copy a consumer reads.

Sources checked:

• The get-signal-schema tool.
• packages/database/src/system-schemas/signal.json, which confirms each pair is two distinct fields (one inside the signal struct, one inside detection) rather than one field documented twice.
• packages/database/src/drizzle/schema/detection.ts plus packages/contracts/.../z-detection.ts, which carry no mitre_* fields at all, so neither copy is populated from the detection resource and a detection's query must write whichever it uses.
• Observed data in data-plane/integration-tests/.../perplogs/expected.json, which projects the detection.* copies.

Neither the schema nor the code answers which copy a detection author should populate. That is a product question.

hosts

Field	Type	Description
hosts[].name	string	Hostname or system identifier.
hosts[].id	string	Unique host identifier.
hosts[].ip	string	Host IP address.
hosts[].mac	string	Host MAC address.
hosts[].architecture	string	System architecture.
hosts[].os	struct	Operating system information.
hosts[].os.family	string	OS family, such as windows, linux, or macos.
hosts[].os.name	string	OS name.
hosts[].os.version	string	OS version.

users

Field	Type	Description
users[].name	string	Username.
users[].id	string	Unique user identifier.
users[].email	string	User email address.
users[].domain	string	User domain.
users[].full_name	string	Full user name.
users[].roles	array<string>	User roles or groups.

sources

Field	Type	Description
sources[].ip	string	Source IP address.
sources[].port	int	Source port.
sources[].domain	string	Source domain name.
sources[].geo	struct	Geographic location information for the source.
sources[].geo.country	string	Source country.
sources[].geo.city	string	Source city.
sources[].geo.location	unknown	Geographic coordinates.
sources[].user	struct	User information associated with the source.
sources[].user.name	string	Source username.
sources[].as	struct	Autonomous System information for the source IP.
sources[].as.number	int	Autonomous System Number.
sources[].as.organization	string	AS organization name.

destinations

Field	Type	Description
destinations[].ip	string	Destination IP address.
destinations[].port	int	Destination port.
destinations[].domain	string	Destination domain name.
destinations[].geo	struct	Geographic location information for the destination.
destinations[].geo.country	string	Destination country.

processes

Field	Type	Description
processes[].name	string	Process name.
processes[].pid	int	Process ID.
processes[].ppid	int	Parent process ID.
processes[].executable	string	Full path to executable.
processes[].command_line	string	Full command line.
processes[].working_directory	string	Working directory.
processes[].hash	struct	File hashes of the process executable.
processes[].hash.md5	string	MD5 hash of executable.
processes[].hash.sha256	string	SHA256 hash of executable.

files

Field	Type	Description
files[].path	string	Full file path.
files[].name	string	File name.
files[].directory	string	Directory path.
files[].extension	string	File extension.
files[].size	int	File size in bytes.
files[].hash	struct	File hashes, for integrity verification and threat intelligence lookup.
files[].hash.md5	string	MD5 hash of the file.
files[].hash.sha256	string	SHA256 hash of the file.
files[].created	timestamp	File creation time.
files[].modified	timestamp	Last modification time.

network_flows

Field	Type	Description
network_flows[].protocol	string	Network protocol.
network_flows[].transport	string	Transport protocol.
network_flows[].application	string	Application protocol.
network_flows[].direction	string	Traffic direction: inbound, outbound, internal, or external.
network_flows[].bytes	int	Total bytes transferred.
network_flows[].packets	int	Total packets.
network_flows[].community_id	string	Community ID flow hash, for correlating network flows.

registry_entries

Field	Type	Description
registry_entries[].path	string	Full registry path.
registry_entries[].key	string	Registry key.
registry_entries[].value	string	Registry value name.
registry_entries[].hive	string	Registry hive.
registry_entries[].data	struct	Registry value data.
registry_entries[].data.strings	array<string>	Registry value data as a string array.
registry_entries[].data.type	string	Registry value type.

cloud

Field	Type	Description
cloud.provider	string	Cloud provider: aws, azure, gcp, or digitalocean.
cloud.region	string	Cloud region.
cloud.account	struct	Cloud account information.
cloud.account.id	string	Cloud account ID.
cloud.account.name	string	Cloud account name.
cloud.project	struct	Cloud project information, for GCP and Azure.
cloud.project.id	string	Project or subscription ID.
cloud.service	struct	Cloud service information.
cloud.service.name	string	Cloud service name, such as ec2, lambda, iam, or s3.

urls

Field	Type	Description
urls[].full	string	Full URL.
urls[].domain	string	Domain name.
urls[].path	string	URL path.
urls[].query	string	Query string.
urls[].scheme	string	URL scheme.

threat

Field	Type	Description
threat.enrichments	array<struct>	Threat intelligence enrichments from indicator matching.
threat.enrichments[].indicator	struct	Threat indicator details from threat intelligence enrichment.
threat.enrichments[].matched	struct	Details about how the indicator matched the event.

threat.enrichments[].indicator

Field	Type	Description
threat.enrichments[].indicator.type	string	Indicator type, such as ipv4-addr, domain-name, file-hash, url, or email-addr.
threat.enrichments[].indicator.confidence	string	Vendor-neutral confidence rating.
threat.enrichments[].indicator.name	string	Display name for the indicator.
threat.enrichments[].indicator.description	string	Description of threat activity associated with this indicator.
threat.enrichments[].indicator.email_address	string	Email address indicator value.
threat.enrichments[].indicator.ip	string	IP address indicator value.
threat.enrichments[].indicator.port	int	Port number indicator value.
threat.enrichments[].indicator.first_seen	timestamp	When the intelligence source first reported this indicator.
threat.enrichments[].indicator.last_seen	timestamp	When the intelligence source last reported this indicator.
threat.enrichments[].indicator.modified_at	timestamp	Last modification timestamp for the indicator.
threat.enrichments[].indicator.marking_tlp	string	Traffic Light Protocol (TLP) sharing designation.
threat.enrichments[].indicator.marking_tlp_version	string	TLP version of the marking.
threat.enrichments[].indicator.provider	string	Threat intelligence provider name.
threat.enrichments[].indicator.reference	string	URL with additional information about the indicator.
threat.enrichments[].indicator.scanner_stats	int	Count of AV and EDR vendors detecting malicious content.
threat.enrichments[].indicator.sightings	int	Number of observations of this indicator.
threat.enrichments[].indicator.as	struct	Autonomous System information for IP indicators.
threat.enrichments[].indicator.as.number	int	Autonomous System Number.
threat.enrichments[].indicator.as.organization	string	AS organization name.
threat.enrichments[].indicator.file	struct	File information for file-based indicators.
threat.enrichments[].indicator.file.hash_md5	string	MD5 hash of the file.
threat.enrichments[].indicator.file.hash_sha256	string	SHA256 hash of the file.
threat.enrichments[].indicator.file.name	string	File name.
threat.enrichments[].indicator.file.path	string	File path.
threat.enrichments[].indicator.file.size	int	File size in bytes.
threat.enrichments[].indicator.geo	struct	Geographic information for the indicator.
threat.enrichments[].indicator.geo.country	string	Country code.
threat.enrichments[].indicator.geo.city	string	City name.
threat.enrichments[].indicator.geo.location	unknown	Geographic coordinates.
threat.enrichments[].indicator.registry	struct	Registry information for registry-based indicators.
threat.enrichments[].indicator.registry.path	string	Full registry path.
threat.enrichments[].indicator.registry.key	string	Registry key.
threat.enrichments[].indicator.registry.value	string	Registry value name.
threat.enrichments[].indicator.url	struct	URL information for URL-based indicators.
threat.enrichments[].indicator.url.full	string	Full URL.
threat.enrichments[].indicator.url.domain	string	Domain name.
threat.enrichments[].indicator.url.path	string	URL path.
threat.enrichments[].indicator.url.scheme	string	URL scheme.

threat.enrichments[].matched

Field	Type	Description
threat.enrichments[].matched.atomic	string	The atomic indicator value that matched.
threat.enrichments[].matched.field	string	The field in the event that matched the indicator.
threat.enrichments[].matched.id	string	Indicator document ID.
threat.enrichments[].matched.index	string	Indicator document index.
threat.enrichments[].matched.occurred	timestamp	Match generation time.
threat.enrichments[].matched.type	string	Match type identifier.

related

Field	Type	Description
related.events	array<struct>	Related events involved in the detected activity.
related.events[].timestamp	timestamp	Time when the related event occurred.
related.events[].message	string	Human-readable description of the related event.
related.events[].labels	map<string, string>	Key-value context map for the related event.
related.events[].tags	array<string>	Tags categorizing the related event.
related.events[].event	struct	Event metadata for the related event.
related.events[].event.id	string	Unique identifier for the related event.
related.signals	array<struct>	Related signals involved in the detected activity.
related.signals[].timestamp	timestamp	Time when the related signal fired.
related.signals[].message	string	Human-readable description of the related signal.
related.signals[].labels	map<string, string>	Key-value context map for the related signal.
related.signals[].tags	array<string>	Tags categorizing the related signal.
related.signals[].signal	struct	Signal metadata for the related signal.
related.signals[].signal.id	string	Unique identifier for the related signal.
related.signals[].signal.severity	string	Severity of the related signal. Valid values critical, high, medium, low, informational.
related.signals[].signal.risk_score	int	Risk score of the related signal, 0 to 100.

Related

• Detections, the resource whose query writes these fields.
• ECS field reference, the schema of the normalized events a detection reads.
• Signals vs alerts, what happens to a signal after a detection writes it.
• Write a detection, how to author and deploy the query that fills these fields.