# archr
[](https://github.com/psf/black)
Traditionally, binary analysis has been implicitly _program-centric_, meaning that the atomic unit of concern is the binary being analyzed.
This assumption is usually implicit: `angr.Project` is instantiated with the binary in question, `afl` launches the binary itself, generally hyper-modified to make it easier to fuzz, and so on.
However, outside of the CGC, programs do not exist in a vacuum.
Specific library versions, values in configuration files, environment variables, and a myriad other factors combine with the program binary itself to make a unique holistic _target_, and in many cases, it is that target that needs to be analyzed, not just the program itself.
This is specifically true for analysis that need extreme accuracy, such as automatic exploit generation.
`archr` is an implementation of such a _target-centric_ analysis paradigm.
It consists of two main concepts: `Targets`, which describe the specification of the target itself, how it is configured, how it will be launched, and how it would be interacted with, and `Analyzers`, which specialize targets for specific analysis actions, such as tracing, symbolic execution, and so on.
To accomplish their tasks, Analyzers might inject `Implants` (i.e., qemu-user, gdbserver, and so on) into the target.
We have the following Targets:
* DockerImageTarget, which takes a description of the target in the form of a docker image
* LocalTarget, which just describes running the target in the local system
The following Analyzers exist:
- DataScoutAnalyzer (will grabs the memory map, environment, and auxv of the process, exactly as it is at launch)
- AngrProjectAnalyzer (can create an angr project with the right libs at the right offsets)
- AngrStateAnalyzer (can create a angr states with the right env, args, and fs)
- QEMUTraceAnalyzer (does qemu tracing of the target)
- GDBServerAnalyzer (launches the target in a gdbserver)
- STraceAnalyzer (straces a target)
- CoreAnalyzer (launches the target and retrieves a core)
- InputFDAnalyzer (determines the FD number for user input (in some cases))
## Using archr
To use archr, one must first create a Target.
First, build a docker image that launches your target.
Here is an example dockerfile for a `docker-cat` image:
```
from ubuntu:latest
entrypoint ["/bin/cat"]
```
Then, load it as a target:
```
import archr
t = archr.targets.DockerImageTarget('docker-cat').build()
```
And _viola!_, your target is ready to use.
archr will automatically figure out how your binary runs inside your target, and then you can launch and interact with it:
```
t.start()
assert t.run_command(stdin=subprocess.DEVNULL).wait() == 0
t.stop()
```
archr makes heavy use of `with` contexts, which will help clean up resources.
Embrace them.
For example, you can:
```
with t.start():
with t.run_context() as p:
print(p,"is a subprocess.Popen object!")
p.stdin.write("hello")
assert p.stdout.read(5) == "hello"
```
There is even a context that will allow you to temporarily replace files on the target!
```
with t.start():
with t.replacemenet_context("/etc/passwd", "hahaha"), t.run_context(args_suffix=["/etc/passwd"]) as p:
assert p.stdout.read() == "hahaha"
assert t.run_command(args_suffix=["/etc/passwd"]).stdout.read() != "hahaha"
```
And even one that will _temporarily replace the target binary's code with shellcode_:
```
with t.start():
with t.shellcode_context(asm_code="mov rax, 60; mov rdi, 42; syscall") as p:
assert p.wait() == 42
```
You can retrieve files from the target with `retrieve_contents`, `retrieve_paths`, and `retrieve_glob`, inject files with `inject_path`, `inject_contents`, and so on, get network endpoints using `ipv4_address`, `udp_ports`, and `tcp_ports`, and some other interesting stuff!
You can also make a `LocalTarget` to just run stuff on your host, and it is almost perfectly interchange with a DockerTarget:
```
import archr
t = archr.targets.LocalTarget(["/bin/cat"]).build()
```
To figure out how to run the binary, `LocalTarget` takes at least an argv list.
You can also pass in an env.
Keep in mind that since some of the above examples need write access to files, you will need to use writable files instead of `/etc/passwd` and `/bin/cat`.
## Caveats
Some caveats at the moment:
- archr does not handle string-specified (as opposed to array-specified) entrypoint directives in the docker file.
This isn't hard; we just haven't gotten around to it (see issue #1).
Raw data
{
"_id": null,
"home_page": "https://github.com/angr/archr",
"name": "archr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/04/0a/7068dd0940864cad2dc7cf7829709873429d7263691bcace8dac01640d3d/archr-9.2.133.tar.gz",
"platform": null,
"description": "# archr\n[](https://github.com/psf/black)\n\nTraditionally, binary analysis has been implicitly _program-centric_, meaning that the atomic unit of concern is the binary being analyzed.\nThis assumption is usually implicit: `angr.Project` is instantiated with the binary in question, `afl` launches the binary itself, generally hyper-modified to make it easier to fuzz, and so on.\n\nHowever, outside of the CGC, programs do not exist in a vacuum.\nSpecific library versions, values in configuration files, environment variables, and a myriad other factors combine with the program binary itself to make a unique holistic _target_, and in many cases, it is that target that needs to be analyzed, not just the program itself.\nThis is specifically true for analysis that need extreme accuracy, such as automatic exploit generation.\n\n`archr` is an implementation of such a _target-centric_ analysis paradigm.\nIt consists of two main concepts: `Targets`, which describe the specification of the target itself, how it is configured, how it will be launched, and how it would be interacted with, and `Analyzers`, which specialize targets for specific analysis actions, such as tracing, symbolic execution, and so on.\nTo accomplish their tasks, Analyzers might inject `Implants` (i.e., qemu-user, gdbserver, and so on) into the target.\n\nWe have the following Targets:\n\n* DockerImageTarget, which takes a description of the target in the form of a docker image\n* LocalTarget, which just describes running the target in the local system\n\nThe following Analyzers exist:\n\n- DataScoutAnalyzer (will grabs the memory map, environment, and auxv of the process, exactly as it is at launch)\n- AngrProjectAnalyzer (can create an angr project with the right libs at the right offsets)\n- AngrStateAnalyzer (can create a angr states with the right env, args, and fs)\n- QEMUTraceAnalyzer (does qemu tracing of the target)\n- GDBServerAnalyzer (launches the target in a gdbserver)\n- STraceAnalyzer (straces a target)\n- CoreAnalyzer (launches the target and retrieves a core)\n- InputFDAnalyzer (determines the FD number for user input (in some cases))\n\n## Using archr\n\nTo use archr, one must first create a Target.\nFirst, build a docker image that launches your target.\nHere is an example dockerfile for a `docker-cat` image:\n\n```\nfrom ubuntu:latest\nentrypoint [\"/bin/cat\"]\n```\n\nThen, load it as a target:\n\n```\nimport archr\nt = archr.targets.DockerImageTarget('docker-cat').build()\n```\n\nAnd _viola!_, your target is ready to use.\narchr will automatically figure out how your binary runs inside your target, and then you can launch and interact with it:\n\n```\nt.start()\nassert t.run_command(stdin=subprocess.DEVNULL).wait() == 0\nt.stop()\n```\n\narchr makes heavy use of `with` contexts, which will help clean up resources.\nEmbrace them.\nFor example, you can:\n\n```\nwith t.start():\n\twith t.run_context() as p:\n\t\tprint(p,\"is a subprocess.Popen object!\")\n\t\tp.stdin.write(\"hello\")\n\t\tassert p.stdout.read(5) == \"hello\"\n```\n\nThere is even a context that will allow you to temporarily replace files on the target!\n\n```\nwith t.start():\n\twith t.replacemenet_context(\"/etc/passwd\", \"hahaha\"), t.run_context(args_suffix=[\"/etc/passwd\"]) as p:\n\t\tassert p.stdout.read() == \"hahaha\"\n\tassert t.run_command(args_suffix=[\"/etc/passwd\"]).stdout.read() != \"hahaha\"\n```\n\nAnd even one that will _temporarily replace the target binary's code with shellcode_:\n\n```\nwith t.start():\n\twith t.shellcode_context(asm_code=\"mov rax, 60; mov rdi, 42; syscall\") as p:\n\t\tassert p.wait() == 42\n```\n\nYou can retrieve files from the target with `retrieve_contents`, `retrieve_paths`, and `retrieve_glob`, inject files with `inject_path`, `inject_contents`, and so on, get network endpoints using `ipv4_address`, `udp_ports`, and `tcp_ports`, and some other interesting stuff!\nYou can also make a `LocalTarget` to just run stuff on your host, and it is almost perfectly interchange with a DockerTarget:\n\n```\nimport archr\nt = archr.targets.LocalTarget([\"/bin/cat\"]).build()\n```\n\nTo figure out how to run the binary, `LocalTarget` takes at least an argv list.\nYou can also pass in an env.\n\nKeep in mind that since some of the above examples need write access to files, you will need to use writable files instead of `/etc/passwd` and `/bin/cat`.\n\n## Caveats\n\nSome caveats at the moment:\n\n- archr does not handle string-specified (as opposed to array-specified) entrypoint directives in the docker file.\n This isn't hard; we just haven't gotten around to it (see issue #1).\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "Target-centric program analysis.",
"version": "9.2.133",
"project_urls": {
"Homepage": "https://github.com/angr/archr"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c300163ab7d5492bdf539e0f6096b056a3da854d7519c4c20f6033a957bf642",
"md5": "e770605eb15fe70a83eef2c535cc7514",
"sha256": "eb1d79d72c9573ea748c6faf2b248b803390ec205f2653f1b0845a6bbd9a8df9"
},
"downloads": -1,
"filename": "archr-9.2.133-py3-none-manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "e770605eb15fe70a83eef2c535cc7514",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 67726,
"upload_time": "2024-12-17T17:26:13",
"upload_time_iso_8601": "2024-12-17T17:26:13.947170Z",
"url": "https://files.pythonhosted.org/packages/4c/30/0163ab7d5492bdf539e0f6096b056a3da854d7519c4c20f6033a957bf642/archr-9.2.133-py3-none-manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "040a7068dd0940864cad2dc7cf7829709873429d7263691bcace8dac01640d3d",
"md5": "cef409f398237b09507094c707aff36c",
"sha256": "420281289fb42d26c75deff65fddb087e936b837f3edce38d4a3739798075938"
},
"downloads": -1,
"filename": "archr-9.2.133.tar.gz",
"has_sig": false,
"md5_digest": "cef409f398237b09507094c707aff36c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 58661,
"upload_time": "2024-12-17T17:26:45",
"upload_time_iso_8601": "2024-12-17T17:26:45.789697Z",
"url": "https://files.pythonhosted.org/packages/04/0a/7068dd0940864cad2dc7cf7829709873429d7263691bcace8dac01640d3d/archr-9.2.133.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 17:26:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "angr",
"github_project": "archr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "archr"
}
JSON
