yaraast

Python AST 툴킷으로 YARA 규칙을 파싱, 분석, 변환하세요

개요

yaraast는 추상 구문 트리(AST)를 사용하여 YARA 계열 규칙을 파싱하고 조작하기 위한 Python 라이브러리입니다. 자동 방언 감지와 CLI 도구를 지원하며 클래식 YARA, YARA-L, YARA-X 워크플로우를 지원합니다.

주요 기능

기능	설명
다중 방언 파싱	파일 또는 문자열에서 YARA, YARA-L, YARA-X 파싱
자동 방언 감지	통합 파서가 규칙 방언을 자동 감지
AST 도구	AST 빌드, 변환, diff, 직렬화
포맷팅 및 검증	파싱/포맷/검증 워크플로우용 CLI 명령
스트리밍 지원	스트리밍 모드로 매우 큰 파일 파싱
생태계 통합	선택적 LSP 및 libyara 관련 기능

지원되는 규칙 생태계

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

방언별 지원 수준은 다릅니다. 클래식 YARA는 안정적이며, YARA-X는 베타, YARA-L은 실험적이며, 자동 방언 감지는 최선의 노력(best effort) 방식입니다. CI에서 실행되는 정확한 엔진과 기능은 호환성 매트릭스를 참조하세요.

설치

PyPI에서 설치 (권장)

pip install yaraast

소스에서 설치

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 .

빠른 시작

import yaraast

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

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

사용법

명령줄 인터페이스

# 정규화된 YARA 파싱 및 출력
yaraast parse rules.yar

# JSON으로 파싱
yaraast parse rules.yar --format json

# 명시적 방언으로 파싱
yaraast parse rules.yar --dialect yara-x

# 파일 검증 (구문 + 파싱 검사)
yaraast validate rules.yar

# 파일을 제자리에서 포맷 (AST 기반 포맷터)
yaraast fmt rules.yar

# 파일을 수정하지 않고 포맷 확인
yaraast fmt rules.yar --check

핵심 CLI 명령

명령	설명
`parse`	규칙 파일을 파싱하고 YARA/JSON/YAML/tree 출력
`validate`	규칙 검증 및 검증 하위 명령 실행
`fmt`	AST 기반 포맷터 (`--check` 및 `--diff` 지원)
`format`	입력을 대상 출력 파일로 포맷
`validate-syntax`	구문 중심 검증 진입점
`lsp`	Language Server Protocol 기능 실행

Python 라이브러리

통합 파싱

from pathlib import Path

import yaraast

source = "rule example { condition: true }"

# 방언 자동 감지
document = yaraast.parse(source)

# 특정 방언 강제 지정
document = yaraast.parse(source, dialect="yara")

# 파일 파싱, 새 소스 생성, 표준 형식으로 포맷
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")

# 명시적 UTF-8 바이트 편집 외의 모든 바이트 보존
offset = source.encode("utf-8").index(b"true")
rewritten = yaraast.rewrite_lossless(
    source,
    [yaraast.SourceEdit(offset, offset + 4, "false")],
)

# 공개 파서는 제한된 기본값을 적용합니다. 필요 시 작업별로 재정의하세요.
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()는 모든 제한을 명시적으로 비활성화합니다. CLI 파싱은 공개 기본값을 사용하며, LSP 파싱은 더 엄격한 입력, 토큰, 중첩, 패턴, 마감 시간 제한을 사용하고 취소 또는 제한 실패 후 부분 결과를 절대 캐시하지 않습니다.

직접 파서 + 방문자

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)

선택적 종속성

# LSP 지원
pip install yaraast[lsp]

# libyara 통합
pip install yaraast[libyara]

# 성능 도구
pip install yaraast[performance]

# 시각화 지원
pip install yaraast[visualization]

# 런타임 지원 번들
pip install yaraast[all]

# 런타임 및 개발 도구
pip install yaraast[dev-all]

런타임 문서

방언 호환성: docs/compatibility.md
LSP 런타임 내부: docs/lsp-runtime.md
LSP 패리티 보고서: docs/lsp-parity-report.md
최신 런타임 벤치마크 아티팩트: docs/benchmarks/lsp-runtime-latest.json

요구 사항

Python 3.11, 3.12, 3.13 또는 3.14
전체 종속성 및 추가 목록은 pyproject.toml 참조

기여

기여를 환영합니다. 설정, 품질 검사 및 워크플로우 지침은 CONTRIBUTING.md를 참조하세요.

저장소를 포크합니다
브랜치를 생성합니다 (git checkout -b feature/your-change)
변경 사항을 커밋합니다 (git commit -m "Add your change")
푸시합니다 (git push origin feature/your-change)
Pull Request를 엽니다

프로젝트 정책은 SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md 및 MIGRATING.md에 문서화되어 있습니다.

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - LICENSE 참조.

저자

Marc Rivero ([email protected])
저장소: github.com/seifreed/yaraast

_{악성코드 분석 및 탐지 엔지니어링 워크플로우를 위해 제작됨}

yaraast v2.0.1rc1

카테고리