<!-- Copyright 2019-Present Sonatype Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <p align="center"> <img src="https://github.com/sonatype-nexus-community/auditjs/blob/main/assets/images/auditjs.png" width="350"/> </p>

AuditJS

[![shield_gh-workflow-test]][link_gh-workflow-test] [![shield_license]][license_file]

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.

If you have an issue migrating from AuditJS 3.x to AuditJS 4.x, please file a GitHub issue here.

Audits JavaScript projects using the OSS Index v3 REST API to identify known vulnerabilities and outdated package versions.

Supports any project with package managers that install npm dependencies into a node_modules folder including:

• npm
• Angular
• yarn
• bower

<img src="https://github.com/sonatype-nexus-community/auditjs/blob/main/assets/images/auditjsnew.png?raw=true" width="640">

Requirements

For users wanting to use Nexus IQ Server as their data source for scanning:

1. Version 77 or above must be installed. This is when the Third-Party Scan REST API was incorporated into Nexus IQ Server.

2. The User performing the scan must have the permission "Can Evaluate Applications", this can be found in the Role Editor > User > Permissions > IQ

Installation

You can use auditjs a number of ways:

via npx (least permanent install)

npx auditjs@latest ossi

via global install (most permanent install)

npm install -g auditjs

We suggest you use it via npx, as global installs are generally frowned upon in the nodejs world.

Usage

auditjs supports node LTS versions of 8.x forward at the moment. Usage outside of these node versions will error.

Note that the OSS Index v3 API is rate limited. If you are seeing errors that indicate a problem (HTTP code 429) then you may need to make an account at OSS Index and supply the username and "token". See below for more details.

Generic Usage

auditjs [command]

Commands:
  auditjs iq [options]    Audit this application using Nexus IQ Server
  auditjs config          Set config for OSS Index or Nexus IQ Server
  auditjs ossi [options]  Audit this application using Sonatype OSS Index

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]

OSS Index Usage

auditjs ossi [options]

Audit this application using Sonatype OSS Index

Options:
  --version        Show version number                                 [boolean]
  --help           Show help                                           [boolean]
  --server, -h     Specify OSS Index server url                         [string]
  --user, -u       Specify OSS Index username                           [string]
  --password, -p   Specify OSS Index password or token                  [string]
  --cache, -c      Specify path to use as a cache location              [string]
  --quiet, -q      Only print out vulnerable dependencies              [boolean]
  --json, -j       Set output to JSON                                  [boolean]
  --xml, -x        Set output to JUnit XML format                      [boolean]
  --whitelist, -w  Set path to whitelist file                           [string]
  --clear          Clears cache location if it has been set in config  [boolean]
  --bower          Force the application to explicitly scan for Bower  [boolean]

Nexus IQ Server Usage

auditjs iq [options]

Audit this application using Nexus IQ Server

Options:
  --version          Show version number                               [boolean]
  --help             Show help                                         [boolean]
  --application, -a  Specify IQ application public ID        [string] [required]
  --stage, -s        Specify IQ app stage
  [choices: "develop", "build", "stage-release", "release"] [default: "develop"]
  --server, -h       Specify IQ server url/port
                                     [string] [default: "http://localhost:8070"]
  --timeout, -t      Specify an optional timeout in seconds for IQ Server
                     Polling                             [number] [default: 300]
  --user, -u         Specify username for request    [string] [default: "admin"]
  --password, -p     Specify password for request [string] [default: "admin123"]
  --artie, -x        Artie                                             [boolean]
  --dev, -d          Include Development Dependencies                  [boolean]

AuditJS usage with IQ Server, and what to expect

TL;DR

AuditJS 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.

The full scoop

AuditJS 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:

• Drug a vulnerable copy of jQuery into your project and left it in a folder (npm does not know about this)
• Copied and pasted code from a project into one of your files

The 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.

It is our suggestion that when you are using this tooling to:

• 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.
• 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"

Usage Information

Execute from inside a node project (above the node_modules directory) to audit the dependencies. This will audit not only the direct dependencies of the project, but all transitive dependencies. To identify transitive dependencies they must all be installed for the project under audit.

If a vulnerability is found to be affecting an installed library the package header will be highlighted in red and information about the pertinent vulnerability will be printed to the screen.

By default we write all silly debug and error data to:

YOUR_HOME_DIR/.ossindex/.auditjs.combined.log

{ level: 'debug',
  message: 'Results audited',
  label: 'AuditJS',
  timestamp: '2019-12-22T20:09:33.447Z' }

Usage in CI

Jenkins

TBD

CircleCI

We'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.

TravisCI

We'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.

GitHub Actions

We'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.

Proxy integration

The tool reads the http_proxy or https_proxy environment variables to perform network request through a Proxy.

Usage As A NPM Script

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.

You would install auditjs like so:

$ npm i auditjs -D

An example snippet from a package.json:

  },
  "scripts": {
    "test": "mocha -r ts-node/register src/**/*.spec.ts",
    "build": "tsc -p tsconfig.json",
    "build-dev": "tsc -p tsconfig.development.json",
    "start": "node ./bin/index.js",
    "prepare": "npm run build",
    "prepublishOnly": "npm run test",
    "scan": "auditjs ossi"
  },
  "keywords": [

Now 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.

Note: 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.

Config file

Config is now set via the command line, you can do so