feat(security): Add package name typosquatting detection #1059

AmineRaouane · 2025-04-21T11:24:02Z

Implement typosquatting detection for package names during analysis. Compares package names against a list of popular packages using the Jaro-Winkler similarity algorithm. Packages exceeding a defined threshold of similarity to a popular package are flagged.

Summary

Adds typosquatting detection for package names during analysis using Jaro-Winkler similarity.

Description of changes

This PR introduces a new security analysis feature to detect potential typosquatting in package names. The implementation compares the name of a package being analyzed against a list of popular package names. By default, it uses a predefined list stored in a dedicated file, but it also offers an option to use a custom list provided via a configuration path.

The comparison utilizes the Jaro-Winkler similarity algorithm to calculate a similarity score between the package name and each name in the popular packages list. If the calculated similarity score exceeds a configurable threshold, the package is flagged as a potential typosquat.

This feature helps identify malicious packages attempting to mimic legitimate, popular ones through slight variations in spelling, thus enhancing the security posture of the project by warning users about such risks.

The changes include:

Integration of the Jaro-Winkler similarity algorithm.
Inclusion of a default file containing a list of popular package names for comparison.
Addition of a configuration option to provide a custom file path for the popular packages list, overriding the default.
Implementation of the comparison logic and threshold-based flagging.

Related issues

Checklist

I have reviewed the contribution guide.
My PR title and commits follow the Conventional Commits convention.
My commits include the "Signed-off-by" line.
I have signed my commits following the instructions provided by GitHub. Note that we run GitHub's commit verification tool to check the commit signatures. A green verified label should appear next to all of your commits on GitHub.
I have tested my changes and verified they work as expected.

oracle-contributor-agreement · 2025-04-21T11:24:07Z

Thank you for your pull request and welcome to our community! To contribute, please sign the Oracle Contributor Agreement (OCA).
The following contributors of this PR have not signed the OCA:

PR author: AmineRaouane
r1@amines-macbook-pro.local

To sign the OCA, please create an Oracle account and sign the OCA in Oracle's Contributor Agreement Application.

When signing the OCA, please provide your GitHub username. After signing the OCA and getting an OCA approval from Oracle, this PR will be automatically updated.

If you are an Oracle employee, please make sure that you are a member of the main Oracle GitHub organization, and your membership in this organization is public.

Implement typosquatting detection for package names during analysis. Compares package names against a list of popular packages using the Jaro-Winkler similarity algorithm. Packages exceeding a defined threshold of similarity to a popular package are flagged. Signed-off-by: Amine <r1@Amines-MacBook-Pro.local>

Adds a new security analysis feature to detect potential typosquatting in package names. Compares the package name against a list of popular packages using the Jaro-Winkler similarity algorithm. Packages exceeding a configurable threshold are flagged. Includes a default popular package list and an option for a custom list via configuration. Signed-off-by: Amine <amine.raouane@enim.ac.ma>

behnazh-w · 2025-04-24T05:57:40Z

@AmineRaouane Please add unit tests following the instructions here.

Take a look at the unit tests for other malware heuristics at tests/malware_analyzer/pypi/ and add a similar one for this new heuristic.

For small and standalone functions, you can add test cases to the docstring itself. You can find an example here.

art1f1c3R · 2025-04-28T00:54:42Z

Would it be possible to make the path to the custom file list of packages configurable through defaults.ini? Our configurations for heuristic analyzers live under the [heuristic.pypi] section in the file. Check out some of the heuristics that use it to get an idea (anomalous_version.py, high_release_frequency.py), I do something similar with paths in the semgrep PR.

Added unit tests for typosquatting detection. Analyzer variables, including the file path, are now loaded from defaults.ini. Raised heuristic confidence level from medium to high. BREAKING CHANGE: Analyzer config must now be defined in defaults.ini. Signed-off-by: Amine <amine.raouane@enim.ac.ma>

src/macaron/malware_analyzer/pypi_heuristics/metadata/typosquatting_presence.py

Signed-off-by: Amine <amine.raouane@enim.ac.ma>

tromai · 2025-05-14T09:41:16Z

tests/parsers/.DS_Store

I see some .DS_Store files being checked into the Pull Request. Could you please remove them and may be add an entry for it to .gitignore?

art1f1c3R · 2025-05-15T00:52:57Z

src/macaron/slsa_analyzer/checks/detect_malicious_metadata_check.py

@@ -395,12 +397,18 @@ def run_check(self, ctx: AnalyzeContext) -> CheckResultData:
        failed({Heuristics.ONE_RELEASE.value}),
        failed({Heuristics.ANOMALOUS_VERSION.value}).

+    % Package released with a name similar to a popular package.
+    {Confidence.HIGH.value}::trigger(malware_high_confidence_4) :-


Can this be placed further up in the text under malware_high_confidence_3? Just for readability.

art1f1c3R · 2025-05-15T00:53:21Z

src/macaron/slsa_analyzer/checks/detect_malicious_metadata_check.py

    % ----- Evaluation -----

    % Aggregate result
    {problog_result_access} :- trigger(malware_high_confidence_1).
    {problog_result_access} :- trigger(malware_high_confidence_2).
    {problog_result_access} :- trigger(malware_high_confidence_3).
+    {problog_result_access} :- trigger(malware_high_confidence_4).
+    {problog_result_access} :- trigger(malware_high_confidence_5).


I don't see any rule defined for malware_high_confidence_5?

art1f1c3R · 2025-05-15T00:57:32Z

src/macaron/malware_analyzer/pypi_heuristics/metadata/typosquatting_presence.py

+            with open(self.popular_packages_path, encoding="utf-8") as file:
+                popular_packages = file.read().splitlines()
+        except OSError as exception:
+            err_msg = f"Could not read popular packages file {self.popular_packages_path}: {exception}"


Can you raise a HeuristicAnalyzerValueError here as opposed to returning HeuristicResult.SKIP? Please take a look at #1052 to understand how the error and skip results should be used.

art1f1c3R · 2025-05-15T01:01:07Z

src/macaron/malware_analyzer/pypi_heuristics/metadata/typosquatting_presence.py

+        tuple[HeuristicResult, dict[str, JsonType]]:
+            The result and related information collected during the analysis.
+        """
+        if not self.popular_packages_path or not os.path.exists(self.popular_packages_path):


Should we maybe open and store the file when initializing the analyzer? That way this error can be caught earlier? I do something similar in 965

art1f1c3R · 2025-05-15T01:02:02Z

src/macaron/malware_analyzer/pypi_heuristics/metadata/typosquatting_presence.py

+        if not popular_packages:
+            err_msg = f"Popular packages file is empty: {self.popular_packages_path}"
+            logger.warning(err_msg)
+            return HeuristicResult.SKIP, {"error": err_msg}


Similarly here with raising an error instead of skipping.

AmineRaouane requested review from behnazh-w and tromai as code owners April 21, 2025 11:24

oracle-contributor-agreement bot added the OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. label Apr 21, 2025

Amine and others added 2 commits April 23, 2025 09:28

AmineRaouane force-pushed the main branch from f9a60f4 to 250f2e2 Compare April 23, 2025 09:11

behnazh-w requested review from art1f1c3R and benmss April 24, 2025 01:58

benmss reviewed Apr 29, 2025

View reviewed changes

src/macaron/malware_analyzer/pypi_heuristics/metadata/typosquatting_presence.py Show resolved Hide resolved

benmss reviewed Apr 29, 2025

View reviewed changes