7. YARA API для C

Вы можете интегрировать YARA в свой C/C++ проект с помощью API, предоставляемого библиотекой libyara. Этот API дает вам доступ к каждой функции YARA, и это тот же API, который используется инструментами командной строки yara и yarac.

7.1. Инициализация и завершение libyara

Первое, что ваша программа должна сделать при использовании libyara - это инициализации библиотеки. Это делается путем вызова функции yr_initialize(). Эта функция выделяет все ресурсы, необходимые библиотеке, и инициализирует внутренние структуры данных. В паре с функцией yr_initialize() работает функция yr_finalize(), которая должна быть вызвана, когда вы закончите использовать библиотеку.

В многопоточной программе функции yr_initialize() и yr_finalize() должен вызывать только основной поток. Никаких других действий от других потоков, использующих библиотеку не требуется.

7.2. Компиляция правил

Перед использованием ваших правил для сканирования любых данных вам необходимо скомпилировать их в двоичную форму. Для этого вам понадобится компилятор YARA, который можно создать с помощью yr_compiler_create(). После использования компилятор должен быть уничтожен с помощью yr_compiler_destroy().

Вы можете использовать yr_compiler_add_file(), yr_compiler_add_fd() или yr_compiler_add_string(), чтобы добавить один или несколько входных источников для компиляции. Эти функции получают необязательное пространство имен. Правила, добавленные в том же пространстве имен, ведут себя так, как если бы они содержались в одном и том же исходном файле или строке, поэтому идентификаторы правил должны быть уникальными среди всех источников, совместно использующих пространство имен. Если аргумент пространства имен равен NULL, правила помещаются в пространство имен по умолчанию (default).

Функции yr_compiler_add_file(), yr_compiler_add_fd() и yr_compiler_add_string() возвращают количество ошибок, найденных в исходном коде. Если правила верны, они возвращают 0. Если какая-либо из этих функций возвращает ошибку, компилятор больше не может использоваться ни для добавления дополнительных правил, ни для получения скомпилированных правил.

Для получения подробной информации об ошибке вы должны установить функцию обратного вызова, используя yr_compiler_set_callback() перед вызовом любой из функций компиляции. Функция обратного вызова имеет следующий прототип:

void callback_function(
        int error_level,
        const char* file_name,
        int line_number,
        const char* message,
        void* user_data)

Изменения в версии 3.3.0.

Возможные значения для error_level: YARA_ERROR_LEVEL_ERROR и YARA_ERROR_LEVEL_WARNING. Аргументы file_name и line_number содержат имя файла и номер строки, где происходит ошибка или предупреждение. file_name - это то, что передается в yr_compiler_add_file() или yr_compiler_add_fd(). Это может быть NULL, если вы передали NULL или если вы используете yr_compiler_add_string(). Указатель user_data - это то же самое, что вы передали в yr_compiler_set_callback().

По умолчанию для правил, содержащих ссылки на другие файлы (включая “filename.yara”), YARA попытается найти эти файлы на диске. Однако, если вы хотите получить импортированные правила из другого источника (например, из базы данных или удаленной службы), функцию обратного вызова можно установить с помощью yr_compiler_set_include_callback().

Обратный вызов получает следующие параметры:

  • include_name: имя запрашиваемого файла.
  • calling_rule_filename: запрашивающее имя файла (NULL, если не файл).
  • calling_rule_namespace: пространство имен (NULL, если не определено).
  • user_data: указатель тот же, что был передан в yr_compiler_set_include_callback().

Он должен вернуть содержимое запрошенного файла в виде строки с нулевым символом в конце. Память для этой строки должна быть выделена функцией обратного вызова. Как только можно будет безопасно освободить память, используемую для возврата результата обратного вызова, будет вызвана функция include_free, переданная в yr_compiler_set_include_callback(). Если память не нужно освобождать, вместо нее можно передать NULL. Вы можете полностью отключить поддержку включений, установив функцию обратного вызова в NULL с помощью yr_compiler_set_include_callback().

