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를 참조하세요.

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

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

---

라이선스

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

저자

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

---

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