yaraast

Analysez, analysez et transformez les règles YARA avec une boîte à outils AST Python

Aperçu

yaraast est une bibliothèque Python pour analyser et manipuler les règles de la famille YARA à l'aide d'arbres de syntaxe abstraite (AST). Elle prend en charge les flux de travail classiques YARA, YARA-L et YARA-X avec détection automatique de dialecte et outils CLI.

Fonctionnalités clés

Fonctionnalité	Description
Analyse multi-dialectes	Analyse YARA, YARA-L et YARA-X à partir de fichiers ou de chaînes
Détection automatique de dialecte	Analyseur unifié qui détecte automatiquement les dialectes de règles
Outils AST	Construire, transformer, différencier et sérialiser les AST
Formatage et validation	Commandes CLI pour les flux de travail d'analyse/formatage/validation
Prise en charge du streaming	Analyse de très grands fichiers en mode streaming
Intégrations écosystème	Capacités optionnelles liées à LSP et libyara

Écosystème de règles pris en charge

Dialectes   YARA, YARA-L, YARA-X
Analyseurs  Analyseur standard, analyseur unifié, analyseur de streaming
Sorties     YARA, JSON, YAML, vues d'arbre AST
Outils      CLI, visiteurs, constructeurs, sérialisation, vérifications sémantiques

Les niveaux de prise en charge diffèrent selon le dialecte. Le YARA classique est stable, YARA-X est en version bêta, YARA-L est expérimental, et la détection automatique de dialecte est au mieux. Consultez la matrice de compatibilité pour connaître les moteurs et capacités exacts testés par CI.

Installation

Depuis PyPI (recommandé)

pip install yaraast

Depuis la source

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 .

Démarrage rapide

import yaraast

yara_code = """
rule example {
    strings:
        $a = "malware" nocase
    condition:
        $a
}
"""

document = yaraast.parse(yara_code)
print(document.ast.rules[0].name)

Utilisation

Interface en ligne de commande

# Analyse et affiche le YARA normalisé
yaraast parse rules.yar

# Analyse en JSON
yaraast parse rules.yar --format json

# Analyse avec un dialecte explicite
yaraast parse rules.yar --dialect yara-x

# Valide le fichier (vérifications de syntaxe + d'analyse)
yaraast validate rules.yar

# Formate le fichier en place (formateur basé sur AST)
yaraast fmt rules.yar

# Vérifie le formatage sans modifier le fichier
yaraast fmt rules.yar --check

Commandes CLI principales

Commande	Description
`parse`	Analyse un fichier de règles et génère YARA/JSON/YAML/arbre
`validate`	Valide les règles et exécute les sous-commandes de validation
`fmt`	Formateur basé sur AST (avec `--check` et `--diff`)
`format`	Formate l'entrée vers un fichier de sortie cible
`validate-syntax`	Point d'entrée de validation axé sur la syntaxe
`lsp`	Lance les fonctionnalités du Language Server Protocol

Bibliothèque Python

Analyse unifiée

from pathlib import Path

import yaraast

source = "rule example { condition: true }"

# Détection automatique du dialecte
document = yaraast.parse(source)

# Forcer un dialecte spécifique
document = yaraast.parse(source, dialect="yara")

# Analyser des fichiers, générer une nouvelle source et formater de manière canonique
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")

# Préserver chaque octet en dehors d'une modification d'octet UTF-8 explicite
offset = source.encode("utf-8").index(b"true")
rewritten = yaraast.rewrite_lossless(
    source,
    [yaraast.SourceEdit(offset, offset + 4, "false")],
)

# Les analyseurs publics appliquent des limites par défaut bornées. Remplacez-les par opération si nécessaire.
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ève ParseCancelledError

ResourceLimits() désactive explicitement toutes les limites. L'analyse CLI utilise les valeurs par défaut publiques ; l'analyse LSP utilise des limites d'entrée, de jeton, d'imbrication, de motif et de délai plus strictes et ne met jamais en cache un résultat partiel après une annulation ou un échec de limite.

Analyseur direct + visiteur

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)

Dépendances optionnelles

# Prise en charge LSP
pip install yaraast[lsp]

# Intégration libyara
pip install yaraast[libyara]

# Outils de performance
pip install yaraast[performance]

# Prise en charge de la visualisation
pip install yaraast[visualization]

# Pack de prise en charge d'exécution
pip install yaraast[all]

# Outils d'exécution et de développement
pip install yaraast[dev-all]

Documentation d'exécution

Compatibilité des dialectes : docs/compatibility.md
Internes d'exécution LSP : docs/lsp-runtime.md
Rapport de parité LSP : docs/lsp-parity-report.md
Artefact de benchmark d'exécution le plus récent : docs/benchmarks/lsp-runtime-latest.json

Prérequis

Python 3.11, 3.12, 3.13 ou 3.14
Consultez pyproject.toml pour la liste complète des dépendances et extras

Contribution

Les contributions sont les bienvenues. Consultez CONTRIBUTING.md pour la configuration, les contrôles de qualité et les directives de flux de travail.

Forkez le dépôt
Créez une branche (git checkout -b feature/your-change)
Validez les modifications (git commit -m "Add your change")
Poussez (git push origin feature/your-change)
Ouvrez une Pull Request

La politique du projet est documentée dans SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md et MIGRATING.md.

Licence

Ce projet est sous licence MIT - voir LICENSE.

Auteur

Marc Rivero ([email protected])
Dépôt : github.com/seifreed/yaraast

_{Conçu pour les flux de travail d'analyse de logiciels malveillants et d'ingénierie de détection}

Lire plus

yaraast v2.0.1rc1

Catégories