diff --git a/README.md b/README.md index 9e06f87d2..4bf60ff86 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,74 @@ -``` - _ _ _. . _ _ _ . ___ _. _ . ___ - ( | ) (_| |_ (_ (_) ( \_) | (/_ ( \_) | +# malcontent + +```text + _ _ _. . _ _ _ . ___ _. _ . ___ +( | ) (_| |_ (_ (_) ( \_) | (/_ ( \_) | - overtly paranoid open-source malware scanner + the paranoid open-source malware scanner ``` -malcontent is a malware scanner and analysis tool for high-risk environments such as CI/CD pipelines. It's goal is to reveal hitherto undiscovered malware, so it is overtly paranoid and highly prone to false positives. +malcontent is a malware scanner and analysis tool for high-risk environments such as CI/CD pipelines. Its goal is to reveal novel undiscovered malware, +and is overtly paranoid and highly prone to false positives. malcontent offers 3 modes of operation depending on your use case: -* `analyze`: deep analysis of a programs capabilities +* `scan`: find malicious content across a variety of file formats +* `analyze`: deep analysis of a program's capabilities * `diff`: show the capability differences between two versions of a program -* `scan`: basic malware scanner -*WARNING: This tool is in early development and raises more false-positives than even we would like. We're working on it :)* +*NOTE: malcontent is a work in progress and has a higher false-positive rate than we would like; we're working on it!* ## Features -- 15,300+ open-source YARA rules -- Analyzes binaries from almost any architecture (arm64, amd64, riscv, ppc64, sparc64), format (ELF, machO, PE), -- Analyzes programs for almost any operating system (Linux, macOS, OpenBSD, FreeBSD, Solaris, Windows) -- Analyzes scripts in almost any language (PERL, Python, shell, Javascript, Typescript, PHP) -- Transparent archive support (`.apk`, `.gem`, `.gz`, `.jar`, `.tar.gz`, `.tar.xz`, `.tar`, `.tgz`, and `.zip`) and OCI archives -- Multiple output formats (JSON, YAML, Markdown, Terminal) -- Includes 3rd party YARA rules from esteemed organizations such as Avast, Elastic, FireEye, Google, JP-CERT, Nextron, and others +* 16,000+ [YARA](YARA) detection rules! + * Including third-party rules from esteemed organizations such as Avast, Elastic, FireEye, Mandiant, Nextron, ReversingLabs, and more! +* Analyzes binaries for nearly any environment (Linux, macOS, Windows, etc.) +* Analyzes scripts (Python, shell, Javascript, Typescript, PHP, Perl) +* Analyzes container images +* Transparent archive support (apk, tar, zip, etc.) +* Multiple output formats (JSON, YAML, Markdown, Terminal) ## Modes +### Scan + +Scan directories for possible malware: + +![scan screenshot](./images/scan.png) + +You can also scan a container image: `mal scan -i cgr.dev/chainguard/nginx:latest` + +Useful flags: + +* `--include-data-files`: Include files that do not appear to be programs +* `--processes`: scan active process binaries (experimental) + ### Analyze -To analyze a program, pass the path as an argument to `mal analyze`. For example: +To analyze the capabilities of a program, use `mal analyze`. For example: ![analyze screenshot](./images/analyze.png) -The analyze mode emits a list of capabilities that are often seen in malware, categorized by risk level. In general, `CRITICAL` findings should be considered malicious. +The analyze mode emits a list of capabilities often seen in malware, categorized by risk level. It works with programs in a wide variety of file formats and scripting languages. + +`CRITICAL` findings should be considered malicious. Useful flags include: + +* `--format=json`: output to JSON for data parsing +* `--min-risk=high`: only show high or critical risk findings ### Diff -To detect unexpected capability changes, we have a `diff` mode. Using the [3CX Compromise](https://www.fortinet.com/blog/threat-research/3cx-desktop-app-compromised) as an example: +To detect unexpected capability changes, try `diff` mode. Using the [3CX Compromise](https://www.fortinet.com/blog/threat-research/3cx-desktop-app-compromised) as an example, we're able to use malcontent to detect malicious code inserted in an otherwise harmless library: ![diff screenshot](./images/diff.png) -Each of the lines that beginsl with a "+" represent a newly added capability. For use in CI/CD pipelines, you may find the following flags useful: +Each line that begins with a "+" represents a newly added capability.You can use it to diff entire directories recursively, even if they contain programs written in a variety of languages. -It's worth noting that none of the "CRITICAL" findings, except for the `evasnion/xor/user_agent`, would have been found pre-3CX compromise. The diff mode is designed to surface subtle unexpected changes that you might not have an explatanion for, such as "why does `libffmpeg.dylib` need access to `chown`? +For use in CI/CD pipelines, you may find the following flags helpful: * `--format=markdown`: output in markdown for use in GitHub Actions * `--min-file-risk=critical`: only show diffs for critical-level changes -* `--quantity-increases-risk=false`: disable the heuristics that increase file criticality due to result frequency - -### Scan - -![scan screenshot](./images/scan.png) - -Like other commands, you can even point this tool at a container image: `mal scan --i cgr.dev/chainguard/nginx` - -Useful flags: - -* `--include-data-files`: Include files that are detected as non-program (binary or source) files +* `--quantity-increases-risk=false`: disable heuristics that increase file criticality due to result frequency ## Installation @@ -69,9 +80,9 @@ Useful flags: Requirements: -- [go](https://go.dev/) - the programming language -- [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) - for dependency handling, included in many UNIX distributions -- [yara](https://virustotal.github.io/yara/) - the rule language +* [yara](https://virustotal.github.io/yara/) - the rule language +* [go](https://go.dev/) - the programming language +* [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) - for dependency handling, included in many UNIX distributions For example, to install the YARA library on Linux or macOS: @@ -88,6 +99,6 @@ go install github.com/chainguard-dev/malcontent/cmd/mal@latest ## Help Wanted -![help wanted sign](./images/wanted.jpg) +![help wanted sign](./images/wanted.png) -malcontent is an honest-to-goodness open-source project: if you are interested in contributing, check out [DEVELOPMENT.md](DEVELOPMENT.md) \ No newline at end of file +malcontent is an honest-to-goodness open-source project: if you are interested in contributing, check out [DEVELOPMENT.md](DEVELOPMENT.md) diff --git a/images/scan.png b/images/scan.png index b13f04d6e..6a6f6628c 100644 Binary files a/images/scan.png and b/images/scan.png differ diff --git a/images/wanted.jpg b/images/wanted.jpg deleted file mode 100644 index 011d62c8a..000000000 Binary files a/images/wanted.jpg and /dev/null differ diff --git a/images/wanted.png b/images/wanted.png new file mode 100644 index 000000000..da2781dc9 Binary files /dev/null and b/images/wanted.png differ