Функция обратного вызова имеет следующий прототип:

const char* include_callback(
        const char* include_name,
        const char* calling_rule_filename,
        const char* calling_rule_namespace,
        void* user_data);

Функция освобождения памяти имеет следующий прототип:

void include_free(
        const char* callback_result_ptr,
        void* user_data);

После успешного добавления некоторых источников можно получить скомпилированные правила с помощью функции yr_compiler_get_rules(). Вы получите указатель на структуру YR_RULES, которая может быть использована для сканирования ваших данных, как описано в разделе сканирование данных. После того, как yr_compiler_get_rules() вызвана, вы не сможете добавить больше источников в компилятор, но вы можете получить несколько экземпляров скомпилированных правил, вызывая yr_compiler_get_rules() несколько раз.

Каждый экземпляр YR_RULES должен быть уничтожен с помощью yr_rules_destroy().

7.3. Определение внешних переменных

Если в ваших правилах используются внешние переменные (как в примере ниже), вы должны определить эти переменные, используя любую из функций yr_compiler_define_XXXX_variable. Переменные должны быть определены до того, как правила скомпилированы с помощью функции yr_compiler_add_XXXX, и они должны быть определены с типом, который соответствует контексту, в котором переменная используется в правиле, к примеру, переменная, которая используется как my_var == 5, не может быть определена как строковая переменная.

При определении внешних переменных с помощью yr_compiler_define_XXXX_variable вы должны предоставить значение для каждой переменной. Это значение встраивается в скомпилированные правила и используется всякий раз, когда переменная появляется в правиле. Однако вы можете изменить значение, связанное с внешней переменной, после компиляции правил, используя любую из функций yr_rules_define_XXXX_variable.

7.4. Сохранение и извлечение скомпилированных правил

Скомпилированные правила могут быть сохранены в файл и извлечены позже с помощью yr_rules_save() и yr_rules_load(). Правила, скомпилированные и сохраненные на одной машине, могут быть загружены на другую машину, если они имеют одинаковый порядок байтов, независимо от операционной системы или ее разрядности (32 или 64-разрядная). Однако файлы, сохраненные в более старых версиях YARA, могут не работать с более новыми версиями из-за изменений в макете файла.

Вы также можете сохранять свои правила в общие потоки данных и извлекать их из общих потоков данных с помощью функций yr_rules_save_stream() и yr_rules_load_stream() соответственно. Эти функции получают указатель на структуру YR_STREAM, определенную как:

typedef struct _YR_STREAM
{
        void* user_data;

        YR_STREAM_READ_FUNC read;
        YR_STREAM_WRITE_FUNC write;

} YR_STREAM;

Вы должны предоставить свои собственные реализации для функций чтения и записи. Функция чтения используется yr_rules_load_stream() для чтения данных из вашего потока, а функция записи используется yr_rules_save_stream() для записи данных в ваш поток.

Ваши реализации функций read и write должны отвечать этим прототипам:

size_t read(
        void* ptr,
        size_t size,
        size_t count,
        void* user_data);

size_t write(
        const void* ptr,
        size_t size,
        size_t count,
        void* user_data);

Аргумент ptr - это указатель на буфер, куда функция read должна поместить прочитанные данные, или где функция write найдет данные, которые должны быть записаны в поток. В обоих случаях size - это размер каждого читаемого или записываемого элемента и count количества элементов. Общий размер читаемых или записываемых данных равен size * count. Функция read должна возвращать количество прочитанных элементов, функция write должна возвращать общее количество записанных элементов.

Указатель user_data является тем же, который вы указали в структуре YR_STREAM. Вы можете использовать его для передачи произвольных данных в функции чтения и записи.

7.5. Сканирование данных

Если у вас есть экземпляр YR_RULES, вы можете использовать его непосредственно с одной из функций yr_rules_scan_XXXX, описанной ниже, или создать сканер с помощью yr_scanner_create (). Давайте начнем с обсуждения первого подхода.

