This document describes the structure and fields of JSON alerts in OSSEC.
Basic Structure
The JSON alert is a structured object containing several key sections:
{
"version": "string",
"timestamp": "string",
"id": "string",
"rule": { ... },
"agent": { ... },
"manager": { ... },
"data": { ... },
"location": "string",
"full_log": "string"
}
Field Descriptions
Top-Level Fields
- version: The version of the alert format
- timestamp: The time when the alert was generated (format: YYYY-MM-DDTHH:MM:SS.mmm+ZZZZ)
- id: Unique identifier for the alert
- location: Source location of the alert (e.g., file path, syslog source)
- full_log: The complete log message that triggered the alert
Rule Object
The rule object contains information about the rule that triggered the alert:
{
"id": "string",
"level": number,
"description": "string",
"groups": ["string"],
"info": "string",
"frequency": number,
"firedtimes": number,
"mail": boolean
}
- id: Rule identifier
- level: Severity level (0-15)
- description: Rule description
- groups: Array of rule groups/categories
- cve: CVE identifier (if applicable)
- info: Additional rule information
- frequency: Rule frequency
- firedtimes: Number of times the rule has fired
- mail: Whether email alerts are enabled for this rule
Agent Object
The agent object contains information about the agent that generated the alert:
{
"id": "string",
"name": "string",
"ip": "string"
}
- id: Agent identifier
- name: Agent name
- ip: Agent IP address
Manager Object
The manager object contains information about the manager that processed the alert:
{
"name": "string"
}
- name: Manager hostname
Data Object
The data object contains additional alert-specific information:
{
"protocol": "string",
"action": "string",
"srcip": "string",
"srcport": "string",
"srcuser": "string",
"dstip": "string",
"dstport": "string",
"dstuser": "string",
"file": "string",
"file_diff": { ... }
}
- protocol: Network protocol (if applicable)
- action: Action that triggered the alert
- srcip: Source IP address
- srcport: Source port
- srcuser: Source user
- dstip: Destination IP address
- dstport: Destination port
- dstuser: Destination user
- file: File path (for file-related alerts)
- file_diff: Object containing file change information
File Diff Object
The file_diff object contains information about file changes:
{
"size_before": "string",
"size_after": "string",
"perm_before": "string",
"perm_after": "string",
"win_perm_before": { ... },
"win_perm_after": { ... },
"value_type": "string"
}
- size_before: File size before change
- size_after: File size after change
- perm_before: File permissions before change
- perm_after: File permissions after change
- win_perm_before: Windows permissions before change
- win_perm_after: Windows permissions after change
- value_type: Type of value (for registry changes)
Cluster Information
If cluster information is enabled, the alert may include:
{
"cluster": {
"name": "string",
"node": "string"
}
}
- name: Cluster name
- node: Node name
Additional Fields
Depending on the alert type, additional fields may be present:
- srcgeoip: Source IP geolocation information
- dstgeoip: Destination IP geolocation information
- md5_old: Old MD5 hash
- md5_new: New MD5 hash
- sha1_old: Old SHA1 hash
- sha1_new: New SHA1 hash
- sha256_old: Old SHA256 hash
- sha256_new: New SHA256 hash
Dynamic Decoders
OSSEC supports dynamic decoders that can extract custom fields from log messages. These fields are stored in the data object of the alert. Dynamic decoders are defined in XML files and can extract fields using regular expressions.
Dynamic Fields Structure
Dynamic fields are stored in the data object with their custom names:
{
"data": {
"custom_field1": "value1",
"custom_field2": "value2",
...
}
}
Decoder Configuration
Dynamic decoders are configured in XML files (/var/ossec/etc/decoders.d) with the following structure:
<decoder name="decoder_name">
<parent>parent_decoder</parent>
<regex>regular_expression</regex>
<order>field1, field2, field3</order>
</decoder>
- name: Unique identifier for the decoder
- parent: Parent decoder name (optional)
- regex: Regular expression to match and extract fields
- order: Comma-separated list of field names to extract
Example Dynamic Decoder
Here’s an example of a dynamic decoder that extracts QualysGuard fields:
<decoder name="qualys_fields">
<parent>qualysguard</parent>
<regex offset="after_regex">^""(\w*)"",|(\s*),</regex>
<order>qualysguard.instance</order>
</decoder>
This decoder would extract fields into the alert’s data object like:
{
"data": {
"qualysguard.instance": "value"
}
}
Dynamic Field Types
Dynamic decoders can extract various types of fields:
- Standard fields (predefined in OSSEC):
- srcip, dstip: IP addresses
- srcport, dstport: Port numbers
- protocol: Network protocol
- action: Action type
- id: Identifier
- url: URL
- data: Additional data
- extra_data: Extra information
- status: Status code
- system_name: System name
- Custom fields:
- Any field name can be used in the order tag
- Fields are stored as key-value pairs in the data object
- Values can be strings, numbers, or arrays
Field Extraction Process
- The decoder matches the log message against the regular expression
- Captured groups from the regex are assigned to fields in the order specified
- Fields are stored in the alert’s data object
- If a field is not captured, it will be set to null or an empty string
Example Alert
{
"version": "1.0",
"timestamp": "2024-03-21T10:15:30.123+0000",
"id": "1234567890.12345",
"rule": {
"id": "1002",
"level": 7,
"description": "SSH authentication failed",
"groups": ["authentication_failed", "sshd"],
"mail": true
},
"agent": {
"id": "001",
"name": "agent1",
"ip": "192.168.1.100"
},
"manager": {
"name": "ossec-manager"
},
"data": {
"srcip": "10.0.0.1",
"srcuser": "root",
"action": "failed"
},
"location": "/var/log/auth.log",
"full_log": "Mar 21 10:15:30 agent1 sshd[1234]: Failed password for root from 10.0.0.1 port 12345 ssh2"
}