How matias-gonz/abstraktor works
Project Type and Purpose
• Abstraktor is a Rust-based CLI tool for validating distributed protocol implementations by generating enabling-preserving abstractions (EPAs).
• It is structured as a command-line orchestrator (“CLI Tool”) that invokes:
a. An LLVM-based Instrumenter to rewrite target binaries,
b. A Mallory fuzzing engine extension to collect runtime state,
c. An EPA Generator to build abstractions from the collected data.
File Structure Analysis
• Top-level Cargo.toml and src/: core Rust CLI code lives under src/
• src/main.rs – entry point and argument parsing using clap or similar.
• src/commands/ – subcommands: prepare-binary (instrument), run-mallory, generate-epas, get-targets.
• src/model/instrumentor.rs – high-level Rust API for driving LLVM instrumentation.
• llvm/ directory encapsulates the C-based instrumenter users:
• llvm/src/ and llvm/include/ – LLVM pass and runtime support.
• llvm/rustc-demangle/ – helper crate for symbol demangling.
• tests/ – integration fixtures demonstrating instrumentation workflows.
README Insights
• Describes a 4-stage workflow: annotate source, prepare-binary, run-mallory, generate-epas.
Main Architectural Components
a. Developer/Client – annotates code and invokes the CLI.
b. CLI Tool (Rust) – src/main.rs + src/commands/ modules.
c. LLVM Instrumenter – C and Rust wrapper under llvm/ + src/model/instrumentor.
d. Mallory Extension – external fuzzing engine invoked by run-mallory command.
e. EPA Generator – part of the CLI’s generate-epas command, implemented in Rust.
f. File-system & Test harness – integration tests drive the end-to-end.
Component Relationships and Data Flow
• The Developer invokes the CLI.
• prepare-binary → CLI calls the Instrumenter module → loads and runs LLVM passes → outputs an instrumented target binary.
• run-mallory → CLI launches Mallory with the instrumented binary → Mallory fuzzes and emits runtime event logs.
• generate-epas → CLI reads event logs → EPA Generator builds and serializes abstractions.
Architectural Patterns and Design Principles
• Modular CLI subcommand pattern: clear separation of concerns by command.
• Adapter pattern: src/model/instrumentor wraps the LLVM/C code under llvm/ to present a Rust API.
• Pipeline/workflow orchestration: linear 4-stage processing, each stage pluggable.
• Test-driven integration: tests/instrument_test demonstrates real code being instrumented and validated.
Technologies and Frameworks
• Rust & Cargo – main implementation language and build system.
• LLVM C-API – real code instrumentation.
• Mallory engine – external or vendored fuzzing tool.
• clap or structopt (presumed) for CLI parsing.
• serde/json – for event log and EPA serialization (implied by expected_targets.json).
Essential Details to Capture
• Distinguish between compile-time (instrumentation) and runtime (fuzzing, EPA gen).
• Data artifacts at each stage.
• Modular CLI design and the separation of concerns in src/commands/.