Skip to content

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

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Jump to bottom
Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

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

wants to merge 9 commits into from

Conversation

AmineRaouane
Copy link
Member

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 Oracle Contributor Agreement
Copy link

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:

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.

@oracle-contributor-agreement oracle-contributor-agreement bot added the OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. label Apr 21, 2025
@behnazh-w behnazh-w requested review from art1f1c3R and benmss April 24, 2025 01:58
@behnazh-w
Copy link
Member

@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
Copy link
Member

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.

tromai
tromai reviewed May 14, 2025
View reviewed changes
@AmineRaouane AmineRaouane force-pushed the main branch 2 times, most recently from 0a8ddbf to 80afd9e Compare May 17, 2025 22:30
benmss
benmss reviewed May 20, 2025
View reviewed changes
.gitignore
@@ -181,3 +181,4 @@ docs/_build
bin/
requirements.txt
.macaron_env_file
**/.DS_Store
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not cover subdirectories such as tests, parsers, etc.

Copy link
Member Author

@AmineRaouane AmineRaouane May 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed it to .DS_Store

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, I was wrong above. **/.DS_Store should be sufficient, you just need to remove all the matching files that were already added.

benmss
benmss reviewed May 20, 2025
View reviewed changes
tests/slsa_analyzer/checks/test_detect_malicious_metadata_check.py
@@ -29,7 +29,7 @@
# heuristic, a false negative has been introduced. Note that if the unit test were allowed to access the OSV
# knowledge base, it would report the package as malware. However, we intentionally block unit tests
# from reaching the network.
("pkg:pypi/zlibxjson", CheckResultType.PASSED),
("pkg:pypi/zlibxjson", CheckResultType.UNKNOWN),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is an expected change, the comment above should be updated to reflect the new situation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't push the code because that test fails

@AmineRaouane
feat: implement typosquatting detection for package names
ad7c576 
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>
@AmineRaouane
feat: implement typosquatting detection for package names
25fc7d0 
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>
@AmineRaouane
feat: implement typosquatting detection for package names
f560201 
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>
@AmineRaouane
feat(typosquatting): add tests and move analyzer config to defaults.ini
a775b6d 
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>
@AmineRaouane
chore(typosquatting): improve variable names and comments for clarity
4140160 
Signed-off-by: Amine <amine.raouane@enim.ac.ma>
@AmineRaouane
refactor(core): improve logic, error handling, and apply minor fixes
4c506c2 
Signed-off-by: Amine <amine.raouane@enim.ac.ma>
@AmineRaouane
refactor(core): improve logic, error handling, and apply minor fixes
28f9936 
Signed-off-by: Amine <amine.raouane@enim.ac.ma>
@AmineRaouane
chore(typosquatting): improve variable names and comments for clarity
e0b538e 
Signed-off-by: Amine <amine.raouane@enim.ac.ma>
@AmineRaouane
docs: update docs and refine existing test
8d37e9b 
Signed-off-by: Amine <amine.raouane@enim.ac.ma>
@oracle-contributor-agreement oracle-contributor-agreement bot added OCA Verified All contributors have signed the Oracle Contributor Agreement. and removed OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. labels May 21, 2025
art1f1c3R
art1f1c3R reviewed May 22, 2025
View reviewed changes
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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So now with the change for filling in self.popular_packages in the __init__ method, I see this scenario is skipping the heuristic in the event there were no popular packages to check against. I think this is okay and a good use of SKIP here, but in the detail info returned I don't think I'd call the entry key "error": , probably "warning": , similar to how you log a warning.

# for free to join this conversation on GitHub. Already have an account? # to comment
Reviewers

@benmss benmss benmss left review comments

@tromai tromai tromai left review comments

@art1f1c3R art1f1c3R art1f1c3R left review comments

@behnazh-w behnazh-w Awaiting requested review from behnazh-w behnazh-w is a code owner

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
OCA Verified All contributors have signed the Oracle Contributor Agreement.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@AmineRaouane @behnazh-w @art1f1c3R @benmss @tromai