Managing SIEM Mappings

The biggest challenge when working with the external SIEM servers is to map messages existing in the system in the correct CEF/LEEF format. In order to allow administrators to have full control over how to represent FileCloud's System Alerts and Audit records in the external SIEM system a flexible mapping syntax is supported.

SIEM Mappings - general rules

Create and access SIEM mappings files

Access WWWROOT. It is typically located at:

Windows	Linux
c:\xampp\htdocs	/var/www/html

Navigate to the following directory:

WWWROOT/app/siem/maps

It contains the following files:

auditmap-sample.php
systemalertsmap-sample.php

These files store mappings for audit and system alerts.

Modify the mappings to correspond to your system, and save them as
auditmap.php and systemalertsmap.php.

auditmap.php enables FileCloud to convert audit entries to valid SIEM messages.
systemalertsmap.php enables FileCloud to convert FileCloud's system alerts to valid SIEM messages.

Mappings are stored in the .php file, so they have to follow all PHP syntax rules as well as internal mappings rules and syntax. To validate all mappings, navigate to Settings > Third Party Integrations > SIEM and click on Validate mappings.

SIEM mapping format

A sample SIEM mapping is a PHP array entry, which itself is an array. It contains the following fields:

id (required) - identifies the SystemAlert / Audit entry this map refers to.
Note that it can be a string literal that matches the audit operation name or one of the SiemArea values available in FileCloud, an array of values, or a wildcard '*' that specifies that the mapping is applied to all audit entries/system alerts.

prefilter (optional) - A collection of preconditions that an event has to meet in order to be processed and sent to the SIEM system. It is an array of filters, where each filter has the following format: property => value

where:

property is a valid property available for the Audit/System Alert record

value is a value that has to be matched in order to process the Audit / System Alert record, i.e.

Sample System Alert Mappings

    'prefilter' => [
        'level' => SysAlert::SYSALERT_LEVEL_MELTDOWN
    ],

specifies that only System Alerts with the Meltdown criticality level would be sent to the SIEM server.

map (Required) - specifies the actual mapping between the FileCloud object being processed and the SIEM-formatted message that will be sent to the SIEM server. SIEM object to contain the following four fields:

eventClass - class of the event in the SIEM system.
eventName - The name of the event.
severity - this is a SIEM side severity, which is a number from the 1-10 range.
extension - a collection (array) of additional key-value pairs that will be stored in the SIEM system (i.e. the user that performed the action, IP address of the request, etc.). The key can be any arbitrary string.

To resolve mappings, provide values in any of the following ways:

As a literal value (string or number)

Sample System Alert Mappings

'eventClass' => 'authentication',
'eventName' => 'invalid login',
'severity' => 3

As a property binding that resolves the value with the actual value provided by the FileCloud audit system alert being processed:
Sample System Alert Mappings
```
'eventClass' => '$siemArea',
'eventName' => '$description',
'user' => '$username',
'filename' => '$request.filename', //Access a field in the request object/array
'filePath' => '$realpath > $request.path > $notes' //The filePath will be resolved to the first non-empty value
'ip' => '$ip'
```
Properties should appear on the right-hand side of the arrow operator (=>). The property name must be prefixed with a dollar sign ($). Properties can take one of the following values:
- A standalone value - '$property'
- An array of values of an object with properties. The following syntax can be used to access any of the values: '$array.field' or '$object.field', for example, '$request.filename'. This can be applied recursively if the internal field is also an array or object, for example, '$response.meta.type'.
- As a chain of fallback properties ('$property1 > $property2.field > $property3') - the value is resolved to the first non-empty property value. For example, the following syntax is resolved to filename if present or to the $request.fname otherwise: 'fname' => '$filename > $request.fname'. This allows the admin to provide more generic rules.
As a method call:
Sample System Alert Mappings
```
'severity' => [[SiemConversionHelper::class, 'getSysAlertSeverity'], ['$level']],
```
NOTE: Users can create and use their own methods here. The first parameter is the PHP callback (class, method name) and the second parameter is the array of values (optional) that is processed by that callback. Parameters can be set to literal values or runtime-resolvable properties as described earlier. In FileCloud 19.2 getSysAlertSeverity is the only method available out of the box. It assigns internal System Alerts a severity of 1-10 as required by SIEM integration in the following way:
- Meltdown: 10
- Critical: 7
- Warning: 4
- Information: 1

