docs: updated README and CONTRIBUTING for information on how to contribute to the malware analyzer

Signed-off-by: Carl Flottmann <[email protected]>

Author: art1f1c3R

CONTRIBUTING.md

@@ -72,6 +72,10 @@ See below for instructions to set up the development environment.
 - PRs should be merged using the `Squash and merge` strategy. In most cases a single commit with
 a detailed commit message body is preferred. Make sure to keep the `Signed-off-by` line in the body.
 
+### PyPI Malware Detection Contribution
+
+Please see the [README for the malware analyzer](./src/macaron/malware_analyzer/README.md) for information on contributing Heuristics and code patterns.
+
 ## Branching model
 
 * The `main` branch is only used for releases and the `staging` branch is used for development. We only merge to `main` when we want to create a new release for Macaron.

src/macaron/malware_analyzer/README.md

@@ -1,4 +1,4 @@
-# Implementation of Heuristic Malware Detector
+# Implementation of Malware Detector
 
 ## PyPI Ecosystem
 
@@ -63,6 +63,47 @@ The following analyzer has been added in as an experimental feature, available b
 
 This feature is currently a work in progress, and supports detection of code obfuscation techniques and remote exfiltration behaviors. It uses Semgrep OSS for detection.
 
+### Contributing
+
+When contributing an analyzer, it must meet the following requirements:
+
+- The analyzer must be implemented in a separate file, placed in the relevant folder based on what it analyzes ([metadata](./pypi_heuristics/metadata/) or [sourcecode](./pypi_heuristics/sourcecode/)).
+- The analyzer must inherit from the `BaseHeuristicAnalyzer` class and implement the `analyze` function, returning relevant information specific to the analysis.
+- The analyzer must be added to the list of analyzers in `detect_malicious_metadata_check.py` to be run.
+
+**Contributing Code Pattern Rules**
+
+When contributing more Semgrep rules for `pypi_sourcecode_analyzer.py` to use, the following requirements must be met:
+
+- Semgrep `.yaml` Rules are stored in `src/macaron/resources/pypi_malware_rules` and are named based on the category of code behaviors they detect.
+- If the rule comes under one of the already defined categories, place it within that `.yaml` file, else create a new `.yaml` file using the category name.
+- Each rule ID must be prefixed by the category followed by a single underscore ('_'), so for obfuscation rules in `obfuscation.yaml` each rule ID is prefixed with `obfuscation_`, followed by an ID which uses a hiphen ('-') as a separator.
+- Tests must be written for each rule contributed. These are stored in `tests/malware_analyzer/pypi/test_pypi_sourcescode_analyzer.py`.
+- These tests are written on a per-category bases, running each category individually. Each category must have a folder under `tests/malware_analyzer/pypi/resources/sourcecode_samples`.
+- Within these folders, there must be sample code patterns for testing, and a file `expected_results.json` with the expected JSON output of the analyzer for that category.
+- Each sample code pattern `.py` file must not have executable permissions and must include code that prevents it from being accidentally imported or run. The current files use this method:
+
+```
+"""
+Running this code will not produce any malicious behavior, but code isolation measures are
+in place for safety.
+"""
+
+import sys
+
+# ensure no symbols are exported so this code cannot accidentally be used
+__all__ = []
+sys.exit()
+
+def test_function():
+    """
+    All code to be tested will be defined inside this function, so it is all local to it. This is
+    to isolate the code to be tested, as it exists to replicate the patterns present in malware
+    samples.
+    """
+    sys.exit()
+```
+
 ### Confidence Score Motivation
 
 The original seven heuristics which started this work were Empty Project Link, Unreachable Project Links, One Release, High Release Frequency, Unchange Release, Closer Release Join Date, and Suspicious Setup. These heuristics (excluding those with a dependency) were run on 1167 packages from trusted organizations, with the following results: