
Мощная библиотека Python и инструмент командной строки для разбора, анализа и манипуляции правилами YARA с использованием представления в виде абстрактного синтаксического дерева (AST).
<p align="center">
<img src="https://img.shields.io/badge/YARAAST-YARA%20Parser%20&%20AST-blue?style=for-the-badge" alt="YARAAST">
</p>
<h1 align="center">yaraast</h1>
<p align="center">
<strong>Разбор, анализ и преобразование YARA-правил с помощью Python-набора инструментов для работы с AST</strong>
</p>
<p align="center">
<a href="https://github.com/seifreed/yaraast/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/seifreed/yaraast/ci.yml?branch=main&style=flat-square&logo=github&label=CI" alt="CI"></a>
<a href="https://github.com/seifreed/yaraast/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License: MIT"></a>
<img src="https://img.shields.io/badge/python-3.11--3.14-blue?style=flat-square&logo=python&logoColor=white" alt="Python 3.11-3.14">
</p>
<p align="center">
<a href="https://github.com/seifreed/yaraast/stargazers"><img src="https://img.shields.io/github/stars/seifreed/yaraast?style=flat-square&logo=github" alt="GitHub Stars"></a>
<a href="https://github.com/seifreed/yaraast/issues"><img src="https://img.shields.io/github/issues/seifreed/yaraast?style=flat-square&logo=github" alt="GitHub Issues"></a>
<a href="https://github.com/seifreed/yaraast/tree/main/docs"><img src="https://img.shields.io/badge/docs-GitHub-blue?style=flat-square&logo=readthedocs&logoColor=white" alt="Docs"></a>
</p>
---
## Обзор
**yaraast** — это Python-библиотека для разбора и манипулирования правилами семейства YARA с использованием абстрактных синтаксических деревьев (AST). Она поддерживает классические рабочие процессы YARA, YARA-L и YARA-X с автоматическим определением диалекта и инструментами командной строки.
### Ключевые возможности
| Возможность | Описание |
|---------|-------------|
| **Многодиалектный разбор** | Разбор YARA, YARA-L и YARA-X из файлов или строк |
| **Автоматическое определение диалекта** | Единый парсер автоматически определяет диалекты правил |
| **Инструменты AST** | Создание, преобразование, сравнение и сериализация AST |
| **Форматирование и проверка** | Команды CLI для рабочих процессов parse/format/validate |
| **Потоковая поддержка** | Разбор очень больших файлов в потоковом режиме |
| **Интеграции экосистемы** | Дополнительные возможности LSP и libyara |
### Поддерживаемая экосистема правил
```text
Dialects YARA, YARA-L, YARA-X
Parsers Standard parser, unified parser, streaming parser
Outputs YARA, JSON, YAML, AST tree views
Tooling CLI, visitors, builders, serialization, semantic checks
```
Уровни поддержки различаются в зависимости от диалекта. Классический YARA стабилен, YARA-X находится в стадии бета-тестирования, YARA-L — экспериментальный, а автоматическое определение диалекта работает по принципу «best effort». См. [матрицу совместимости](https://github.com/seifreed/yaraast/blob/main/docs/compatibility.md) для точного перечня движков и возможностей, проверяемых CI.
---
## Установка
### Из PyPI (рекомендуется)
```bash
pip install yaraast
```
### Из исходного кода
```bash
git clone https://github.com/seifreed/yaraast.git
cd yaraast
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e .
```
---
## Быстрый старт
```python
import yaraast
yara_code = """
rule example {
strings:
$a = "malware" nocase
condition:
$a
}
"""
document = yaraast.parse(yara_code)
print(document.ast.rules[0].name)
```
---
## Использование
### Интерфейс командной строки
```bash
# Разбор и вывод нормализованного YARA
yaraast parse rules.yar
# Разбор в JSON
yaraast parse rules.yar --format json
# Разбор с явным указанием диалекта
yaraast parse rules.yar --dialect yara-x
# Проверка файла (синтаксис + проверки разбора)
yaraast validate rules.yar
# Форматирование файла на месте (форматтер на основе AST)
yaraast fmt rules.yar
# Проверка форматирования без изменения файла
yaraast fmt rules.yar --check
```
### Основные команды CLI
| Команда | Описание |
|--------|-------------|
| `parse` | Разбор файла правил и вывод YARA/JSON/YAML/дерева |
| `validate` | Проверка правил и выполнение подкоманд проверки |
| `fmt` | Форматтер на основе AST (с `--check` и `--diff`) |
| `format` | Форматирование входных данных в целевой выходной файл |
| `validate-syntax` | Точка входа для проверки, ориентированной на синтаксис |
| `lsp` | Запуск функций Language Server Protocol |
---
## Python-библиотека
### Единый разбор
```python
from pathlib import Path
import yaraast
source = "rule example { condition: true }"
# Автоматическое определение диалекта
document = yaraast.parse(source)
# Принудительное указание конкретного диалекта
document = yaraast.parse(source, dialect="yara")
# Разбор файлов, генерация нового исходного кода и каноническое форматирование
Path("rules.yar").write_text(source, encoding="utf-8")
file_document = yaraast.parse_file("rules.yar")
generated = yaraast.generate(file_document)
formatted = yaraast.format_canonical(source, dialect="yara")
# Сохранение каждого байта за пределами явного редактирования UTF-8
offset = source.encode("utf-8").index(b"true")
rewritten = yaraast.rewrite_lossless(
source,
[yaraast.SourceEdit(offset, offset + 4, "false")],
)
# Публичные парсеры применяют ограниченные значения по умолчанию. При необходимости переопределяйте их для каждой операции.
limits = yaraast.ResourceLimits(max_input_bytes=1024 * 1024, parse_deadline=5.0)
document = yaraast.parse(source, resource_limits=limits)
cancel = yaraast.CancellationToken()
cancel.cancel()
# yaraast.parse(source, cancellation_token=cancel) вызывает ParseCancelledError
```
`ResourceLimits()` явно отключает все ограничения. Разбор через CLI использует публичные значения по умолчанию; разбор через LSP использует более строгие ограничения на входные данные, токены, вложенность, шаблоны и сроки и никогда не кэширует частичный результат после отмены или сбоя ограничения.
### Прямой парсер + посетитель
```python
from pathlib import Path
from yaraast.parser import Parser
from yaraast.visitor import BaseVisitor
class RuleCollector(BaseVisitor):
def __init__(self):
self.rules = []
def visit_rule(self, node):
self.rules.append(node.name)
super().visit_rule(node)
ast = Parser(Path("rules.yar").read_text(encoding="utf-8")).parse()
collector = RuleCollector()
collector.visit(ast)
print(collector.rules)
```
---
## Дополнительные зависимости
```bash
# Поддержка LSP
pip install yaraast[lsp]
# Интеграция libyara
pip install yaraast[libyara]
# Инструменты производительности
pip install yaraast[performance]
# Поддержка визуализации
pip install yaraast[visualization]
# Полный пакет поддержки времени выполнения
pip install yaraast[all]
# Инструменты времени выполнения и разработки
pip install yaraast[dev-all]
```
## Документация по времени выполнения
- Совместимость диалектов: [docs/compatibility.md](https://github.com/seifreed/yaraast/blob/main/docs/compatibility.md)
- Внутреннее устройство LSP: [docs/lsp-runtime.md](https://github.com/seifreed/yaraast/blob/main/docs/lsp-runtime.md)
- Отчёт о паритете LSP: [docs/lsp-parity-report.md](https://github.com/seifreed/yaraast/blob/main/docs/lsp-parity-report.md)
- Последний артефакт бенчмарка: [docs/benchmarks/lsp-runtime-latest.json](https://github.com/seifreed/yaraast/blob/main/docs/benchmarks/lsp-runtime-latest.json)
---
## Требования
- Python 3.11, 3.12, 3.13 или 3.14
- См. [pyproject.toml](https://github.com/seifreed/yaraast/blob/main/pyproject.toml) для полного списка зависимостей и дополнительных пакетов
---
## Участие в разработке
Вклад приветствуется. См. [CONTRIBUTING.md](https://github.com/seifreed/yaraast/blob/main/CONTRIBUTING.md) для получения информации о настройке, проверках качества и рекомендациях по рабочему процессу.
1. Сделайте форк репозитория
2. Создайте ветку (`git checkout -b feature/your-change`)
3. Зафиксируйте изменения (`git commit -m "Add your change"`)
4. Отправьте изменения (`git push origin feature/your-change`)
5. Откройте Pull Request
Политика проекта описана в [SECURITY.md](https://github.com/seifreed/yaraast/blob/main/SECURITY.md),
[CODE_OF_CONDUCT.md](https://github.com/seifreed/yaraast/blob/main/CODE_OF_CONDUCT.md), [CHANGELOG.md](https://github.com/seifreed/yaraast/blob/main/CHANGELOG.md) и
[MIGRATING.md](https://github.com/seifreed/yaraast/blob/main/MIGRATING.md).
---
## Лицензия
Этот проект лицензирован по лицензии MIT — см. [LICENSE](https://github.com/seifreed/yaraast/blob/main/LICENSE).
**Автор**
- Marc Rivero ([[email protected]](mailto:[email protected]))
- Репозиторий: [github.com/seifreed/yaraast](https://github.com/seifreed/yaraast)
---
<p align="center">
<sub>Создано для рабочих процессов анализа вредоносных программ и разработки правил обнаружения</sub>
</p>