npm package: @silintl/vulnerability-scanner
Description: Scan your repos for vulnerabilities (such as dependencies with published security advisories)
Author: Matt Henderson
Latest version: 2.0.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Vulnerability Scanner

Scan your repos for vulnerabilities (such as dependencies with published security advisories)

## Dependencies

- NodeJS
- Docker (for tests and dependency updates)
- Make (because it's just easier that way)

## Running

### Locally

First, do this setup:

1. Copy `.env.dist` to `.env` and add appropriate values.
2. Install [node](https://nodejs.org/en/download/)
3. Run `npm install`

Next, use one of the following commands, depending on what you want to do. Note
that if you also pass a URL to a CSV file specifying what versions of PHP and
NodeJS various Docker images use, then any use of End-of-Life'd (EOL'd) versions
of PHP and NodeJS will also be reported.

#### Scan an Entire GitHub Organization's Repos

Run this, replacing "ORGANIZATION" with the desired GitHub org. name:

`node cli/scan-github-org.js ORGANIZATION "[VERSIONS_CSV_URL]"`

#### Scan a Specific GitHub Repo

Run this, replacing "REPO" with the desired GitHub repo, in the format
"repo-owner/repo-name":

`node cli/scan-github-repo.js REPO "[VERSIONS_CSV_URL]"`

#### Scan an Entire Bitbucket Workspaces's Repos

Run this, replacing "WORKSPACE" with the desired Bitbucket workspace name:

`node cli/scan-bitbucket-workspace.js WORKSPACE "[VERSIONS_CSV_URL]"`

#### Scan a Specific Bitbucket Repo

Run this, replacing "REPO" with the desired Bitbucket repo, in the format
"repo-owner/repo-name":

`node cli/scan-bitbucket-repo.js REPO "[VERSIONS_CSV_URL]"`

#### Scan an Entire GitHub Organization and Bitbucket Workspace

Run this, replacing "GH_ORGANIZATION" with the desired GitHub org. name and
"BB_WORKSPACE" with the desired Bitbucket workspace name:

`node cli/scan-gh-bb.js GH_ORGANIZATION BB_WORKSPACE "[VERSIONS_CSV_URL]"`

### NPM

This library is also published as an npm package for use in other
JavaScript/Node applications:  
<https://www.npmjs.com/package/@silintl/vulnerability-scanner>

### AWS Lambda

To run this on AWS Lambda, see  
<https://github.com/silinternational/serverless-vulnerability-scanner>

## Testing

To run the (local) tests, simply run `make test`. For more details, see the
`Makefile`.

## Backwards Compatibility

This repo uses semver, and its public interface (in order to determine what
changes would break backwards-compatibility) is defined as the functions
exported by `./index.js`. 

## Checking Programming Language Versions

Each of the commands for scanning one or more repos also accepts an optional URL
to a CSV file with mapping information between Docker images and programming
language versions (e.g. PHP, NodeJS).

### Docker-language-versions CSV file

Example CSV content:

```
Docker image,PHP version,NodeJS version
openjdk:8-jdk-alpine,NONE,NONE
php:7.3-apache-buster,7.3,NONE
node:16,NONE,v16
```

**Note**:

- The header line needs to use exactly those values.
- The values in the Docker image column should be the exact value used as the
  `FROM` in the Dockerfile.
- For Docker images that do include PHP, specify only the major and minor
  version (such as `7.3`, **not** `7.3.24`).
- For Docker images that do include NodeJS, enter a `v` and the major version
  (such as `v16`, **not** `v16.13.1`).
- For Docker images that do not include the given programming language, use
  `NONE`.

**Tip**:  
One easy way to maintain a URL-accessible CSV file is as a Google Sheet, using
the "File" > "Publish to Web" feature, selecting the desired sheet (tab),
specifying "CSV" as the format option, and using the given URL in calls to this
library.

### Missing Docker image values

If your list of vulnerabilities includes a warning like the following...
```
No record found in spreadsheet for php:7.3-apache-buster
```
... you simply need to add a row to your CSV file with that Docker image (in
this case, `php:7.3-apache-buster`) and what version of PHP it uses (in this
case, `7.3`).

If you do not know what version of PHP it uses (and if it is a Docker image you
trust enough to run on your local computer), you can run a command like this,
replacing `YOUR-DOCKER-IMAGE-STRING` with the actual value:
```
docker run --rm --entrypoint php YOUR-DOCKER-IMAGE-STRING -v
```

In the example above, that would mean running the following command:
```
docker run --rm --entrypoint php php:7.3-apache-buster -v
```

**Note**:

There is a little `get-docker-lang-versions.sh` helper script for determining
the PHP, NodeJS, and Python versions (if any) used in a list of Docker images.
However, it may change (and even be renamed) in future changes to this library.
Feel free to use it, but don't depend on its current behavior or filename to
remain unchanged.

For example, you could create a file called `docker-images-unknown-versions.txt`
with a single docker image per line, then run the following:
```
cat docker-images-unknown-versions.txt | ./get-docker-lang-versions.sh
```
That would write out to a `docker-lang-versions.txt` file the CSV data to use
in your spreadsheet of what programming language versions are used in what
Docker images. There is also a `make docker-lang-versions` command you can run
to run the above code more easily (and not have to re-read this documenation
every time).

## Unknown PHP versions

If your list of vulnerabilities includes a warning like the following...
```
Unknown PHP version: 8.1
```
... please submit a PR on this repo to add that PHP version and its EOL date to
the "src/php.js" file's list of EOL dates.

To find the End-Of-Life (EOL) date for that version of PHP, go to
<https://www.php.net/supported-versions> and find the latest date any kind of
support is planned for that version (typically the "Security Support Until"
date).

Thanks!

## Unknown NodeJS versions

If your list of vulnerabilities includes a warning like the following...
```
Unknown NodeJS version: v19
```
... please submit a PR on this repo to add that NodeJS version and its EOL date
to the "src/nodejs.js" file's list of EOL dates.

To find the End-Of-Life (EOL) date for that version of NodeJS, go to
<https://nodejs.org/en/about/releases/> and look at the "END-OF-LIFE" value for
that version in the table near the end of the page.

Thanks!