# Trustify Dependency Analytics JavaScript Client<br/>![latest-no-snapshot][0] ![latest-snapshot][1]

* Looking for the OpenAPI Spec? Try [Trustify Dependency Analytics API](https://github.com/guacsec/trustify-da-api-spec)
* Looking for our Java API? Try [Trustify Dependency Analytics Java Client](https://github.com/guacsec/trustify-da-java-client).
* Looking for our Backend implementation? Try [Trustify Dependency Analytics](https://github.com/guacsec/trustify-dependency-analytics).

<h3>Usage</h3>
<p>

<strong>Prerequisites:</strong> Supply the Trustify Dependency Analytics backend URL through <code>options.TRUSTIFY_DA_BACKEND_URL</code> or the <code>TRUSTIFY_DA_BACKEND_URL</code> environment variable (see <a href="#customization">Customization</a>). Programmatic options take precedence over environment variables.

<ul>
<li>
Use as ESM Module from an ESM module

```shell
npm install @trustify-da/trustify-da-javascript-client
```

```shell
# Set the mandatory backend URL
export TRUSTIFY_DA_BACKEND_URL=https://trustify-da.example.com
```

```javascript
import client from '@trustify-da/trustify-da-javascript-client'
import fs from 'node:fs'

// Get stack analysis in JSON format
let stackAnalysis = await client.stackAnalysis('/path/to/pom.xml')
// Get stack analysis in HTML format (string)
let stackAnalysisHtml = await client.stackAnalysis('/path/to/pom.xml', true)
// Get component analysis in JSON format
let componentAnalysis = await client.componentAnalysis('/path/to/pom.xml')
// For monorepos, pass workspace root so the client finds the lock file
let monorepoOpts = { workspaceDir: '/path/to/workspace-root' }
let stackAnalysisMonorepo = await client.stackAnalysis('/path/to/package.json', false, monorepoOpts)
// Batch analysis for entire workspace (Cargo or JS/TS); optional parallel SBOM generation
let batchReport = await client.stackAnalysisBatch('/path/to/workspace-root', false, { batchConcurrency: 10 })
// Get image analysis in JSON format
let imageAnalysis = await client.imageAnalysis(['docker.io/library/node:18'])
// Get image analysis in HTML format (string)
let imageAnalysisHtml = await client.imageAnalysis(['docker.io/library/node:18'], true)
// Analyze multiple images
let multipleImagesAnalysis = await client.imageAnalysis(['docker.io/library/node:18', 'docker.io/library/python:3.9'])
// Specify architecture using ^^ notation (e.g., httpd:2.4.49^^amd64)
let imageAnalysisWithArch = await client.imageAnalysis(['httpd:2.4.49^^amd64'])
```
</li>
</ul>

<h3>License Detection</h3>
<p>
The client automatically detects your project's license with intelligent fallback:
</p>
<ul>
<li><strong>Manifest-first:</strong> For ecosystems with license support (Maven, JavaScript, Rust Cargo), reads from manifest file (<code>pom.xml</code>, <code>package.json</code>, <code>Cargo.toml</code>)</li>
<li><strong>LICENSE file fallback:</strong> If no license in manifest, or for ecosystems without license support (Gradle, Go, Python), automatically reads from <code>LICENSE</code>, <code>LICENSE.md</code>, or <code>LICENSE.txt</code></li>
<li><strong>SBOM integration:</strong> Detected licenses are included in generated SBOMs for all ecosystems</li>
<li><strong>SPDX support:</strong> Automatically detects common licenses (Apache-2.0, MIT, GPL, BSD) from LICENSE file content</li>
</ul>
<p>
See <a href="./docs/license-resolution-and-compliance.md">License Resolution and Compliance</a> for detailed documentation.
</p>

<ul>
<li>
Use as ESM Module from Common-JS module

```shell
npm install @trustify-da/trustify-da-javascript-client
```

```javascript
async function loadTrustifyDa()
{
// dynamic import is the only way to import ESM module into commonJS module
  const { default: client } = await import('@trustify-da/trustify-da-javascript-client');
  return client
}
const runTrustifyDa = (manifestPath) => {
  return new Promise(async ( resolve, reject) => {
    try {
      let stackAnalysisReport = await (await loadTrustifyDa()).stackAnalysis(manifestPath,false)
      resolve(stackAnalysisReport)

    } catch (error)
    {
      reject(error)
    }
  });
};

runTrustifyDa("./path/to/manifest").then(resp => console.log(JSON.stringify(resp,null,4)))
```
</li>

<li>
Use as CLI Script
<details>
<summary>Click for help menu</summary>

```shell
$ npx @trustify-da/trustify-da-javascript-client help

Usage: trustify-da-javascript-client {component|stack|stack-batch|image|validate-token|license|sbom|remediate}

Commands:
  trustify-da-javascript-client stack </path/to/manifest> [--workspace-dir <path>] [--html|--summary]               produce stack report for manifest path
  trustify-da-javascript-client stack-batch </path/to/workspace-root> [--html|--summary]   produce stack report for all packages/crates in workspace
  trustify-da-javascript-client component <path/to/manifest> [--workspace-dir <path>]   produce component report for a manifest type and content
  trustify-da-javascript-client image <image-refs..> [--html|--summary]               produce image analysis report for OCI image references
  trustify-da-javascript-client validate-token <token-provider> [--token-value <value>]   validate input token if authentic and authorized
  trustify-da-javascript-client license </path/to/manifest>               display project license information from manifest and LICENSE file in JSON format
  trustify-da-javascript-client sbom </path/to/manifest> [--output <file>]               generate a CycloneDX SBOM from a manifest file
  trustify-da-javascript-client remediate <path> [--dry-run] [--providers <list>] [--sources <list>] [--group-by <strategy>] [--exclude <purl>...]   scan and apply vulnerability remediations

Options:
  --help  Show help                                                    [boolean]
```
</details>

```shell
# get stack analysis in json format
$ npx @trustify-da/trustify-da-javascript-client stack /path/to/pom.xml

# get stack analysis in json format (summary only)
$ npx @trustify-da/trustify-da-javascript-client stack /path/to/pom.xml --summary

# get stack analysis in html format format
$ npx @trustify-da/trustify-da-javascript-client stack /path/to/pom.xml --html

# get stack analysis for monorepo (lock file at workspace root)
$ npx @trustify-da/trustify-da-javascript-client stack /path/to/package.json --workspace-dir /path/to/workspace-root

# get component analysis
$ npx @trustify-da/trustify-da-javascript-client component /path/to/pom.xml

# get component analysis for monorepo
$ npx @trustify-da/trustify-da-javascript-client component /path/to/package.json -w /path/to/workspace-root

# batch stack analysis for entire workspace (Cargo or JS/TS)
$ npx @trustify-da/trustify-da-javascript-client stack-batch /path/to/workspace-root

# optional: extra discovery excludes (merged with defaults); repeat --ignore or use TRUSTIFY_DA_WORKSPACE_DISCOVERY_IGNORE
$ npx @trustify-da/trustify-da-javascript-client stack-batch /path/to/workspace-root --ignore '**/fixtures/**'

# get image analysis in json format
$ npx @trustify-da/trustify-da-javascript-client image docker.io/library/node:18

# get image analysis in json format (summary only)
# Note: summary returns an object with imageRef as key
$ npx @trustify-da/trustify-da-javascript-client image docker.io/library/node:18 --summary

# get image analysis in html format
$ npx @trustify-da/trustify-da-javascript-client image docker.io/library/node:18 --html

# analyze multiple images
$ npx @trustify-da/trustify-da-javascript-client image docker.io/library/node:18 docker.io/library/python:3.9

# specify architecture using ^^ notation (e.g., httpd:2.4.49^^amd64)
$ npx @trustify-da/trustify-da-javascript-client image httpd:2.4.49^^amd64

# get project license information
$ npx @trustify-da/trustify-da-javascript-client license /path/to/package.json

# generate a CycloneDX SBOM from a manifest file
$ npx @trustify-da/trustify-da-javascript-client sbom /path/to/pom.xml

# generate SBOM and write to a file
$ npx @trustify-da/trustify-da-javascript-client sbom /path/to/pom.xml --output sbom.json

# scan a manifest and apply vulnerability remediations
$ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml

# preview remediations without modifying files
$ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml --dry-run

# scan a directory for all supported manifests
$ npx @trustify-da/trustify-da-javascript-client remediate /path/to/project/

# filter by vulnerability providers (order determines priority)
$ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml --providers provider1,provider2

# group report output by bundle instead of per-dependency
$ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml --dry-run --group-by bundle

# exclude specific dependencies or groups from remediation (repeat --exclude per entry)
$ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml --exclude pkg:maven/com.example/legacy-lib
$ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml --exclude 'pkg:maven/com.example/*' --exclude 'pkg:npm/**'
```
</li>

<li>
Use as Global Binary

```shell
npm install --global @trustify-da/trustify-da-javascript-client
```

```shell
# get stack analysis in json format
$ trustify-da-javascript-client stack /path/to/pom.xml

# get stack analysis in json format (summary only)
$ trustify-da-javascript-client stack /path/to/pom.xml --summary

# get stack analysis in html format format
$ trustify-da-javascript-client stack /path/to/pom.xml --html

# get stack analysis for monorepo (lock file at workspace root)
$ trustify-da-javascript-client stack /path/to/package.json --workspace-dir /path/to/workspace-root

# get component analysis
$ trustify-da-javascript-client component /path/to/pom.xml

# get component analysis for monorepo
$ trustify-da-javascript-client component /path/to/package.json -w /path/to/workspace-root

# batch stack analysis for entire workspace
$ trustify-da-javascript-client stack-batch /path/to/workspace-root

# with extra discovery excludes
$ trustify-da-javascript-client stack-batch /path/to/workspace-root -i '**/vendor/**'

# get image analysis in json format
$ trustify-da-javascript-client image docker.io/library/node:18

# get image analysis in json format (summary only)
# Note: summary returns an object with imageRef as key
$ trustify-da-javascript-client image docker.io/library/node:18 --summary

# get image analysis in html format
$ trustify-da-javascript-client image docker.io/library/node:18 --html

# analyze multiple images
$ trustify-da-javascript-client image docker.io/library/node:18 docker.io/library/python:3.9

# specify architecture using ^^ notation (e.g., httpd:2.4.49^^amd64)
$ trustify-da-javascript-client image httpd:2.4.49^^amd64

# get project license information
$ trustify-da-javascript-client license /path/to/package.json

# generate a CycloneDX SBOM from a manifest file
$ trustify-da-javascript-client sbom /path/to/pom.xml

# generate SBOM and write to a file
$ trustify-da-javascript-client sbom /path/to/pom.xml --output sbom.json

# scan a manifest and apply vulnerability remediations
$ trustify-da-javascript-client remediate /path/to/pom.xml

# preview remediations without modifying files
$ trustify-da-javascript-client remediate /path/to/pom.xml --dry-run

# scan a directory for all supported manifests
$ trustify-da-javascript-client remediate /path/to/project/

# filter by vulnerability providers (order determines priority)
$ trustify-da-javascript-client remediate /path/to/pom.xml --providers provider1,provider2

# group report output by bundle instead of per-dependency
$ trustify-da-javascript-client remediate /path/to/pom.xml --dry-run --group-by bundle

# exclude specific dependencies or groups from remediation (repeat --exclude per entry)
$ trustify-da-javascript-client remediate /path/to/pom.xml --exclude pkg:maven/com.example/legacy-lib
$ trustify-da-javascript-client remediate /path/to/pom.xml --exclude 'pkg:maven/com.example/*' --exclude 'pkg:npm/**'
```
</li>
</ul>

<h3>Supported Ecosystems</h3>
<ul>
<li><a href="https://www.java.com/">Java</a> - <a href="https://maven.apache.org/">Maven</a></li>
<li><a href="https://www.javascript.com/">JavaScript</a> - <a href="https://www.npmjs.com/">Npm</a></li>
<li><a href="https://www.javascript.com/">JavaScript</a> - <a href="https://pnpm.io/">pnpm</a></li>
<li><a href="https://www.javascript.com/">JavaScript</a> - <a href="https://classic.yarnpkg.com/">Yarn Classic</a> /  <a href="https://yarnpkg.com/">Yarn Berry</a></li>
<li><a href="https://go.dev/">Golang</a> - <a href="https://go.dev/blog/using-go-modules/">Go Modules</a></li>
<li><a href="https://www.python.org/">Python</a> - <a href="https://pypi.org/project/pip/">pip Installer</a> (<code>requirements.txt</code>)</li>
<li><a href="https://www.python.org/">Python</a> - <a href="https://python-poetry.org/">Poetry</a> / <a href="https://docs.astral.sh/uv/">uv</a> (<code>pyproject.toml</code>)</li>
<li><a href="https://gradle.org/">Gradle (Groovy and Kotlin DSL)</a> - <a href="https://gradle.org/install/">Gradle Installation</a></li>
<li><a href="https://www.rust-lang.org/">Rust</a> - <a href="https://doc.rust-lang.org/cargo/">Cargo</a></li>
</ul>

<h3>Dockerfile Analysis Prerequisites</h3>
<p>
OCI image and <code>Dockerfile</code>/<code>Containerfile</code> analysis require the following external tools to be installed and available on your <code>PATH</code>:
</p>
<ul>
<li><a href="https://github.com/anchore/syft">Syft</a> — generates the image SBOM.</li>
<li><a href="https://github.com/containers/skopeo">skopeo</a> — resolves the image digest and manifest from the registry.</li>
</ul>
<p>
<strong>Dockerfile analysis is not supported on Windows</strong>, because <code>skopeo</code> provides no native Windows binary.
</p>

<h3>License Detection</h3>
<p>
The client automatically detects your project's license with intelligent fallback:
</p>
<ul>
<li><strong>Manifest-first:</strong> For ecosystems with license support (Maven, JavaScript, Rust Cargo), reads from manifest file (<code>pom.xml</code>, <code>package.json</code>, <code>Cargo.toml</code>)</li>
<li><strong>LICENSE file fallback:</strong> If no license in manifest, or for ecosystems without license support (Gradle, Go, Python), automatically reads from <code>LICENSE</code>, <code>LICENSE.md</code>, or <code>LICENSE.txt</code></li>
<li><strong>SBOM integration:</strong> Detected licenses are included in generated SBOMs for all ecosystems</li>
<li><strong>SPDX support:</strong> Automatically detects common licenses (Apache-2.0, MIT, GPL, BSD) from LICENSE file content</li>
</ul>
<p>
See <a href="./docs/license-resolution-and-compliance.md">License Resolution and Compliance</a> for detailed documentation.
</p>


<h3>Excluding Packages</h3>
<p>
Excluding a package from any analysis can be achieved by marking the package for exclusion.
</p>

<ul>
<li>
<em>Java Maven</em> users can add a comment in <em>pom.xml</em>

```xml
<dependency> <!--exhortignore-->
  <groupId>...</groupId>
  <artifactId>...</artifactId>
  <version>...</version>
</dependency>
```
</li>

</ul>
<ul>
<li>
<em>Javascript</em> users can add a root (key, value) pair with value of list of names (strings) to be ignored (without versions), and key called <b>exhortignore</b> in <em>package.json</em>,  example:

```json
{
  "name": "sample",
  "version": "1.0.0",
  "description": "",
  "main": "js",
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "dotenv": "^8.2.0",
    "express": "^4.17.1",
    "jsonwebtoken": "^8.5.1",
    "mongoose": "^5.9.18"
  },
  "exhortignore": [
    "jsonwebtoken"
  ]
}
```
</li>

<li>
<em>Golang</em> users can add in go.mod a comment with <code>// exhortignore</code> next to the package to be ignored, or to "piggyback" on existing comment ( e.g - <code>// indirect</code>), for example:

```go
module github.com/trustify-da/SaaSi/deployer

go 1.19

require (
        github.com/gin-gonic/gin v1.9.1
        github.com/google/uuid v1.1.2
        github.com/jessevdk/go-flags v1.5.0 // exhortignore
        github.com/kr/pretty v0.3.1
        gopkg.in/yaml.v2 v2.4.0
        k8s.io/apimachinery v0.26.1
        k8s.io/client-go v0.26.1
)

require (
        github.com/davecgh/go-spew v1.1.1 // indirect; exhortignore
        github.com/emicklei/go-restful/v3 v3.9.0 // indirect
        github.com/go-logr/logr v1.2.3 // indirect; exhortignore

)
```

<b>NOTE</b>: It is important to format <code>exhortignore</code> markers on indirect dependencies as shown above, otherwise the Go tooling (as well as this library) may incorrectly parse dependencies marked as indirect as being direct dependencies instead.
</li>


<li>
<em>Python pip</em> users can add in requirements.txt a comment with #exhortignore(or # exhortignore) to the right of the same artifact to be ignored, for example:

```properties
anyio==3.6.2
asgiref==3.4.1
beautifulsoup4==4.12.2
certifi==2023.7.22
chardet==4.0.0
click==8.0.4 #exhortignore
contextlib2==21.6.0
fastapi==0.75.1
Flask==2.0.3
h11==0.13.0
idna==2.10
immutables==0.19
importlib-metadata==4.8.3
itsdangerous==2.0.1
Jinja2==3.0.3
MarkupSafe==2.0.1
pydantic==1.9.2 # exhortignore
requests==2.25.1
six==1.16.0
sniffio==1.2.0
soupsieve==2.3.2.post1
starlette==0.17.1
typing_extensions==4.1.1
urllib3==1.26.16
uvicorn==0.17.0
Werkzeug==2.0.3
zipp==3.6.0

```
</li>

<li>
<em>Gradle</em> users can add in build.gradle a comment with //exhortignore next to the package to be ignored:

```build.gradle
plugins {
    id 'java'
}

group = 'groupName'
version = 'version'

repositories {
    mavenCentral()
}

dependencies {
    implementation "groupId:artifactId:version" // exhortignore
}
test {
    useJUnitPlatform()
}
```

<em>Rust Cargo</em> users can add a comment with <code># trustify-da-ignore</code> (or <code># exhortignore</code>) in <em>Cargo.toml</em> next to the dependency to be ignored. This works for inline declarations, table-based declarations, and workspace-level dependency sections:

```toml
[dependencies]
serde = "1.0" # trustify-da-ignore
tokio = { version = "1.35", features = ["full"] }

[dependencies.regex] # trustify-da-ignore
version = "1.10"

[workspace.dependencies]
log = "0.4" # trustify-da-ignore
```


<em>Python pyproject.toml</em> users can add a comment with <code>#exhortignore</code> (or <code># trustify-da-ignore</code>) next to the dependency in <code>pyproject.toml</code>.

PEP 621 style (<code>[project]</code> dependencies):
```toml
[project]
dependencies = [
    "flask>=2.0.3",
    "requests>=2.25.1",
    "uvicorn>=0.17.0", #exhortignore
    "click>=8.0.4", # trustify-da-ignore
]
```

Poetry style (<code>[tool.poetry.dependencies]</code>):
```toml
[tool.poetry.dependencies]
flask = "^2.0.3"
requests = "^2.25.1"
uvicorn = "^0.17.0" #exhortignore
click = "^8.0.4" # trustify-da-ignore
```

All of the above examples are valid for marking a package to be ignored
</li>
</ul>

<h3>Customization</h3>
<p>
There are two approaches for customizing <em>Trustify Dependency Analytics JavaScript Client</em>. Whether you're using this API as a
<em>Global Module</em>, a <em>Remote Script</em>, or an <em>ESM Module</em>, you can use <em>Environment Variables</em>
for various customization. <em>ESM Module</em> users can also pass programmatic options.

<strong>Precedence:</strong> Programmatic options override environment variables, which override built-in defaults. A backend URL supplied through either <code>options.TRUSTIFY_DA_BACKEND_URL</code> or <code>TRUSTIFY_DA_BACKEND_URL</code> is mandatory.

Example programmatic customization:

```javascript
import client from '@trustify-da/trustify-da-javascript-client'
import fs from 'node:fs'

let options = {
  // Mandatory: Backend URL for Trustify Dependency Analytics service
  'TRUSTIFY_DA_BACKEND_URL': 'https://api.trustify.dev',
  'TRUSTIFY_DA_MVN_PATH': '/path/to/my/mvn',
  'TRUSTIFY_DA_NPM_PATH': '/path/to/npm',
  'TRUSTIFY_DA_PNPM_PATH': '/path/to/pnpm',
  'TRUSTIFY_DA_GO_PATH': '/path/to/go',
  //python - python3, pip3 take precedence if python version > 3 installed
  'TRUSTIFY_DA_PYTHON3_PATH' : '/path/to/python3',
  'TRUSTIFY_DA_PIP3_PATH' : '/path/to/pip3',
  'TRUSTIFY_DA_PYTHON_PATH' : '/path/to/python',
  'TRUSTIFY_DA_PIP_PATH' : '/path/to/pip',
  'TRUSTIFY_DA_UV_PATH' : '/path/to/uv',
  'TRUSTIFY_DA_POETRY_PATH' : '/path/to/poetry',
  'TRUSTIFY_DA_GRADLE_PATH' : '/path/to/gradle',
  'TRUSTIFY_DA_CARGO_PATH' : '/path/to/cargo',
  // Workspace root for monorepos (Cargo, npm/pnpm/yarn); lock file expected here
  'workspaceDir': '/path/to/workspace-root',
  // Configure proxy for all requests
  'TRUSTIFY_DA_PROXY_URL': 'http://proxy.example.com:8080'
}

// Get stack analysis in JSON format ( all package managers, pom.xml is as an example here)
let stackAnalysis = await client.stackAnalysis('/path/to/pom.xml', false, options)
// Get stack analysis in HTML format in string ( all package managers, pom.xml is as an example here)
let stackAnalysisHtml = await client.stackAnalysis('/path/to/pom.xml', true, options)

// Get component analysis in JSON format
let componentAnalysis = await client.componentAnalysis('/path/to/pom.xml', options)

// Get image analysis in JSON format
let imageAnalysis = await client.imageAnalysis(['docker.io/library/node:18'], false, options)
// Get image analysis in HTML format in string
let imageAnalysisHtml = await client.imageAnalysis(['docker.io/library/node:18'], true, options)
// Specify architecture using ^^ notation (e.g., httpd:2.4.49^^amd64)
let imageAnalysisWithArch = await client.imageAnalysis(['httpd:2.4.49^^amd64'], false, options)
```
 **_Programmatic options take precedence over environment variables._**
</p>

<h4>Monorepo / Workspace Support</h4>
<p>
For monorepos (Cargo workspaces, npm/pnpm/yarn workspaces) where the lock file lives at the workspace root rather than next to the manifest, pass the workspace root via <code>workspaceDir</code> or <code>TRUSTIFY_DA_WORKSPACE_DIR</code>:
</p>
<ul>
<li><strong>Cargo:</strong> When set, the client checks only the given directory for <code>Cargo.lock</code> instead of walking up from the manifest.</li>
<li><strong>JavaScript (npm, pnpm, yarn):</strong> When set, the client looks for the lock file (<code>package-lock.json</code>, <code>pnpm-lock.yaml</code>, <code>yarn.lock</code>) at the workspace root.</li>
</ul>
<p>
Use <code>stackAnalysisBatch(workspaceRoot, html, opts)</code> to analyze all packages/crates in a workspace in one request. Supports Cargo workspaces and JS/TS workspaces (pnpm, npm, yarn). Optional <code>batchConcurrency</code> (or <code>TRUSTIFY_DA_BATCH_CONCURRENCY</code>) limits parallel SBOM generation (default 10). For JS/TS, each <code>package.json</code> must have non-empty <code>name</code> and <code>version</code>; invalid manifests are skipped (warnings). Per-manifest SBOM failures are skipped if at least one SBOM succeeds (unless <code>continueOnError: false</code>). Set <code>batchMetadata: true</code> (or <code>TRUSTIFY_DA_BATCH_METADATA</code>) to receive <code>{ analysis, metadata }</code> with <code>errors[]</code>. CLI: <code>stack-batch --metadata</code>, <code>--fail-fast</code>. See <a href="./docs/monorepo-implementation-plan.md">monorepo implementation plan</a> §2.3 and §3.5.
</p>
<p>
See <a href="./docs/vscode-extension-integration-requirements.md">VS Code Extension Integration Requirements</a> for integration details.
</p>

<h4>Proxy Configuration</h4>
<p>
You can configure a proxy for all HTTP/HTTPS requests made by the API. This is useful when your environment requires going through a proxy to access external services.

You can set the proxy URL in two ways:

1. Using environment variable:
```shell
export TRUSTIFY_DA_PROXY_URL=http://proxy.example.com:8080
```

2. Using the options object when calling the API programmatically:
```javascript
const options = {
  'TRUSTIFY_DA_PROXY_URL': 'http://proxy.example.com:8080'
}
```

When both are supplied, <code>options.TRUSTIFY_DA_PROXY_URL</code> takes precedence over the environment variable.

The proxy URL should be in the format: `http://host:port` or `https://host:port`. The API will automatically use the appropriate protocol (HTTP or HTTPS) based on the proxy URL provided.
</p>

<h4>License resolution and dependency license compliance</h4>
<p>
The client can resolve the <strong>project license</strong> from the manifest (e.g. <code>package.json</code> <code>license</code>, <code>pom.xml</code> <code>&lt;licenses&gt;</code>, <code>Cargo.toml</code> <code>license</code>) and from a <code>LICENSE</code> or <code>LICENSE.md</code> file in the project, and report when they differ. For <strong>component analysis</strong>, you can optionally run a license check: the client fetches dependency licenses from the backend (by purl) and reports dependencies whose licenses are incompatible with the project license. See <a href="docs/license-resolution-and-compliance.md">License resolution and compliance</a> for design and behavior. To disable the check on component analysis, set <code>TRUSTIFY_DA_LICENSE_CHECK=false</code> or pass <code>licenseCheck: false</code> in the options. An explicit <code>licenseCheck</code> option takes precedence over the environment variable.
</p>

<h4>Customizing Executables</h4>
<p>
This project uses each ecosystem's executable for creating dependency trees. These executables are expected to be
present on the system's PATH environment. If they are not, or perhaps you want to use custom ones. Use can use the
following keys for setting custom paths for the said executables.
</p>

<table>
<tr>
<th>Ecosystem</th>
<th>Default</th>
<th>Executable Key</th>
</tr>
<tr>
<td><a href="https://maven.apache.org/">Maven</a></td>
<td><em>mvn</em></td>
<td>TRUSTIFY_DA_MVN_PATH</td>
</tr>
<tr>
<td><a href="https://maven.apache.org/">Maven</a></td>
<td><em>maven</em></td>
<td>TRUSTIFY_DA_PREFER_MVNW</td>
</tr>
<tr>
<td><a href="https://www.npmjs.com/">NPM</a></td>
<td><em>npm</em></td>
<td>TRUSTIFY_DA_NPM_PATH</td>
</tr>
<tr>
<td><a href="https://pnpm.io/">PNPM</a></td>
<td><em>pnpm</em></td>
<td>TRUSTIFY_DA_PNPM_PATH</td>
</tr>
<tr>
<td><a href="https://classic.yarnpkg.com/">Yarn Classic</a> / <a href="https://yarnpkg.com/">Yarn Berry</a></td>
<td><em>yarn</em></td>
<td>TRUSTIFY_DA_YARN_PATH</td>
</tr>
<tr>
<td><a href="https://go.dev/blog/using-go-modules/">Go Modules</a></td>
<td><em>go</em></td>
<td>TRUSTIFY_DA_GO_PATH</td>
</tr>
<tr>
<td><a href="https://www.python.org/">Python programming language</a></td>
<td><em>python3</em></td>
<td>TRUSTIFY_DA_PYTHON3_PATH</td>
</tr>
<tr>
<td><a href="https://pypi.org/project/pip/">Python pip Package Installer</a></td>
<td><em>pip3</em></td>
<td>TRUSTIFY_DA_PIP3_PATH</td>
</tr>
<tr>
<td><a href="https://www.python.org/">Python programming language</a></td>
<td><em>python</em></td>
<td>TRUSTIFY_DA_PYTHON_PATH</td>
</tr>
<tr>
<td><a href="https://pypi.org/project/pip/">Python pip Package Installer</a></td>
<td><em>pip</em></td>
<td>TRUSTIFY_DA_PIP_PATH</td>
</tr>
<tr>
<td><a href="https://gradle.org/">Gradle</a></td>
<td><em>gradle</em></td>
<td>TRUSTIFY_DA_GRADLE_PATH</td>
</tr>
<tr>
<td><a href="https://gradle.org/">Gradle</a></td>
<td><em>gradle</em></td>
<td>TRUSTIFY_DA_PREFER_GRADLEW</td>
</tr>
<tr>
<td><a href="https://www.rust-lang.org/">Rust Cargo</a></td>
<td><em>cargo</em></td>
<td>TRUSTIFY_DA_CARGO_PATH</td>
</tr>
<tr>
<td><a href="https://docs.astral.sh/uv/">uv</a></td>
<td><em>uv</em></td>
<td>TRUSTIFY_DA_UV_PATH</td>
</tr>
<tr>
<td><a href="https://python-poetry.org/">Poetry</a></td>
<td><em>poetry</em></td>
<td>TRUSTIFY_DA_POETRY_PATH</td>
</tr>
<tr>
<td>Workspace root (monorepos)</td>
<td>—</td>
<td>workspaceDir / TRUSTIFY_DA_WORKSPACE_DIR</td>
</tr>
</table>

#### Match Manifest Versions Feature

##### Background

In Python pip and in golang go modules package managers ( especially in Python pip) , There is a big chance that for a certain manifest and a given package inside it, the client machine environment has different version installed/resolved
for that package, which can lead to perform the analysis on the installed packages' versions , instead on the declared versions ( in manifests - that is requirements.txt/go.mod ), and this
can cause a confusion for the user in the client consuming the API and leads to inconsistent output ( in THE manifest there is version X For a given Package `A` , and in the analysis report there is another version for the same package `A` - Y).

##### Usage

To eliminate confusion and improve clarity as discussed above, the following setting was introduced - `MATCH_MANIFEST_VERSIONS`, in the form of an environment variable or key in opts. When both are supplied, the value in opts takes precedence.
for two ecosystems:
 - Golang - Go Modules
 - Python - pip

Two possible values for this setting:

1. MATCH_MANIFEST_VERSIONS="false" - means that if installed/resolved versions of packages are different than the ones declared in the manifest, the process will ignore this difference and will continue to analysis with installed/resolved versions ( this is the original logic flow )
<br>


2. MATCH_MANIFEST_VERSIONS="true" - means that before starting the analysis,
   the api will compare all the versions of packages in manifest against installed/resolved versions on client' environment, in case there is a difference, it will throw an error to the client/user with message containing the first encountered versions mismatch, including package name, and the versions difference, and will suggest to set setting `MATCH_MANIFEST_VERSIONS`="false" to ignore all differences

#### Golang Support

By default, Golang dependency resolution follows the [Minimal Version Selection (MVS) Algorithm](https://go.dev/ref/mod#minimal-version-selection).
This means that when analyzing a project, only the module versions that would actually be included in the final executable are considered.

For example, if your `go.mod` file declares two modules, `a` and `b`, and both depend on the same package `c` (same major version `v1`) but with different minor versions:

- `namespace/c/v1@v1.1`
- `namespace/c/v1@v1.2`

Only one of these versions — the minimal version selected by MVS — will be included in the generated SBOM and analysis results.
This mirrors the behavior of a real Go build, where only one minor version of a given major version can be present in the executable (since Go treats packages with the same name and major version as identical).

The MVS-based resolution is **enabled by default**.
If you want to disable this behavior and instead include **all transitive module versions** (as listed in `go.mod` dependencies), set the system property or environment variable:

```bash
TRUSTIFY_DA_GO_MVS_LOGIC_ENABLED=false
```

#### Python Support

The client supports two Python manifest formats:

- **`requirements.txt`** — uses pip/pip3 to resolve dependencies
- **`pyproject.toml`** — uses [uv](https://docs.astral.sh/uv/) or [Poetry](https://python-poetry.org/) to resolve dependencies

##### pyproject.toml

For `pyproject.toml` projects, the client detects which tool manages the project by checking for lock files:
- If `poetry.lock` is present and `[tool.poetry]` is defined, **Poetry** is used (`poetry show --tree` and `poetry show --all`)
- If `uv.lock` is present, **uv** is used (`uv export --format requirements.txt --frozen --no-hashes`)
- If neither lock file is found, an error is thrown

Both PEP 621 (`[project]` dependencies) and Poetry-style (`[tool.poetry.dependencies]`) are supported.

Custom executable paths can be set via `TRUSTIFY_DA_UV_PATH` and `TRUSTIFY_DA_POETRY_PATH`.

##### requirements.txt

By default, For python support, the api assumes that the package is installed using the pip/pip3 binary on the system PATH, or using the customized
Binaries passed to environment variables. In any case, If the package is not installed , then an error will be thrown.

There is an experimental feature of installing the requirements.txt on a virtual env(only python3 or later is supported for this feature) - in this case,
it's important to pass in a path to python3 binary as `TRUSTIFY_DA_PYTHON3_PATH` or instead make sure that python3 is on the system path.
in such case, You can use that feature by setting environment variable `TRUSTIFY_DA_PYTHON_VIRTUAL_ENV` to true.

##### "Best Efforts Installation"
Since Python pip packages are very sensitive/picky regarding python version changes( every small range of versions is only tailored for a certain python version), I'm introducing this feature, that
tries to install all packages in requirements.txt onto created virtual environment while **disregarding** versions declared for packages in requirements.txt.
This increasing the chances and the probability that the automatic installation will succeed.

###### Usage
A New setting is introduced - `TRUSTIFY_DA_PYTHON_INSTALL_BEST_EFFORTS` (as both env variable/key in `options` object)
1. `TRUSTIFY_DA_PYTHON_INSTALL_BEST_EFFORTS`="false" - install requirements.txt while respecting declared versions for all packages.
2. `TRUSTIFY_DA_PYTHON_INSTALL_BEST_EFFORTS`="true" - install all packages from requirements.txt, not respecting the declared version, but trying to install a version tailored for the used python version. When using this setting, you must set `TRUSTIFY_DA_PYTHON_VIRTUAL_ENV` to 'true' and `MATCH_MANIFEST_VERSIONS` to 'false'.

##### Using `pipdeptree`
By default, The API algorithm will use native commands of PIP installer as data source to build the dependency tree.
It's also possible to use the lightweight Python PIP utility [pipdeptree](https://pypi.org/project/pipdeptree/) as data source instead. In order to activate this, you need to set the environment variable/option `TRUSTIFY_DA_PIP_USE_DEP_TREE` to 'true'.

#### Toggle Red Hat Trusted Content recommendations
Both the HTML-based report and JSON response will by default contain recommendations for migrating to Red Hat-based Trusted Content repositories. This feature can be disabled by setting `TRUSTIFY_DA_RECOMMEND` to 'false' via environment variables or options.

#### Additional CLI arguments
For some ecosystems we support passing additional CLI arguments to the underlying tools. The following table outlines the supported ecosystems and the environment variable/option that configures this. Note that the arguments are expected to be in the format of a JSON array.

|Ecosystem|Key            |
|---------|---------------|
|Maven    |TRUSTIFY_DA_MVN_ARGS|


<h3>Remediation</h3>
<p>
The <code>remediate</code> command scans manifest files for known vulnerabilities and applies version upgrades to resolve them. By default, it modifies manifest files in place. Use <code>--dry-run</code> to preview changes without modifying any files.
</p>

<h4>Supported Manifest Formats</h4>
<ul>
<li><strong>Maven</strong> — <code>pom.xml</code> (single-module projects; updates dependency version elements and resolves property references)</li>
<li><strong>Gradle Version Catalog</strong> — <code>libs.versions.toml</code> or any <code>*.versions.toml</code> file (updates centralized version references and inline version declarations)</li>
</ul>

<h4>CLI Flags</h4>
<table>
<tr>
<th>Flag</th>
<th>Alias</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td><code>&lt;path&gt;</code></td>
<td>—</td>
<td>string (positional)</td>
<td><em>required</em></td>
<td>Path to a manifest file or directory to scan recursively</td>
</tr>
<tr>
<td><code>--dry-run</code></td>
<td><code>-d</code></td>
<td>boolean</td>
<td><code>false</code></td>
<td>Preview changes without modifying files</td>
</tr>
<tr>
<td><code>--providers</code></td>
<td>—</td>
<td>string</td>
<td>—</td>
<td>Comma-separated list of vulnerability providers (env: <code>TRUSTIFY_DA_PROVIDERS</code>)</td>
</tr>
<tr>
<td><code>--sources</code></td>
<td>—</td>
<td>string</td>
<td>—</td>
<td>Comma-separated list of vulnerability sources (env: <code>TRUSTIFY_DA_SOURCES</code>)</td>
</tr>
<tr>
<td><code>--group-by</code></td>
<td>—</td>
<td>string</td>
<td><code>dependency</code></td>
<td>Report grouping strategy (<code>dependency</code> or <code>bundle</code>)</td>
</tr>
<tr>
<td><code>--exclude</code></td>
<td>—</td>
<td>string[]</td>
<td>—</td>
<td>Version-less purl glob patterns to exclude from remediation. <code>*</code> matches within a segment, <code>**</code> crosses segments. Repeat flag per entry.</td>
</tr>
</table>

<h4>Provider Priority Resolution</h4>
<p>
When multiple vulnerability providers suggest different remediation versions for the same dependency, the <code>--providers</code> flag determines priority. Providers listed first have the highest priority.
</p>
<ul>
<li>The provider ordering in <code>--providers</code> determines rank (first = highest priority).</li>
<li>Trustify vendor trusted packages always take precedence over non-trusted content at equal provider rank.</li>
<li>Two version selection strategies are used internally:
  <ul>
  <li><strong>Closest coverage</strong> (default) — prefers the remediation version closest to the current version within the same major version.</li>
  <li><strong>Highest</strong> — always selects the highest available remediation version.</li>
  </ul>
</li>
</ul>

<h4>Exit Codes</h4>
<ul>
<li><code>0</code> — no remediations needed, or remediations applied successfully</li>
<li><code>1</code> — error during execution</li>
<li><code>2</code> — remediations available (only returned in <code>--dry-run</code> mode when changes would be made; never returned when changes are applied)</li>
</ul>

<h4>Known Limitations</h4>
<ul>
<li>Gradle DSL files (<code>build.gradle</code>, <code>build.gradle.kts</code>) are not supported — only version catalog files (<code>*.versions.toml</code>).</li>
<li>Multi-module Maven projects with inherited dependency versions from parent POMs are not supported — only versions declared directly in the scanned <code>pom.xml</code> are updated.</li>
</ul>

<h4>Example: GitHub Action Workflow</h4>
<p>
The following workflow runs a scheduled remediation scan using the container image and opens a pull request with any version updates. Save this as <code>.github/workflows/trustify-da-remediation.yml</code> in your repository:
</p>

```yaml
name: Trustify DA Remediation Scan

on:
  schedule:
    # Run weekly on Monday at 08:00 UTC
    - cron: '0 8 * * 1'
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  remediate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run remediation scan
        uses: docker://ghcr.io/guacsec/trustify-da-javascript-client:latest
        env:
          TRUSTIFY_DA_BACKEND_URL: ${{ secrets.TRUSTIFY_DA_BACKEND_URL }}
        with:
          args: remediate . --providers provider1,provider2

      - name: Create pull request
        uses: peter-evans/create-pull-request@v7
        with:
          title: 'fix(deps): apply Trustify DA vulnerability remediations'
          body: |
            Automated dependency version updates from Trustify Dependency Analytics.

            This PR was generated by a scheduled remediation scan.
          branch: trustify-da-remediation
          commit-message: 'fix(deps): apply Trustify DA vulnerability remediations'
```

<!-- Badge links -->
[0]: https://img.shields.io/github/v/release/guacsec/trustify-da-javascript-client?color=green&label=latest
[1]: https://img.shields.io/github/v/release/guacsec/trustify-da-javascript-client?color=yellow&include_prereleases&label=early-access

### Known Issues

- For pip requirements.txt - It's been observed that for python versions 3.11.x, there might be slowness for invoking the analysis.
  If you encounter a performance issue with version >= 3.11.x, kindly try to set environment variable/option `TRUSTIFY_DA_PIP_USE_DEP_TREE=true`, before calling the analysis.


- For maven pom.xml, it has been noticed that using java 17 might cause stack analysis to hang forever.
  This is caused by maven [`dependency` plugin](https://maven.apache.org/plugins/maven-dependency-plugin/) bug when running with JDK/JRE' JVM version 17.

  To overcome this, you can use any other java version (14,20,21, etc..). ( best way is to install JDK/JRE version different from 17 , and set the location of the installation in environment variable `JAVA_HOME` so maven will use it.)