YR_RULES, который вы получили от компилятора, может использоваться с yr_rules_scan_file(), yr_rules_scan_fd() или yr_rules_scan_mem() для сканирования файла, дескриптора файла или буфера в памяти соответственно. Результаты сканирования возвращаются в вашу программу через функцию обратного вызова. Обратный вызов имеет следующий прототип:

int callback_function(
        int message,
        void* message_data,
        void* user_data);

Возможные значения для message:

CALLBACK_MSG_RULE_MATCHING
CALLBACK_MSG_RULE_NOT_MATCHING
CALLBACK_MSG_SCAN_FINISHED
CALLBACK_MSG_IMPORT_MODULE
CALLBACK_MSG_MODULE_IMPORTED

Ваша функция обратного вызова будет вызываться один раз для каждого правила с сообщением CALLBACK_MSG_RULE_MATCHING или CALLBACK_MSG_RULE_NOT_MATCHING, в зависимости от того, выполняется правило или нет. В обоих случаях указатель на структуру YR_RULE, связанную с правилом, передается в аргументе message_data. Вам просто нужно выполнить приведение типа из void* в YR_RULE*, чтобы получить доступ к структуре.

Этот обратный вызов также может быть вызван с сообщением CALLBACK_MSG_IMPORT_MODULE. Все модули, на которые ссылается оператор import в правилах, импортируются один раз для каждого сканируемого файла. В этом случае message_data указывает на структуру YR_MODULE_IMPORT. Эта структура содержит поле module_name, указывающее на строку с нулевым символом в конце с именем импортируемого модуля, и два других поля: module_data и module_data_size. Эти поля изначально установлены в NULL и 0, но ваша программа может назначить указатель на некоторые произвольные данные для module_data при установке в module_data_size размера этих данных. Таким образом, вы можете передавать дополнительные данные тем модулям, которым это необходимо, например, модулю Cuckoo.

Как только модуль импортирован, обратный вызов вызывается с сообщением CALLBACK_MSG_MODULE_IMPORTED. Когда это происходит, message_data указывает на структуру YR_OBJECT_STRUCTURE. Эта структура содержит всю информацию, предоставленную модулем о сканируемом в данный момент файле.

Наконец, функция обратного вызова также вызывается с сообщением CALLBACK_MSG_SCAN_FINISHED, когда сканирование завершено. В этом случае message_data имеет значение NULL.

Функция обратного вызова должна возвращать одно из следующих значений:

CALLBACK_CONTINUE
CALLBACK_ABORT
CALLBACK_ERROR

Если она возвращает CALLBACK_CONTINUE, YARA продолжит сканирование, CALLBACK_ABORT прервет сканирование, но результатом функции yr_rules_scan_XXXX будет ERROR_SUCCESS. С другой стороны, CALLBACK_ERROR также прервет сканирование, но результат из yr_rules_scan_XXXX будет ERROR_CALLBACK_ERROR.

Аргумент user_data, передаваемый в функцию обратного вызова, является таким же, что и аргумент передаваемый в yr_rules_scan_xxxx. Этот указатель не касается YARA, это просто способ для вашей программы передать произвольные данные в функцию обратного вызова.

Все функции yr_rules_scan_XXXX получают аргумент flags и аргумент timeout. Единственный флаг, определенный в настоящее время, это SCAN_FLAGS_FAST_MODE, поэтому вы должны передать либо этот флаг, либо нулевое значение. Аргумент timeout заставляет функцию возвращаться через указанное количество секунд, а ноль означает отсутствие тайм-аута вообще.

Флаг SCAN_FLAGS_FAST_MODE делает сканирование немного быстрее, избегая многократного совпадения одной и той же строки, когда в этом нет необходимости. Как только строка найдена в файле, она впоследствии игнорируется, подразумевая, что у вас будет одно совпадение для строки, даже если она появляется несколько раз в отсканированных данных. Этот флаг имеет тот же эффект, что и параметр командной строки -f, описанный в Главе 5 Запуск YARA из командной строки.

Обратите внимание, что вы не должны вызвать любую из функций yr_rules_scan_XXXX из функции обратного вызова, так как эти функции не реентерабельны.

