Monitor changes to your filesystem

Monitor changes to your filesystem

Splunk's file system change monitor is useful for tracking changes in your file system. The file system change monitor watches any directory you specify and generates an event in Splunk when that directory undergoes any change. It is completely configurable and can detect when any file on the system is edited, deleted, or added (not just Splunk-specific files). For example, you can tell the file system change monitor to watch /etc/sysconfig/ and alert you any time the system's configurations are changed.

Configure the file system change monitor in inputs.conf.

Important: If you want to use this feature with forwarding, to send the events to a remote indexer, you must either use a heavy forwarder or follow the configuration instructions provided below in "Use with a universal forwarder".

Note: If you're interested in auditing file reads on Windows, check out this topic on the Splunk Community best practices Wiki. Some users might find it more straightforward to use Windows native auditing tools.

How the file system change monitor works

The file system change monitor detects changes using:

• modification date/time
• group ID
• user ID
• file mode (read/write attributes, etc.)
• optional SHA256 hash of file contents

You can configure the following features of the file system change monitor:

• whitelist using regular expressions
  • specify files that will be checked, no matter what
• blacklist using regular expressions
  • specify files to skip
• directory recursion
  • including symbolic link traversal
  • scanning multiple directories, each with their own polling frequency
• cryptographic signing
  • creates a distributed audit trail of file system changes
• indexing entire file as an event on add/change
  • size cutoffs for sending entire file and/or hashing
• all change events indexed by, and searchable through, Splunk

Caution: Do not configure the file system change monitor to monitor your root filesystem. This can be dangerous and time-consuming if directory recursion is enabled.

Configure the file system change monitor

By default, the file system change monitor will generate audit events whenever the contents of $SPLUNK_HOME/etc/ are changed, deleted, or added to. When you start Splunk for the first time, an audit event will be generated for each file in the $SPLUNK_HOME/etc/ directory and all subdirectories. Any time after that, any change in configuration (regardless of origin) will generate an audit event for the affected file(s). If you have signedaudit=true , the file system change audit event will be indexed into the audit index (index=_audit). If signedaudit is not turned on, by default, the events are written to the main index unless you specify another index.

Note: The file system change monitor does not track the user name of the account executing the change, only that a change has occurred. For user-level monitoring, consider using native operating system audit tools, which have access to this information.

To use the file system change monitor to watch any directory, add or edit an [fschange] stanza to inputs.conf in $SPLUNK_HOME/etc/system/local/ or your own custom application directory in $SPLUNK_HOME/etc/apps/. For information on configuration files in general, see "About configuration files".

Note: You must restart Splunk any time you make changes to the [fschange] stanza.

Syntax

Here is the syntax for the [fschange] stanza:

[fschange:<directory or file to monitor>]
<attribute1> = <val1>
<attribute2> = <val2>
...

Note the following:

• The system will monitor all adds/updates/deletes to the directory and its subdirectories.
• Any change will generate an event that is indexed by Splunk.
• <directory or file to monitor> defaults to $SPLUNK_HOME/etc/.

Attributes

All attributes are optional. Here is the list of available attributes:

index=<indexname>

• The index to store all events generated.
• Defaults to main (unless you have turned on audit event signing).

recurse=<true | false>

• If true, recurse all directories within the directory specified in <code[fschange]</code>.
• Defaults to true.

followLinks=<true | false>

• If true, the file system change monitor will follow symbolic links.
• Defaults to false.

Caution: If you are not careful when setting followLinks, file system loops may occur.

pollPeriod=N

• Check this directory for changes every N seconds.
• Defaults to 3600.
  • If you make a change, the file system audit events could take anywhere between 1 and 3600 seconds to be generated and become available in audit search.

hashMaxSize=N

• Calculate a SHA1 hash for every file that is less than or equal to N size in bytes.
• This hash can be used as an additional method for detecting change in the file/directory.
• Defaults to -1 (no hashing used for change detection).

signedaudit=<true | false>

• Send cryptographically signed add/update/delete events.
• Defaults to false.
• Setting to true will generate events in the _audit index.
• This should be set to false if you're setting the index attribute.

Note: When setting signedaudit to true, make sure auditing is enabled in audit.conf.

fullEvent=<true | false>

• Send the full event if an add or update change is detected.
• Further qualified by the sendEventMaxSize attribute.
• Defaults to false.

sendEventMaxSize=N

• Only send the full event if the size of the event is less than or equal to N bytes.
• This limits the size of indexed file data.
• Defaults to -1, which is unlimited.

sourcetype = <string>

• Set the source type for events from this input.
• "sourcetype::" is automatically prepended to <string>.
• Defaults to audittrail (if signedaudit=true) or fs_notification (if signedaudit=false).

filesPerDelay = <integer>

• Injects a delay specified by delayInMills after processing <integer> files.
• This is used to throttle file system monitoring so it doesn't consume as much CPU.

delayInMills = <integer>

• The delay in milliseconds to use after processing every <integer> files as specified in filesPerDelay.
• This is used to throttle file system monitoring so it doesn't consume as much CPU.

filters=<filter1>,<filter2>,...<filterN>

Each of these filters will apply from left to right for each file or directory that is found during the monitors poll cycle. See the next section for information on defining filters.

Define a filter

To define a filter to use with the filters attribute, add a [filter...] stanza as follows:

[filter:blacklist:backups] 
regex1 = .*bak
regex2 = .*bk
[filter:whitelist:code] 
regex1 = .*\.c 
regex2 = .*\.h 
 
[fschange:/etc] 
filters = backups,code 

Fschange white/blacklist logic is handed similarly to typical firewalls. The events run down through the list of filters until they reach their first match. If the first filter to match an event is a whitelist, the event will be indexed. If the first filter to match an event is a blacklist, the event will not be indexed. If an event reaches the end of the chain with no matches, it will be indexed. This means that there is an implicit "all pass" built in. To default to a situation where events are not indexed if they don't match a whitelist explicitly, end the chain with a blacklist that will match all remaining events.

For example:

...
filters = <filter1>, <filter2>, ... terminal-blacklist

[filter:blacklist:terminal-blacklist] 
regex1 = .?

Important: If a directory is ever blacklisted including via a terminal blacklist at the end of a series of whitelists, then all its subfolders and files are automatically blacklisted and will not pass any whitelist. To accommodate this, whitelist all desired folders and subfolders explicitly ahead of the blacklist items in your filters.

Example

This configuration monitors files in the specified directory with the extensions .config, .xml, .properties, and .log and ignores all others.

Note: In this example, a directory could be blacklisted. If this is the case, all its subfolders and files would automatically blacklisted as well -- only files in the specified directory would be monitored.

[filter:whitelist:configs]
regex1 = .*\.config 
regex2 = .*\.xml 
regex3 = .*\.properties 
regex4 = .*\.log
 
[filter:blacklist:terminal-blacklist]
regex1 = .?
 
[fschange:/var/apache] 
index = sample 
recurse = true 
followLinks = false 
signedaudit = false 
fullEvent = true 
sendEventMaxSize = 1048576 
delayInMills = 1000 
filters = configs,terminal-blacklist 

Use with a universal forwarder

To forward file system change monitor events from a universal forwarder, you must set signedaudit = false and index=_audit:

[fschange:<directory or file to monitor>]
signedaudit = false
index=_audit

With this workaround, file system change monitor events are indexed in the _audit index with sourcetype set to fs_notification and source set to fschangemonitor, instead of the default value of audittrail for both sourcetype and source .

• Was this topic useful?
• Post a comment