Configuring YARA-X
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
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.
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 /settings/yara HTTP/1.1
Host:
Authorization: Basic username:password
api-version: text
Accept: */*
Current configuration
{
"scans": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"threshold": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"fileIntegrity": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"incidents": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
}
}PUT /settings/yara HTTP/1.1
Host:
Authorization: Basic username:password
api-version: text
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 225
{
"scans": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"threshold": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"fileIntegrity": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"incidents": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
}
}{
"scans": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"threshold": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"fileIntegrity": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
},
"incidents": {
"rulesPath": "text",
"maxFileSizeInBytes": 1
}
}Replace the path/to/... values with the actual paths to your YARA-X rule files for each analysis type.
Enabling YARA-X in Threshold Analysis
To enable YARA-X for threshold analysis, use the /settings/threshold endpoint:
Number of threshold buckets
Limit of data points to analyze
PUT /settings/threshold HTTP/1.1
Host:
Authorization: Basic username:password
api-version: text
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 264
{
"entropyCheck": {
"enabled": true,
"maxCheckAttempts": 1
},
"magicNumberCheck": {
"enabled": true,
"filesChecked": 1
},
"yaraCheck": {
"enabled": true
},
"numberOfBuckets": 1,
"pointsLimit": 1,
"writesPerSecond": {
"high": 1,
"medium": 1,
"low": 1
},
"riskWeights": {
"high": 1,
"medium": 1,
"low": 1
}
}{
"entropyCheck": {
"enabled": true,
"maxCheckAttempts": 1
},
"magicNumberCheck": {
"enabled": true,
"filesChecked": 1
},
"yaraCheck": {
"isEnabled": true
},
"numberOfBuckets": 1,
"pointsLimit": 1,
"writesPerSecond": {
"high": 1,
"medium": 1,
"low": 1
},
"riskWeights": {
"high": 1,
"medium": 1,
"low": 1
}
}Include the following in your request body:
{
"yaraCheck": {
"enabled": true
}
// Other threshold settings...
}
Enabling YARA-X in File Integrity Checks
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
Indicates if the file integrity strategy is enabled
PUT /settings/file-integrity HTTP/1.1
Host:
Authorization: Basic username:password
api-version: text
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 16
{
"enabled": true
}{
"enabled": true,
"paths": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"prefix": "text",
"checkFileContents": true
}
]
}Include the following in your request body:
{
"enabled": true,
"paths": [
{
"id": <id>,
"prefix": <prefix string>,
"checkFileContents": true
}
]
}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:
Scan creation request
Paths that will be recursively scanned
Indicates if file names found during scan should be analyzed to find files with names often used by ransomware
Indicates if files should be scanned using YARA rules
If true, Agent will raise alert on suspicious file found
If present, causes exclusions to work as if filesystem root was at each of provided paths
POST /scans HTTP/1.1
Host:
Authorization: Basic username:password
api-version: text
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 115
{
"paths": [
"text"
],
"checkBlockListPatterns": true,
"checkYaraRules": true,
"sendAlerts": true,
"rootMountPoints": [
"text"
]
}No content
Include the following in your request body:
{
"checkYaraRules": true
// Other scan parameters...
}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:
systemctl restart Catalogic.GuardMode.Agent.serviceOn Windows:
Restart-Service -Name CatalogicGuardModeAgentPerformance 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
maxFileSizecan 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.
Last updated