Quickstart

Get started with angr and run your first binary analysis

This guide will help you install angr and run your first binary analysis in minutes.

Installation

The quickest way to install angr is using pip with a virtual environment:

1. Create a virtual environment

   Create and activate a Python virtual environment:

   python -m venv angr-env
   source angr-env/bin/activate  # On Windows: angr-env\Scripts\activate
   

   Using a virtual environment prevents package conflicts with other Python projects.
2. Install angr

   Install angr using pip:

   pip install angr
   

   This will install angr and all its required dependencies. The installation may take a few minutes.

3. Verify installation

   Test that angr is installed correctly:

   python -c "import angr; print(angr.__version__)"
   

   You should see the version number printed (e.g., 9.2.205.dev0).

Your first angr script

Let’s start by loading a binary and exploring its basic properties.

Load a binary

Create a new Python file called analyze.py:

import angr

# Load a binary (replace with your own binary path)
project = angr.Project('/bin/ls', auto_load_libs=False)

print(f"Architecture: {project.arch}")
print(f"Entry point: {hex(project.entry)}")
print(f"Binary filename: {project.filename}")

Run it:

python analyze.py

The auto_load_libs=False parameter tells angr not to load shared libraries, which speeds up loading for simple analysis.

Symbolic execution example

Here’s a simple example of using symbolic execution to automatically solve a CTF challenge:

import angr

# Load the binary
project = angr.Project("challenge_binary", auto_load_libs=False)

# Hook a specific address to print when reached
@project.hook(0x400844)
def print_flag(state):
    print("FLAG SHOULD BE:", state.posix.dumps(0))
    project.terminate_execution()

# Execute the program symbolically
project.execute()

This example:

1. Loads a binary challenge file
2. Hooks a specific address (0x400844) where the flag is printed
3. Automatically explores execution paths to reach that address
4. Prints the flag value when found

In an enhanced REPL like IPython, you can use tab-autocomplete on the project object to discover available methods and their docstrings.

Understanding the Project object

The angr.Project class is the main entry point for binary analysis. It provides:

• arch - Architecture information (x86, ARM, etc.)
• entry - Program entry point address
• loader - Binary loader with information about loaded objects
• factory - Factory for creating analysis states and simulation managers
• analyses - Access to all available analyses (CFG, VFG, etc.)

Interactive exploration

For interactive exploration, launch IPython or Python:

import angr

p = angr.Project('/bin/bash')

# Explore available methods with tab completion
p.<TAB>  # In IPython, press TAB to see available methods

# Get help on any method
help(p.factory.entry_state)

Basic analysis workflow

A typical angr analysis follows this pattern:

1. Load the binary

   project = angr.Project('binary_file', auto_load_libs=False)
   
2. Create an initial state

   state = project.factory.entry_state()
   
3. Create a simulation manager

   simgr = project.factory.simulation_manager(state)
   
4. Explore execution paths

   simgr.explore(find=0x400844, avoid=0x400850)
   
5. Extract results

   if simgr.found:
       solution = simgr.found[0]
       print(solution.posix.dumps(0))  # Print stdin
   

Next steps

Now that you have angr running, here’s what to explore next:

Installation Guide

Learn about advanced installation options and optional dependencies

Official Documentation

Explore comprehensive guides on symbolic execution, CFG analysis, and more

API Reference

Browse the complete API documentation

CTF Examples

See angr solve real CTF challenges

angr requires Python 3.10 or higher. If you see compatibility errors, check your Python version with python --version.