
Eine leistungsstarke Python-Bibliothek und CLI-Tool zum Parsen, Analysieren und Manipulieren von YARA-Regeln mittels Abstract Syntax Tree (AST)-Darstellung.
<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-Regeln mit einem Python-AST-Toolkit parsen, analysieren und transformieren</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>
---
## Übersicht
**yaraast** ist eine Python-Bibliothek zum Parsen und Manipulieren von YARA-Familienregeln mithilfe von abstrakten Syntaxbäumen (AST). Sie unterstützt klassische YARA-, YARA-L- und YARA-X-Workflows mit automatischer Dialekterkennung und CLI-Werkzeugen.
### Hauptfunktionen
| Funktion | Beschreibung |
|---------|-------------|
| **Multi-Dialekt-Parsing** | YARA, YARA-L und YARA-X aus Dateien oder Zeichenketten parsen |
| **Automatische Dialekterkennung** | Einheitlicher Parser erkennt Regeldialekte automatisch |
| **AST-Werkzeuge** | ASTs erstellen, transformieren, diffen und serialisieren |
| **Formatierung & Validierung** | CLI-Befehle für Parse-/Format-/Validierungs-Workflows |
| **Streaming-Unterstützung** | Sehr große Dateien im Streaming-Modus parsen |
| **Ökosystem-Integrationen** | Optionale LSP- und libyara-bezogene Fähigkeiten |
### Unterstütztes Regel-Ökosystem
```text
Dialekte YARA, YARA-L, YARA-X
Parser Standard-Parser, einheitlicher Parser, Streaming-Parser
Ausgaben YARA, JSON, YAML, AST-Baumansichten
Werkzeuge CLI, Besucher, Builder, Serialisierung, semantische Prüfungen
```
Der Unterstützungsgrad variiert je nach Dialekt. Klassisches YARA ist stabil, YARA-X ist Beta,
YARA-L ist experimentell, und die automatische Dialekterkennung ist eine Best-Effort-Lösung. Siehe
die [Kompatibilitätsmatrix](https://github.com/seifreed/yaraast/blob/main/docs/compatibility.md) für die genauen Engines und
Fähigkeiten, die von CI getestet werden.
---
## Installation
### Von PyPI (empfohlen)
```bash
pip install yaraast
```
### Aus dem Quellcode
```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 .
```
---
## Schnellstart
```python
import yaraast
yara_code = """
rule example {
strings:
$a = "malware" nocase
condition:
$a
}
"""
document = yaraast.parse(yara_code)
print(document.ast.rules[0].name)
```
---
## Verwendung
### Befehlszeilenschnittstelle
```bash
# Parsen und normalisiertes YARA ausgeben
yaraast parse rules.yar
# Als JSON parsen
yaraast parse rules.yar --format json
# Mit explizitem Dialekt parsen
yaraast parse rules.yar --dialect yara-x
# Datei validieren (Syntax- + Parse-Prüfungen)
yaraast validate rules.yar
# Datei direkt formatieren (AST-basierter Formatierer)
yaraast fmt rules.yar
# Formatierung prüfen, ohne die Datei zu ändern
yaraast fmt rules.yar --check
```
### Zentrale CLI-Befehle
| Befehl | Beschreibung |
|--------|-------------|
| `parse` | Eine Regeldatei parsen und YARA/JSON/YAML/Baum ausgeben |
| `validate` | Regeln validieren und Validierungs-Unterbefehle ausführen |
| `fmt` | AST-basierter Formatierer (mit `--check` und `--diff`) |
| `format` | Eingabe in eine Zieldatei formatieren |
| `validate-syntax` | Auf Syntax fokussierter Validierungs-Einstiegspunkt |
| `lsp` | Language Server Protocol-Funktionen starten |
---
## Python-Bibliothek
### Einheitliches Parsing
```python
from pathlib import Path
import yaraast
source = "rule example { condition: true }"
# Dialekt automatisch erkennen
document = yaraast.parse(source)
# Bestimmten Dialekt erzwingen
document = yaraast.parse(source, dialect="yara")
# Dateien parsen, neuen Quellcode erzeugen und kanonisch formatieren
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")
# Jedes Byte außerhalb einer expliziten UTF-8-Byte-Änderung erhalten
offset = source.encode("utf-8").index(b"true")
rewritten = yaraast.rewrite_lossless(
source,
[yaraast.SourceEdit(offset, offset + 4, "false")],
)
# Öffentliche Parser wenden begrenzte Standardwerte an. Bei Bedarf pro Vorgang überschreiben.
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) löst ParseCancelledError aus
```
`ResourceLimits()` deaktiviert alle Grenzen explizit. CLI-Parsing verwendet die öffentlichen
Standardwerte; LSP-Parsing verwendet strengere Eingabe-, Token-, Verschachtelungs-, Muster- und Frist-
Grenzen und speichert nach einem Abbruch oder einem Grenzwertfehler niemals ein Teilergebnis zwischen.
### Direkter Parser + Besucher
```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)
```
---
## Optionale Abhängigkeiten
```bash
# LSP-Unterstützung
pip install yaraast[lsp]
# libyara-Integration
pip install yaraast[libyara]
# Leistungswerkzeuge
pip install yaraast[performance]
# Visualisierungsunterstützung
pip install yaraast[visualization]
# Laufzeit-Unterstützungspaket
pip install yaraast[all]
# Laufzeit- und Entwicklungswerkzeuge
pip install yaraast[dev-all]
```
## Laufzeit-Dokumentation
- Dialekt-Kompatibilität: [docs/compatibility.md](https://github.com/seifreed/yaraast/blob/main/docs/compatibility.md)
- LSP-Laufzeit-Interna: [docs/lsp-runtime.md](https://github.com/seifreed/yaraast/blob/main/docs/lsp-runtime.md)
- LSP-Paritätsbericht: [docs/lsp-parity-report.md](https://github.com/seifreed/yaraast/blob/main/docs/lsp-parity-report.md)
- Neuestes Laufzeit-Benchmark-Artefakt: [docs/benchmarks/lsp-runtime-latest.json](https://github.com/seifreed/yaraast/blob/main/docs/benchmarks/lsp-runtime-latest.json)
---
## Anforderungen
- Python 3.11, 3.12, 3.13 oder 3.14
- Siehe [pyproject.toml](https://github.com/seifreed/yaraast/blob/main/pyproject.toml) für die vollständige Liste der Abhängigkeiten und Extras
---
## Mitwirken
Beiträge sind willkommen. Siehe [CONTRIBUTING.md](https://github.com/seifreed/yaraast/blob/main/CONTRIBUTING.md) für Einrichtung, Qualitätsprüfungen und Workflow-Richtlinien.
1. Repository forken
2. Branch erstellen (`git checkout -b feature/your-change`)
3. Änderungen committen (`git commit -m "Add your change"`)
4. Pushen (`git push origin feature/your-change`)
5. Pull Request öffnen
Die Projektrichtlinien sind dokumentiert in [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) und
[MIGRATING.md](https://github.com/seifreed/yaraast/blob/main/MIGRATING.md).
---
## Lizenz
Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe [LICENSE](https://github.com/seifreed/yaraast/blob/main/LICENSE).
**Autor**
- Marc Rivero ([[email protected]](mailto:[email protected]))
- Repository: [github.com/seifreed/yaraast](https://github.com/seifreed/yaraast)
---
<p align="center">
<sub>Entwickelt für Malware-Analyse- und Detection-Engineering-Workflows</sub>
</p>