Shared properties

Properties listed below can be used in both System Alerts and Audit mappings.

Property	Description	Values
who	Author of the operation	Name of the user or process that has triggered the operation
ip	IP Address	A regular IPv4 address
ts	Operation timestamp	Timestamp

Audit mappings

Audit stores information about actions being performed within the system. Currently, audit stores information about 200+ unique operations being performed within FileCloud. Each Audit record contains some generic information, shared with the System Alerts properties (see Shared Properties, above), common for each audit entry, and some unique properties, stored only for a group of actions.

Shared Audit Properties

Property	Description	Values
request	Request payload	The full request payload provided as a collection of key-value pairs that can be extracted in the mapping. Each operation carries a unique request. The request can be mapped as a full object, and its info will be sent to the SIEM server as a string. For example: `'request' => '$request'`, will be sent as `{"op":"loginguest","userid":"john.doe","password":"xxx"}` Each field can also be sent individually if provided in the mapping: `'loggedUser' => '$request.userid'`, where `userid` is one of the parameters of the request.
response	Response payload	Similar to the request, the response provides a collection of key-value pairs that can be extracted in the mapping or sent as a string. Each operation has a different response, so it is better to use this for dedicated rules. NOTE: Responses are not stored in audit by default, and they have to be enabled in Admin > Settings > Admin (Audit Settings section) > Audit Logging Level (FULL), This is not recommended for production as it may affect performance and usually is not needed for auditing.
notes	Context of the operation	This field provides the most important information about each operation. The content is unique for each operation.
userAgent	The User-Agent that triggered the operation	NOTE: Web browser is used as a generic user-agent for all web browsers.
userName	Name of the user that triggered the operation
operation	Name of the operation that was triggered
resultCode	Result of the operation	1 - the operation was performed successfully (for example, login attempt was successful, a file was deleted) 0 - operation failed (for example, login was not possible, a file was not deleted due to invalid permissions)
recordId	A MongoDB id of the audit entry	This is a MongoDB ObjectId
hostname	A name of the host	The name of the current host. This allows SIEM to differentiate tenants.

Operation-specific Audit Properties

Property	Description	Values	Supported operations
auditArea	Provides information about the system area of the operation	Name of the system area	Currently only supported for operations from the following groups: workflows retention
serviceId	Additional information about the operation target	Carries additional information about the operations such as the name of the workflow or the id of the retention policy that was updated	Available only when the auditArea field is present
bandwidth	Information about the size of the file	File size in bytes	Available for the following operations: upload (file upload operation) downloadfile
realpath	File or folder realpath	FileCloud's original location of the file/folder, for example. /johndoe/document/internal/doc.txt	Available only for retention-related and dlp operations
metadata	A list of non-empty, custom attributes assigned to the file or folder	Any non-empty attributes assigned by the Custom metadata sets as a result of the Smart Classification rule	The following operations are supported: downloadfilemulti - Download multiple files downloadfile - Download single file getaudio - Play audio file getvideo - Play video file getfsslideimage - View image file docconvert - Open/view file quickshare - Quick share addusertoshare - Add specific users to share addgrouptoshare - Add specific groups to share setallowpublicaccess - Make share public (after sharing only with certain users/groups)
deviceInfo	Name of the client application	Name of the application, i.e. FileCloud Drive	Any operation that is performed by one of the client apps: Drive or Sync

Sample mappings

The following shows sample mappings for the most common operations:

/**************************************** Downloads ****************************************/
// Download file
$mappings[] = [
    'id' => 'downloadfile',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'FileOperations',
        'eventName' => '$operation',
        'severity' => 2,
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'fname' => '$request.filename > $notes', // $notes is a fallback for downloadfilemulti operation
            'filePath' => '$realpath > $request.filePath', // realpath is used for downloadfilemulti
            'fsize' => '$bandwidth',
            'cs1' => '$metadata',
            'cs1Label' => 'Metadata assigned to the file'
        ]
    ]
];

