A command-line tool for creating and administering isolated development
environments for S2E. Each environment contains all the
tools required to run S2E plus one or more "projects". A project is essentially
an analysis target. For example, one project might be the analysis of a CGC
binary, while another project
might be the analysis of the
file program from
We assume that you are working on an Ubuntu 14.04 or 16.04 64-bit OS.
Repo only works with Python 2.7, so you
should use Python 2.7 too. You will also need
Some commands (such as basic block coverage) require a disassembler. Supported disassemblers include:
git clone https://github.com/S2E/s2e-env.git cd s2e-env pip install . # Note: if you use pip earlier than version 19, you must add --process-dependency-links: pip install . --process-dependency-links
If you wish to install
s2e-env to a Python
please create and activate this virtualenv before installing
Tests can be run via
python setup.py test
s2e-env is configurable in two ways. Firstly, there is a global YAML
configuration file located in
s2e_env/dat/config.yaml. This configuration
file controls how all environments are created. You are not normally required
to modify the settings in this file. If you wish to customize how environments
are created, you should edit this file before running
pip install to
For example, you may want to clone the S2E source repos via SSH rather than
HTTPS, in which case you would set the
url option to
A second YAML configuration file,
s2e.yaml, is created in each S2E
environment. This contains settings that are local to each S2E environment. For
example, if you want to generate basic block coverage, you will also have to
The package can be installed via
pip, thus making the
To list the available commands:
s2e help --commands
To get help on a particular command:
s2e <subcommand> --help
Most commands use the
S2EDIR environment variable so that commands can be run
from any directory.
S2EDIR can be set by sourcing
s2e_activate in your
environment directory. Sourcing this file also makes
available, which unsets the S2E environment variables.
Alternatively, most commands take an optional
--env /path/to/env argument.
This argument can be used to specify the path to the S2E environment you want
to execute the command in.
Note that one of the
S2EDIR environment variable or
must be used.
Each command follows the Unix philosophy that each command ("tool") consists of a small program designed to accomplish a single, particular task, rather than trying to develop monolithic commands to do a number of tasks.
A typical workflow is therefore:
s2e init $DIRto create a new S2E environment in
$DIR. This will create the environment, install dependencies (unless
--skip-dependenciesis used) and fetch all of the S2E engine code.
- Activate the environment via
- Look around the source code, make some modifications, etc. Then when you are
ready to build run
- You'll need some images to analyze your software in! See what images are
s2e image_build $TEMPLATEto build one of the images listed in the previous step. This will create the image in the
s2e new_projectto create a new analysis project. This will create all the launch scripts, configuration files and bootstrap scripts necessary to perform the analysis on a given target. Currently Linux ELF executables, Decree CGC binaries, Windows PE executables and Windows DLLs can be targeted with the
- Change into the project directory and run the S2E analysis with the
- After your analysis has finished, a number of subcommands exist to analyze
and summarize your results, e.g. the
Other useful commands:
s2e infocan be used to display a summary of the S2E environment.
- To download the latest changes from the git repositories, run
- Projects can be shared using
s2e init generates the following directory structure in your S2E environment.
. ├── build/ ├── images/ ├── install/ ├── projects/ ├── s2e.yaml ├── source/
build: Staging directory for builds
images: Images created with
s2e image_buildgo here
install: Installed executables, libraries, header files, etc.
projects: Analysis projects created with
s2e new_projectgo here
s2e.yaml: A per-environment configuration file. This file is also used to "mark" the directory as an S2E environment, so please do not delete it!
source: Source code repositories
For example, to create a command
Create a new Python module
Commandclass that extends
s2e_env.command.BaseCommand- The base class. Probably not that useful to inherit directly from this class
s2e_env.command.EnvCommand- For commands that operate on an existing S2E environment
s2e_env.command.ProjectCommand- For commands that operate on an existing analysis project
The only method required in your
handle(self, *args, **options). This method contains your command logic
You may optionally define an
add_arguments(self, parser)method for parsing command-line arguments specific to the
parserargument is essentially an
ArgumentParserfrom the argparse library.
If you extend from
EnvCommandyou must call the super
def add_arguments(self, parser): super(Command, self).add_arguments(parser) # Add your arguments/options here
On error, an
s2e_env.command.CommandErrorshould be raised
loggingmodule for printing messages. When calling
logging.getLoggerthe command name should be provided as the logger name.
Running commands from your code
Like Django's command subsystem (see
s2e-env also allows you to call commands programatically
from s2e_env.commands.new_project import Command as NewProjectCommand from s2e_env.manage import call_command def create_s2e_project(target_path, s2e_env_path): call_command(NewProjectCommand(), target_path, env=s2e_env_path, force=True)
Occasionally the default analysis projects (e.g., Windows driver, Linux
application, etc.) may not meet your requirements. In these cases, a custom
project may be created by extending the
This child class must implement the following methods:
_configure: Generates a configuration dictionary that describes the project. The contents of this dictionary are up to the user; and
_create: Creates the actual project on disk. This should including, making the project directory, and creating the files necessary to run the project in this project directory. The project creation is guided by the configuration dictionary generated in
_make_config. The path to the project should be returned from this method.
Optionally, the child class may also implement:
_get_instructions: Return a string that is displayed to the user upon successful creation of a project; and
_is_valid_image: If an image is not specified, this method is used as a predicate when automatically selecting an image.
Currently, custom projects can only be used programmatically as follows:
import os from s2e_env.commands.new_project import Command as NewProjectCommand from s2e_env.commands.project_creation import AbstractProject from s2e_env.manage import call_command class MyProject(AbstractProject): def _configure(self, target, *args, **kwargs): return dict(project_dir='/path/to/my/project') def _create(self, config, force=False): os.mkdir(config['project_dir']) return config['project_dir'] def _get_instructions(self, config): return 'Your project has been successfully created in %s' % config['project_dir'] call_command(NewProjectCommand(), env='/path/to/s2e', project_class=MyProject)