7.5.1. Использование сканера

Функции yr_rules_scan_XXXX достаточно в большинстве случаев, но иногда может понадобиться более детальный контроль над сканированием. В этих случаях вы можете создать сканер с помощью функции yr_scanner_create(). Сканер - это просто оболочка вокруг структуры YR_RULES, которая содержит дополнительную конфигурацию, например внешние переменные, не затрагивая других пользователей структуры YR_RULES.

Сканер особенно полезен, когда вы хотите использовать один и тот же YR_RULES с несколькими потребителями (это может быть отдельный поток, сопрограмма и т. д.), И каждому потребителю необходимо установить различный набор значений для внешних переменных. В этом случае вы не можете использовать yr_rules_define_XXXX_variable для установки значений ваших внешних переменных, поскольку такие изменения затронут каждого потребителя, использующего YR_RULES. Однако у каждого потребителя может быть свой собственный сканер, в котором сканеры используют один и тот же YR_RULES и используют yr_scanner_define_XXXX_variable для установки внешних переменных без влияния на остальных потребителей.

Это лучшее решение, чем иметь отдельный YR_RULES для каждого потребителя, так как структуры YR_RULES имеют большой объем памяти (особенно если у вас много правил), в то время как сканеры гораздо менее ресурсоемкие.

7.6. Описание API

7.6.1. Структуры данных

YR_COMPILER

Структура данных, представляющая компилятор YARA.


YR_MATCH

Структура данных, представляющая строковое соответствие.

  • int64_t base - Базовое смещение/адрес совпадения. При сканировании файла это поле обычно равно нулю, а при сканировании пространства памяти процесса это поле является виртуальным адресом блока памяти, в котором было найдено совпадение.
  • int64_t offset - Смещение совпадения относительно base.
  • int32_t match_length - Длина совпадающей строки.
  • const uint8_t* data - Указатель на буфер, содержащий часть совпадающей строки.
  • int32_t data_length - Длина буфера data. Минимальное значение data_length-match_length, максимальное - MAX_MATCH_DATA.

Изменено в версии 3.5.0.

YR_META

Структура данных, представляющая значения метаданных.

  • const char* identifier - Идентификатор метаданных.

  • int32_t type - Один из следующих типов метаданных:

    • META_TYPE_NULL
    • META_TYPE_INTEGER
    • META_TYPE_STRING
    • META_TYPE_BOOLEAN

YR_MODULE_IMPORT

  • const char* module_name - Имя импортируемого модуля.
  • void* module_data - Указатель на дополнительные данные, передаваемые в модуль. Первоначально установленный в NULL, при этом ваша программа отвечает за установку этого указателя при обработке сообщения CALLBACK_MSG_IMPORT_MODULE.
  • size_t module_data_size - Размер дополнительных данных, передаваемых в модуль. Ваша программа должна установить соответствующее значение, если module_data изменен.

YR_RULE

Структура данных, представляющая одно правило.

  • const char* identifier - Идентификатор правила.
  • const char* tags - Указатель на последовательность строк с нулевым символом в конце с именами тегов. Дополнительный нулевой символ отмечает конец последовательности. Пример: tag1\0tag2\0tag3\0\0. Для перебора тегов вы можете использовать yr_rule_tags_foreach().
  • YR_META* metas - Указатель на последовательность структур YR_META. Для перебора структур используйте yr_rule_metas_foreach().
  • YR_STRING* strings - Указатель на последовательность структур YR_STRING. Для перебора структур используйте yr_rule_strings_foreach().
  • YR_NAMESPACE* ns - Указатель на структуру YR_NAMESPACE.

YR_RULES

Структура данных, представляющая набор правил.


YR_STREAM

Добавлено в версии 3.4.0. Структура данных, представляющая поток, используемый с функциями yr_rules_load_stream() и yr_rules_save_stream().

  • void* user_data - Пользовательский указатель.
  • YR_STREAM_READ_FUNC read - Указатель на функцию потока ‘read’, предоставленную пользователем.
  • YR_STREAM_WRITE_FUNC write - Указатель на функцию потока ‘write’, предоставленную пользователем.

