@trustify-da/trustify-da-javascript-client 0.3.0-ea.ec6824b → 0.3.0-ea.efdc87d

package/README.md

@@ -7,7 +7,7 @@
 <h3>Usage</h3>
 <p>
 
-<strong>Prerequisites:</strong> The <code>TRUSTIFY_DA_BACKEND_URL</code> environment variable must be set to the URL of the Trustify Dependency Analytics backend service. You can set it as an environment variable or pass it in the options object (see <a href="#customization">Customization</a> section).
+<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>
@@ -103,14 +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|license}
+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>]   scan and apply vulnerability remediations
 
 Options:
   --help  Show help                                                    [boolean]
@@ -160,6 +163,27 @@ $ 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>
 
@@ -213,6 +237,27 @@ $ 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>
@@ -230,6 +275,18 @@ $ trustify-da-javascript-client license /path/to/package.json
 <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:
@@ -421,13 +478,13 @@ All of the above examples are valid for marking a package to be ignored
 
 <h3>Customization</h3>
 <p>
-There are 2 approaches for customizing <em>Trustify Dependency Analytics JavaScript Client</em>. Whether you're using this API as a
+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.
+for various customization. <em>ESM Module</em> users can also pass programmatic options.
 
-<strong>Note:</strong> The <code>TRUSTIFY_DA_BACKEND_URL</code> environment variable is <strong>mandatory</strong> and must be set to the URL of the Trustify Dependency Analytics backend service. Without this variable, the API will throw an error.
+<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.
 
-However, <em>ESM Module</em> users, can opt for customizing programmatically:
+Example programmatic customization:
 
 ```javascript
 import client from '@trustify-da/trustify-da-javascript-client'
@@ -470,7 +527,7 @@ let imageAnalysisHtml = await client.imageAnalysis(['docker.io/library/node:18']
 // Specify architecture using ^^ notation (e.g., httpd:2.4.49^^amd64)
 let imageAnalysisWithArch = await client.imageAnalysis(['httpd:2.4.49^^amd64'], false, options)
 ```
- **_Environment variables takes precedence._**
+ **_Programmatic options take precedence over environment variables._**
 </p>
 
 <h4>Monorepo / Workspace Support</h4>
