yaraast

Parse, analyze, and transform YARA rules with a Python AST toolkit

Overview

yaraast is a Python library for parsing and manipulating YARA-family rules using Abstract Syntax Trees (AST). It supports classic YARA, YARA-L, and YARA-X workflows with automatic dialect detection and CLI tooling.

Key Features

Supported Rule Ecosystem

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

Support levels differ by dialect. Classic YARA is stable, YARA-X is beta, YARA-L is experimental, and automatic dialect detection is best effort. See the compatibility matrix for the exact engines and capabilities exercised by CI.

Installation

From PyPI (Recommended)

pip install yaraast

From 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 .

Quick Start

import yaraast

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

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

Usage

Command Line Interface

# Parse and print normalized YARA
yaraast parse rules.yar

# Parse to JSON
yaraast parse rules.yar --format json

# Parse with explicit dialect
yaraast parse rules.yar --dialect yara-x

# Validate file (syntax + parse checks)
yaraast validate rules.yar

# Format file in-place (AST-based formatter)
yaraast fmt rules.yar

# Check formatting without modifying file
yaraast fmt rules.yar --check

Core CLI Commands

Python Library

Unified Parsing

from pathlib import Path

import yaraast

source = "rule example { condition: true }"

# Auto-detect dialect
ast = yaraast.parse(source)

# Force specific dialect
ast = yaraast.parse(source, dialect="yara")

# Parse files, generate new source, and format canonically
Path("rules.yar").write_text(source, encoding="utf-8")
file_ast = yaraast.parse_file("rules.yar")
generated = yaraast.generate(file_ast, dialect="yara")
formatted = yaraast.format_canonical(source, dialect="yara")

# Preserve every byte outside an explicit UTF-8 byte edit
offset = source.encode("utf-8").index(b"true")
rewritten = yaraast.rewrite_lossless(
    source,
    [yaraast.SourceEdit(offset, offset + 4, "false")],
)

# Public parsers apply bounded defaults. Override them per operation when needed.
limits = yaraast.ResourceLimits(max_input_bytes=1024 * 1024, parse_deadline=5.0)
ast = yaraast.parse(source, resource_limits=limits)

cancel = yaraast.CancellationToken()
cancel.cancel()
# yaraast.parse(source, cancellation_token=cancel) raises ParseCancelledError

ResourceLimits() disables all bounds explicitly. CLI parsing uses the public defaults; LSP parsing uses tighter input, token, nesting, pattern, and deadline limits and never caches a partial result after cancellation or a limit failure.

Direct Parser + Visitor

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)

Optional Dependencies

# LSP support
pip install yaraast[lsp]

# libyara integration
pip install yaraast[libyara]

# Performance tooling
pip install yaraast[performance]

# Visualization support
pip install yaraast[visualization]

# Everything
pip install yaraast[all]

Runtime Docs

• Dialect compatibility: docs/compatibility.md
• LSP runtime internals: docs/lsp-runtime.md
• LSP parity report: docs/lsp-parity-report.md
• Latest runtime benchmark artifact: docs/benchmarks/lsp-runtime-latest.json

Requirements

• Python 3.11, 3.12, 3.13, or 3.14
• See pyproject.toml for full dependency and extras list

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, quality checks, and workflow guidelines.

1. Fork the repository
2. Create a branch (git checkout -b feature/your-change)
3. Commit changes (git commit -m "Add your change")
4. Push (git push origin feature/your-change)
5. Open a Pull Request

Project policy is documented in SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md, and MIGRATING.md.

License

This project is licensed under the MIT License - see LICENSE.

Author

• Marc Rivero (mriverolopez@gmail.com)
• Repository: github.com/seifreed/yaraast

_{Built for malware analysis and detection engineering workflows}