# OWASP dependency-check

## OWASP dependency-check

<https://github.com/jeremylong/DependencyCheck>

[DependencyCheck](https://gitlab.com/johnmkane/tech-recipe-book/-/blob/main/Book/Web%20Dev/Dependency%20Checking/OWASP%20dependency-check/OWASP%20dependency-check/DependencyCheck/README.md)

## [Dependency-Check](https://github.com/jeremylong/DependencyCheck#dependency-check)

Dependency-Check is a Software Composition Analysis (SCA) tool that attempts to detect publicly disclosed vulnerabilities contained within a project's dependencies. It does this by determining if there is a Common Platform Enumeration (CPE) identifier for a given dependency. If found, it will generate a report linking to the associated CVE entries.

Documentation and links to production binary releases can be found on the [github pages](http://jeremylong.github.io/DependencyCheck/). Additionally, more information about the architecture and ways to extend dependency-check can be found on the [wiki](https://github.com/jeremylong/DependencyCheck/wiki).

### [8.0.0 Upgrade Notice](https://github.com/jeremylong/DependencyCheck#800-upgrade-notice)

8.0.0 contains breaking changes which requires updates to the database. If using an externally hosted database the schema will need to be updated. When using the embedded H2 database the schema should be upgraded automatically. However, if issues arise you may need to purge the database:

* gradle: `./gradlew dependencyCheckPurge`
* maven: `mvn org.owasp:dependency-check-maven:8.0.0:purge`
* cli: `dependency-check.sh --purge`

### [Requirements](https://github.com/jeremylong/DependencyCheck#requirements)

#### [Internet Access](https://github.com/jeremylong/DependencyCheck#internet-access)

OWASP dependency-check requires access to several externally hosted resources. For more information see [Internet Access Required](https://jeremylong.github.io/DependencyCheck/data/index.html).

#### [Build Tools](https://github.com/jeremylong/DependencyCheck#build-tools)

In order to analyze some technology stacks dependency-check may require other development tools to be installed. Some of the analysis listed below may be experimental and require the experimental analyzers to be enabled.

1. To analyze .NET Assemblies the dotnet 6 run time or SDK must be installed.
   * Assemblies targeting other run times can be analyzed - but 6 is required to run the analysis.
2. If analyzing GoLang projects `go` must be installed.
3. The analysis of `Elixir` projects requires `mix_audit`.
4. The analysis of `npm`, `pnpm`, and `yarn` projects requires `npm`, `pnpm`, or `yarn` to be installed.
   * The analysis performed utilize the respective `audit` feature of each.
5. The analysis of Ruby is a wrapper around `bundle-audit`, which must be installed.

### [Current Releases](https://github.com/jeremylong/DependencyCheck#current-releases)

#### [Jenkins Plugin](https://github.com/jeremylong/DependencyCheck#jenkins-plugin)

For instructions on the use of the Jenkins plugin please see the [OWASP Dependency-Check Plugin page](https://wiki.jenkins-ci.org/display/JENKINS/OWASP+Dependency-Check+Plugin).

#### [Command Line](https://github.com/jeremylong/DependencyCheck#command-line)

More detailed instructions can be found on the [dependency-check github pages](http://jeremylong.github.io/DependencyCheck/dependency-check-cli/). The latest CLI can be downloaded from github in the [releases section](https://github.com/jeremylong/DependencyCheck/releases).

Downloading the latest release:

```
$ VERSION=$(curl -s https://jeremylong.github.io/DependencyCheck/current.txt)
$ curl -Ls "https://github.com/jeremylong/DependencyCheck/releases/download/v$VERSION/dependency-check-$VERSION-release.zip" --output dependency-check.zip

```

On \*nix

```
$ ./bin/dependency-check.sh -h
$ ./bin/dependency-check.sh --out . --scan [path to jar files to be scanned]

```

On Windows

```
> .\bin\dependency-check.bat -h
> .\bin\dependency-check.bat --out . --scan [path to jar files to be scanned]

```

On Mac with [Homebrew](http://brew.sh/) Note - homebrew users upgrading from 5.x to 6.0.0 will need to run `dependency-check.sh --purge`.

```
$ brew update && brew install dependency-check
$ dependency-check -h
$ dependency-check --out . --scan [path to jar files to be scanned]

```

#### [Maven Plugin](https://github.com/jeremylong/DependencyCheck#maven-plugin)

More detailed instructions can be found on the [dependency-check-maven github pages](http://jeremylong.github.io/DependencyCheck/dependency-check-maven). By default, the plugin is tied to the `verify` phase (i.e. `mvn verify`). Alternatively, one can directly invoke the plugin via `mvn org.owasp:dependency-check-maven:check`.

The dependency-check plugin can be configured using the following:

```
<project>
    <build>
        <plugins>
            ...
            <plugin>
              <groupId>org.owasp</groupId>
              <artifactId>dependency-check-maven</artifactId>
              <executions>
                  <execution>
                      <goals>
                          <goal>check</goal>
                      </goals>
                  </execution>
              </executions>
            </plugin>
            ...
        </plugins>
        ...
    </build>
    ...
</project>
```

#### [Gradle Plugin](https://github.com/jeremylong/DependencyCheck#gradle-plugin)

For instructions on the use of the Gradle Plugin, please see the [dependency-check-gradle github page](http://jeremylong.github.io/DependencyCheck/dependency-check-gradle).

#### [Ant Task](https://github.com/jeremylong/DependencyCheck#ant-task)

For instructions on the use of the Ant Task, please see the [dependency-check-ant github page](http://jeremylong.github.io/DependencyCheck/dependency-check-ant).

### [Development Prerequisites](https://github.com/jeremylong/DependencyCheck#development-prerequisites)

For installation to pass, you must have the following components installed:

* Java: `java -version` 1.8
* Maven: `mvn -version` 3.5.0 and higher

Tests cases require:

* dotnet core version 6.0
* Go: `go version` 1.12 and higher
* Ruby [bundler-audit](https://github.com/rubysec/bundler-audit#install)
* [Yarn](https://classic.yarnpkg.com/en/docs/install/)
* [pnpm](https://pnpm.io/installation)

### [Development Usage](https://github.com/jeremylong/DependencyCheck#development-usage)

The following instructions outline how to compile and use the current snapshot. While every intention is to maintain a stable snapshot it is recommended that the release versions listed above be used.

The repository has some large files due to test resources. The team has tried to clean up the history as much as possible. However, it is recommended that you perform a shallow clone to save yourself time:

```
git clone --depth 1 https://github.com/jeremylong/DependencyCheck.git
```

On \*nix

```
$ mvn -s settings.xml install
$ ./cli/target/release/bin/dependency-check.sh -h
$ ./cli/target/release/bin/dependency-check.sh --out . --scan ./src/test/resources

```

On Windows

```
> mvn -s settings.xml install
> .\cli\target\release\bin\dependency-check.bat -h
> .\cli\target\release\bin\dependency-check.bat --out . --scan ./src/test/resources

```

Then load the resulting 'dependency-check-report.html' into your favorite browser.

#### [Building without running tests](https://github.com/jeremylong/DependencyCheck#building-without-running-tests)

To speed up your turnaround cycle times, you can also compile without running the tests each time:

`mvn -s settings.xml install -DskipTests=true`

Please remember to at least run the tests once before opening the PR. :)

#### [IntelliJ Idea](https://github.com/jeremylong/DependencyCheck#intellij-idea)

To be able to debug your tests in IntelliJ Idea, you can introduce a maven configuration that executes your test and enables debugging with breakpoints etc.

Basically, you do what´s described in <https://www.jetbrains.com/help/idea/work-with-tests-in-maven.html#run_single_test> and set the `forkCount` to 0, otherwise debugging won´t work.

Step by step:

* `Run -> Edit Configurations`
* `+ (Add new configuration) -> Maven`
* Give the Configuration a name, e.g. `Run tests`
* Choose working directory, e.g. `core`
* In `command line`, enter `DforkCount=0 -f pom.xml -s ../settings.xml test`
* Press `OK`
* `Run -> Debug`, then choose the newly created run configuration

IntelliJ will now execute the test run for the `core` subproject with enabled debugging. Breakpoints set anywhere in code should work.

#### [Only test one function or one class](https://github.com/jeremylong/DependencyCheck#only-test-one-function-or-one-class)

If you would like to speed up your turnaround cycle times, you can also just test one function or one test class.

This works by adding `-Dtest=MyTestClass` or `-Dtest=MyTestClass#myTestFunction` to the run configuration. The complete command line in the run configuration then would be:

* `Dtest=MyTestClass#myTestFunction -DforkCount=0 -f pom.xml -s ../settings.xml test`

#### [Docker](https://github.com/jeremylong/DependencyCheck#docker)

In the following example it is assumed that the source to be checked is in the current working directory and the reports will be written to `$(pwd)/odc-reports`. Persistent data and cache directories are used, allowing you to destroy the container after running.

For Linux:

```
#!/bin/sh

DC_VERSION="latest"
DC_DIRECTORY=$HOME/OWASP-Dependency-Check
DC_PROJECT="dependency-check scan: $(pwd)"
DATA_DIRECTORY="$DC_DIRECTORY/data"
CACHE_DIRECTORY="$DC_DIRECTORY/data/cache"

if [ ! -d "$DATA_DIRECTORY" ]; then
    echo "Initially creating persistent directory: $DATA_DIRECTORY"
    mkdir -p "$DATA_DIRECTORY"
fi
if [ ! -d "$CACHE_DIRECTORY" ]; then
    echo "Initially creating persistent directory: $CACHE_DIRECTORY"
    mkdir -p "$CACHE_DIRECTORY"
fi

# Make sure we are using the latest version
docker pull owasp/dependency-check:$DC_VERSION

docker run --rm \
    -e user=$USER \
    -u $(id -u ${USER}):$(id -g ${USER}) \
    --volume $(pwd):/src:z \
    --volume "$DATA_DIRECTORY":/usr/share/dependency-check/data:z \
    --volume $(pwd)/odc-reports:/report:z \
    owasp/dependency-check:$DC_VERSION \
    --scan /src \
    --format "ALL" \
    --project "$DC_PROJECT" \
    --out /report
    # Use suppression like this: (where /src == $pwd)
    # --suppression "/src/security/dependency-check-suppression.xml"
```

For Windows:

```
@echo off

set DC_VERSION="latest"
set DC_DIRECTORY=%USERPROFILE%\OWASP-Dependency-Check
SET DC_PROJECT="dependency-check scan: %CD%"
set DATA_DIRECTORY="%DC_DIRECTORY%\data"
set CACHE_DIRECTORY="%DC_DIRECTORY%\data\cache"

IF NOT EXIST %DATA_DIRECTORY% (
    echo Initially creating persistent directory: %DATA_DIRECTORY%
    mkdir %DATA_DIRECTORY%
)
IF NOT EXIST %CACHE_DIRECTORY% (
    echo Initially creating persistent directory: %CACHE_DIRECTORY%
    mkdir %CACHE_DIRECTORY%
)

rem Make sure we are using the latest version
docker pull owasp/dependency-check:%DC_VERSION%

docker run --rm ^
    --volume %CD%:/src ^
    --volume %DATA_DIRECTORY%:/usr/share/dependency-check/data ^
    --volume %CD%/odc-reports:/report ^
    owasp/dependency-check:%DC_VERSION% ^
    --scan /src ^
    --format "ALL" ^
    --project "%DC_PROJECT%" ^
    --out /report
    rem Use suppression like this: (where /src == %CD%)
    rem --suppression "/src/security/dependency-check-suppression.xml"
```

### [Building From Source](https://github.com/jeremylong/DependencyCheck#building-from-source)

To build dependency-check (using Java 8) run the command:

```
mvn -s settings.xml install

```

### [Running dependency-check on dependency-check](https://github.com/jeremylong/DependencyCheck#running-dependency-check-on-dependency-check)

Dependency-check references several vulnerable dependencies that are never used except as test resources. All of these optional test dependencies are included in the `test-dependencies` profile. To run dependency-check against itself simple exclude the `test-dependencies` profile:

```
mvn org.owasp:dependency-check-maven:aggregate -P-test-dependencies -DskipProvidedScope=true
```

### [Building the documentation](https://github.com/jeremylong/DependencyCheck#building-the-documentation)

The documentation on the [github pages](http://jeremylong.github.io/DependencyCheck/) is generated from this repository:

```
mvn -s settings.xml site  site:staging

```

Once done, point your browser to `./target/staging/index.html`.

### [Building The Docker Image](https://github.com/jeremylong/DependencyCheck#building-the-docker-image)

To build dependency-check docker image run the command:

```
mvn -s settings.xml install
./build-docker.sh

```

### [License](https://github.com/jeremylong/DependencyCheck#license)

Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. See the [LICENSE.txt](https://raw.githubusercontent.com/jeremylong/DependencyCheck/main/LICENSE.txt) file for the full license.

Dependency-Check makes use of several other open source libraries. Please see the [NOTICE.txt](https://github.com/jeremylong/DependencyCheck/blob/main/NOTICE.txt) file for more information.

Copyright (c) 2012-2023 Jeremy Long. All Rights Reserved.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.konstantinsecurity.com/readme/web-dev/dependency-checking/owasp-dependency-check.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.