{"id":13743120,"url":"https://github.com/spaceraccoon/npm-scan","last_synced_at":"2025-05-09T00:32:41.811Z","repository":{"id":48028031,"uuid":"160127846","full_name":"spaceraccoon/npm-scan","owner":"spaceraccoon","description":"An extensible, heuristic-based vulnerability scanning tool for installed npm packages","archived":true,"fork":false,"pushed_at":"2021-08-10T20:50:13.000Z","size":221,"stargazers_count":49,"open_issues_count":7,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-02-14T17:33:10.654Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spaceraccoon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-03T03:33:11.000Z","updated_at":"2024-01-08T14:36:10.000Z","dependencies_parsed_at":"2022-08-12T17:00:54.538Z","dependency_job_id":null,"html_url":"https://github.com/spaceraccoon/npm-scan","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceraccoon%2Fnpm-scan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceraccoon%2Fnpm-scan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceraccoon%2Fnpm-scan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceraccoon%2Fnpm-scan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spaceraccoon","download_url":"https://codeload.github.com/spaceraccoon/npm-scan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253171166,"owners_count":21865275,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T05:00:40.959Z","updated_at":"2025-05-09T00:32:41.560Z","avatar_url":"https://github.com/spaceraccoon.png","language":"JavaScript","funding_links":[],"categories":["Static Code Analysis"],"sub_categories":[],"readme":"# npm-scan\n[![Black Hat Arsenal](https://raw.githubusercontent.com/spaceraccoon/npm-scan/master/bha2019.svg?sanitize=true)]()\n[![Contributors](https://img.shields.io/github/contributors/spaceraccoon/npm-scan.svg)]()\n\nAn extensible, heuristic-based vulnerability scanning tool for installed npm packages.\n\n*WARNING: npm-scan is still very much in early development and should not be used in production.* We are developing more accurate heuristics. **We are actively seeking new contributors with ideas for additional heuristics, so please do get in touch :)**\n\nAnother important project you can contribute to is [npm-zoo](https://github.com/spaceraccoon/npm-zoo), where past malicious packages are uploaded for research. We need more examples in order to develop better heuristics.\n\n## Quickstart\n```\nnpm install https://github.com/spaceraccoon/npm-scan.git\nnpx npm-scan\n```\n\n## Usage\n```\nUsage: npx npm-scan [options]\n\nOptions:\n  -V, --version                     output the version number\n  -p, --packages-dir \u003cdir path\u003e     set directory path for packages. defaults to node_modules\n  -e, --exclude-heuristics \u003citems\u003e  exclude comma-separated list of heuristics\n  -o, --output \u003cfile path\u003e          set file path for JSON output\n  -v, --verbose                     print more details for each package scan\n  -s, --strict                      include low-risk heuristics\n  -h, --help                        output usage information\n```\n\n## Developing\n```\ngit clone https://github.com/spaceraccoon/npm-scan.git\nnpm link\nnpm run scan\nnpm run test\nnpm run lint\n```\nPush changes on a separate branch.\n\nTo add a new heuristic, you will require the following:\n\n1. **name** - Name of the heuristic\n2. **message** - Description of the heuristic\n3. **reference** - URL to a report or disclosure of the vulnerability/suspicious code\n4. **run** - A function that runs the tests, returning a `result` object if the test is positive and null otherwise. Refer to the existing heuristics for formatting.\n\nThere are two types of heuristics, file-based regex and manifest-based checks (like checking version numbers, last update time, etc.). These are specified in `lib/heuristics/index.js` and affects how the scanner runs the heuristic.\n\n## Pitch\nOn 26/11/2018, a popular NPM package event-stream\u003csup\u003e1\u003c/sup\u003e with millions of weekly installs was [found to contain obfuscated and encrypted malicious code\u003csup\u003e2\u003c/sup\u003e that tries to steal a user's bitcoins. This was caused by an attacker posing as a new maintainer of event-stream adding an unknown dependency (flatmap-stream\u003csup\u003e3\u003c/sup\u003e) that contained the malicious code.\n\nThis incident highlighted the shocking lack of accountability in NPM that had immense ramifications. It is the norm for packages to be linked to a chain of other packages, making it hard to maintain trust.  Furthermore, NPM defaults to accepting all new minor versions of a package, making it even harder to keep track of packages.\n\n#### Q. So how can we prevent such incidents from happening again?\nA. We want to give all users and developers power to check their currently installed node_modules for malicious intent.\n\n#### Q. How will you do that?\nA. We created npm-scan. It uses simple regex-based heuristics to check for suspicious lines of code in any installed node module. A particular package with many suspicious lines of code indicates possible malicious behavior. These scores are compiled into a report for the user to check which dependency contains suspicious code, and determine if there are any areas of concern.  \n\n#### Q. How is this different from other scanners out there?\nA. Most scanners such as Source Clear and Black Duck conduct their scanning based on databases such as the National Vulnerability Database\u003csup\u003e4\u003c/sup\u003e. This is slow as it could be weeks or months by the time a vulnerability is disclosed, inwhich time the malicious package would have been automatically updated on millions of devices. \n\nOur heuristics-based approach gives immediate feedback on how suspicious a package is without having to run it. The heuristics are just flagging any suspicious behavior that would not be the norm of typical node packages. For example, flatmap-stream is shipped in minified form (under dependencies in package.json), which is not typical behavior (the top 50 node packages, encompassing 1000+ dependencies, all do not ship in minified form). Although this will be flagged with a low severity score (since it isn't exactly malicious behavior in itself), combine that with other heauristics such as containing the hexadecimal version of the string \"AES256\", and flatmap-stream starts to look very suspicious. This will all be reflected in npm-scan's report.\n\n## Scoring\nCurrently, our detection consists of line-based regex. We score each package's severity based on the number of flagged lines. \n\nIn the future, we can assign categories to each heuristic to do more complex scoring, such as one based on CVSS v3.0\u003csup\u003e5\u003c/sup\u003e. \n\n## References\n1. https://github.com/dominictarr/event-stream\n2. https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident\n3. https://libraries.io/npm/flatmap-stream/0.1.1\n4. https://nvd.nist.gov/\n5. https://www.first.org/cvss/specification-document\n6. https://resources.sei.cmu.edu/asset_files/TechnicalNote/2005_004_001_14474.pdf\n7. https://www.snort.org/rules_explanation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspaceraccoon%2Fnpm-scan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspaceraccoon%2Fnpm-scan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspaceraccoon%2Fnpm-scan/lists"}