Note. GuardMode uses YARA-X, which is a re-implementation of YARA. While YARA-X aims to be compatible with YARA rules, there are some differences between the two. For example, YARA-X requires the { character to be escaped in regular expressions, whereas YARA does not. For a comprehensive list of differences, please refer to the YARA-X documentation. Keep these differences in mind when writing or adapting YARA rules for use with GuardMode.
YARA-X is a powerful pattern-matching tool used for malware classification and detection. In GuardMode, YARA-X analysis enhances file analysis capabilities alongside entropy and magic number checks.
Understanding YARA-X in GuardMode
YARA-X analysis is integrated into GuardMode’s file analysis process. For scans, file integrity checks, and threshold analysis, GuardMode considers a file suspicious when:
It has high entropy combined with no identifiable magic numbers, or
It matches any YARA-X rule
Note. GuardMode 2024.3 comes with a default YARA-X ruleset. You can still add your custom rulesets for YARA-X analysis.
In incident detection, files matching YARA-X rules are treated separately as potentially malicious.
Enabling and Configuring YARA-X Analysis
By default, YARA-X analysis is disabled. To enable and configure it:
(Optional) Add your YARA-X rule files to the YaraRules folder in the agent’s installation directory.
Tip. Use only .yar or .yara file extensions for your YARA-X rule files. GuardMode will only load rules from files with these extensions. Also, periodically review and update your YARA-X rules to maintain effective threat detection.
Use the REST API to enable YARA-X analysis and configure rule paths.
Configuring YARA-X via REST API
To configure YARA-X analysis, use the following REST API endpoints:
Get current YARA analysis configuration
get
Authorizations
AuthorizationstringRequired
Basic Authorization header
Header parameters
api-versionstringRequired
Responses
200
Current configuration
get
/settings/yara
200
Current configuration
Update YARA analysis configuration
put
Authorizations
AuthorizationstringRequired
Basic Authorization header
Header parameters
api-versionstringRequired
Body
Responses
200
Updated configuration
400
Bad request was sent
put
/settings/yara
Replace the path/to/... values with the actual paths to your YARA-X rule files for each analysis type.
Tip. Set an appropriate maxFileSizeInBytes value to limit YARA analysis on very large files. This helps maintain system performance while still providing effective threat detection. Consider that YARA loads the entire file into RAM for analysis, so a large file size limit could significantly impact memory usage.
Enabling YARA-X in Threshold Analysis
To enable YARA-X for threshold analysis, use the /settings/threshold endpoint:
For file integrity checks, YARA-X analysis is controlled by the checkFileContents setting per path. Use the /settings/file-integrity endpoint:
Updates file integrity strategy configuration
put
Authorizations
AuthorizationstringRequired
Basic Authorization header
Header parameters
api-versionstringRequired
Body
Updates file integrity strategy configuration
enabledbooleanRequired
Indicates if the file integrity strategy is enabled
Responses
200
OK
File integrity strategy configuration
enabledbooleanRequired
Indicates if the file integrity strategy is enabled
400
Request validation failed
put
/settings/file-integrity
Include the following in your request body:
Note. When checkFileContents is enabled, all checks (entropy, magic numbers, and YARA) are performed. If there are no YARA rules in the folder for this application, it functions as if YARA was not present.
Enabling YARA-X in On-Demand Scanning
To enable YARA-X analysis during on-demand scanning, you need to include the checkYaraRules parameter when initiating a scan. This is done through the /scans endpoint:
Start new scan
post
Authorizations
AuthorizationstringRequired
Basic Authorization header
Header parameters
api-versionstringRequired
Body
Scan creation request
pathsstring[]Required
Paths that will be recursively scanned
checkBlockListPatternsbooleanRequired
Indicates if file names found during scan should be analyzed to find files with names often used by ransomware
checkYaraRulesbooleanOptional
Indicates if files should be scanned using YARA rules
sendAlertsbooleanOptional
If true, Agent will raise alert on suspicious file found
rootMountPointsstring[] · nullableOptional
If present, causes exclusions to work as if filesystem root was at each of provided paths
Responses
200
Returns a newly created scan
No content
202
Accepted
400
Bad request was sent
post
/scans
No content
Include the following in your request body:
By setting checkYaraRules to true, you enable YARA-X analysis for the on-demand scan.
Applying Configuration Changes
After modifying YARA-X rules or updating the configuration, restart the GuardMode agent to apply the changes:
On Linux:
On Windows:
Performance Considerations
YARA-X analysis time is proportional to the number of rules and the size of the file, unlike entropy and magic number checks, which take a fixed time regardless of file size.
YARA-X is typically used for malware detection rather than identifying encrypted files. While very large files are less likely to be malware, setting a reasonable maxFileSize can help balance detection capabilities with performance.
By leveraging YARA-X analysis alongside entropy and magic number checks, GuardMode provides a robust file analysis system to detect potential threats and suspicious activities in your environment.