YR_STRING

Структура данных, представляющая строку, объявленную в правиле.

  • const char* identifier - Идентификатор строки.

YR_NAMESPACE

Структура данных, представляющая пространство имен правила.

  • const char* name - Пространство имен правила.

7.6.2. Функции

int yr_initialize (void)

Инициализация библиотеки. Должна быть вызвана главным потоком перед использованием любой другой функции. Возвращает ERROR_SUCCESS в случае успеха, либо другой код ошибки в случае неудачи. Список возможных кодов возврата варьируется в зависимости от модулей, скомпилированных в YARA.


int yr_finalize (void)

Завершает работу библиотеки. Должна вызываться основным потоком для освобождения любого ресурса, выделенного библиотекой. Возвращает ERROR_SUCCESS в случае успеха, либо другой код ошибки в случае неудачи. Список возможных кодов возврата зависит от модулей, скомпилированных в YARA.


void yr_finalize_thread (void)

Устаревшая начиная с версии 3.8.0 функция. Любой поток, использующий библиотеку, кроме основного потока, должен вызывать эту функцию, при завершении использования библиотеки. Начиная с версии 3.8.0, вызов этой функции больше не требуется.


int yr_compiler_create (YR_COMPILER** compiler)

Создает компилятор YARA. В качестве параметра передается адрес указателя на YR_COMPILER, при этом функция установит указатель на вновь выделенный компилятор. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY

void yr_compiler_destroy (YR_COMPILER* compiler)

Уничтожает компилятор YARA.


void yr_compiler_set_callback (YR_COMPILER* compiler, YR_COMPILER_CALLBACK_FUNC callback, void* user_data)

Изменено начиная с версии 3.3.0. Устанавливает обратный вызов для получения информации об ошибке и предупреждении. Указатель на user_data передается в функцию обратного вызова.


void yr_compiler_set_include_callback (YR_COMPILER* compiler, YR_COMPILER_INCLUDE_CALLBACK_FUNC callback, YR_COMPILER_INCLUDE_FREE_FUNC include_ free, void* user_data)

Устанавливает обратный вызов для предоставления правил из пользовательского источника при вызове директивы include. Указатель user_data остается нетронутым и передается назад в функцию обратного вызова и в свободную функцию. Как только результат обратного вызова больше не нужен, будет вызвана функция include_free. Если память не должна быть освобождена, include_free может быть присвоено значение null. Если обратный вызов имеет значение NULL, поддержка директив include отключена.


int yr_compiler_add_file (YR_COMPILER* compiler, FILE* file, const char* namespace, const char* file_name)

Компилирует правила из файла file. Правила помещаются в пространство имен namespace, если namespace равно NULL, они будут помещены в пространство имен по умолчанию. file_name - это имя файла для создания отчетов об ошибках, которое может иметь значение NULL. Возвращает количество ошибок, обнаруженных во время компиляции.


int yr_compiler_add_fd (YR_COMPILER* compiler, YR_FILE_DESCRIPTOR rules_fd, const char* namespace, const char* file_name)

Добавлено в версии 3.6.0. Компилирует правила из файлового дескриптора rules_fd. Правила помещаются в пространство имен namespace, если namespace равно NULL, они будут помещены в пространство имен по умолчанию. file_name - это имя файла для создания отчетов об ошибках, которое может иметь значение NULL. Возвращает количество ошибок, обнаруженных во время компиляции.


int yr_compiler_add_string (YR_COMPILER* compiler, const char* string, const char* namespace)

Компилирует правила из строки string. Правила помещаются в пространство имен namespace, если namespace равно NULL, они будут помещены в пространство имен по умолчанию. file_name - это имя файла для создания отчетов об ошибках, которое может иметь значение NULL. Возвращает количество ошибок, обнаруженных во время компиляции.


int yr_compiler_get_rules (YR_COMPILER* compiler, YR_RULES** rules)

