Page tree
Skip to end of metadata
Go to start of metadata

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.

On this page:

SIEM Mappings - general rules

Create and access SIEM mappings files

Access WWWROOT. It is typically located at: 

Windows

Linux

(later than Ubuntu 14.04)

Linux

(earlier than Ubuntu 14.04)

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

Navigate to the following directory:

WWWROOT/app/siem/maps

It contains the following files:

auditmap.php
auditmap-sample.php
systemalertsmap.php
systemalertsmap-sample.php

These files store mappings and mapping samples for audit and system alert.

  • To enable FileCloud to convert audit entries to valid SIEM messages edit auditmap.php.
  • To enable FileCloud to convert FileCloud's System Alerts to valid SIEM messages edit systemalertsmap.php.
  • Samples are provided in auditmap-sample.php and systemalertsmap-sample.php.

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.

PropertyDescriptionValues
whoAuthor of the operationName of the user or process that has triggered the operation

ip

IP AddressA regular IPv4 address
tsOperation timestampTimestamp

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

PropertyDescriptionValues
requestRequest 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.

notesContext of the operationThis field provides the most important information about each operation. The content is unique for each operation.
userAgentThe User-Agent that triggered the operationNOTE: Web browser is used as a generic user-agent for all web browsers.
userNameName of the user that triggered the operation
operationName of the operation that was triggered
resultCodeResult 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)

recordIdA MongoDB id of the audit entryThis is a MongoDB ObjectId
hostnameA name of the hostThe name of the current host. This allows SIEM to differentiate tenants.

Operation-specific Audit Properties

PropertyDescriptionValuesSupported operations
auditAreaProvides information about the system area of the operationName of the system area

Currently only supported for operations from the following groups:

  • workflows
  • retention

serviceId

Additional information about the operation targetCarries additional information about the operations such as the name of the workflow or the id of the retention policy that was updatedAvailable only when the auditArea field is present
bandwidthInformation about the size of the fileFile size in bytes

Available for the following operations:

  • upload (file upload operation)
  • downloadfile
realpathFile or folder realpathFileCloud's original location of the file/folder, for example. /johndoe/document/internal/doc.txt

Available only for retention-related and dlp operations

metadataA list of non-empty, custom attributes assigned to the file or folderAny 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)
deviceInfoName of the client applicationName 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
        ]
    ]
];

/************************************* 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'
        ]
    ]
];

/****************************************** 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

PropertyDescriptionValues
siemAreaSystem area where the alert was raisedOne 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
levelSystem alert critical level

One of the following values:

SysAlert::SYSALERT_LEVEL_MELTDOWN
SysAlert::SYSALERT_LEVEL_CRITICAL
SysAlert::SYSALERT_LEVEL_WARNING
SysAlert::SYSALERT_LEVEL_INFORMATION
typeType 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
notesAlert notes
usernameThe user whose actions raised the alert
alertContextAdditional 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'
        ]
    ]
];
  • No labels