@trustify-da/trustify-da-javascript-client 0.3.0-ea.61444d4 → 0.3.0-ea.62b88e5

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>
@@ -275,6 +275,18 @@ $ trustify-da-javascript-client remediate /path/to/pom.xml --dry-run --group-by
 <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:
@@ -466,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'
@@ -515,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>
@@ -551,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>
@@ -664,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

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",
@@ -47,8 +49,7 @@
         "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",
@@ -68,12 +69,12 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@babel/core": "^7.23.2",
+        "@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": "^10.4.1",

package/dist/src/analysis.d.ts

@@ -15,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<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?: 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<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>>}
+ * @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?: boolean, opts?: any): Promise<string | {
-    [x: string]: any;
+}, 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;
 }>;
 /**
  *

package/dist/src/analysis.js

@@ -7,6 +7,24 @@ import { addProxyAgent, getCustom, getTokenHeaders, TRUSTIFY_DA_OPERATION_TYPE_H
 /** Media type for CycloneDX JSON batch payloads (batch-analysis API). */
 export const CYCLONEDX_JSON_MEDIA_TYPE = 'application/vnd.cyclonedx+json';
 export default { requestComponent, requestStack, requestStackBatch, requestImages, validateToken, appendAnalysisQueryParams };
+/**
+ * @overload
+ * @param {import('./provider').Provider} provider
+ * @param {string} manifest
+ * @param {string} url
+ * @param {true} [html]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<string>}
+ */
+/**
+ * @overload
+ * @param {import('./provider').Provider} provider
+ * @param {string} manifest
+ * @param {string} url
+ * @param {false} [html]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {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
@@ -14,7 +32,7 @@ export default { requestComponent, requestStack, requestStackBatch, requestImage
  * @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>}
+ * @returns {Promise<string|import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>}
  */
 async function requestStack(provider, manifest, url, html = false, opts = {}) {
     opts["source-manifest"] = Buffer.from(fs.readFileSync(manifest).toString()).toString('base64');
@@ -75,7 +93,7 @@ async function requestStack(provider, manifest, url, html = false, opts = {}) {
  * @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>}
  */
 async function requestComponent(provider, manifest, url, opts = {}) {
     opts["source-manifest"] = Buffer.from(fs.readFileSync(manifest).toString()).toString('base64');
@@ -113,7 +131,9 @@ async function requestComponent(provider, manifest, url, opts = {}) {
             console.log(JSON.stringify(result, null, 4));
             console.log("Ending time of sending component analysis request to Trustify DA backend server= " + new Date());
         }
-        const licenseCheckEnabled = getCustom('TRUSTIFY_DA_LICENSE_CHECK', 'true', opts) !== 'false' && opts.licenseCheck !== false;
+        const licenseCheckEnabled = typeof opts.licenseCheck === 'boolean'
+            ? opts.licenseCheck
+            : getCustom('TRUSTIFY_DA_LICENSE_CHECK', 'true', opts) !== 'false';
         if (licenseCheckEnabled) {
             try {
                 result.licenseSummary = await runLicenseCheck(provided.content, manifest, url, opts, result);
@@ -128,13 +148,29 @@ async function requestComponent(provider, manifest, url, opts = {}) {
     }
     return Promise.resolve(result);
 }
+/**
+ * @overload
+ * @param {Object.<string, object>} sbomByPurl
+ * @param {string} url
+ * @param {true} [html=false]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {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>>}
+ */
 /**
  * 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
  * @param {import("index.js").Options} [opts={}]
- * @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>>}
  */
 async function requestStackBatch(sbomByPurl, url, html = false, opts = {}) {
     const finalUrl = new URL(`${url}/api/v5/batch-analysis`);
@@ -177,7 +213,7 @@ async function requestStackBatch(sbomByPurl, url, html = false, opts = {}) {
  * @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>>}
  */
 async function requestImages(imageRefs, url, html = false, opts = {}) {
     const imageSboms = {};

package/dist/src/cli.js

@@ -3,9 +3,45 @@ import fs from 'node:fs';
 import * as path from "path";
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
+import { resolveConfig } from './config.js';
 import { getProjectLicense, getLicenseDetails } from './license/index.js';
 import { runRemediation } from './remediate.js';
+import { generateReport } from './remediation_report.js';
 import client, { selectTrustifyDABackend, generateSbom } from './index.js';
+/**
+ * Builds a yargs middleware that loads `.trustify-da.yml` (discovered by walking
+ * up from the command's target path, or cwd when no path is available) and fills `--providers`, `--sources`, and
+ * `--group-by` with config file values when they were not supplied on the CLI or
+ * via environment variables. Precedence: CLI flag > env var > config file > default.
+ * @param {string} [pathKey] - positional argument holding the target path; defaults to the current working directory
+ * @param {{ groupBy?: boolean }} [options={}] - set `groupBy` when the command exposes `--group-by`
+ * @returns {(args: object) => object} yargs middleware
+ */
+function configMiddleware(pathKey, options = {}) {
+    return args => {
+        const startPath = pathKey === undefined ? process.cwd() : args[pathKey];
+        const envVars = options.groupBy
+            ? process.env
+            : Object.fromEntries(Object.entries(process.env).filter(([key]) => key !== 'TRUSTIFY_DA_GROUP_BY'));
+        const merged = resolveConfig(startPath, { backendUrl: args.backendUrl, providers: args.providers, sources: args.sources, groupBy: args['group-by'] }, envVars);
+        if (merged.backendUrlSource === 'file' && process.env.TRUSTIFY_DA_TOKEN) {
+            throw new Error('Refusing to send TRUSTIFY_DA_TOKEN to a backend selected by project configuration. Set --backend-url or TRUSTIFY_DA_BACKEND_URL to explicitly trust it.');
+        }
+        if (args.providers !== undefined || merged.providers.length) {
+            args.providers = merged.providers.join(',');
+        }
+        if (args.sources !== undefined || merged.sources.length) {
+            args.sources = merged.sources.join(',');
+        }
+        if (merged.backendUrl != null) {
+            args.backendUrl = merged.backendUrl;
+        }
+        if (options.groupBy) {
+            args['group-by'] = merged.groupBy;
+        }
+        return args;
+    };
+}
 // command for component analysis take manifest type and content
 const component = {
     command: 'component </path/to/manifest>',
@@ -21,6 +57,10 @@ const component = {
             type: 'string',
             normalize: true,
         },
+        backendUrl: {
+            desc: 'Trustify DA backend URL (env: TRUSTIFY_DA_BACKEND_URL)',
+            type: 'string',
+        },
         providers: {
             desc: 'Comma-separated list of vulnerability providers (env: TRUSTIFY_DA_PROVIDERS)',
             type: 'string',
@@ -29,14 +69,17 @@ const component = {
             desc: 'Comma-separated list of vulnerability sources (env: TRUSTIFY_DA_SOURCES)',
             type: 'string',
         }
-    }),
+    }).middleware(configMiddleware('/path/to/manifest')),
     handler: async (args) => {
         let manifestName = args['/path/to/manifest'];
         const opts = args.workspaceDir ? { TRUSTIFY_DA_WORKSPACE_DIR: args.workspaceDir } : {};
-        if (args.providers) {
+        if (args.backendUrl !== undefined) {
+            opts.TRUSTIFY_DA_BACKEND_URL = args.backendUrl;
+        }
+        if (args.providers !== undefined) {
             opts.TRUSTIFY_DA_PROVIDERS = args.providers;
         }
-        if (args.sources) {
+        if (args.sources !== undefined) {
             opts.TRUSTIFY_DA_SOURCES = args.sources;
         }
         let res = await client.componentAnalysis(manifestName, opts);
@@ -88,6 +131,10 @@ const image = {
             type: 'boolean',
             conflicts: 'html'
         },
+        backendUrl: {
+            desc: 'Trustify DA backend URL (env: TRUSTIFY_DA_BACKEND_URL)',
+            type: 'string',
+        },
         providers: {
             desc: 'Comma-separated list of vulnerability providers (env: TRUSTIFY_DA_PROVIDERS)',
             type: 'string',
@@ -96,7 +143,7 @@ const image = {
             desc: 'Comma-separated list of vulnerability sources (env: TRUSTIFY_DA_SOURCES)',
             type: 'string',
         }
-    }),
+    }).middleware(configMiddleware()),
     handler: async (args) => {
         let imageRefs = args['image-refs'];
         if (!Array.isArray(imageRefs)) {
@@ -105,10 +152,13 @@ const image = {
         let html = args['html'];
         let summary = args['summary'];
         const opts = {};
-        if (args.providers) {
+        if (args.backendUrl !== undefined) {
+            opts.TRUSTIFY_DA_BACKEND_URL = args.backendUrl;
+        }
+        if (args.providers !== undefined) {
             opts.TRUSTIFY_DA_PROVIDERS = args.providers;
         }
-        if (args.sources) {
+        if (args.sources !== undefined) {
             opts.TRUSTIFY_DA_SOURCES = args.sources;
         }
         let res = await client.imageAnalysis(imageRefs, html, opts);
@@ -163,6 +213,10 @@ const stack = {
             type: 'string',
             normalize: true,
         },
+        backendUrl: {
+            desc: 'Trustify DA backend URL (env: TRUSTIFY_DA_BACKEND_URL)',
+            type: 'string',
+        },
         providers: {
             desc: 'Comma-separated list of vulnerability providers (env: TRUSTIFY_DA_PROVIDERS)',
             type: 'string',
@@ -171,16 +225,19 @@ const stack = {
             desc: 'Comma-separated list of vulnerability sources (env: TRUSTIFY_DA_SOURCES)',
             type: 'string',
         }
-    }),
+    }).middleware(configMiddleware('/path/to/manifest')),
     handler: async (args) => {
         let manifest = args['/path/to/manifest'];
         let html = args['html'];
         let summary = args['summary'];
         const opts = args.workspaceDir ? { TRUSTIFY_DA_WORKSPACE_DIR: args.workspaceDir } : {};
-        if (args.providers) {
+        if (args.backendUrl !== undefined) {
+            opts.TRUSTIFY_DA_BACKEND_URL = args.backendUrl;
+        }
+        if (args.providers !== undefined) {
             opts.TRUSTIFY_DA_PROVIDERS = args.providers;
         }
-        if (args.sources) {
+        if (args.sources !== undefined) {
             opts.TRUSTIFY_DA_SOURCES = args.sources;
         }
         let theProvidersSummary = new Map();
@@ -246,6 +303,10 @@ const stackBatch = {
             type: 'boolean',
             default: false,
         },
+        backendUrl: {
+            desc: 'Trustify DA backend URL (env: TRUSTIFY_DA_BACKEND_URL)',
+            type: 'string',
+        },
         providers: {
             desc: 'Comma-separated list of vulnerability providers (env: TRUSTIFY_DA_PROVIDERS)',
             type: 'string',
@@ -254,12 +315,15 @@ const stackBatch = {
             desc: 'Comma-separated list of vulnerability sources (env: TRUSTIFY_DA_SOURCES)',
             type: 'string',
         }
-    }),
+    }).middleware(configMiddleware('/path/to/workspace-root')),
     handler: async (args) => {
         const workspaceRoot = args['/path/to/workspace-root'];
         const html = args['html'];
         const summary = args['summary'];
         const opts = {};
+        if (args.backendUrl !== undefined) {
+            opts.TRUSTIFY_DA_BACKEND_URL = args.backendUrl;
+        }
         if (args.concurrency != null) {
             opts.batchConcurrency = args.concurrency;
         }
@@ -273,10 +337,10 @@ const stackBatch = {
         if (args.failFast) {
             opts.continueOnError = false;
         }
-        if (args.providers) {
+        if (args.providers !== undefined) {
             opts.TRUSTIFY_DA_PROVIDERS = args.providers;
         }
-        if (args.sources) {
+        if (args.sources !== undefined) {
             opts.TRUSTIFY_DA_SOURCES = args.sources;
         }
         let res = await client.stackAnalysisBatch(workspaceRoot, html, opts);
@@ -455,19 +519,33 @@ const remediate = {
         'group-by': {
             type: 'string',
             choices: ['dependency', 'bundle'],
-            default: 'dependency',
-            desc: 'Report grouping strategy',
+            desc: 'Report grouping strategy (default: dependency)',
         },
-    }),
+        backendUrl: {
+            desc: 'Trustify DA backend URL (env: TRUSTIFY_DA_BACKEND_URL)',
+            type: 'string',
+        },
+    }).middleware(configMiddleware('path', { groupBy: true })),
     handler: async (args) => {
         try {
             const result = await runRemediation(args.path, {
                 dryRun: args['dry-run'],
                 providers: args.providers,
                 sources: args.sources,
-                groupBy: args['group-by'],
+                backendUrl: args.backendUrl,
             });
-            console.log(result.output);
+            if (result.remediations.length === 0 && result.manifests.length === 0) {
+                console.log('No supported manifest files found.');
+                process.exit(result.exitCode);
+            }
+            if (!args['dry-run'] && result.appliedFiles.length > 0) {
+                console.log(`Updated ${result.appliedFiles.length} file(s):`);
+                for (const file of result.appliedFiles) {
+                    console.log(`  ${file}`);
+                }
+                console.log('');
+            }
+            console.log(generateReport(result.remediations, { groupBy: args['group-by'], dryRun: args['dry-run'] }));
             process.exit(result.exitCode);
         }
         catch (err) {

package/dist/src/config.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Discovers and parses `.trustify-da.yml` by walking up from `startPath`.
+ * A missing config file is not an error — an empty object is returned so callers
+ * can fall back to defaults.
+ * @param {string} [startPath] - manifest file or directory to start the search from
+ * @returns {FileConfig} the parsed config object, or `{}` when no file is found
+ * @throws {Error} when the config file exists but contains malformed YAML
+ */
+export function loadConfig(startPath?: string): FileConfig;
+/**
+ * Merges config sources with precedence: CLI flag > environment variable
+ * (`TRUSTIFY_DA_*`) > config file > hardcoded default. Providers and sources are
+ * normalized to arrays regardless of whether the source used a YAML array or a
+ * comma-separated string.
+ * @param {FileConfig} [fileConfig={}] - values parsed from `.trustify-da.yml`
+ * @param {{ providers?: string, sources?: string, groupBy?: string, backendUrl?: string }} [cliFlags={}]
+ * @param {{ [key: string]: string | undefined }} [envVars={}] - typically `process.env`
+ * @returns {ResolvedConfig} the resolved, typed config object
+ */
+export function mergeConfig(fileConfig?: FileConfig, cliFlags?: {
+    providers?: string;
+    sources?: string;
+    groupBy?: string;
+    backendUrl?: string;
+}, envVars?: {
+    [key: string]: string | undefined;
+}): ResolvedConfig;
+/**
+ * Loads and merges the project configuration for a target path.
+ * @param {string} [startPath] - manifest file or directory to start discovery from
+ * @param {{ providers?: string, sources?: string, groupBy?: string, backendUrl?: string }} [cliFlags={}] - explicit options
+ * @param {{ [key: string]: string | undefined }} [envVars={}] - typically `process.env`
+ * @returns {ResolvedConfig} the resolved, typed config object
+ */
+export function resolveConfig(startPath?: string, cliFlags?: {
+    providers?: string;
+    sources?: string;
+    groupBy?: string;
+    backendUrl?: string;
+}, envVars?: {
+    [key: string]: string | undefined;
+}): ResolvedConfig;
+/**
+ * @typedef {{
+ *   'group-by'?: 'dependency' | 'bundle',
+ *   exclude?: string[],
+ *   labels?: string[],
+ *   'branch-prefix'?: string,
+ *   [key: string]: unknown
+ * }} RemediationConfig
+ */
+/** @typedef {{ critical?: number, high?: number, 'license-conflicts'?: number, [key: string]: unknown }} FailOnConfig */
+/** @typedef {{ 'fail-on'?: FailOnConfig, [key: string]: unknown }} CheckConfig */
+/** @typedef {{ format?: string, targets?: string[], [key: string]: unknown }} SbomConfig */
+/**
+ * @typedef {{
+ *   'backend-url'?: string,
+ *   providers?: string[] | string,
+ *   sources?: string[] | string,
+ *   remediation?: RemediationConfig,
+ *   check?: CheckConfig,
+ *   sbom?: SbomConfig,
+ *   [key: string]: unknown
+ * }} FileConfig
+ */
+/**
+ * @typedef {{
+ *   backendUrl: string | null,
+ *   backendUrlSource: 'cli' | 'environment' | 'file' | 'default',
+ *   providers: string[],
+ *   sources: string[],
+ *   groupBy: string,
+ *   remediation: object,
+ *   check: object,
+ *   sbom: object
+ * }} ResolvedConfig
+ */
+/** Config file names discovered by walking up the directory tree, in precedence order. */
+export const CONFIG_FILENAMES: string[];
+export type RemediationConfig = {
+    "group-by"?: "dependency" | "bundle";
+    exclude?: string[];
+    labels?: string[];
+    "branch-prefix"?: string;
+    [key: string]: unknown;
+};
+export type FailOnConfig = {
+    critical?: number;
+    high?: number;
+    "license-conflicts"?: number;
+    [key: string]: unknown;
+};
+export type CheckConfig = {
+    "fail-on"?: FailOnConfig;
+    [key: string]: unknown;
+};
+export type SbomConfig = {
+    format?: string;
+    targets?: string[];
+    [key: string]: unknown;
+};
+export type FileConfig = {
+    "backend-url"?: string;
+    providers?: string[] | string;
+    sources?: string[] | string;
+    remediation?: RemediationConfig;
+    check?: CheckConfig;
+    sbom?: SbomConfig;
+    [key: string]: unknown;
+};
+export type ResolvedConfig = {
+    backendUrl: string | null;
+    backendUrlSource: "cli" | "environment" | "file" | "default";
+    providers: string[];
+    sources: string[];
+    groupBy: string;
+    remediation: object;
+    check: object;
+    sbom: object;
+};