{"id":18925286,"url":"https://github.com/s2e/s2e-env","last_synced_at":"2025-04-15T01:29:22.234Z","repository":{"id":38391154,"uuid":"87578023","full_name":"S2E/s2e-env","owner":"S2E","description":"Your S2E project management tools. Visit https://s2e.systems/docs to get started.","archived":false,"fork":false,"pushed_at":"2024-04-13T18:49:04.000Z","size":1032,"stargazers_count":90,"open_issues_count":130,"forks_count":52,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-04-14T08:54:54.606Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/S2E.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"vitalych","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2017-04-07T19:01:34.000Z","updated_at":"2024-04-20T16:49:38.392Z","dependencies_parsed_at":"2024-03-17T12:35:18.477Z","dependency_job_id":"2652406a-ff3e-4301-8e55-657bf93885e6","html_url":"https://github.com/S2E/s2e-env","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fs2e-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fs2e-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fs2e-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fs2e-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/S2E","download_url":"https://codeload.github.com/S2E/s2e-env/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248988537,"owners_count":21194443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T11:10:29.340Z","updated_at":"2025-04-15T01:29:22.209Z","avatar_url":"https://github.com/S2E.png","language":"Python","funding_links":["https://github.com/sponsors/vitalych"],"categories":[],"sub_categories":[],"readme":"# `s2e-env`\n\nA command-line tool for creating and administering isolated development\nenvironments for [S2E](http://s2e.systems). Each environment contains all the\ntools required to run S2E plus one or more \"projects\". A project is essentially\nan analysis target. For example, one project might be the analysis of a [CGC\nbinary](https://github.com/CyberGrandChallenge/samples), while another project\nmight be the analysis of the ``file`` program from\n[Coreutils](https://www.gnu.org/software/coreutils/coreutils.html).\n\n# Prerequisites\n\nWe assume that you are working on an Ubuntu 18.04 LTS 64-bit OS.\nYou will need the following packages:\n\n```console\n$ sudo apt-get install git gcc python3 python3-dev python3-venv\n```\n\nSome commands (such as basic block coverage) require a disassembler. Supported\ndisassemblers include:\n\n* [IDA Pro](https://www.hex-rays.com/products/ida/)\n* [Radare](https://rada.re/). Requires\n  [r2pipe](https://pypi.python.org/pypi/r2pipe)\n* [Binary Ninja](https://binary.ninja/). Requires GUI-less processing\n\n# Install\n\nWe recommend installing ``s2e-env`` into a virtual environment.\n\n```console\ngit clone https://github.com/S2E/s2e-env.git\ncd s2e-env\npython3 -m venv venv\n. venv/bin/activate\npip install .\n\n# Note: if you use pip earlier than version 19, you must add --process-dependency-links:\npip install . --process-dependency-links\n```\n\n# Tests\n\nRun tests with the following command:\n\n```console\n$ ./test.sh\n```\n\nThis will create a fresh virtual environment ``venv-test``, install all requirements,\nrun pylint, the tests, and record coverage.\n\n# Configuring\n\n`s2e-env` is configurable in two ways. Firstly, there is a global YAML\nconfiguration file located in `s2e_env/dat/config.yaml`. This configuration\nfile controls how *all* environments are created. You are not normally required\nto modify the settings in this file. If you wish to customize how environments\nare created, you should edit this file **before** running `pip install` to\ninstall `s2e-env`.\n\nFor example, you may want to clone the S2E source repos via SSH rather than\nHTTPS, in which case you would set the `repos`, `url` option to\n`git@github.com:S2E`.\n\nA second YAML configuration file, `s2e.yaml`, is created in each S2E\nenvironment. This contains settings that are local to each S2E environment. For\nexample, if you want to generate basic block coverage, you will also have to\nset the `ida`, `path` option.\n\n# Usage\n\nThe package can be installed via `pip`, thus making the `s2e` command\navailable.\n\nTo list the available commands:\n\n```\ns2e help --commands\n```\n\nTo get help on a particular command:\n\n```\ns2e \u003csubcommand\u003e --help\n```\n\nMost commands use the `S2EDIR` environment variable so that commands can be run\nfrom any directory. `S2EDIR` can be set by sourcing `s2e_activate` in your\nenvironment directory. Sourcing this file also makes `s2e_deactivate`\navailable, which unsets the S2E environment variables.\n\nAlternatively, most commands take an optional `--env /path/to/env` argument.\nThis argument can be used to specify the path to the S2E environment you want\nto execute the command in.\n\nNote that **one of** the `S2EDIR` environment variable or `--env` option\n**must** be used.\n\n## Workflow\n\nEach command follows the Unix philosophy that each command (\"tool\") consists of\na small program designed to accomplish a single, particular task, rather than\ntrying to develop monolithic commands to do a number of tasks.\n\nA typical workflow is therefore:\n\n1. Run `s2e init $DIR` to create a new S2E environment in `$DIR`. This will\n   create the environment, install dependencies (unless `--skip-dependencies`\n   is used) and fetch all of the S2E engine code.\n2. Activate the environment via `. $DIR/s2e_activate`.\n3. Look around the source code, make some modifications, etc. Then when you are\n   ready to build run `s2e build`.\n4. You'll need some images to analyze your software in! See what images are\n   available with `s2e image_build`.\n5. Run `s2e image_build $TEMPLATE` to build one of the images listed in the\n   previous step. This will create the image in the `images` directory.\n6. Use `s2e new_project` to create a new analysis project. This will create all\n   the launch scripts, configuration files and bootstrap scripts necessary to\n   perform the analysis on a given target. Currently Linux ELF executables,\n   Decree CGC binaries, Windows PE executables and Windows DLLs can be\n   targeted with the `new_project` command.\n7. Change into the project directory and run the S2E analysis with the\n   `launch-s2e.sh` script.\n8. After your analysis has finished, a number of subcommands exist to analyze\n   and summarize your results, e.g. the ``coverage`` and ``execution_trace``\n   subcommands.\n\nOther useful commands:\n\n* `s2e info` can be used to display a summary of the S2E environment.\n* To download the latest changes from the git repositories, run `s2e update`.\n* Projects can be shared using `s2e export_project` and `s2e import_project`.\n\n## Environment structure\n\n`s2e init` generates the following directory structure in your S2E environment.\n\n```\n.\n├── build/\n├── images/\n├── install/\n├── projects/\n├── s2e.yaml\n├── source/\n```\n\n* `build`: Staging directory for builds\n* `images`: Images created with `s2e image_build` go here\n* `install`: Installed executables, libraries, header files, etc.\n* `projects`: Analysis projects created with `s2e new_project` go here\n* `s2e.yaml`: A per-environment configuration file. This file is also used to\n  \"mark\" the directory as an S2E environment, so please do not delete it!\n* `source`: Source code repositories\n\n# Extending\n\nExtending with new commands is relatively simple. `s2e-env` is heavily\ninfluenced by [Django's](https://github.com/django/django) command subsystem,\nso there is a wealth of documentation already available (for example,\n[here](https://docs.djangoproject.com/en/1.10/howto/custom-management-commands/)).\n\nFor example, to create a command `foo`:\n\n1. Create a new Python module `s2e_env/commands/foo.py`\n2. In `foo.py` define a `Command` class that extends\n    * `s2e_env.command.BaseCommand` - The base class. Probably not that useful\n      to inherit directly from this class\n    * `s2e_env.command.EnvCommand` - For commands that operate on an existing\n      S2E environment\n    * `s2e_env.command.ProjectCommand` - For commands that operate on an\n      existing analysis project\n3. The only method required in your `Command` class is\n  `handle(self, *args, **options)`. This method contains your command logic\n4. You may optionally define an `add_arguments(self, parser)` method for\n   parsing command-line arguments specific to the `foo` command. The `parser`\n   argument is essentially an `ArgumentParser` from the\n   [argparse](https://docs.python.org/3/library/argparse.html) library.\n   \n   If you extend from `EnvCommand` you **must** call the super `add_arguments`,\n   i.e.:\n\n   ```python\n   def add_arguments(self, parser):\n       super(Command, self).add_arguments(parser)\n       # Add your arguments/options here\n   ```\n\n5. On error, an `s2e_env.command.CommandError` should be raised\n6. Use the `logging` module for printing messages. When calling\n   `logging.getLogger` the command name should be provided as the logger name.\n\n# Running commands from your code\n\nLike Django's command subsystem (see\n[here](https://docs.djangoproject.com/en/1.10/ref/django-admin/#running-management-commands-from-your-code)),\n`s2e-env` also allows you to call commands programatically\nvia the `call_command` function.\n\nExample:\n\n```python\nfrom s2e_env.commands.new_project import Command as NewProjectCommand\nfrom s2e_env.manage import call_command\n\n\ndef create_s2e_project(target_path, s2e_env_path):\n    call_command(NewProjectCommand(), target_path, env=s2e_env_path, force=True)\n```\n\n## Custom projects\n\nOccasionally the default analysis projects (e.g., Windows driver, Linux\napplication, etc.) may not meet your requirements. In these cases, a custom\nproject may be created by extending the\n`s2e_env.commands.project_creation.abstract_project.AbstractProject` class.\nThis child class **must** implement the following methods:\n\n - `_configure`: Generates a configuration dictionary that describes the\n   project. The contents of this dictionary are up to the user; and\n - `_create`: Creates the actual project on disk. This should including,\n   making the project directory, and creating the files necessary to run the\n   project in this project directory. The project creation is guided by the\n   configuration dictionary generated in `_make_config`. The path to the\n   project should be returned from this method.\n\nOptionally, the child class may also implement:\n\n - `_get_instructions`: Return a string that is displayed to the user upon\n   successful creation of a project; and\n - `_is_valid_image`: If an image is not specified, this method is used as a\n   predicate when automatically selecting an image.\n\nCurrently, custom projects can only be used programmatically as follows:\n\n```python\nimport os\n\nfrom s2e_env.commands.new_project import Command as NewProjectCommand\nfrom s2e_env.commands.project_creation import AbstractProject\nfrom s2e_env.manage import call_command\n\n\nclass MyProject(AbstractProject):\n    def _configure(self, target, *args, **kwargs):\n        return dict(project_dir='/path/to/my/project')\n\n    def _create(self, config, force=False):\n        os.mkdir(config['project_dir'])\n\n        return config['project_dir']\n\n    def _get_instructions(self, config):\n        return 'Your project has been successfully created in %s' % config['project_dir']\n\n\ncall_command(NewProjectCommand(), env='/path/to/s2e', project_class=MyProject)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs2e%2Fs2e-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs2e%2Fs2e-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs2e%2Fs2e-env/lists"}