Frequently Asked Questions
This is a collection of commonly-asked "how do I do X?" questions and other general questions about angr, for those too lazy to read this whole document.
If your question is of the form "how do I fix X issue", see also the Troubleshooting section of the install instructions.
Why is it named angr?
The core of angr's analysis is on VEX IR, and when something is vexing, it makes you angry.
How should "angr" be stylized?
All lowercase, even at the beginning of sentences. It's an anti-proper noun.
How can I get diagnostic information about what angr is doing?
angr uses the standard
logging module for logging, with every package and submodule creating a new logger.
The simplest way to get debug output is the following:
import logging logging.getLogger('angr').setLevel('DEBUG')
You may want to use
INFO or whatever else instead.
By default, angr will enable logging at the
Each angr module has its own logger string, usually all the python modules above it in the hierarchy, plus itself, joined with dots.
Because of the way the python logging module works, you can set the verbosity for all submodules in a module by setting a verbosity level for the parent module.
logging.getLogger('angr.analyses').setLevel('INFO') will make the CFG, as well as all other analyses, log at the INFO level.
Why is angr so slow?
How do I find bugs using angr?
The easiest way to do this is to define a "bug condition", for example, "the instruction pointer has become a symbolic variable", and run symbolic exploration until you find a state matching that condition, then dump the input as a testcase.
However, you will quickly run into the state explosion problem.
How you address this is up to you.
Your solution may be as simple as adding an
avoid condition or as complicated as implementing CMU's MAYHEM system as an Exploration Technique.
Why did you choose VEX instead of another IR (such as LLVM, REIL, BAP, etc)?
We had two design goals in angr that influenced this choice:
- angr needed to be able to analyze binaries from multiple architectures. This mandated the use of an IR to preserve our sanity, and required the IR to support many architectures.
- We wanted to implement a binary analysis engine, not a binary lifter. Many projects start and end with the implementation of a lifter, which is a time consuming process. We needed to take something that existed and already supported the lifting of multiple architectures.
Searching around the internet, the major choices were:
- LLVM is an obvious first candidate, but lifting binary code to LLVM cleanly is a pain. The two solutions are either lifting to LLVM through QEMU, which is hackish (and the only implementation of it seems very tightly integrated into S2E), or mcsema, which only supports x86.
- TCG is QEMU's IR, but extracting it seems very daunting as well and documentation is very scarse.
- REIL seems promising, but there is no standard reference implementation that supports all the architectures that we wanted. It seems like a nice academic work, but to use it, we would have to implement our own lifters, which we wanted to avoid.
- BAP was another possibility. When we started work on angr, BAP only supported lifting x86 code, and up-do-date versions of BAP were only available to academic collaborators of the BAP authors. These were two deal-breakers. BAP has since become open, but it still only supports x86_64, x86, and ARM.
- VEX was the only choice that offered an open library and support for many architectures. As a bonus, it is very well documented and designed specifically for program analysis, making it very easy to use in angr.
While angr uses VEX now, there's no fundamental reason that multiple IRs cannot be used. There are two parts of angr, outside of the
angr.engines.vex package, that are VEX-specific:
- the jump lables (i.e., the
Ijk_Callfor calls, and so forth) are VEX enums.
- VEX treats registers as a memory space, and so does angr. While we provide accesses to
state.regs.raxand friends, on the backend, this does
state.registers.load(8, 8), where the first
8is a VEX-defined offset for
raxto the register file.
To support multiple IRs, we'll either want to abstract these things or translate their labels to VEX analogues.
My load options are ignored when creating a Project.
CLE options are an optional argument. Make sure you call Project with the following syntax:
b = angr.Project('/bin/true', load_options=load_options)
b = angr.Project('/bin/true', load_options)
Why are some ARM addresses off-by-one?
In order to encode THUMB-ness of an ARM code address, we set the lowest bit to one.
This convention comes from LibVEX, and is not entirely our choice!
If you see an odd ARM address, that just means the code at
address - 1 is in THUMB mode.
How do I serialize angr objects?
Pickle will work.
However, python will default to using an extremely old pickle protocol that does not support more complex python data structures, so you must specify a more advanced data stream format.
The easiest way to do this is
UnsupportedIROpError("floating point support disabled") mean?
This might crop up if you're using a CGC analysis such as driller or rex. Floating point support in angr has been disabled in the CGC analyses for a tight-knit nebula of reasons:
- Libvex's representation of floating point numbers is imprecise - it converts the 80-bit extended precision format used by the x87 for computation to 64-bit doubles, making it impossible to get precise results
- There is very limited implementation support in angr for the actual primitive operations themselves as reported by libvex, so you will often get a less friendly "unsupported operation" error if you go too much further
- For what operations are implemented, the basic optimizations that allow tractability during symbolic computation (AST deduplication, operation collapsing) are not implemented for floating point ops, leading to gigantic ASTs
- There are memory corruption bugs in z3 that get triggered frighteningly easily when you're using huge workloads of mixed floating point and bitvector ops. We haven't been able to get a testcase that doesn't involve "just run angr" for the z3 guys to investigate.
Instead of trying to cope with all of these, we have simply disabled floating point support in the symbolic execution engine. To allow for execution in the presence of floating point ops, we have enabled an exploration technique called the https://github.com/angr/angr/blob/master/angr/exploration_techniques/oppologist.py that is supposed to catch these issues, concretize their inputs, and run the problematic instructions through qemu via uniciorn engine, allowing execution to continue. The intuition is that the specific values of floating point operations don't typically affect the exploitation process.
If you're seeing this error and it's terminating the analysis, it's probably because you don't have unicorn installed or configured correctly. If you're seeing this issue just in a log somewhere, it's just the oppologist kicking in and you have nothing to worry about.