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

Feature	Description
Multi-dialect Parsing	Parse YARA, YARA-L, and YARA-X from files or strings
Automatic Dialect Detection	Unified parser auto-detects rule dialects
AST Tooling	Build, transform, diff, and serialize ASTs
Formatting & Validation	CLI commands for parse/format/validate workflows
Streaming Support	Parse very large files with streaming mode
Ecosystem Integrations	Optional LSP and libyara-related capabilities

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
}
"""

document = yaraast.parse(yara_code)
print(document.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

Command	Description
`parse`	Parse a rule file and output YARA/JSON/YAML/tree
`validate`	Validate rules and run validation subcommands
`fmt`	AST-based formatter (with `--check` and `--diff`)
`format`	Format input into a target output file
`validate-syntax`	Syntax-focused validation entrypoint
`lsp`	Launch Language Server Protocol features

Python Library

Unified Parsing

from pathlib import Path

import yaraast

source = "rule example { condition: true }"

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

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

# Parse files, generate new source, and format canonically
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")

# 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)
document = 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]

# Runtime support bundle
pip install yaraast[all]

# Runtime and development tooling
pip install yaraast[dev-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.

Fork the repository
Create a branch (git checkout -b feature/your-change)
Commit changes (git commit -m "Add your change")
Push (git push origin feature/your-change)
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 ([email protected])
Repository: github.com/seifreed/yaraast

_{Built for malware analysis and detection engineering workflows}

yaraast v2.0.1rc1

Categories