Enumerates program capabilities and malicious behaviors using fragment analysis.
- 15,300+ rules that detect everything from
ioctls to malware - Analyzes binaries from any architecture
arm64,amd64,riscv,ppc64,sparc64
- CI/CD-friendly
- Diff-friendly output via Markdown, JSON, or YAML
- Integrates YARA forge for rules by Avast, Elastic, FireEye, Google, Nextron, and others
- Other third-party rules are also included
- Support for archives
.apk,.gem,.gz,.jar,.tar.gz,.tar.xz,.tar,.tgz, and.zip
- Support for OCI images
- Support for scripting languages such as bash, PHP, Perl, Ruby, NodeJS, and Python
- Tuned for especially excellent performance with Linux programs
- Minimal rule support for Windows and Java (help wanted!)
- Early in development; output is subject to change
A container runtime environment such as Podman or Docker, or local developer tools:
- go 1.21+
- Install via the official installer,
goenv, Homebrew, or a preferred package manager
- Install via the official installer,
- pkg-config - included in many UNIX distributions
- yara
docker pull cgr.dev/chainguard/bincapz:latest
Install YARA (dependency):
brew install yara || sudo apt install libyara-dev \
|| sudo dnf install yara-devel || sudo pacman -S yaraInstall bincapz:
go install github.com/chainguard-dev/bincapz@latestTo inspect a binary, pass it as an argument to dump a list of predicted capabilities:
bincapz /bin/pingThere are flags for controlling output (see the Usage section) and filtering out rules. Here's the --format=markdown output:
To only show output for the most suspicious behaviors, use --min-risk=high, which shows only "HIGH" or "CRITICAL" behaviors.
Let's say you are a company that is sensitive to supply-chain compromises. You want to make sure an update doesn't introduce unexpected capability changes. There's a --diff mode for that:
bincapz -diff old_ffmpeg.dylib new_ffmpeg.dylibHere is a result using the 3CX compromise as a test case. Each of the lines that beginsl with a "+" represent a newly added capability.
If you like to do things the hard way, you can also generate your own diff using JSON keys.
bincapz --format=json <file> | jq '.Files.[].Behaviors | keys'--all: ignore nothing, show all--data-files: include files that are detected to as non-program (binary or source) files--diff: show capability drift between two files--formatstring: Output type. Valid values are: json, markdown, simple, terminal, yaml (default "terminal")--ignore-self: ignore thebincapzbinary--ignore-tagsstring: Rule tags to ignore--min-file-risk- Only show results for files that meet this risk level (any,low,medium,high,critical)--min-risk: minimum suspicion level to report (any,low,medium,high,critical)--oci: scan OCI images--omit-empty: omit files that contain no matches--profile: capture profiling/tracing information forbincapz--stats: display statistics for risk level andprogramkind--third-party: include third-party rules, which may have licensing restrictions (default true)--verbose: turn on verbose output for diagnostic/troubleshooting purposes
Bincapz samples are stored in the bincapz-samples repository here due to the size of the samples. While the samples were originally stored in this repository, size became a concern and polluted the Git history making the repository difficult to pull.
The new repository is cloned when running make test and the contents of test_data are copied into the resulting samples directory. This allows for the tests to run as usual. To update sample test data, make refresh-sample-testdata will now write updated test data content to the files in test_data which can be committed.
bincapz behaves similarly to the initial triage step most security analysts use when faced with an unknown binary: a cursory strings inspection. bincapz has several advantages over human analysis: the ability to match raw byte sequences, decrypt data, and a library of 14,500+ YARA rules that combines the experience of security engineers worldwide.
This strategy works, as every program leaves traces of its capabilities in its contents, particularly on UNIX platforms. These fragments are typically libc or syscall references or error codes. Scripting languages are easier to analyze due to their cleartext nature and are also supported.
Mostly because fragment analysis is so effective. Capability analysis through reverse engineering is challenging to get right, particularly for programs that execute other programs, such as malware that executes /bin/rm. Capability analysis through reverse engineering that supports a wide array of file formats also requires significant engineering investment.
The most exciting malware only triggers when the right conditions are met. Nation-state actors, in particular, are fond of time bombs and locale detection. bincapz will enumerate the capabilities, regardless of conditions.
Sometimes you don't have it! Sometimes your CI/CD infrastructure is the source of compromise. Source-code-based capability analysis is also complicated for polyglot programs, or programs that execute external binaries, such as /bin/rm.
bincapz alerts when an obfuscated or packed binary is detected, such as those generated by upx. Fragment analysis may still work to a lesser degree. For the full story, we recommend unpacking binaries first.
bincapz was initially inspired by mandiant/capa. While capa is a fantastic tool, it only works on x86-64 binaries (ELF/PE), and does not work for macOS programs, arm64 binaries, or scripting languages. https://karambit.ai/ and https://www.reversinglabs.com/ offer capability analysis through reverse engineering as a service. If you require more than what bincapz can offer, such as Windows binary analysis, you should check them out.
If you find malware that bincapz doesn't surface suspicious behaviors for, send us a patch! All of the rules are defined in YARA format, and can be found in the rules/ folder.
In addition to contributed code, automated PRs and commits can be verified by following these steps.
bincapz can be profiled by running --profile=true. This will generate timestamped profiles in an untracked profiles directory:
bash-5.2$ ls -l profiles/ | grep -v "total" | awk '{ print $9 }'
cpu_329605000.pprof
mem_329605000.pprof
trace_329605000.out
The traces can be inspected via go tool pprof and go tool trace.
For example, the memory profile can be inspected by running:
go tool pprof -http=:8080 profiles/mem_<timestamp>.pprof
If you get this error at installation:
ld: library 'yara' not found
The yara C library is required:
brew install yara || sudo apt install libyara-devel || sudo dnf install yara-devel || sudo pacman -S yara
Additionally, ensure that Yara's version is 4.3.2.
If this version is not available via package managers, manually download the release from here and build it from source by following these steps.
Once Yara is installed, run sudo ldconfig -v to ensure that the library is loaded.