Crate yara_x_capi 

C bindings for the YARA-X library.

This crate defines the C-compatible API that C/C++ programs can use for interfacing with the YARA-X Rust library. A header file for this library (yara_x.h) will be automatically generated by cbindgen, during compilation, together with dynamic-linking and static-linking versions of the library.

How to build and install

You will need cargo-c for building this library, if you didn’t install it before, this is the first step:

cargo install cargo-c

You will also need the openssl library, depending on your platform you can choose one of the following methods:

Ubuntu:

sudo apt install libssl-dev

MacOS (using brew):

brew install openssl@3

Windows (using vcpkg):

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
bootstrap-vcpkg.bat
vcpkg install openssl:x64-windows-static
set OPENSSL_DIR=%cd%\installed\x64-windows-static

Once you have installed the pre-requisites, go to the root directory of the YARA-X repository and type:

cargo cinstall -p yara-x-capi --release

The command above will put the library and header files in the correct path in your system (usually /usr/local/lib and /usr/local/include for Linux and macOS users), and will generate a .pc file so that pkg-config knows about the library.

In Linux and macOS you can check if everything went fine by compiling a simple test program, like this:

cat <<EOF > test.c
#include <yara_x.h>
int main() {
    YRX_RULES* rules;
    yrx_compile("rule dummy { condition: true }", &rules);
    yrx_rules_destroy(rules);
}
EOF

gcc `pkg-config --cflags yara_x_capi` `pkg-config --libs yara_x_capi` test.c

The compilation should succeed without errors.

Windows users can find all the files you need for importing the YARA-X library in your project in the target/x86_64-pc-windows-msvc/release directory. This includes:

• A header file (yara_x.h)
• A module definition file (yara_x_capi.def)
• A DLL file (yara_x_capi.dll) with its corresponding import library (yara_x_capi.dll.lib)
• A static library (yara_x_capi.lib)

Structs

YRX_BUFFER

Represents a buffer with arbitrary data.

YRX_MATCH

Contains information about a pattern match.

YRX_METADATA

A metadata entry.

YRX_METADATA_BYTES

Represents a metadata value that contains raw bytes.

YRX_PATTERN

A pattern defined in a rule.

YRX_RULE

A single YARA rule.

YRX_RULES

A set of compiled YARA rules.

YRX_SCANNER

A scanner that scans data with a set of compiled YARA rules.

Enums

YRX_METADATA_TYPE

Types of metadata values.

YRX_RESULT

Error codes returned by functions in this API.

Functions

yrx_buffer_destroy^⚠

Destroys a YRX_BUFFER object.

yrx_compile^⚠

Compiles YARA source code and creates a YRX_RULES object that contains the compiled rules.

yrx_finalize^⚠

Finalizes YARA-X.

yrx_last_error^⚠

Returns the error message for the most recent function in this API invoked by the current thread.

yrx_pattern_identifier^⚠

Returns the name of the pattern represented by YRX_PATTERN.

yrx_pattern_iter_matches^⚠

Iterates over the matches of a pattern, calling the callback with a pointer to a YRX_MATCH structure for each pattern.

yrx_rule_identifier^⚠

Returns the name of the rule represented by YRX_RULE.

yrx_rule_iter_metadata^⚠

Iterates over the metadata of a rule, calling the callback with a pointer to a YRX_METADATA structure for each metadata in the rule.

yrx_rule_iter_patterns^⚠

Iterates over the patterns in a rule, calling the callback with a pointer to a YRX_PATTERN structure for each pattern.

yrx_rule_iter_tags^⚠

Iterates over the tags in a rule, calling the callback with a pointer to each tag.

yrx_rule_namespace^⚠

Returns the namespace of the rule represented by YRX_RULE.

yrx_rules_count^⚠

Returns the total number of rules.

yrx_rules_deserialize^⚠

Deserializes the rules from a sequence of bytes produced by yrx_rules_serialize.

yrx_rules_destroy^⚠

Destroys a YRX_RULES object.

yrx_rules_iter^⚠

Iterates over the compiled rules, calling the callback function for each rule.

yrx_rules_iter_imports^⚠

Iterates over the modules imported by the rules, calling the callback with the name of each imported module.

yrx_rules_serialize^⚠

Serializes the rules as a sequence of bytes.

yrx_scanner_clear_profiling_data^⚠

Clears all accumulated profiling data.

yrx_scanner_create^⚠

Creates a YRX_SCANNER object that can be used for scanning data with the provided YRX_RULES.

yrx_scanner_destroy^⚠

Destroys a YRX_SCANNER object.

yrx_scanner_fast_scan^⚠

Enables or disables fast scan mode for the scanner.

yrx_scanner_finish^⚠

Finalizes the scan of a set of memory blocks.

yrx_scanner_iter_slowest_rules^⚠

Iterates over the slowest N rules, calling the callback for each rule.

yrx_scanner_on_console_log^⚠

Sets the callback for console module.

yrx_scanner_on_matching_rule^⚠

Sets a callback function that is called by the scanner for each rule that matched during a scan.

yrx_scanner_scan^⚠

Scans a data buffer.

yrx_scanner_scan_block^⚠

Scans a block of data.

yrx_scanner_scan_file^⚠

Scans a file.

yrx_scanner_set_global_bool^⚠

Sets the value of a global variable of type bool.

yrx_scanner_set_global_float^⚠

Sets the value of a global variable of type float.

yrx_scanner_set_global_int^⚠

Sets the value of a global variable of type int.

yrx_scanner_set_global_json^⚠

Sets the value of a global variable from a JSON-encoded string.

yrx_scanner_set_global_str^⚠

Sets the value of a global variable of type string.

yrx_scanner_set_module_data^⚠

Specifies metadata for a module.

yrx_scanner_set_module_output^⚠

Specifies the output data structure for a module.

yrx_scanner_set_timeout^⚠

Sets a timeout (in seconds) for scan operations.

Type Aliases

YRX_CONSOLE_CALLBACK

Callback function used when a YARA rule calls the console module.

YRX_IMPORT_CALLBACK

Callback function passed to yrx_rules_iter_imports.

YRX_MATCH_CALLBACK

Callback function passed to yrx_pattern_iter_matches.

YRX_METADATA_CALLBACK

Callback function passed to yrx_rule_iter_metadata.

YRX_PATTERN_CALLBACK

Callback function passed to yrx_rule_iter_patterns.

YRX_RULE_CALLBACK

Callback function passed to yrx_scanner_on_matching_rule or yrx_rules_iter.

YRX_SLOWEST_RULES_CALLBACK

Callback function passed to yrx_scanner_iter_slowest_rules.

YRX_TAG_CALLBACK

Callback function passed to yrx_rule_iter_tags.

Unions

YRX_METADATA_VALUE

A metadata value.