
Una potente biblioteca de Python y herramienta CLI para analizar, examinar y manipular reglas YARA mediante la representación de Árbol de Sintaxis Abstracta (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>Analiza, procesa y transforma reglas YARA con un kit de herramientas AST en Python</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="Licencia: 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="Estrellas de GitHub"></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="Problemas de GitHub"></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="Documentación"></a>
</p>
---
## Descripción general
**yaraast** es una biblioteca de Python para analizar y manipular reglas de la familia YARA mediante Árboles de Sintaxis Abstracta (AST). Admite flujos de trabajo clásicos de YARA, YARA-L y YARA-X con detección automática de dialectos y herramientas de línea de comandos.
### Características principales
| Característica | Descripción |
|---------|-------------|
| **Análisis multidialecto** | Analiza YARA, YARA-L y YARA-X desde archivos o cadenas |
| **Detección automática de dialectos** | El analizador unificado detecta automáticamente los dialectos de las reglas |
| **Herramientas AST** | Construye, transforma, compara y serializa AST |
| **Formato y validación** | Comandos CLI para flujos de trabajo de análisis/formato/validación |
| **Soporte de streaming** | Analiza archivos muy grandes con modo de streaming |
| **Integraciones del ecosistema** | Capacidades opcionales relacionadas con LSP y libyara |
### Ecosistema de reglas compatible
```text
Dialectos YARA, YARA-L, YARA-X
Analizadores Analizador estándar, analizador unificado, analizador de streaming
Salidas YARA, JSON, YAML, vistas de árbol AST
Herramientas CLI, visitantes, constructores, serialización, comprobaciones semánticas
```
Los niveles de soporte difieren según el dialecto. El YARA clásico es estable, YARA-X está en beta,
YARA-L es experimental y la detección automática de dialectos es un esfuerzo de mejor esfuerzo. Consulta
la [matriz de compatibilidad](https://github.com/seifreed/yaraast/blob/main/docs/compatibility.md) para conocer los motores y las
capacidades exactas que se ejercitan en CI.
---
## Instalación
### Desde PyPI (recomendado)
```bash
pip install yaraast
```
### Desde el código fuente
```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 .
```
---
## Inicio rápido
```python
import yaraast
yara_code = """
rule example {
strings:
$a = "malware" nocase
condition:
$a
}
"""
document = yaraast.parse(yara_code)
print(document.ast.rules[0].name)
```
---
## Uso
### Interfaz de línea de comandos
```bash
# Analiza e imprime YARA normalizado
yaraast parse rules.yar
# Analiza a JSON
yaraast parse rules.yar --format json
# Analiza con dialecto explícito
yaraast parse rules.yar --dialect yara-x
# Valida archivo (comprobaciones de sintaxis + análisis)
yaraast validate rules.yar
# Formatea archivo en el lugar (formateador basado en AST)
yaraast fmt rules.yar
# Comprueba el formato sin modificar el archivo
yaraast fmt rules.yar --check
```
### Comandos CLI principales
| Comando | Descripción |
|--------|-------------|
| `parse` | Analiza un archivo de reglas y genera YARA/JSON/YAML/árbol |
| `validate` | Valida reglas y ejecuta subcomandos de validación |
| `fmt` | Formateador basado en AST (con `--check` y `--diff`) |
| `format` | Formatea la entrada en un archivo de salida de destino |
| `validate-syntax` | Punto de entrada de validación centrado en la sintaxis |
| `lsp` | Inicia las funciones del Protocolo de Servidor de Lenguaje |
---
## Biblioteca de Python
### Análisis unificado
```python
from pathlib import Path
import yaraast
source = "rule example { condition: true }"
# Detecta el dialecto automáticamente
document = yaraast.parse(source)
# Fuerza un dialecto específico
document = yaraast.parse(source, dialect="yara")
# Analiza archivos, genera nuevo código fuente y formatea de forma canónica
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")
# Conserva cada byte fuera de una edición explícita de bytes UTF-8
offset = source.encode("utf-8").index(b"true")
rewritten = yaraast.rewrite_lossless(
source,
[yaraast.SourceEdit(offset, offset + 4, "false")],
)
# Los analizadores públicos aplican límites predeterminados acotados. Anúlalos por operación cuando sea necesario.
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) lanza ParseCancelledError
```
`ResourceLimits()` desactiva explícitamente todos los límites. El análisis CLI utiliza los
valores predeterminados públicos; el análisis LSP utiliza límites más estrictos de entrada, tokens, anidamiento, patrones y plazos,
y nunca almacena en caché un resultado parcial después de una cancelación o un fallo de límite.
### Analizador directo + visitante
```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)
```
---
## Dependencias opcionales
```bash
# Soporte LSP
pip install yaraast[lsp]
# Integración con libyara
pip install yaraast[libyara]
# Herramientas de rendimiento
pip install yaraast[performance]
# Soporte de visualización
pip install yaraast[visualization]
# Paquete de soporte en tiempo de ejecución
pip install yaraast[all]
# Herramientas de tiempo de ejecución y desarrollo
pip install yaraast[dev-all]
```
## Documentación en tiempo de ejecución
- Compatibilidad de dialectos: [docs/compatibility.md](https://github.com/seifreed/yaraast/blob/main/docs/compatibility.md)
- Internals del tiempo de ejecución LSP: [docs/lsp-runtime.md](https://github.com/seifreed/yaraast/blob/main/docs/lsp-runtime.md)
- Informe de paridad LSP: [docs/lsp-parity-report.md](https://github.com/seifreed/yaraast/blob/main/docs/lsp-parity-report.md)
- Artefacto de benchmark de tiempo de ejecución más reciente: [docs/benchmarks/lsp-runtime-latest.json](https://github.com/seifreed/yaraast/blob/main/docs/benchmarks/lsp-runtime-latest.json)
---
## Requisitos
- Python 3.11, 3.12, 3.13 o 3.14
- Consulta [pyproject.toml](https://github.com/seifreed/yaraast/blob/main/pyproject.toml) para ver la lista completa de dependencias y extras
---
## Contribuciones
Las contribuciones son bienvenidas. Consulta [CONTRIBUTING.md](https://github.com/seifreed/yaraast/blob/main/CONTRIBUTING.md) para conocer la configuración, los controles de calidad y las pautas del flujo de trabajo.
1. Haz un fork del repositorio
2. Crea una rama (`git checkout -b feature/your-change`)
3. Confirma los cambios (`git commit -m "Add your change"`)
4. Sube los cambios (`git push origin feature/your-change`)
5. Abre una solicitud de extracción
La política del proyecto está documentada en [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) y
[MIGRATING.md](https://github.com/seifreed/yaraast/blob/main/MIGRATING.md).
---
## Licencia
Este proyecto está licenciado bajo la Licencia MIT; consulta [LICENSE](https://github.com/seifreed/yaraast/blob/main/LICENSE).
**Autor**
- Marc Rivero ([[email protected]](mailto:[email protected]))
- Repositorio: [github.com/seifreed/yaraast](https://github.com/seifreed/yaraast)
---
<p align="center">
<sub>Diseñado para flujos de trabajo de análisis de malware e ingeniería de detección</sub>
</p>