malcontent branding: rewrite README, new go install target (#477)

* pip: add known good list * Branding update: README refactor, make target * make README clearer * Update DEVELOPMENT.md Co-authored-by: Evan Gibler <[email protected]> Signed-off-by: Thomas Strömberg <[email protected]> --------- Signed-off-by: Thomas Strömberg <[email protected]> Co-authored-by: Evan Gibler <[email protected]>
chainguard-dev · Oct 2, 2024 · e5cf03d · e5cf03d
1 parent 19e37ec
commit e5cf03d
Show file tree

Hide file tree

Showing 9 changed files with 134 additions and 191 deletions.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -0,0 +1,79 @@
+
+# Development
+
+## How do I contribute new rules?
+
+Contributing is easy! All of malcontent's rules are in [YARA](https://virustotal.github.io/yara/) format: just throw a new rule into the `rules/` subdirectory and you are ready to go.
+
+You can verify that your new rule works by running:
+
+```
+go run ./cmd/mal analyze <path>
+```
+
+For debugging rules, it's sometimes useful to use the `yara` command:
+
+```
+yara -s -w rules/combo/dropper/shell.yara <path>
+```
+
+## Running tests
+
+```make test```
+
+## Writing rule tests
+
+Not every rule needs a test, but tests do ensure that a rules behavior stays consistent:
+
+1. Add a sample to https://github.com/chainguard-dev/malcontent-samples
+2. Create a directory within `test_data` using the same directory name as your sample:
+
+```
+mkdir -p test_data/macOS/2024.Rustdoor/
+```
+3. Create an empty file for a specific sample file with the ending name of ".simple":
+
+```
+touch test_data/macOS/2024.Rustdoor/fakepdf.sh.simple
+```
+4. Refresh all the testdata: `make refresh-sample-testdata`
+
+## Profiling
+
+`malcontent` 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
+```
+## Troubleshooting
+
+#### Error: ld: library 'yara' not found
+
+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](https://github.com/VirusTotal/yara/releases) and build it from source by following [these](https://yara.readthedocs.io/en/latest/gettingstarted.html#compiling-and-installing-yara) steps.
+
+Once Yara is installed, run `sudo ldconfig -v` to ensure that the library is loaded.
diff --git a/Makefile b/Makefile
@@ -117,7 +117,7 @@ bench-windows:
 .PHONY: out/mal
 out/mal:
 	mkdir -p out
-	go build -o out/mal .
+	go build -o out/mal ./cmd/mal
 
 .PHONY: update-third-party
 update-third-party:

diff --git a/README.md b/README.md
diff --git a/malcontent.go → cmd/mal/mal.go b/malcontent.go → cmd/mal/mal.go
diff --git a/images/analyze.png b/images/analyze.png
diff --git a/images/diff.png b/images/diff.png
diff --git a/images/scan.png b/images/scan.png
diff --git a/images/screenshot.png b/images/screenshot.png
diff --git a/images/wanted.jpg b/images/wanted.jpg