files‑api Audit

Collects a list of the files on host endpoints using system calls.

This audit may return more information than expected if the Get Resources parameter is requested for the audit. FireEye strongly recommends using the Get Resources parameter only when targeting a single file.

This audit was formerly known as the w32apifiles audit.

The Preserve Times parameter of this audit does not work in macOS environments. (ENDPT-515)

Supported Platforms

Windows, macOS, and Linux

Input Parameters

The following input parameters are available for this audit. Some parameters are supported only in specific environments.

Path

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	FilePath	Valid values are a full file path and file name.
Required?	yes	This parameter is required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify the absolute path of the directory containing the files to acquire. The trailing back-slash is optional. For example: `C:\\WINDOWS\\`

Regex

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	String	Valid values are a string of text.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify the Perl-compatible regular expression a file must match to be collected. You must use standard regex expressions, including regex escaping techniques. (Specifying `'\\\\'` matches a single `'\\'` and specifying `'\\'` matches `'\'`.) The following example matches all files in any subdirectory: `.` The following example matches all the `.xls` files in any subdirectory: `.*\.xls` The files in a subdirectory named `Temp`, such as `C:\Windows\Temp\<filename>.xls` (note that backslashes must be escaped: `.\\Temp\\.\.xls`)

Important

When adding a backslash to regex in Web UI data acquisition scripts, only a single backslash needs to be specified. When the Endpoint Security (HX) server converts the regex to JSON, these single backslashes are converted to double-backslashes. Thus, the regex in the exported script will not match the version you see in the Web UI.

Path Regex

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	String	Valid values are a string of text.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify an alias for the `Regex` parameter.

Depth

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	Numeric	Valid values are numeric.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify the number of directory levels to include in the audit. Specifying `-1` represents full depth.

MD5

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether an MD5 hash should be computed for each returned file.

SHA1

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether an SHA1 hash should be computed for each returned file.

SHA256

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether an SHA256 hash should be computed for each returned file.

Preserve Times

Details	Values	Description
Platform	Windows and Linux	Windows and Linux environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the last access times for audited files should be manually reset.

Minimum Sizes

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	ArrayOfString	Valid values are specified in an array of string values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify the minimum file size, in bytes, of a file collected for this audit.

Maximum Sizes

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	ArrayOfString	Valid values are specified in an array of string values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify the maximum file size, in bytes, of a file collected for this audit.

Filter MD5

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	ArrayOfString	Valid values are specified in an array of string values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Filter the results based on a specific MD5 hash.

Filter SHA1

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	ArrayOfString	Valid values are specified in an array of string values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Filter the results based on a specific SHA1 hash.

Filter SHA256

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	ArrayOfString	Valid values are specified in an array of string values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Filter the results based on a specific SHA256 hash.

Verify Digital Signatures

Details	Values	Description
Platform	Windows and macOS	Windows and macOS environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should verify that the executable files are digitally signed. This operation cannot be performed on a memory image.

Content Regex

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	ArrayOfString	Valid values are specified in an array of string values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify a valid regex string for which to search.

AND Operator

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should collect a file only if its content matches all regex parameters.

Include Files

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should return file item types.

Include Directories

Details	Values	Description
Platform	Windows, macOS, and Linux	Windows, macOS, and Linux environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should return directory item types.

Include Remote Locations

Details	Values	Description
Platform	macOS and Linux	macOS and Linux environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should return remote locations, such as mounted NFS directories.

Analyze Entropy

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the entropy for executable files should be calculated for the audit. High entropy may indicate a packed executable.

Enumerate Imports

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether modules and functions imported by executable files should be identified in the audit.

Enumerate Exports

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether modules and functions exported by executable files should be identified in the audit.

Analyze File Anomalies

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should detect higher-order anomalies that might indicate malicious files.

Scan Entry Point Distance

Details	Values	Description
Platform	Windows	Windows environments
Format	Numeric	Valid values are numeric.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify the number of bytes from the entry point to scan for jumps.

Strings

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether to parse specified files for strings. If this parameter is enabled, the default string length is 4 bytes (see the `shortest matched string` parameter).

shortest matched string

Details	Values	Description
Platform	Windows	Windows environments
Format	Numeric	Valid values are numeric.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify the minimum recognized string length.

Get Resources

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should return resources stored in a PE file. This audit may return more information than expected if the Get Resources parameter is requested for the audit. FireEye strongly recommends using the Get Resources parameter only when targeting a single file.

Get Resource Data

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should return all data associated with all resources in a PE file. Caution This option can return very large amounts of data even with narrowly scoped audits. Consider using `Exclude Resource Types` parameter and verifying the size of the results from a single host before running on multiple hosts.

Get Version Info

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether the audit should return version information stored in a PE file.

Exclude Resource Types

Details	Values	Description
Platform	Windows	Windows environments
Format	ArrayOfString	Valid values are specified in an array of string values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Specify a list of resource types to exclude when extracting PE resources.

Prevent Hibernation

Details	Values	Description
Platform	Windows	Windows environments
Format	Bool	Valid values are Boolean values.
Required?	no	This parameter is not required.
Repeatable?	no	This parameter can be specified only once per audit request. It cannot be repeated.
Valid Values		Use Boolean values to indicate whether to prevent the host endpoint from entering hibernation while this audit is executed.