README ¶
bincapz
Enumerates program capabilities and malicious behaviors using fragment analysis.
Features
- Analyzes binaries from any architecture - arm64, amd64, riscv, ppc64, sparc64
- Supports scripting languages such as bash, PHP, Perl, Ruby, NodeJS, and Python
- Supports OCI images and archives
- Integrates YARA forge for rules by Avast, Elastic, FireEye, Google, Nextron, and others.
- 12,000+ rules that detect everything from ioctl's to malware
- Tuned for especially excellent performance with Linux programs
- Diff-friendly output in Markdown, JSON, YAML outputs
- CI/CD friendly
Shortcomings
- Minimal rule support for Windows and Java (help wanted!)
- Early in development; output is subject to change
Requirements
A container runtime environment such as Podman or Docker, or local developer tools:
- go 1.21+
- pkg-config - included in many UNIX distributions
- yara
Installation
Containerized
docker pull cgr.dev/chainguard/bincapz:latest
Local
Install YARA (dependency):
brew install yara || sudo apt install libyara-dev \
|| sudo dnf install yara-devel || sudo pacman -S yara
Install bincapz:
go install github.com/chainguard-dev/bincapz@latest
Usage
To inspect a binary, pass it as an argument to dump a list of predicted capabilities:
bincapz /bin/ping
There 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-level=3
, which shows only "HIGH" or "CRITICAL" behaviors.
Diff mode to detect supply-chain attacks
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.dylib
Here is a result using the 3CX compromise as a test case. Each of the lines that beginsl with a "+" represent a newly added capability.
Changed: . [⚠️ MEDIUM → 🚨 CRITICAL]
20 new behaviors
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'
Supported Flags
--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--format
string: Output type. Valid values are: json, markdown, simple, terminal, yaml (default "terminal")--ignore-tags
string: Rule tags to ignore--min-level
: minimum suspicion level to report (1=low, 2=medium, 3=high, 4=critical) (default 1)--oci
: scan OCI images--omit-empty
: omit files that contain no matches--stats
: display statistics for risk level andprogramkind
--third-party
: include third-party rules, which may have licensing restrictions (default true)
FAQ
How does it work?
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 12,000+ 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.
Why not properly reverse-engineer binaries?
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.
Why not just observe binaries in a sandbox?
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.
Why not just analyze the source code?
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
.
How does bincapz work for packed binaries (UPX)?
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.
What related software is out there?
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.
How can I help?
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.
Troubleshooting
Error: ld: library 'yara' not found
If you get this error at installation:
ld: library 'yara' not found
You'll need to install the yara
C library:
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.
MacOS: bincapz
will damage your computer
The Rules from https://github.com/mthcht/ThreatHunting-Keywords-yara-rules will set off macOS' malware protections.
In order to compile the rules from this project there are a couple of options:
- Run
bincapz
by pulling the official imagedocker pull cgr.dev/chainguard/bincapz:latest
- Run a Linux container or VM of choice and install
bincapz
and its dependencies
Disabling macOS' System Integrity Protection via csrutil
to run bincapz
with --third-party
is not recommended.