docs: made API docs and updated malware analyzer README

Signed-off-by: Carl Flottmann <carl.flottmann@oracle.com>
oracle · Feb 27, 2025 · df42e78 · df42e78
1 parent df90484
commit df42e78
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 0 deletions.
diff --git a/...developers_guide/apidoc/macaron.malware_analyzer.pypi_heuristics.sourcecode.rst b/...developers_guide/apidoc/macaron.malware_analyzer.pypi_heuristics.sourcecode.rst
@@ -9,6 +9,14 @@ macaron.malware\_analyzer.pypi\_heuristics.sourcecode package
 Submodules
 ----------
 
+macaron.malware\_analyzer.pypi\_heuristics.sourcecode.pypi\_sourcecode\_analyzer module
+---------------------------------------------------------------------------------------
+
+.. automodule:: macaron.malware_analyzer.pypi_heuristics.sourcecode.pypi_sourcecode_analyzer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 macaron.malware\_analyzer.pypi\_heuristics.sourcecode.suspicious\_setup module
 ------------------------------------------------------------------------------
 

diff --git a/src/macaron/malware_analyzer/README.md b/src/macaron/malware_analyzer/README.md
@@ -52,6 +52,17 @@ When a heuristic fails, with `HeuristicResult.FAIL`, then that is an indicator b
    - **Rule**: Return `HeuristicResult.FAIL` if the major or epoch is abnormally high; otherwise, return `HeuristicResult.PASS`.
    - **Dependency**: Will be run if the One Release heuristic fails.
 
+### Experimental: Source Code Analysis with Semgrep
+
+The following analyzer has been added in as an experimental feature, available by supplying `--analyze-source` in the CLI to `macaron analyze`:
+
+**PyPI Source Code Analyzer**
+- **Description**: Uses Semgrep, with default rules written in `src/macaron/resources/pypi_malware_rules` and custom rules available by supplying a path to `custom_semgrep_rules` in `defaults.ini`, to scan the package `.tar` source code.
+- **Rule**: If any Semgrep rule is triggered, the heuristic fails with `HeuristicResult.FAIL` and subsequently fails the package with `CheckResultType.FAILED`. If no rule is triggered, the heuristic passes with `HeuristicResult.PASS` and the `CheckResultType` result from the combination of all other heuristics is maintained.  
+- **Dependency**: Will be run if the Source Code Repo fails.
+
+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.
+
 ### 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: