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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"name": "string"
}
```
- `name`: Manager hostname
### Data Object
The `data` object contains additional alert-specific information:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```xml
<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:
```xml
<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:
```json
{
"data": {
"qualysguard.instance": "value"
}
}
```
### Dynamic Field Types
Dynamic decoders can extract various types of fields:
1. 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
2. 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
1. The decoder matches the log message against the regular expression
2. Captured groups from the regex are assigned to fields in the order specified
3. Fields are stored in the alert's `data` object
4. If a field is not captured, it will be set to null or an empty string
## Example Alert
```json
{
"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"
}
```