/***************************************** Uploads *****************************************/
// Upload
$mappings[] = [
    'id' => 'upload',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'FileOperations',
        'eventName' => '$operation',
        'severity' => 2,
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'fname' => '$request.filename', // $notes can be used as well
            'filePath' => '$request.path',
            'fsize' => '$bandwidth'
        ]
    ]
];

/****************************************** Shares *****************************************/
// addusertoshare - Adding user to the existing share
$mappings[] = [
    'id' => 'addusertoshare',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Shares',
        'eventName' => '$operation',
        'severity' => 2,
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'filePath' => '$notes',
            'duser' => '$request.userid',
            'cs1' => '$metadata',
            'cs1Label' => 'Metadata assigned to the file'
        ]
    ]
];

// updateshare - updating existing share
$mappings[] = [
    'id' => 'updateshare',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Shares',
        'eventName' => '$operation',
        'severity' => 2,
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'filePath' => '$request.sharelocation',
            'cs1' => '$metadata',
            'cs1Label' => 'Metadata assigned to the file'
        ]
    ]
];

// setuseraccessforshare - sets user permissions for share
$mappings[] = [
    'id' => 'setuseraccessforshare',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Shares',
        'eventName' => '$operation',
        'severity' => 6, // this can be a potentially risky operation since data exposure and leakage might happen
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'filePath' => '$notes',
            'duser' => '$request.userid',
            'cs1' => '$metadata',
            'cs1Label' => 'Metadata assigned to the file',
            'cs2' => '$request.shareid',
            'cs2Label' => 'Share Identifier'
        ]
    ]
];

// setallowpublicaccess - happens when a share is mad public
$mappings[] = [
    'id' => 'setallowpublicaccess',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Shares',
        'eventName' => '$operation',
        'severity' => 6, // this can be a potentially risky operation since data exposure and leakage might happen
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'filePath' => '$notes',
            'ispublic' => '$request.allowpublicaccess', // 1 - public share, 0 - private share
            'cs1' => '$metadata',
            'cs1Label' => 'Metadata assigned to the file',
			'cs2' => '$request.shareid',
            'cs2Label' => 'Share Identifier'
        ]
    ]
];

/**************************************** Smart DLP ****************************************/
// DLP Violation
$mappings[] = [
    'id' => 'dlp',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'DLP Violation',
        'eventName' => '$operation',
        'severity' => 6,
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'filePath' => '$realpath',
            'msg' => '$notes.message',
            'shareTargetEmail' => '$notes.shareTargetEmail',
            'cs1' => '$metadata',
            'cs1Label' => 'Metadata assigned to the file',
            'cs3' => '$request.op', // operation that triggered the violation / $notes.action can be uses as well for a less granular info: DOWNLOAD / SHARE / LOGIN
            'cs3Label' => 'DLP Violation trigger',
            // Additional information can be grabbed from the request object
            'cs4' => '$notes.violatedRule', // DLP rule that was violated
            'cs4Label' => 'DLP Violation rule'
        ]
    ]
];

/*********************************** Smart Classification **********************************/
// Smart Classification - apply match action
$mappings[] = [
    'id' => 'ccsapplymatchaction',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'CCE match',
        'eventName' => '$operation',
        'severity' => 2,
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'msg' => '$notes',
    		'filePath' => '$realpath',
			'cs5' => '$svcid',
			'cs5Label' => 'Content classification rule name'
        ]
    ]
];

/******************************************** Login ******************************************/
//Failed login attempt
$mappings[] = [
    'id' => 'loginguest',
    'prefilter' => [
        //List of conditions that audit entry has to met in order to be processed (or filtered out if excluded option is there)
        'resultCode' => '0', //incidents only
        'exclude' => false // optional 'include' is used by default
    ],
    'map' => [
        'eventClass' => 'login',
        'eventName' => 'Invalid login attempt',
        'severity' => 2,
        'extension' => [
            'user' => '$userName',
            'ip' => '$ip',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
        ]
    ]
]; 


