@trustify-da/trustify-da-javascript-client 0.3.0-ea.e12bc82 → 0.3.0-ea.e258fba

package/README.md

@@ -32,6 +32,11 @@ let stackAnalysis = await client.stackAnalysis('/path/to/pom.xml')
 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)
@@ -43,6 +48,21 @@ 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
@@ -83,12 +103,17 @@ Use as CLI Script
 ```shell
 $ npx @trustify-da/trustify-da-javascript-client help
 
-Usage: trustify-da-javascript-client {component|stack|image|validate-token}
+Usage: trustify-da-javascript-client {component|stack|stack-batch|image|validate-token|license|sbom|remediate}
 
 Commands:
-  trustify-da-javascript-client stack </path/to/manifest> [--html|--summary]               produce stack report for manifest path
-  trustify-da-javascript-client component <path/to/manifest> [--summary]   produce component report for a manifest type and content
+  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>]   scan and apply vulnerability remediations
 
 Options:
   --help  Show help                                                    [boolean]
@@ -105,9 +130,21 @@ $ npx @trustify-da/trustify-da-javascript-client stack /path/to/pom.xml --summar
 # 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
 
@@ -123,6 +160,30 @@ $ npx @trustify-da/trustify-da-javascript-client image docker.io/library/node:18
 
 # 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
 ```
 </li>
 
@@ -143,9 +204,21 @@ $ 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
 
@@ -161,6 +234,30 @@ $ trustify-da-javascript-client image docker.io/library/node:18 docker.io/librar
 
 # 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
 ```
 </li>
 </ul>
@@ -172,10 +269,27 @@ $ trustify-da-javascript-client image httpd:2.4.49^^amd64
 <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></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>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.
@@ -219,8 +333,11 @@ Excluding a package from any analysis can be achieved by marking the package for
   ]
 }
 ```
+</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:
 
-<em>Golang</em> users can add in go.mod a comment with //exhortignore next to the package to be ignored, or to "piggyback" on existing comment ( e.g - //indirect) , for example:
 ```go
 module github.com/trustify-da/SaaSi/deployer
 
@@ -229,7 +346,7 @@ 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/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
@@ -237,14 +354,20 @@ require (
 )
 
 require (
-        github.com/davecgh/go-spew v1.1.1 // indirect exhortignore
+        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
+        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
@@ -275,11 +398,14 @@ 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'
+    id 'java'
 }
 
 group = 'groupName'
@@ -297,9 +423,45 @@ test {
 }
 ```
 
-All of the 5 above examples are valid for marking a package to be ignored
-</li>
+<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>
@@ -328,7 +490,12 @@ let options = {
   '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'
 }
@@ -351,6 +518,21 @@ let imageAnalysisWithArch = await client.imageAnalysis(['httpd:2.4.49^^amd64'],
  **_Environment variables takes precedence._**
 </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.
@@ -372,6 +554,11 @@ const options = {
 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.
+</p>
+
 <h4>Customizing Executables</h4>
 <p>
 This project uses each ecosystem's executable for creating dependency trees. These executables are expected to be
@@ -445,6 +632,26 @@ following keys for setting custom paths for the said executables.
 <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
@@ -493,6 +700,24 @@ 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.
 
@@ -508,14 +733,14 @@ This increasing the chances and the probability that the automatic installation
 ###### 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 setting `MATCH_MANIFEST_VERSIONS` to 'false'.
+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_RECOMMENDATIONS_ENABLED` to 'false' via environment variables or options.
+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.
@@ -525,6 +750,135 @@ For some ecosystems we support passing additional CLI arguments to the underlyin
 |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>
+</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:
+          entrypoint: trustify-da-javascript-client
+          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