Ailment: Angr Intermediate Language

9.2.158 verified Thu Apr 16 auth: no python

Ailment is the Intermediate Language (IL) used by the angr binary analysis framework. It provides a higher-level, more abstract representation of program execution than traditional assembly or micro-code, aiding in static analysis and program transformation. Currently at version 9.2.158, it is actively maintained as a core component of the angr ecosystem, with frequent updates tied to angr's release cadence.

pip install ailment

Common errors

error AttributeError: module 'ailment' has no attribute 'Block' ↓

cause You are trying to import AIL core classes (like Block, Statement, Expression) directly from the top-level 'ailment' package.

fix

Import these classes from their specific submodules. For example: from ailment.block import Block, from ailment.statement import Assignment, from ailment.expression import Const.

error TypeError: argument of type 'Assignment' is not iterable ↓

cause The `statements` argument for the `Block` constructor expects a list of statement objects, even if there's only one statement.

fix

Wrap your single statement in a list: Block(addr, size, [my_statement]).

error AttributeError: 'Load' object has no attribute 'addr' (or similar errors when manipulating Load/Store objects) ↓

cause Your code is likely trying to use the `Load` or `Store` objects with an API compatible with Ailment 8.x, while running on Ailment 9.x or later. In 9.x, `Load` and `Store` are expressions, not statements, and their structure changed.

fix

Refactor your code to treat Load and Store as expressions representing memory accesses within other statements (e.g., an Assignment). Consult the Ailment 9.x documentation for the updated API. You'll generally find them as the source or destination of an Assignment expression.

Warnings

breaking Ailment is tightly coupled with the angr framework. Mismatched major versions between 'ailment' and 'angr' (e.g., ailment 8.x with angr 9.x) can lead to runtime errors due to API incompatibilities. ↓

fix Always install 'angr' and 'ailment' together, preferably by running `pip install angr`, which will pull the compatible 'ailment' version as a dependency. If installing separately, ensure their major versions align.

gotcha All AIL objects (Block, Statement, Expression, etc.) are immutable after creation. Attempting to modify their attributes directly will not work or will result in unexpected behavior. ↓

fix If you need to 'modify' an AIL object, you must create a new object with the desired changes. Some AIL objects might provide `.copy()` or `.replace()` methods for convenience, but the underlying principle is immutability.

breaking The representation of memory loads and stores changed significantly in Ailment 9.x. Previously, `Load` and `Store` were standalone statements. In 9.x, they are 'expressions' representing memory access within other statements (e.g., an `Assignment`'s source or destination). ↓

fix Update your code to use `Load` and `Store` as expressions. For example, to read from memory into a register, you would use `Assignment(..., dst=Register(...), src=Load(...))` instead of a standalone `Load` statement. Consult the Ailment 9.x API documentation for the new usage patterns.

Imports

Block
wrong
```
from ailment import Block
```
correct
```
from ailment.block import Block
```
Core AIL components like Block, Statement, and Expression are located in specific submodules, not directly under the top-level 'ailment' package.
Statement
wrong
```
from ailment import Statement
```
correct
```
from ailment.statement import Statement, Assignment
```
Core AIL components like Block, Statement, and Expression are located in specific submodules, not directly under the top-level 'ailment' package.
Expression
wrong
```
from ailment import Expression
```
correct
```
from ailment.expression import Expression, Const, Register, BinaryOp
```
Core AIL components like Block, Statement, and Expression are located in specific submodules, not directly under the top-level 'ailment' package.

Quickstart

This quickstart demonstrates how to manually construct basic AIL objects: a constant expression, a register expression, an assignment statement, and finally a block containing that statement. It highlights the modular nature of AIL components and their hierarchical structure.

from ailment.expression import Const, Register
from ailment.statement import Assignment
from ailment.block import Block

# Create a 64-bit constant expression with value 0x123
constant_expr = Const(0, None, 64, 0x123)

# Create a 64-bit register expression representing RAX (offset 0 in an abstract context)
# In AIL, registers are often identified by their size and offset within a CPU context.
rax_reg = Register(0, None, 64, 0) # stmt_idx=0, ins_addr=None, size=64 bits, reg_offset=0

# Create an assignment statement: RAX = 0x123
# Arguments: stmt_idx, dst_expression, src_expression
assignment_stmt = Assignment(0, rax_reg, constant_expr)

# Create an AIL block containing the assignment statement
# Arguments: addr, size, statements (must be a list), idx (optional)
# 'addr' and 'size' are the abstract address and size of the block.
ail_block = Block(0x400000, 10, [assignment_stmt])

print(f"Created AIL Block at 0x{ail_block.addr:x}:")
print(f"  Statements: {len(ail_block.statements)}")
print(f"  First statement: {ail_block.statements[0]}")
print(f"    Destination: {ail_block.statements[0].dst}")
print(f"    Source: {ail_block.statements[0].src}")