//Failed SSO login attempt
$mappings[] = [
    'id' => 'samlsso',
    'prefilter' => [
        //List of conditions that audit entry has to met in order to be processed (or filtered out if excluded option is there)
        'resultCode' => '0', //incidents only
        'exclude' => false // optional 'include' is used by default
    ],
    'map' => [
        'eventClass' => 'login',
        'eventName' => 'Invalid SSO login attempt',
        'severity' => 2,
        'extension' => [
            'user' => '$userName',
            'ip' => '$ip',
            'shost' => '$hostname', // name of the host
            'recordId' => '$recordId', // Audit record id
        ]
    ]
];

//Successful SSO login attempt
$mappings[] = [
    'id' => 'samlsso',
    'prefilter' => [
        //List of conditions that audit entry has to met in order to be processed (or filtered out if excluded option is there)
        'resultCode' => '1',
        'exclude' => false // optional 'include' is used by default
    ],
    'map' => [
        'eventClass' => 'login',
        'eventName' => 'Successfull SSO login attempt',
        'severity' => 2,
        'extension' => [
            'user' => '$userName',
            'ip' => '$ip',
            'shost' => '$hostname', // name of the host
            'recordId' => '$recordId', // Audit record id
        ]
    ]
];

 /************************************* AV - Virus removed ***********************************/
// When AV finds and removes the file containing a Virus (i.e. ICAP AV)
$mappings[] = [
    'id' => 'virusremoved',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'virusremoved',
        'eventName' => 'Virus Removed',
        'severity' => 8,
        'extension' => [
            'user' => '$userName',
            'userAgent' => '$userAgent',
            'ip' => '$ip',
            'fname' => '$request.filename',
            'filePath' => '$request.path',
            'notes' => '$notes'
        ]
    ]
];

/******************************* Group management *****************************************/

// Group rename
$mappings[] = [
    'id' => 'updategroup',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Groups',
        'eventName' => '$operation',
        'severity' => 6,
        'extension' => [
            'suser' => '$userName',
            'shost' => '$hostname', // name of the host
            'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'msg' => '$notes'
        ]
    ]
];

$mappings[] = [
    'id' => 'addmembertogroup',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Groups',
        'eventName' => '$operation',
        'severity' => 5,
        'extension' => [
            'suser' => '$userName',
            'shost' => '$hostname', // name of the host
            'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'duser' => '$request.userid',
            'msg' => '$notes'
        ]
    ]
];

$mappings[] = [
    'id' => 'deletememberfromgroup',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Groups',
        'eventName' => '$operation',
        'severity' => 5,
        'extension' => [
            'suser' => '$userName',
            'shost' => '$hostname', // name of the host
            'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'duser' => '$request.userid',
            'msg' => '$notes'
        ]
    ]
];

/******************************* User management *****************************************/

$mappings[] = [
    'id' => 'adduser',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Users',
        'eventName' => '$operation',
        'severity' => 5,
        'extension' => [
            'suser' => '$userName',
            'shost' => '$hostname', // name of the host
            'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'duser' => '$request.username', // name of the user that has been added
            'msg' => '$notes' // More info about the user
        ]
    ]
];

// Admin status change
$mappings[] = [
    'id' => 'setadminstatus',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Users',
        'eventName' => '$operation',
        'severity' => 2,
        'extension' => [
            'suser' => '$userName',
            'shost' => '$hostname', // name of the host
            'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'duser' => '$request.profile',
            'msg' => '$request.adminstatus'
        ]
    ]
];

// User password changed by admin
$mappings[] = [
    'id' => 'setuserpassword',
    'prefilter' => [],
    'map' => [
        'eventClass' => 'Users',
        'eventName' => '$operation',
        'severity' => 2,
        'extension' => [
            'suser' => '$userName', // Admin who performed the operation
            'shost' => '$hostname', // name of the host
            'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'duser' => '$request.profile' // User whose password has been changed
        ]
    ]
];  



/****************************************** Generic ****************************************/
// A generic map for all events

