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.

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

basic

AuthorizationstringRequired

Basic Authorization header

Header parameters

api-versionstringRequired

Responses

200

Current configuration

text/plainapplication/jsontext/json

get

/settings/yara

HTTPcURLJavaScriptPython

GET /settings/yara HTTP/1.1
Authorization: Basic username:password
api-version: text
Accept: */*

200

Current configuration

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

Update YARA analysis configuration

put

Authorizations

basic

AuthorizationstringRequired

Basic Authorization header

Header parameters

api-versionstringRequired

Body

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

Responses

200

Updated configuration

text/plainapplication/jsontext/json

400

Bad request was sent

text/plainapplication/jsontext/json

put

/settings/yara

HTTPcURLJavaScriptPython

PUT /settings/yara HTTP/1.1
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
  }
}

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

{
  "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.

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

Authorizations

basic

AuthorizationstringRequired

Basic Authorization header

Header parameters

api-versionstringRequired

Body

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

numberOfBucketsinteger · int32 · max: 1000Required

Number of threshold buckets

pointsLimitinteger · int32 · max: 1000Required

Limit of data points to analyze

Responses

200

Updated threshold configuration

text/plainapplication/jsontext/json

400

Request validation failed

text/plainapplication/jsontext/json

put

/settings/threshold

HTTPcURLJavaScriptPython

PUT /settings/threshold HTTP/1.1
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
  }
}

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

{
  "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

put

Authorizations

basic

AuthorizationstringRequired

Basic Authorization header

Header parameters

api-versionstringRequired

Body

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

Updates file integrity strategy configuration

enabledbooleanRequired

Indicates if the file integrity strategy is enabled

Responses

200

OK

text/plainapplication/jsontext/json

400

Request validation failed

text/plainapplication/jsontext/json

put

/settings/file-integrity

HTTPcURLJavaScriptPython

PUT /settings/file-integrity HTTP/1.1
Authorization: Basic username:password
api-version: text
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 16

{
  "enabled": true
}

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

{
  "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
    }
  ]
}

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

basic

AuthorizationstringRequired

Basic Authorization header

Header parameters

api-versionstringRequired

Body

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

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

text/plainapplication/jsontext/json

post

/scans

HTTPcURLJavaScriptPython

POST /scans HTTP/1.1
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"
  ]
}

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

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