YARA-X (yara-x)

YARA-X rule engine of the file security pipeline: an authenticated HTTPS worker with the navin-baseline rules and controlled rule updates from the internal repository.

Generated from catalog/services/yara-x.yaml: do not edit by hand.

Summary

Version	1.22.1
Use	install and configure
Layer	functional (AI catalog)
Category	Security and policies
Installation methods	python
External connection	no
Sandbox only	no

Licence

SPDX identifier	BSD-3-Clause
Licence policy	licence exception
Licence exception	LEX-023 (pending, awaiting the client)
Platform component	yara-x

Packages and artifacts

A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.

Kind	Package	Version	Licence	Details
Python package	yara-x	1.22.1	BSD-3-Clause	interpreters, in order of preference python3.11, python3.12, python3.10

Supported systems and architectures

Method	Operating systems	Architectures
python	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64, aarch64 (not restricted by the descriptor)

Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.

Prerequisites

Host

• at least 1024 MB of memory (warning, memory).

Network and ports

Component	Port name	Port	Opened in the host firewall
worker	api	8475/tcp	yes

Services and connections needed

This service has no dependency.

Installation methods and modes

Method	Default	What the method uses
python	yes	a Python virtual environment holding the Python packages of the descriptor

Components

Component	Kind	Installation methods	Ports
Worker (worker)	master	python	8475/tcp

Single worker (standalone) (default)

One YARA-X worker.

What the mode deploys:

Component	Placement
worker	min 1, max 1

Replicated (replicated)

Two or more independent workers with the same rule set; the platform fails over between them.

What the mode deploys:

Component	Placement
worker	min 2, recommended 2

Install this service

The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.

1. Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.

2. Choose the service. On the Service step, select YARA-X. The card shows the licence BSD-3-Clause.

3. Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: standalone (default), replicated. Each mode deploys the components listed in Installation methods and modes.

4. Bindings. This service has no dependency: the Bindings step has nothing to bind.

5. Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.

6. Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.

7. Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services. Open the service and choose Run the smoke test in the Checks card: Scans the EICAR test file (must match navin_eicar_test_file), then a clean file (must match nothing).

High availability

Cluster	replicas (replication)
High availability	external (external)
Failover	client side (client)
Replication	none (none)
Quorum	none (none)
Discovery	static (static)
Entry point	client discovery (client-discovery)
Official documentation	https://virustotal.github.io/yara-x/
References	https://virustotal.github.io/yara-x/docs/
Peer TLS parameter	tls_enabled
Peer authentication	Clients authenticate to every worker with the Bearer key; workers have no peer.

Topology per mode

Modes	Highest catalog level	Distribution	Quorum component	Fault domains	Description
standalone	standalone (standalone)	single (single)	-	1	One worker, no fault tolerance (uploads are refused in enforce mode while it is down).
replicated	ha (ha)	active-active (active-active)	-	2	Two or more stateless workers with the same rule set; the platform receives every worker and fails over to the next one.

Notes

• Every worker keeps its own copy of the rules: run update_rules on all workers (target all) so that they serve the same version.

Configuration parameters

Network

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Worker port (port)	port	8475	-	no	no	yes	HTTPS port of the worker (/v1/scan, /v1/rules/reload, /readyz, /metrics).

Security

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
TLS (tls_enabled)	bool	true	-	no	no	yes	Serve the worker over HTTPS with a certificate of the manager CA (required in production).
API key (api_key)	password	generated	-	no	yes	no	Bearer key of the worker clients (EAI_YARAX_API_KEY of the platform).

Rules

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Rule repository (rules_repository_url)	url	{{ mirror.url }}/yara-rules	-	no	no	no	Internal HTTPS repository serving navin-rules-<version>.tar.gz, checked with the manager CA (update_rules).

Scan limits

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Largest file (max_file_size_mb)	int	100	min 1, max 2000, MB	no	no	no	Body limit of /v1/scan (413 above); keep it at least the platform limit EAI_FILE_SCAN_MAX_BYTES.
Scan timeout (scan_timeout_s)	int	60	min 1, max 600, s	no	no	no	Timeout of the YARA-X scanner for one file (500 scan_timeout beyond).

Endpoints

Endpoint	Scheme	Component	Port	Path	TLS parameter	Binding parameters	Binding secrets	Provisioning command
api	http	worker	8475 (port)	-	tls_enabled	-	api_key	-

Commands

Command	Component	Target	Description
Rule set status (rules_status)	worker	every host	Active and previous rule sets of each worker and its readiness.
Update the rules (update_rules)	worker	every host	Downloads navin-rules-<version>.tar.gz from the internal repository, checks its sha256, compiles it in a staging directory, switches atomically and reloads each worker. Any failure keeps the active rules.
Roll back the rules (rollback_rules)	worker	every host	Switches each worker back to its previous rule set and reloads it. (asks for confirmation)
Worker logs (logs)	worker	chosen host	Last lines of the worker journal.

Command parameters

Command	Parameter	Type	Default	Required	Description
update_rules	Version (version)	string	-	yes	Version of the rule set (file navin-rules-<version>.tar.gz of the repository).
update_rules	Expected sha256 (sha256)	string	-	yes	SHA-256 of the archive published with the rule set; the download is refused when it differs.

Health checks

Liveness (per instance)

Component	Check	Details
worker	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.port }}/healthz	Expected 200; 30 retries; interval 2 s; timeout 5 s

Readiness (service check)

Check	Details
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.port }}/readyz	Expected 200; Expected "status": "ready"; 10 retries; interval 3 s; timeout 10 s

Smoke test

Scans the EICAR test file (must match navin_eicar_test_file), then a clean file (must match nothing). (worker: eicar_matched, clean_nothing)

Preflight checks

Check	Type	Meaning	Severity	Components
memory	memory_mb {"min": 1024}	at least 1024 MB of memory	warning	every component
port_free	port_free {"param": "port"}	port 8475 free on the host	blocking	every component

Uninstall

Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.

Quick links

• Worker metrics: {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/metrics

Upstream documentation

• Homepage: https://virustotal.github.io/yara-x/
• Source: https://github.com/VirusTotal/yara-x
• High availability: https://virustotal.github.io/yara-x/
• High availability: https://virustotal.github.io/yara-x/docs/