Configuring YARA-X

Attention! YARA-X analysis is currently a beta/experimental feature in GuardMode. It is disabled by default and should be used with caution in production environments.

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 rules

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:

1. 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.

2. 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/settings/yara

Header parameters

Response

200

Current configuration

Body

text/plainapplication/jsontext/json

scans*YaraRuleSourceConfigurationResponse (object)

threshold*YaraRuleSourceConfigurationResponse (object)

fileIntegrity*YaraRuleSourceConfigurationResponse (object)

incidents*YaraRuleSourceConfigurationResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('/settings/yara', {
    method: 'GET',
    headers: {
      "api-version": "text"
    },
});
const data = await response.json();

Response

200

{
  "scans": {
    "rulesPath": "text"
  },
  "threshold": {
    "rulesPath": "text"
  },
  "fileIntegrity": {
    "rulesPath": "text"
  },
  "incidents": {
    "rulesPath": "text"
  }
}

Update YARA analysis configuration

PUT/settings/yara

Header parameters

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

scans*YaraRuleSourceConfigurationRequest (object)

threshold*YaraRuleSourceConfigurationRequest (object)

fileIntegrity*YaraRuleSourceConfigurationRequest (object)

incidents*YaraRuleSourceConfigurationRequest (object)

Response

200400

Updated configuration

Body

text/plainapplication/jsontext/json

scans*YaraRuleSourceConfigurationResponse (object)

threshold*YaraRuleSourceConfigurationResponse (object)

fileIntegrity*YaraRuleSourceConfigurationResponse (object)

incidents*YaraRuleSourceConfigurationResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('/settings/yara', {
    method: 'PUT',
    headers: {
      "api-version": "text",
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({
      "fileIntegrity": {
        "rulesPath": "text"
      },
      "incidents": {
        "rulesPath": "text"
      },
      "scans": {
        "rulesPath": "text"
      },
      "threshold": {
        "rulesPath": "text"
      }
    }),
});
const data = await response.json();

Response

200400

{
  "scans": {
    "rulesPath": "text"
  },
  "threshold": {
    "rulesPath": "text"
  },
  "fileIntegrity": {
    "rulesPath": "text"
  },
  "incidents": {
    "rulesPath": "text"
  }
}

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:

Update threshold configuration.

PUT/settings/threshold

Header parameters

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

entropyCheck*EntropyCheck (object)

magicNumberCheckMagicNumberCheck (object)

Indicates if magic number check is enabled and how many files per user are checked

yaraCheckYaraConfigRequest (object)

numberOfBuckets*integer (int32)

Number of threshold buckets

pointsLimit*integer (int32)

Limit of data points to analyze

writesPerSecond*ThresholdLevel (object)

Indicates the threshold levels of a given setting

riskWeights*ThresholdLevel (object)

Indicates the threshold levels of a given setting

Response

200400

Updated threshold configuration

Body

text/plainapplication/jsontext/json

entropyCheck*EntropyCheck (object)

magicNumberCheck*MagicNumberCheck (object)

Indicates if magic number check is enabled and how many files per user are checked

yaraCheck*YaraConfigResponse (object)

numberOfBuckets*integer (int32)

Number of threshold buckets

pointsLimit*integer (int32)

Limit of data points to analyze

writesPerSecond*ThresholdLevel (object)

Indicates the threshold levels of a given setting

riskWeights*ThresholdLevel (object)

Indicates the threshold levels of a given setting

Request

JavaScriptCurlPython

const response = await fetch('/settings/threshold', {
    method: 'PUT',
    headers: {
      "api-version": "text",
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({
      "entropyCheck": {
        "enabled": false
      },
      "riskWeights": {},
      "writesPerSecond": {}
    }),
});
const data = await response.json();

Response

200400

{
  "entropyCheck": {
    "enabled": false
  },
  "magicNumberCheck": {
    "enabled": false
  },
  "yaraCheck": {
    "isEnabled": false
  },
  "writesPerSecond": {},
  "riskWeights": {}
}

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

PUT/settings/file-integrity

Header parameters

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

Request received

enabled*boolean

Indicates if the file integrity strategy is enabled

Response

200400

OK

Body

text/plainapplication/jsontext/json

enabled*boolean

Indicates if the file integrity strategy is enabled

paths*array of FileIntegrityPathResponse (object)

List of monitored paths

Request

JavaScriptCurlPython

const response = await fetch('/settings/file-integrity', {
    method: 'PUT',
    headers: {
      "api-version": "text",
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({
      "enabled": false
    }),
});
const data = await response.json();

Response

200400

{
  "enabled": false,
  "paths": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "prefix": "text",
      "checkFileContents": false
    }
  ]
}

Include the following in your request body:

{
  "enabled": true,
  "paths": [
    {
      "id": <id>,
      "prefix": <prefix string>,
      "checkFileContents": true
    }
  ]
}

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

Header parameters

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

paths*array of string

Paths that will be recursively scanned

checkBlockListPatterns*boolean

Indicates if file names found during scan should be analyzed to find files with names often used by ransomware

checkYaraRulesboolean

Indicates if files should be scanned using YARA rules

sendAlertsboolean

If true, Agent will raise alert on suspicious file found

rootMountPointsnullable array of string

If present, causes exclusions to work as if filesystem root was at each of provided paths

Response

200202400

Returns a newly created scan

Request

JavaScriptCurlPython

const response = await fetch('/scans', {
    method: 'POST',
    headers: {
      "api-version": "text",
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({
      "checkBlockListPatterns": false,
      "paths": [
        "text"
      ]
    }),
});
const data = await response.json();

Response

400

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

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.service

On Windows:

Restart-Service -Name CatalogicGuardModeAgent

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.