Получает скомпилированные правила из компилятора. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY

int yr_compiler_define_integer_variable (YR_COMPILER* compiler, const char* identifier, int64_t value)

Определяет внешнюю целочисленную переменную.


int yr_compiler_define_float_variable (YR_COMPILER* compiler, const char* identifier, double value)

Определяет внешнюю переменную с плавающей точкой.


int yr_compiler_define_boolean_variable (YR_COMPILER* compiler, const char* identifier, int value)

Определяет внешнюю переменную типа boolean.


int yr_compiler_define_string_variable (YR_COMPILER* compiler, const char* identifier, const char* value)

Определяет внешнюю строковую переменную.


int yr_rules_define_integer_variable (YR_RULES* rules, const char* identifier, int64_t value)

Определяет внешнюю целочисленную переменную.


int yr_rules_define_boolean_variable (YR_RULES* rules, const char* identifier, int value)

Определяет внешнюю переменную типа boolean.


int yr_rules_define_float_variable (YR_RULES* rules, const char* identifier, double value)

Определяет внешнюю переменную с плавающей точкой.


int yr_rules_define_string_variable (YR_RULES* rules, const char* identifier, const char* value)

Определяет внешнюю строковую переменную.


void yr_rules_destroy (YR_RULES* rules)

Уничтожает скомпилированные правила .


int yr_rules_save (YR_RULES* rules, const char* filename)

Сохраняет скомпилированные правила в файл, указанный в filename. Можно сохранить только правила, полученные с помощью yr_compiler_get_rules(). Правила, полученные с помощью yr_rules_load() или yr_rules_load_stream() не могут быть сохранены. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_COULD_NOT_OPEN_FILE

int yr_rules_save_stream (YR_RULES* rules, YR_STREAM* stream)

Добавлено в версии 3.4.0.

Сохраняет скомпилированные правила rules в stream. Можно сохранить только правила, полученные с помощью yr_compiler_get_rules(). Правила, полученные с помощью yr_rules_load() или yr_rules_load_stream() не могут быть сохранены. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS

int yr_rules_load (const char* filename, YR_RULES** rules)

Загружает скомпилированные правила rules из файла, указанного в параметре filename. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY
  • ERROR_COULD_NOT_OPEN_FILE
  • ERROR_INVALID_FILE
  • ERROR_CORRUPT_FILE
  • ERROR_UNSUPPORTED_FILE_VERSION

int yr_rules_load_stream (YR_STREAM* stream, YR_RULES** rules) Добавлено в версии 3.4.0.

Загружает скомпилированные правила rules из потока stream. Правила, загруженные таким образом, не могут быть сохранены обратно с помощью yr_rules_save_stream(). Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY
  • ERROR_INVALID_FILE
  • ERROR_CORRUPT_FILE
  • ERROR_UNSUPPORTED_FILE_VERSION

int yr_rules_scan_mem (YR_RULES* rules, const uint8_t* buffer, size_t buffer_size, int flags, YR_CALLBACK_FUNC callback, void* user_data, int timeout)

Сканирование участка памяти buffer. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY
  • ERROR_TOO_MANY_SCAN_THREADS
  • ERROR_SCAN_TIMEOUT
  • ERROR_CALLBACK_ERROR
  • ERROR_TOO_MANY_MATCHES

int yr_rules_scan_file (YR_RULES* rules, const char* filename, int flags, YR_CALLBACK_FUNC callback, void* user_data, int timeout)

Сканирование файла. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY
  • ERROR_COULD_NOT_MAP_FILE
  • ERROR_ZERO_LENGTH_FILE
  • ERROR_TOO_MANY_SCAN_THREADS
  • ERROR_SCAN_TIMEOUT
  • ERROR_CALLBACK_ERROR
  • ERROR_TOO_MANY_MATCHES

int yr_rules_scan_fd (YR_RULES* rules, YR_FILE_DESCRIPTOR fd, int flags, YR_CALLBACK_FUNC callback, void* user_data, int timeout)