$mappings[] = [
    'id' => '*',
    'prefilter' => [],
    'map' => [
        'eventClass' => '$operation',
        'eventName' => '$operation',
        'severity' => 2,
        'extension' => [
            'suser' => '$userName',
			'shost' => '$hostname', // name of the host
			'recordId' => '$recordId', // Audit record id
            'requestClientApplication' => '$userAgent',
            'src' => '$ip',
            'msg' => '$notes',
			'fname' => '$request.filename',
			'filePath' => '$realpath > $request.path > $request.filepath',
			'duser' => '$request.userid'
        ]
    ]
];

System Alert mappings

FileCloud allows admins to create mappings for System Alerts generated by the system due to unexpected or unwanted behaviors. System Alert mappings contain properties that can be sent to the SIEM server or logged in the syslog for further processing.

Supported properties

Property	Description	Values
siemArea	System area where the alert was raised	One of the following values: SiemArea::INFECTED_FILE SiemArea::INVALID_FILE_TYPE SiemArea::AV_CHECK_FAILED SiemArea::UNHANDLED_EXCEPTION SiemArea::SYSTEM_ERROR SiemArea::DISK_SPACE_EXCEEDED SiemArea::INDEX_DB_FAILURE SiemArea::RMC_INVALID_POLICY SiemArea::SEND_EMAIL_FAILED SiemArea::BACKGROUNDING_FAILED SiemArea::METADATA_HEALTH_CHECK SiemArea::WORKFLOW SiemArea::ZIP_BACKUP_FAILURE SiemArea::SIEM_SERVER_CONNECTION SiemArea::DLP_SHARE_KILL
level	System alert critical level	One of the following values: SysAlert::SYSALERT_LEVEL_MELTDOWN SysAlert::SYSALERT_LEVEL_CRITICAL SysAlert::SYSALERT_LEVEL_WARNING SysAlert::SYSALERT_LEVEL_INFORMATION
type	Type of system alert	One of the following values: SysAlert::SYSALERT_TYPE_DLP_SHARE_KILL_FAILED SysAlert::SYSALERT_TYPE_DLP_SHARE_KILLED SysAlert::SYSALERT_TYPE_CODE_CONFIGURATION_ERRROR SysAlert::SYSALERT_TYPE_CODE_AV_FAILURE SysAlert::SYSALERT_TYPE_CODE_SIGNATURE_FAILURE SysAlert::SYSALERT_TYPE_CODE_EXCEPTION SysAlert::SYSALERT_TYPE_CODE_ERROR SysAlert::SYSALERT_TYPE_QUOTA_EXCEEDED
description	Alert description
notes	Alert notes
username	The user whose actions raised the alert
alertContext	Additional information, related to the alert	Various contexts, depending on the Alert. For example: file - filename for the File version deletion operation filePath - file location for the Infected file fileName - file name for the Infected file

Sample mappings

Sample System Alert Mappings

//Report all meltdowns
$mappings[] = [
    'id' => '*', //Wildcard denotes all Alerts
    'prefilter' => [
        'level' => SysAlert::SYSALERT_LEVEL_MELTDOWN
    ],
    'map' => [
        'eventClass' => '$siemArea',
        'eventName' => '$description',
        'severity' => 10,
        'extension' => [
            'user' => '$username',
            'ip' => '$ip'
        ]
    ]
];

//AV system alert - infected file found
$mappings[] = [
    'id' => SiemArea::INFECTED_FILE,
    'map' => [
        'eventClass' => 'System Error',
        'eventName' => '$description',
        'severity' => [[SiemConversionHelper::class, 'getSysAlertSeverity'], ['$level']],
        'extension' => [
            'user' => '$username',
            'ip' => '$ip',
            'path' => '$alertContext.filePath',
            'file' => '$alertContext.fileName'
        ]
    ]
];

//Type mismatch report
$mappings[] = [
    'id' => SiemArea::INVALID_FILE_TYPE,
    'map' => [
        'eventClass' => 'System Error',
        'eventName' => '$description',
        'severity' => [[SiemConversionHelper::class, 'getSysAlertSeverity'], ['$level']],
        'extension' => [
            'user' => '$username',
            'ip' => '$ip',
            'path' => '$alertContext.file'
        ]
    ]
];