Skip to content

Commit 06f81a3

Browse files
tstrombergtstromberg
authored
Merge pull request #57 from tstromberg/main
Update the README to include markdown format
2 parents 0be2267 + ae20975 commit 06f81a3

File tree

2 files changed

+78
-141
lines changed

2 files changed

+78
-141
lines changed

‎README.md‎

Lines changed: 78 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,24 @@
22

33
![bincapz logo](./images/logo_small.jpg)
44

5-
Experimental tool to enumerate capabilities and detect malicious behavior within binaries through fragment analysis.
5+
Enumerates program capabilities and malicious behaviors using fragment analysis.
66

77
![screenshot](./images/screenshot.png)
88

99
## Features
1010

1111
- Analyzes binaries from any architecture - arm64, amd64, riscv, ppc64, sparc64
1212
- Supports scripting languages such as bash, PHP, Perl, Ruby, NodeJS, and Python
13-
- 12,000+ rules, for detecting everything from ioctl access to malware
14-
- Integrates [YARA forge](https://yarahq.github.io/), with rules by Avast, Elastic, FireEye, Google, Mandiant, Nextron, and more.
15-
- Diff-friendly JSON output to detect when capabilities change over time
13+
- Integrates [YARA forge](https://yarahq.github.io/) for rules by Avast, Elastic, FireEye, Google, Nextron, and others.
14+
- 12,000+ rules that detect everything from ioctl's to malware
15+
- Tuned for especially excellent performance with Linux programs
16+
- Diff-friendly output in Markdown, JSON, YAML outputs
1617
- CI/CD friendly
1718

1819
## Shortcomings
1920

20-
- This tool is in early development with unstable output
2121
- Does not attempt to process archive files (jar, zip, apk)
22-
- Minimal rule support for Windows executables (help wanted!)
22+
- Minimal rule support for Windows and Java (help wanted!)
2323

2424
## Installation
2525

@@ -35,155 +35,88 @@ To inspect a binary, pass it as an argument to dump a list of predicted capabili
3535
bincapz /bin/ping
3636
```
3737

38-
```
39-
/sbin/ping
40-
--------------------------------------------------------------------------------------------------
41-
RISK | KEY | DESCRIPTION
42-
--------+-----------------------+-------------------------------------------------------------------
43-
meta | sha256 | 1eec23e4189171ea689c7fe6a133e5f22b9683f633e414bde9ca47b9644f090b
44-
meta | entitlements | com.apple.private.network.management.data.development
45-
| | com.apple.security.network.client
46-
| | com.apple.security.network.server
47-
| |
48-
1/LOW | net/hostname/resolve | resolves network hosts via name
49-
1/LOW | net/http/request | Makes HTTP (Hypertext Transport Protocol) requests
50-
1/LOW | net/icmp | ICMP (Internet Control Message Protocol), aka ping
51-
1/LOW | net/interface/get | get network interfaces by name or index
52-
1/LOW | net/interface/list | list network interfaces and their associated addresses
53-
1/LOW | net/ip | access the internet
54-
1/LOW | net/ip/multicast/send | send data to multiple nodes simultaneously
55-
1/LOW | net/ip/resolve | resolves network hosts via IP address
56-
1/LOW | net/ip/send/unicast | send data to the internet
57-
1/LOW | net/socket/connect | initiate a connection on a socket
58-
1/LOW | net/socket/receive | receive a message from a socket
59-
1/LOW | net/socket/send | send a message to a socket
60-
1/LOW | process/userid/set | set real and effective user ID of current process
61-
2/MED | combo/net/scan_tool | may scan networks:
62-
| | connect gethostbyname port scan socket
63-
2/MED | net/ip/string | converts IP address from byte to string
64-
```
65-
66-
That seems low-risk to me. Now, let's analyze a suspected malicious binary:
67-
68-
```log
69-
bpfdoor_2022.x86_64
70-
------------------------------------------------------------------------------------------------------------------------------
71-
RISK | KEY | DESCRIPTION
72-
---------+-------------------------------------+------------------------------------------------------------------------------
73-
meta | sha256 | fd1b20ee5bd429046d3c04e9c675c41e9095bea70e0329bd32d7edd17ebaf68a
74-
| |
75-
1/LOW | exec/program/background | Waits for a process to exit
76-
1/LOW | fd/multiplex | monitor multiple file descriptors
77-
1/LOW | fs/file/delete | deletes files
78-
1/LOW | net/socket/connect | initiate a connection on a socket
79-
1/LOW | net/socket/listen | listen on a socket
80-
1/LOW | net/socket/receive | receive a message from a socket
81-
1/LOW | net/socket/send | send a message to a socket
82-
1/LOW | process/chroot | change the location of root for the process
83-
1/LOW | process/create | Create a new child process using fork
84-
1/LOW | random/insecure | generate random numbers insecurely
85-
1/LOW | ref/path/usr/sbin | References paths within /usr/sbin:
86-
| | /usr/sbin/console-kit-daemon
87-
1/LOW | tty/vhangup | virtually hangup the current terminal
88-
2/MED | device/pseudo_terminal | pseudo-terminal access functions
89-
2/MED | exec/program | executes another program
90-
2/MED | exec/shell_command | execute a shell command
91-
2/MED | fs/file/times/set | change file last access and modification times
92-
2/MED | net/ip/byte/order | convert values between host and network byte order
93-
2/MED | net/ip/string | converts IP address from byte to string
94-
3/HIGH | combo/backdoor/net_term | Listens, provides a terminal, runs program:
95-
| | /dev/ptmx execve grantpt listen
96-
3/HIGH | combo/backdoor/sys_cmd | multiple sys commands:
97-
| | auditd systemd/systemd
98-
3/HIGH | ref/program/ancient_gcc | built by archaic gcc version:
99-
| | GCC: (GNU) 4.4.7
100-
4/CRIT | 3P/elastic/bpfdoor | Detects Linux Trojan Bpfdoor (Linux.Trojan.BPFDoor), by Elastic Security
101-
4/CRIT | 3P/signature_base/redmenshen/bpfd.. | Detects BPFDoor implants used by Chinese actor Red Menshen, by Florian Roth
102-
| | (Nextron Systems)
103-
```
104-
105-
If you want to focus on the most suspicious behaviors, you can pass `--min-level=3`, which will remove a lot of the noise by only showing "HIGH" or "CRITICAL" risk behaviors.
106-
107-
## Diff mode for detecting supply-chain compromises
38+
There are flags for controlling output (see the Usage section) and filtering out rules. Here's the `--format=markdown` output:
39+
40+
41+
| RISK | KEY | DESCRIPTION |
42+
|-------|-----------------------|--------------------------------------------------------|
43+
| meta | entitlements | com.apple.private.network.management.data.development |
44+
| | | com.apple.security.network.client |
45+
| | | com.apple.security.network.server |
46+
| meta | format | macho |
47+
| | | |
48+
| 1/LOW | net/hostname/resolve | resolves network hosts via name |
49+
| 1/LOW | net/icmp | iCMP (Internet Control Message Protocol), aka ping |
50+
| 1/LOW | net/interface/get | get network interfaces by name or index |
51+
| 1/LOW | net/interface/list | list network interfaces and their associated addresses |
52+
| 1/LOW | net/ip | access the internet |
53+
| 1/LOW | net/ip/multicast/send | send data to multiple nodes simultaneously |
54+
| 1/LOW | net/ip/resolve | resolves network hosts via IP address |
55+
| 1/LOW | net/ip/send/unicast | send data to the internet |
56+
| 1/LOW | net/socket/connect | initiate a connection on a socket |
57+
| 1/LOW | net/socket/receive | receive a message from a socket |
58+
| 1/LOW | net/socket/send | send a message to a socket |
59+
| 1/LOW | process/userid/set | set real and effective user ID of current process |
60+
| 2/MED | combo/net/scan_tool | may scan networks: "connect |
61+
| | | gethostbyname |
62+
| | | port |
63+
| | | scan |
64+
| | | socket" |
65+
| 2/MED | net/ip/string | converts IP address from byte to string |
66+
67+
68+
Behaviors are sorted by lowest to highest risk: this binary doesn't have anything particularly exciting about it. If you want to only show output for the most suspicious behaviors, use `--min-level=3`, which shows only "HIGH" or "CRITICAL" risk behaviors.
69+
70+
## Diff mode to detect supply-chain attacks
10871

10972
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:
11073

11174
```shell
11275
bincapz -diff old_ffmpeg.dylib new_ffmpeg.dylib
11376
```
11477

115-
Here is a result using the 3CX compromise as a test case.
116-
117-
```
118-
🐙 changed behaviors: new_ffmpeg.dylib
119-
------------------------------------------------------------------------------------------------------------------
120-
+1/LOW compression/gzip works with gzip files
121-
+1/LOW env/HOME looks up the HOME directory
122-
for the current user
123-
+1/LOW fs/lock/update apply or remove an advisory
124-
lock on a file
125-
+1/LOW kernel/dispatch/semaphore uses Dispatch Semaphores
126-
+1/LOW kernel/hostname/get gets the hostname of the
127-
machine
128-
+1/LOW net/http/accept/encoding able to decode multiple forms
129-
of HTTP responses (example:
130-
gzip)
131-
+1/LOW random/insecure generate random numbers
132-
insecurely
133-
+1/LOW sync/semaphore/user uses semaphores to synchronize
134-
data between processes or
135-
threads
136-
+2/MED exec/pipe uses popen to launch a program
137-
and pipe output to/from it
138-
+2/MED fs/permission/modify modifies file permissions
139-
using chmod
140-
+2/MED net/http/cookies able to access HTTP resources
141-
using cookies
142-
+2/MED net/url/request requests resources via URL
143-
+2/MED ref/path/hidden references a hidden file that
144-
can be generated dynamically:
145-
%s/.main_storage
146-
+2/MED shell/arbitrary_command/dev_null runs arbitrary commands
147-
redirecting output to
148-
/dev/null
149-
+4/CRIT 3P/godmoderules/iddqd/god/mode detects a wide array of
150-
cyber threats, from malware
151-
and ransomware to advanced
152-
persistent threats (APTs), by
153-
Florian Roth
154-
+4/CRIT 3P/signature_base/3cxdesktopapp/ba.. detects 3CXDesktopApp MacOS
155-
Backdoor component, by
156-
X__Junior (Nextron Systems)
157-
+4/CRIT 3P/signature_base/nk/3cx detects malicious DYLIB files
158-
related to 3CX compromise, by
159-
Florian Roth (Nextron Systems)
160-
+4/CRIT 3P/signature_base/susp/xored detects suspicious single byte
161-
XORed keyword 'Mozilla/5.0'
162-
- it uses yara's XOR modifier
163-
and therefore cannot print the
164-
XOR key, by Florian Roth
165-
+4/CRIT 3P/volexity/iconic detects the MACOS version
166-
of the ICONIC loader., by
167-
threatintel@volexity.com
168-
```
169-
170-
Alternatively, you can also store the JSON output and diff the keys by hand:
78+
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.
79+
80+
## 🐙 changed behaviors: testdata/macOS/libffmpeg.dirty.dylib
81+
82+
| RISK | KEY | DESCRIPTION |
83+
|---------|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
84+
| +1/LOW | **compression/gzip** | works with gzip files |
85+
| +1/LOW | **env/HOME** | looks up the HOME directory for the current user |
86+
| +1/LOW | **fs/lock/update** | apply or remove an advisory lock on a file |
87+
| +1/LOW | **kernel/dispatch/semaphore** | uses Dispatch Semaphores |
88+
| +1/LOW | **kernel/hostname/get** | gets the hostname of the machine |
89+
| +1/LOW | **net/http/accept/encoding** | able to decode multiple forms of HTTP responses (example: gzip) |
90+
| +1/LOW | **random/insecure** | generate random numbers insecurely |
91+
| +1/LOW | **sync/semaphore/user** | uses semaphores to synchronize data between processes or threads |
92+
| +2/MED | **exec/pipe** | uses popen to launch a program and pipe output to/from it |
93+
| +2/MED | **fs/permission/modify** | modifies file permissions |
94+
| +2/MED | **net/http/cookies** | able to access HTTP resources using cookies |
95+
| +2/MED | **net/url/request** | requests resources via URL |
96+
| +2/MED | **ref/path/hidden** | references a hidden file that can be generated dynamically: "%s/.main_storage" |
97+
| +2/MED | **shell/arbitrary_command/dev_null** | runs arbitrary commands redirecting output to /dev/null |
98+
| +4/CRIT | **3P/godmoderules/iddqd/god/mode** | detects a wide array of cyber threats, from malware and ransomware to advanced persistent threats (APTs), by Florian Roth |
99+
| +4/CRIT | **3P/signature_base/3cxdesktopapp/backdoor** | detects 3CXDesktopApp MacOS Backdoor component, by X__Junior (Nextron Systems) |
100+
| +4/CRIT | **3P/signature_base/nk/3cx** | detects malicious DYLIB files related to 3CX compromise, by Florian Roth (Nextron Systems) |
101+
| +4/CRIT | **3P/signature_base/susp/xored** | detects suspicious single byte XORed keyword 'Mozilla/5.0' - it uses yara's XOR modifier and therefore cannot print the XOR key, by Florian Roth |
102+
| +4/CRIT | **3P/volexity/iconic** | detects the MACOS version of the ICONIC loader., by threatintel@volexity.com
103+
104+
If you like to do things the hard way, you can also store the JSON output and diff the keys by hand:
171105

172106
```shell
173107
bincapz --format=json <file> | jq '.Files.[].Behaviors | keys'
174108
```
175109

176110
## Supported Flags
177111

178-
* `--all` - Don't filter anything out, include even harmless capabilities
179-
* `--alsologtostderr` - log to standard error
180-
* `--format string` - Output type. Valid values are: table, json (default "table")
181-
* `--ignore-tags` - Rule tags to ignore
182-
* `--diff` - show the diff between two files or directories
183-
* `--data-files` - include files that are detected to as non-program (binary or source) files
184-
* `--min-level` - minimum suspicion level to report (1=low, 2=medium, 3=high, 4=critical) (default 1)
185-
* `--omit-empty` - don't report on files that have no matches
186-
* `--third-party` - include third-party rules, which may have licensing restrictions (default true)
112+
* `--all`: Ignore nothing, show all
113+
* `--data-files`: include files that are detected to as non-program (binary or source) files
114+
* `--diff`: show capability drift between two files
115+
* `--format` string: Output type. Valid values are: json, markdown, simple, terminal, yaml (default "terminal")
116+
* `--ignore-tags` string: Rule tags to ignore
117+
* `--min-level`: minimum suspicion level to report (1=low, 2=medium, 3=high, 4=critical) (default 1)
118+
* `--omit-empty`: omit files that contain no matches
119+
* `--third-party`: include third-party rules, which may have licensing restrictions (default true)
187120

188121
## FAQ
189122

@@ -212,3 +145,7 @@ bincapz alerns when an obfuscated or packed binary is detected. Depending on the
212145
### What related software is out there?
213146

214147
Much of bincapz's functionality is inspired by <https://github.com/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.
148+
149+
### How can I help?
150+
151+
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.

‎images/screenshot.png‎

24.8 KB
Loading

0 commit comments

Comments
 (0)