Сканирование файла по его дескриптору . В системах POSIX YR_FILE_DESCRIPTOR - это int, возвращаемый функцией open (). В Windows YR_FILE_DESCRIPTOR - это HANDLE, возвращаемый CreateFile (). Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY
  • ERROR_COULD_NOT_MAP_FILE
  • ERROR_ZERO_LENGTH_FILE
  • ERROR_TOO_MANY_SCAN_THREADS
  • ERROR_SCAN_TIMEOUT
  • ERROR_CALLBACK_ERROR
  • ERROR_TOO_MANY_MATCHES

yr_rule_tags_foreach (rule, tag)

Повторение по тегам данного правила, выполняя блок кода, который следует каждый раз, с другим значением для tag типа const char *. Например:

const char* tag;

/* rule - объект YR_RULE */

r_rule_tags_foreach(rule, tag)
{
        ..do //сделать что-нибудь с tag
}

yr_rule_metas_foreach (rule, meta)

Выполняет повторение по структуре YR_META*, связанной с данным правилом, в котором выполняется блок кода, который каждый раз следует с другим значением для meta. Например:

YR_META* meta;

/* rule - объект YR_RULE */

yr_rule_metas_foreach(rule, meta)
{
        ..do //сделать что-нибудь с meta
}

yr_rule_strings_foreach (rule, string)

Выполняет повторение по структуре YR_STRING*, связанной с данным правилом, в котором выполняется блок кода, который каждый раз следует с другим значением для string. Например:

YR_STRING* string;

/* rule - объект YR_RULE */

yr_rule_strings_foreach(rule, string)
{
        ..do //сделать что-нибудь с string
}

yr_string_matches_foreach (string, match)

Выполняет повторение по структуре YR_MATCH*, связанной с данным правилом, в котором выполняется блок кода, который каждый раз следует с другим значением для match. Например:

YR_MATCH* match;

/* string - объект YR_STRING */

yr_string_matches_foreach(string, match)
{
        ..do //сделать что-нибудь с match
}

yr_rules_foreach (rules, rule)

Повторение по каждому YR_RULE в объекте YR_RULES, выполняя блок кода, который следует каждый раз с другим значением rule. Например:

YR_RULE* rule;

/* rule - объект YR_RULE */

yr_rules_foreach(rules, rule)
{
        ..do //сделать что-нибудь с rule
}

void yr_rule_disable (YR_RULE* rule)

Добавлено в версии 3.7.0.

Отключает указанное правило. Отключенные правила полностью игнорируются в процессе сканирования и не вызывают совпадений. Если отключенное правило используется в для определения состояния какого-либо другого правила, значение для отключенного правила не определено (т. е. не является ни истинным, ни ложным). Дополнительные сведения о неопределенных значениях см. в разделе 2.6.


void yr_rule_enable (YR_RULE* rule)

Добавлено в версии 3.7.0.

Включает указанное правило. После использования yr_rule_disable() правило можно заново включить с помощью этой функции.

int yr_scanner_create (YR_RULES* rules, YR_SCANNER **scanner)

Добавлено в версии 3.8.0.

Создает новый сканер, который можно использовать для сканирования данных с помощью предоставленных правил. scanner должен быть указателем на YR_SCANNER, при этом функция установит указатель на вновь выделенный сканер. Возвращает один из следующих кодов ошибок:

  • ERROR_INSUFFICIENT_MEMORY

void yr_scanner_destroy (YR_SCANNER *scanner)

Добавлено в версии 3.8.0.

Уничтожает сканер. После использования сканера он должен быть уничтожен с помощью этой функции.


void yr_scanner_set_callback (YR_SCANNER *scanner, YR_CALLBACK_FUNC callback, void* user_data)

Добавлено в версии 3.8.0.

Устанавливает функцию обратного вызова, которая будет вызываться для сообщения о любых совпадениях, найденных сканером.


void yr_scanner_set_timeout (YR_SCANNER* scanner, int timeout)

Добавлено в версии 3.8.0.