@@ -506,12 +563,14 @@ const options = {
 }
 ```
 
+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.
+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>
@@ -619,7 +678,7 @@ can cause a confusion for the user in the client consuming the API and leads to
 
 ##### Usage
 
-To eliminate confusion and improve clarity as discussed above, the following setting was introduced - `MATCH_MANIFEST_VERSIONS`, in the form of environment variable/key in opts ( as usual , environment variable takes precedence )
+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
@@ -688,14 +747,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.
@@ -705,6 +764,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

package/dist/package.json

@@ -25,7 +25,9 @@
         "provenance": true
     },
     "type": "module",
-    "bin": "dist/src/cli.js",
+    "bin": {
+        "trustify-da": "dist/src/cli.js"
+    },
     "main": "dist/src/index.js",
     "module": "dist/src/index.js",
     "types": "dist/src/index.d.ts",
@@ -40,15 +42,14 @@
         "test": "c8 npm run tests",
         "tests": "mocha --config .mocharc.json",
         "tests:rep": "mocha --reporter-option maxDiffSize=0 --reporter json > unit-tests-result.json",
-        "pretest": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm src/providers/tree-sitter-requirements.wasm && cp node_modules/tree-sitter-gomod/tree-sitter-gomod.wasm src/providers/tree-sitter-gomod.wasm",
+        "pretest": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm src/providers/tree-sitter-requirements.wasm && cp node_modules/tree-sitter-gomod/tree-sitter-gomod.wasm src/providers/tree-sitter-gomod.wasm && cp node_modules/tree-sitter-containerfile/tree-sitter-containerfile.wasm src/providers/tree-sitter-containerfile.wasm",
         "precompile": "rm -rf dist",
         "compile": "tsc -p tsconfig.json",
         "compile:dev": "tsc -p tsconfig.dev.json",
-        "postcompile": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm dist/src/providers/tree-sitter-requirements.wasm && cp node_modules/tree-sitter-gomod/tree-sitter-gomod.wasm dist/src/providers/tree-sitter-gomod.wasm"
+        "postcompile": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm dist/src/providers/tree-sitter-requirements.wasm && cp node_modules/tree-sitter-gomod/tree-sitter-gomod.wasm dist/src/providers/tree-sitter-gomod.wasm && cp node_modules/tree-sitter-containerfile/tree-sitter-containerfile.wasm dist/src/providers/tree-sitter-containerfile.wasm"
     },
     "dependencies": {
-        "@babel/core": "^7.23.2",
-        "@cyclonedx/cyclonedx-library": "^10.0.0",
+        "@yarnpkg/parsers": "^3.1.0",
         "eslint-import-resolver-typescript": "^4.4.4",
         "fast-glob": "^3.3.3",
         "fast-xml-parser": "^5.3.4",
@@ -61,25 +62,26 @@
         "p-limit": "^7.3.0",
         "packageurl-js": "~1.0.2",
         "smol-toml": "^1.6.0",
+        "tree-sitter-containerfile": "^0.8.1",
         "tree-sitter-gomod": "github:strum355/tree-sitter-go-mod#56326f2ad478892ace58ff247a97d492a3cbcdda",
         "tree-sitter-requirements": "github:Strum355/tree-sitter-requirements#d0261ee76b84253997fe70d7d397e78c006c3801",
         "web-tree-sitter": "^0.26.7",
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@babel/core": "^7.23.2",
-        "@trustify-da/trustify-da-api-model": "^2.0.8",
+        "@cyclonedx/cyclonedx-library": "^10.2.0",
+        "@eslint/js": "^10.0.0",
+        "@trustify-da/trustify-da-api-model": "^2.0.12",
         "@types/node": "^25.9.1",
         "@types/which": "^3.0.4",
-        "babel-plugin-rewire": "^1.2.0",
+        "ajv": "^8.20.0",
         "c8": "^11.0.0",
         "chai": "^6.2.2",
-        "@eslint/js": "^10.0.0",
         "eslint": "^10.4.1",
         "eslint-import-resolver-typescript": "^4.4.4",
         "eslint-plugin-import-x": "^4.16.2",
-        "globals": "^17.6.0",
         "esmock": "^2.6.2",
+        "globals": "^17.6.0",
         "mocha": "^11.7.6",
         "msw": "^2.12.7",
         "sinon": "^22.0.0",
@@ -117,6 +119,9 @@
             "text"
         ]
     },
+    "overrides": {
+        "tree-sitter": "0.22.4"
+    },
     "resolutions": {
         "@hapi/joi": "17.1.1"
     }

package/dist/src/analysis.d.ts

@@ -6,6 +6,7 @@ declare namespace _default {
     export { requestStackBatch };
     export { requestImages };
     export { validateToken };
+    export { appendAnalysisQueryParams };
 }
 export default _default;
 /**
@@ -14,41 +15,62 @@ export default _default;
  * @param {string} manifest - path for the manifest
  * @param {string} url - the backend url to send the request to
  * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>}
+ * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>}
  */
-declare function requestComponent(provider: any, manifest: string, url: string, opts?: any): Promise<any>;
+declare function requestComponent(provider: any, manifest: string, url: string, opts?: any): Promise<import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts").AnalysisReport>;
 /**
- * Send a stack analysis request and get the report as 'text/html' or 'application/json'.
- * @param {import('./provider').Provider} provider - the provided data for constructing the request
- * @param {string} manifest - path for the manifest
- * @param {string} url - the backend url to send the request to
- * @param {boolean} [html=false] - true will return 'text/html', false will return 'application/json'
- * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<string|import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>}
+ * @overload
+ * @param {import('./provider').Provider} provider
+ * @param {string} manifest
+ * @param {string} url
+ * @param {true} [html]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<string>}
  */
-declare function requestStack(provider: any, manifest: string, url: string, html?: boolean, opts?: any): Promise<string | any>;
+declare function requestStack(provider: any, manifest: string, url: string, html?: true | undefined, opts?: any): Promise<string>;
 /**
- * Send a batch stack analysis request for multiple manifests (SBOMs keyed by purl).
- * @param {Object.<string, object>} sbomByPurl - Map of root purl to CycloneDX SBOM object
- * @param {string} url - the backend url
- * @param {boolean} [html=false] - true returns HTML, false returns JSON
+ * @overload
+ * @param {import('./provider').Provider} provider
+ * @param {string} manifest
+ * @param {string} url
+ * @param {false} [html]
  * @param {import("index.js").Options} [opts={}]
- * @returns {Promise<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>>}
+ * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
+ */
+declare function requestStack(provider: any, manifest: string, url: string, html?: false | undefined, opts?: any): Promise<import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts").AnalysisReport>;
+/**
+ * @overload
+ * @param {Object.<string, object>} sbomByPurl
+ * @param {string} url
+ * @param {true} [html=false]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<string>}
  */
 declare function requestStackBatch(sbomByPurl: {
     [x: string]: object;
-}, url: string, html?: boolean, opts?: any): Promise<string | {
-    [x: string]: any;
+}, url: string, html?: true | undefined, opts?: any): Promise<string>;
+/**
+ * @overload
+ * @param {Object.<string, object>} sbomByPurl
+ * @param {string} url
+ * @param {false} [html=false]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
+ */
+declare function requestStackBatch(sbomByPurl: {
+    [x: string]: object;
+}, url: string, html?: false | undefined, opts?: any): Promise<{
+    [x: string]: import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts").AnalysisReport;
 }>;
 /**
  *
  * @param {Array<string>} imageRefs
  * @param {string} url
  * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>>}
+ * @returns {Promise<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
  */
 declare function requestImages(imageRefs: Array<string>, url: string, html?: boolean, opts?: any): Promise<string | {
-    [x: string]: any;
+    [x: string]: import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts").AnalysisReport;
 }>;
 /**
  *
@@ -57,3 +79,9 @@ declare function requestImages(imageRefs: Array<string>, url: string, html?: boo
  * @return {Promise<number>} return the HTTP status Code of the response from the validate token request.
  */
 declare function validateToken(url: any, opts?: any): Promise<number>;
+/**
+ * Append common analysis query parameters (recommend, providers, sources) to a URL.
+ * @param {URL} url - the URL object to append query parameters to
+ * @param {import("index.js").Options} [opts={}] - options containing parameter overrides
+ */
+declare function appendAnalysisQueryParams(url: URL, opts?: any): void;