Skip to main content

Target-centric program analysis.

Project description

archr

Code style: 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).

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

archr-9.2.163-py3-none-manylinux2014_x86_64.whl (67.8 kB view details)

Uploaded Python 3

File details

Details for the file archr-9.2.163-py3-none-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for archr-9.2.163-py3-none-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 5dc2251243dc0bd0484a1fbd9e6c009b022882f9c8dc023aabb1691186a4afac
MD5 d86ade3d26585038fd3b617b12e46221
BLAKE2b-256 e88f2d0a6311e2037c293cc772beb9306f204fd6ed32306b224ed52436746838

See more details on using hashes here.

Provenance

The following attestation bundles were made for archr-9.2.163-py3-none-manylinux2014_x86_64.whl:

Publisher: angr-release.yml on angr/ci-settings

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page