Устанавливает максимальное количество секунд, которое сканер будет тратить при любом вызове yr_scanner_scan_xxx.


void yr_scanner_set_flags (YR_SCANNER* scanner, int flags)

Добавлено в версии 3.8.0.

Устанавливает флаги, которые будут использоваться при любом вызове yr_scanner_scan_xxx.


int yr_scanner_define_integer_variable (YR_SCANNER* scanner, const char* identifier, int64_t value)

Добавлено в версии 3.8.0.

Определяет внешнюю целочисленную переменную.


int yr_scanner_define_boolean_variable (YR_SCANNER* scanner, const char* identifier, int value)

Добавлено в версии 3.8.0.

Определяет внешнюю переменную типа boolean.


int yr_scanner_define_float_variable (YR_SCANNER* scanner, const char* identifier, double value)

Добавлено в версии 3.8.0.

Определяет внешнюю переменную с плавающей точкой.


int yr_scanner_define_string_variable (YR_SCANNER* scanner, const char* identifier, const char* value)

Добавлено в версии 3.8.0.

Определяет внешнюю строковую переменную.


int yr_scanner_scan_mem (YR_SCANNER* scanner, const uint8_t* buffer, size_t buffer_size)

Добавлено в версии 3.8.0.

Сканирует область памяти. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY
  • ERROR_TOO_MANY_SCAN_THREADS
  • ERROR_SCAN_TIMEOUT
  • ERROR_CALLBACK_ERROR
  • ERROR_TOO_MANY_MATCHES

int yr_scanner_scan_file (YR_SCANNER* scanner, const char* filename)

Добавлено в версии 3.8.0.

Сканирует файл. Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY
  • ERROR_TOO_MANY_SCAN_THREADS
  • ERROR_SCAN_TIMEOUT
  • ERROR_CALLBACK_ERROR
  • ERROR_TOO_MANY_MATCHES

int yr_scanner_scan_fd (YR_SCANNER* scanner, YR_FILE_DESCRIPTOR fd)

Добавлено в версии 3.8.0.

Сканирование файла по его дескриптору. В системах POSIX YR_FILE_DESCRIPTOR - это int, возвращаемый функцией open(). В Windows YR_FILE_DESCRIPTOR - это дескриптор, возвращаемый функцией CreateFile(). Возвращает один из следующих кодов ошибок:

  • ERROR_SUCCESS
  • ERROR_INSUFFICIENT_MEMORY
  • ERROR_TOO_MANY_SCAN_THREADS
  • ERROR_SCAN_TIMEOUT
  • ERROR_CALLBACK_ERROR
  • ERROR_TOO_MANY_MATCHES

7.6.3. Коды ошибок

ERROR_SUCCESS

Все прошло нормально.


ERROR_INSUFFICIENT_MEMORY

Недостаточно памяти для завершения операции.


ERROR_COULD_NOT_OPEN_FILE

Файл не может быть открыт.


ERROR_COULD_NOT_MAP_FILE

Файл не может быть отображен в память.


ERROR_ZERO_LENGTH_FILE

Длина файла равна нулю.


ERROR_INVALID_FILE

Файл не является допустимым файлом правил.


ERROR_CORRUPT_FILE

Файл правил поврежден.


ERROR_UNSUPPORTED_FILE_VERSION

Файл сгенерирован другой версией YARA и не может быть загружен этой версией.


ERROR_TOO_MANY_SCAN_THREADS

Слишком много потоков пытаются использовать один и тот же объект YR_RULES одновременно. Предел определяется YR_MAX_THREADS в ./include/yara/limits.h.


ERROR_SCAN_TIMEOUT

Время сканирования истекло.


ERROR_CALLBACK_ERROR

Функция обратного вызова вернула ошибку.


ERROR_TOO_MANY_MATCHES

Слишком много совпадений для какой-либо строки в правилах. Обычно это происходит, когда правила содержат очень короткие или очень распространенные строки, такие как 01 02 или FF FF FF FF. Предел определяется YR_MAX_STRING_MATCHES в ./include/yara/limits.h.