{"id":13702138,"url":"https://github.com/sonatype-nexus-community/auditjs","last_synced_at":"2025-05-15T01:07:52.627Z","repository":{"id":36712939,"uuid":"41720656","full_name":"sonatype-nexus-community/auditjs","owner":"sonatype-nexus-community","description":"Audits an NPM package.json file to identify known vulnerabilities.","archived":false,"fork":false,"pushed_at":"2024-11-13T16:44:13.000Z","size":1996,"stargazers_count":227,"open_issues_count":46,"forks_count":53,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-13T23:53:45.299Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/auditjs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sonatype-nexus-community.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-01T06:16:45.000Z","updated_at":"2025-03-18T04:31:05.000Z","dependencies_parsed_at":"2024-01-04T22:44:03.919Z","dependency_job_id":"779ee8e8-746d-4af4-a11b-1536216943e2","html_url":"https://github.com/sonatype-nexus-community/auditjs","commit_stats":{"total_commits":335,"total_committers":25,"mean_commits":13.4,"dds":0.791044776119403,"last_synced_commit":"bbb2c37b563f2c1b5effb19be408bd9a0297bdd0"},"previous_names":["ossindex/auditjs"],"tags_count":143,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonatype-nexus-community%2Fauditjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonatype-nexus-community%2Fauditjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonatype-nexus-community%2Fauditjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonatype-nexus-community%2Fauditjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sonatype-nexus-community","download_url":"https://codeload.github.com/sonatype-nexus-community/auditjs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254041,"owners_count":22039792,"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":["hacktoberfest"],"created_at":"2024-08-02T21:00:31.665Z","updated_at":"2025-05-15T01:07:47.608Z","avatar_url":"https://github.com/sonatype-nexus-community.png","language":"TypeScript","funding_links":[],"categories":["Free Tools","Vulnerabilities and Security Advisories","TypeScript","Dependency intelligence"],"sub_categories":["Javascript","SCA and SBOM"],"readme":"\u003c!--\n\n    Copyright 2019-Present Sonatype Inc.\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n        http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n\n--\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/sonatype-nexus-community/auditjs/blob/main/assets/images/auditjs.png\" width=\"350\"/\u003e\n\u003c/p\u003e\n\n# AuditJS\n\n[![CircleCI](https://circleci.com/gh/sonatype-nexus-community/auditjs.svg?style=svg)](https://circleci.com/gh/sonatype-nexus-community/auditjs)\n\n**IMPORTANT NOTE**: Welcome to AuditJS 4.0.0, lots has changed since 3.0.0, mainly around usage. Make sure to read the new docs.\n\nIf you have an issue migrating from AuditJS 3.x to AuditJS 4.x, please [file a GitHub issue here](https://github.com/sonatype-nexus-community/auditjs/issues).\n\nAudits JavaScript projects using the [OSS Index v3 REST API](https://ossindex.sonatype.org/rest)\nto identify known vulnerabilities and outdated package versions.\n\nSupports any project with package managers that install npm dependencies into a node_modules folder including:\n\n- npm\n- Angular\n- yarn\n- bower\n\n\u003cimg src=\"https://github.com/sonatype-nexus-community/auditjs/blob/main/assets/images/auditjsnew.png?raw=true\" width=\"640\"\u003e\n\n## Requirements\n\nFor users wanting to use Nexus IQ Server as their data source for scanning:\n\n1.  Version 77 or above must be installed. This is when the [Third-Party Scan REST API](https://help.sonatype.com/iqserver/automating/rest-apis/third-party-scan-rest-api---v2) was incorporated into Nexus IQ Server.\n\n2.  The User performing the scan must have the permission \"Can Evaluate Applications\", this can be found in the Role Editor \u003e _User_ \u003e Permissions \u003e IQ\n\n## Installation\n\nYou can use `auditjs` a number of ways:\n\nvia npx (least permanent install)\n\n```\nnpx auditjs@latest ossi\n```\n\nvia global install (most permanent install)\n\n```\nnpm install -g auditjs\n```\n\nWe suggest you use it via `npx`, as global installs are generally frowned upon in the nodejs world.\n\n## Usage\n\n`auditjs` supports node LTS versions of 8.x forward at the moment. Usage outside of these node versions will error.\n\nNote that the OSS Index v3 API is rate limited. If you are seeing errors that\nindicate a problem (HTTP code 429) then you may need to make an account at\nOSS Index and supply the username and \"token\". See below for more details.\n\n### Generic Usage\n\n```terminal\nauditjs [command]\n\nCommands:\n  auditjs iq [options]    Audit this application using Nexus IQ Server\n  auditjs config          Set config for OSS Index or Nexus IQ Server\n  auditjs ossi [options]  Audit this application using Sonatype OSS Index\n\nOptions:\n  --version  Show version number                                       [boolean]\n  --help     Show help                                                 [boolean]\n```\n\n### OSS Index Usage\n\n```terminal\nauditjs ossi [options]\n\nAudit this application using Sonatype OSS Index\n\nOptions:\n  --version        Show version number                                 [boolean]\n  --help           Show help                                           [boolean]\n  --user, -u       Specify OSS Index username                           [string]\n  --password, -p   Specify OSS Index password or token                  [string]\n  --cache, -c      Specify path to use as a cache location              [string]\n  --quiet, -q      Only print out vulnerable dependencies              [boolean]\n  --json, -j       Set output to JSON                                  [boolean]\n  --xml, -x        Set output to JUnit XML format                      [boolean]\n  --whitelist, -w  Set path to whitelist file                           [string]\n  --clear          Clears cache location if it has been set in config  [boolean]\n  --bower          Force the application to explicitly scan for Bower  [boolean]\n```\n\n### Nexus IQ Server Usage\n\n```\nauditjs iq [options]\n\nAudit this application using Nexus IQ Server\n\nOptions:\n  --version          Show version number                               [boolean]\n  --help             Show help                                         [boolean]\n  --application, -a  Specify IQ application public ID        [string] [required]\n  --stage, -s        Specify IQ app stage\n  [choices: \"develop\", \"build\", \"stage-release\", \"release\"] [default: \"develop\"]\n  --server, -h       Specify IQ server url/port\n                                     [string] [default: \"http://localhost:8070\"]\n  --timeout, -t      Specify an optional timeout in seconds for IQ Server\n                     Polling                             [number] [default: 300]\n  --user, -u         Specify username for request    [string] [default: \"admin\"]\n  --password, -p     Specify password for request [string] [default: \"admin123\"]\n  --artie, -x        Artie                                             [boolean]\n  --dev, -d          Include Development Dependencies                  [boolean]\n```\n\n#### AuditJS usage with IQ Server, and what to expect\n\n##### TL;DR\n\nAuditJS should catch most if not the exact same amount of issues as the Sonatype Nexus IQ CLI Scanner. It however can't catch a few cases. If you want total visibility, please use the Sonatype Nexus IQ CLI Scanner. You can use both in tandem, too.\n\n##### The full scoop\n\nAuditJS functions by traversing your `node_modules` folder in your project, so it will pick up the dependencies that are physically installed. This will capture your declared as well as transititive dependencies. Once it has done this, it takes the list and converts it into something that we use to communicate with Sonatype Nexus IQ Server. The crux of this approach is that we do \"coordinate\" or \"name based matching\", which we've found to be reliable in the JavaScript ecosystem, but it will not catch corner cases such as if you've:\n\n- Drug a vulnerable copy of jQuery into your project and left it in a folder (npm does not know about this)\n- Copied and pasted code from a project into one of your files\n\nThe Nexus IQ CLI Scanner is equipped to locate and identify cases such as what I've just described. As such if you are using AuditJS, you would not be made aware of these cases, potentially until your code is audited by the IQ CLI Scanner later on.\n\nIt is our suggestion that when you are using this tooling to:\n\n- Use AuditJS in your dev environments, etc... and use it to scan as early and as often as possible. This will alert you and other developers to using bad dependencies right off the bat.\n- Use the Sonatype Nexus IQ CLI Scanner in CI/CD for a more thorough scan, and have development and your Application Security experts evaluate this scan for any \"gotchas\"\n\n### Usage Information\n\nExecute from inside a node project (above the node_modules directory) to audit\nthe dependencies. This will audit not only the direct dependencies of the project,\nbut all **transitive** dependencies. To identify transitive dependencies they must\nall be installed for the project under audit.\n\nIf a vulnerability is found to be affecting an installed library the package\nheader will be highlighted in red and information about the pertinent\nvulnerability will be printed to the screen.\n\nBy default we write all silly debug and error data to:\n\n`YOUR_HOME_DIR/.ossindex/.auditjs.combined.log`\n\n```\n{ level: 'debug',\n  message: 'Results audited',\n  label: 'AuditJS',\n  timestamp: '2019-12-22T20:09:33.447Z' }\n```\n\n### Usage in CI\n\n#### Jenkins\n\nTBD\n\n#### CircleCI\n\nWe've provided an example repo with a working CircleCI config on a \"fake\" but real project, you can see how it is all setup by clicking [this link](https://github.com/sonatype-nexus-community/example-auditjs-repo#usage-in-circleci).\n\n#### TravisCI\n\nWe've provided an example repo with a working TravisCI config on a \"fake\" but real project, you can see how it is all setup by clicking [this link](https://github.com/sonatype-nexus-community/example-auditjs-repo#usage-in-travisci).\n\n#### GitHub Actions\n\nWe've provided an example repo with a working GitHub Action on a \"fake\" but real project, you can see how it is all setup by clicking [this link](https://github.com/sonatype-nexus-community/example-auditjs-repo#usage-with-github-actions).\n\n#### Proxy integration\n\nThe tool reads the `http_proxy` or `https_proxy` environment variables to perform network request through a Proxy.\n\n### Usage As A NPM Script\n\n`auditjs` can be added as a devDependency to your project, and then an npm script can be added so you can leverage it in your npm scripts.\n\nYou would install `auditjs` like so:\n\n```\n$ npm i auditjs -D\n```\n\nAn example snippet from a `package.json`:\n\n```\n  },\n  \"scripts\": {\n    \"test\": \"mocha -r ts-node/register src/**/*.spec.ts\",\n    \"build\": \"tsc -p tsconfig.json\",\n    \"build-dev\": \"tsc -p tsconfig.development.json\",\n    \"start\": \"node ./bin/index.js\",\n    \"prepare\": \"npm run build\",\n    \"prepublishOnly\": \"npm run test\",\n    \"scan\": \"auditjs ossi\"\n  },\n  \"keywords\": [\n```\n\nNow that we've added a `scan` script, you can run `yarn run scan` and your project will invoke `auditjs` and scan your dependencies. This can be handy for local work, or for if you want to run `auditjs` in CI/CD without installing it globally.\n\nNote: these reference implementations are applicable to running an IQ scan as well. The caveat is that the config for the IQ url and auth needs to either be in the home directory of the user running the job, or stored as (preferably secret) environmental variables.\n\n## Config file\n\nConfig is now set via the command line, you can do so by running `auditjs config`. You will be prompted if you'd like to set Nexus IQ Server config or Sonatype OSS Index config. Reasonable defaults are provided for Sonatype Nexus IQ Server that will work for an out of the box install. It is STRONGLY suggested that you do not save your password in config (although it will work), but rather use a token from OSS Index or Nexus IQ Server.\n\nConfig passed in via the command line will be respected over filesystem based config so that you can override specific calls to either Sonatype OSS Index or Nexus IQ Server. Please see usage of either command to see how to set this command line config.\n\n## OSS Index Credentials\n\nThe OSS Index API is rate limited to prevent abuse. Guests (non-authorized users)\nare restricted to 16 requests of 120 packages each, which replenish at a rate\nof one request per minute. This means if you have 600 dependencies, then 5 requests\nwill be used. No problem! If you have many projects which are run close to each\nother you could run into the limit.\n\nYou can either wait for the cool-down period to expire, or make a free account at\nOSS Index. By going to the \"settings\" page for your account, you will see your\n\"token\". Using your username (email address) and this security token you would\nhave access to 64 requests, which is likely plenty for most use cases.\n\nAudit.js caches results, which means if you run against multiple projects which\nhave a common set of dependencies (and they almost certainly will) then you will\nnot use up requests getting the same results more than once.\n\nYou can specify your credentials on either the command line or the configuration\nfile. It is almost certainly better to put the credentials in a configuration\nfile as described above, as using them on the command line is less secure.\n\n## Whitelisting\n\nWhitelisting of vulnerabilities can be done! To accomplish this thus far we have implemented the ability to have a file named `auditjs.json` checked in to your repo ideally, so that it would be at the root where you run `auditjs`. Alternatively you can run `auditjs` with a whitelist file at a different location, with an example such as:\n\n```terminal\n$ auditjs ossi --whitelist /Users/cooldeveloperperson/code/sonatype-nexus-community/auditjs/auditjs.json\n```\n\nThe file should look like:\n\n```json\n{\n  \"ignore\": [{ \"id\": \"78a61524-80c5-4371-b6d1-6b32af349043\", \"reason\": \"Insert reason here\" }]\n}\n```\n\nThe only field that actually matters is `id` and that is the ID you receive from OSS Index for a vulnerability. You can add fields such as `reason` so that you later can understand why you whitelisted a vulnerability.\n\nAny `id` that is whitelisted will be squelched from the results, and not cause a failure.\n\n## Alternative output formats\n\n`auditjs` can output directly as `json` or as `xml` specifically formatted for JUnit test cases.\n\nJSON:\n\n```\nauditjs ossi --json \u003e file.json\n```\n\nXML:\n\n```\nauditjs ossi --xml \u003e file.xml\n```\n\nWe chose to allow output directly to the stdout, so that the user can decide what they want to do with it. If you'd like it to be written to a file by `auditjs` itself, pop in to [this issue](https://github.com/sonatype-nexus-community/auditjs/issues/115) and let us know your thoughts!\n\n## Limitations\n\nAs this program depends on the OSS Index database, network access is\nrequired. Connection problems with OSS Index will result in an exception.\n\n## How to Fix Vulnerabilities\n\nOr, \"Patient: Hey Doc, it hurts when I do this. Doctor: Then don't do that.\"\n\nSo you've found a vulnerability. Now what? The best case is to upgrade the vulnerable component to a newer/non-vulnerable\nversion. However, it is likely the vulnerable component is not a direct dependency, but instead is a transitive dependency\n(a dependency of a dependency, of a dependency, wash-rinse-repeat). In such a case, the first step is to figure out which\ndirect dependency (and sub-dependencies) depend on the vulnerable component. The `npm ls \u003cvulnerable dependency\u003e` \ncommand will print a dependency tree that can lead you through this dependency forest.\n\nIf your project uses yarn, the `yarn why \u003cvulnerable dependency\u003e` command can provide a similar trail of breadcrumbs. \n\nAs an example, suppose we've learned that component `hosted-git-info`, version 2.8.8 is vulnerable (CVE-2021-23362). Use\nthe command below to find which components depend on this vulnerable component.\n```shell\n  $ npm ls hosted-git-info\n  auditjs@4.0.25 /Users/bhamail/sonatype/community/auditjs/auditjs\n  └─┬ read-installed@4.0.3\n    └─┬ read-package-json@2.1.2\n      └─┬ normalize-package-data@2.5.0\n        └── hosted-git-info@2.8.8\n```\nNow we know the `read-installed@4.0.3` component has a transitive dependency on the vulnerable component `hosted-git-info@2.8.8`.\nThe best solution would be to upgrade `read-installed` to a newer version that uses a non-vulnerable version of `hosted-git-info`.\nAs of this writing, however, no such version of `read-installed` exists. The next step is to file an issue with the\n`read-installed` project for them to update the vulnerable sub-dependencies. Be sure to read and follow any vulnerability\nreporting instructions published by the project: Look for a `SECURITY.md` file, or other instructions on how to report\nvulnerabilities. Some projects may prefer you not report the vulnerability publicly. Here's our bug report for this case:\n[bug #53](https://github.com/npm/read-installed/issues/53)\n\nTo fix this particular vulnerability in our project, we need some way to force the transitive dependency to a newer version. \nThis would be relatively easy if we were using yarn (see [yarn's selective dependency resolutions](https://yarnpkg.com/lang/en/docs/selective-version-resolutions/)).\nSince we are not using yarn, we will use [npm-force-resolutions](https://github.com/rogeriochaves/npm-force-resolutions).\nSee the [excellent npm-force-resolutions docs](https://github.com/rogeriochaves/npm-force-resolutions#npm-force-resolutions)\nfor details on how this works.\n\nAfter updating our `package.json` file as described by `npm-force-resolutions`,\n```json\n...\n  \"resolutions\": {\n    \"hosted-git-info\": \"^3.0.8\"\n  },\n  \"scripts\": {\n    \"preinstall\": \"npx npm-force-resolutions\",\n...\n```\nwe run `npm install`, and verify\nour transitive dependency is updated to a new version.\n```shell\n$ rm -rf node_modules \u0026\u0026 npm install\n$ npm ls hosted-git-info\nauditjs@4.0.25 /Users/bhamail/sonatype/community/auditjs/auditjs\n└─┬ read-installed@4.0.3\n  └─┬ read-package-json@2.1.1\n    └─┬ normalize-package-data@2.5.0\n      └── hosted-git-info@3.0.8  invalid\n\nnpm ERR! invalid: hosted-git-info@3.0.8 /Users/bhamail/sonatype/community/auditjs/auditjs/node_modules/normalize-package-data/node_modules/hosted-git-info\n```\nAfter updating the transitive dependency, we need to make sure the tests still pass:\n```shell\nnpm run test\n...\n29 passing (84ms) \n```\nVictory! Commit the changes, and we're done. \n\nYou could also upgrade a higher level transitive dependency: `read-package-json` , like so:\n```shell\n  \"resolutions\": {\n    \"read-package-json\": \"^3.0.1\"\n  },\n```\n\n\n## Credit\n\n---\n\nThank you to everybody who has contributed to this project, both with\n[code contributions](https://github.com/OSSIndex/auditjs/pulls?q=is%3Apr+is%3Aclosed)\nand also suggestions, testing help, and notifying us of new and/or missing\nvulnerabilities.\n\n## Contributing\n\nWe care a lot about making the world a safer place, and that's why we continue to work on this and other plugins for Sonatype OSS Index. If you as well want to speed up the pace of software development by working on this project, jump on in! Before you start work, create a new issue, or comment on an existing issue, to let others know you are!\n\n## Releasing\n\nWe use [semantic-release](https://github.com/semantic-release/semantic-release) to generate releases\nfrom commits to the `main` branch.\n\nFor example, to perform a \"patch\" release, add a commit to `main` with a comment like:\n\n```\nfix: Adds insecure flag, implements (#213)\n```\n\n## The Fine Print\n\nRemember:\n\nIt is worth noting that this is **NOT SUPPORTED** by Sonatype, and is a contribution of ours to the open source\ncommunity (read: you!)\n\n* Use this contribution at the risk tolerance that you have\n* Do NOT file Sonatype support tickets related to `ossindex-lib`\n* DO file issues here on GitHub, so that the community can pitch in\n\nPhew, that was easier than I thought. Last but not least of all - have fun!\n\n## Getting help\n\nLooking to contribute to our code but need some help? There's a few ways to get information:\n\n- Chat with us on the [AuditJS Gitter](https://gitter.im/sonatype-nexus-community/auditjs) or the [Nexus-Developers Gitter](https://gitter.im/sonatype/nexus-developers)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonatype-nexus-community%2Fauditjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsonatype-nexus-community%2Fauditjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonatype-nexus-community%2Fauditjs/lists"}