@trustify-da/trustify-da-javascript-client 0.3.0-ea.2ea1d77 → 0.3.0-ea.328523e

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +272 -19
  2. package/dist/package.json +33 -28
  3. package/dist/src/analysis.d.ts +52 -22
  4. package/dist/src/analysis.js +77 -22
  5. package/dist/src/cli.js +238 -7
  6. package/dist/src/config.d.ts +120 -0
  7. package/dist/src/config.js +260 -0
  8. package/dist/src/cyclone_dx_sbom.d.ts +27 -1
  9. package/dist/src/cyclone_dx_sbom.js +82 -9
  10. package/dist/src/index.d.ts +97 -22
  11. package/dist/src/index.js +115 -42
  12. package/dist/src/license/index.d.ts +4 -4
  13. package/dist/src/license/index.js +13 -7
  14. package/dist/src/license/license_utils.js +4 -1
  15. package/dist/src/license/licenses_api.d.ts +3 -3
  16. package/dist/src/license/licenses_api.js +1 -1
  17. package/dist/src/oci_image/images.d.ts +1 -1
  18. package/dist/src/oci_image/images.js +15 -1
  19. package/dist/src/oci_image/utils.d.ts +5 -5
  20. package/dist/src/oci_image/utils.js +11 -2
  21. package/dist/src/package_version.d.ts +8 -0
  22. package/dist/src/package_version.js +31 -0
  23. package/dist/src/provider.d.ts +4 -3
  24. package/dist/src/provider.js +12 -2
  25. package/dist/src/providers/base_java.d.ts +67 -12
  26. package/dist/src/providers/base_java.js +82 -61
  27. package/dist/src/providers/base_javascript.d.ts +90 -15
  28. package/dist/src/providers/base_javascript.js +206 -24
  29. package/dist/src/providers/base_pyproject.d.ts +158 -0
  30. package/dist/src/providers/base_pyproject.js +322 -0
  31. package/dist/src/providers/containerfile_parser.d.ts +5 -0
  32. package/dist/src/providers/containerfile_parser.js +20 -0
  33. package/dist/src/providers/golang_gomodules.d.ts +23 -13
  34. package/dist/src/providers/golang_gomodules.js +208 -120
  35. package/dist/src/providers/gomod_parser.d.ts +4 -0
  36. package/dist/src/providers/gomod_parser.js +16 -0
  37. package/dist/src/providers/java_gradle.d.ts +67 -0
  38. package/dist/src/providers/java_gradle.js +320 -22
  39. package/dist/src/providers/java_gradle_groovy.d.ts +1 -1
  40. package/dist/src/providers/java_gradle_kotlin.d.ts +1 -1
  41. package/dist/src/providers/java_maven.d.ts +37 -9
  42. package/dist/src/providers/java_maven.js +269 -11
  43. package/dist/src/providers/javascript_bun.d.ts +22 -0
  44. package/dist/src/providers/javascript_bun.js +141 -0
  45. package/dist/src/providers/javascript_npm.d.ts +19 -0
  46. package/dist/src/providers/javascript_npm.js +61 -1
  47. package/dist/src/providers/javascript_pnpm.d.ts +13 -0
  48. package/dist/src/providers/javascript_pnpm.js +53 -3
  49. package/dist/src/providers/javascript_yarn.d.ts +12 -0
  50. package/dist/src/providers/javascript_yarn.js +75 -2
  51. package/dist/src/providers/manifest.d.ts +2 -0
  52. package/dist/src/providers/manifest.js +28 -7
  53. package/dist/src/providers/marker_evaluator.d.ts +14 -0
  54. package/dist/src/providers/marker_evaluator.js +191 -0
  55. package/dist/src/providers/oci_dockerfile.d.ts +51 -0
  56. package/dist/src/providers/oci_dockerfile.js +177 -0
  57. package/dist/src/providers/processors/yarn_berry_processor.d.ts +6 -2
  58. package/dist/src/providers/processors/yarn_berry_processor.js +91 -7
  59. package/dist/src/providers/processors/yarn_classic_processor.d.ts +6 -2
  60. package/dist/src/providers/processors/yarn_classic_processor.js +8 -6
  61. package/dist/src/providers/python_controller.d.ts +5 -1
  62. package/dist/src/providers/python_controller.js +69 -8
  63. package/dist/src/providers/python_pip.d.ts +5 -0
  64. package/dist/src/providers/python_pip.js +6 -6
  65. package/dist/src/providers/python_pip_pyproject.d.ts +61 -0
  66. package/dist/src/providers/python_pip_pyproject.js +146 -0
  67. package/dist/src/providers/python_poetry.d.ts +98 -0
  68. package/dist/src/providers/python_poetry.js +286 -0
  69. package/dist/src/providers/python_uv.d.ts +46 -0
  70. package/dist/src/providers/python_uv.js +275 -0
  71. package/dist/src/providers/requirements_parser.js +1 -1
  72. package/dist/src/providers/rust_cargo.d.ts +6 -2
  73. package/dist/src/providers/rust_cargo.js +101 -33
  74. package/dist/src/providers/tree-sitter-containerfile.wasm +0 -0
  75. package/dist/src/providers/tree-sitter-gomod.wasm +0 -0
  76. package/dist/src/remediate.d.ts +107 -0
  77. package/dist/src/remediate.js +244 -0
  78. package/dist/src/remediation.d.ts +81 -0
  79. package/dist/src/remediation.js +475 -0
  80. package/dist/src/remediation_report.d.ts +23 -0
  81. package/dist/src/remediation_report.js +180 -0
  82. package/dist/src/sbom.d.ts +25 -1
  83. package/dist/src/sbom.js +23 -2
  84. package/dist/src/tools.d.ts +37 -13
  85. package/dist/src/tools.js +92 -13
  86. package/dist/src/updaters/maven_updater.d.ts +58 -0
  87. package/dist/src/updaters/maven_updater.js +345 -0
  88. package/dist/src/updaters/toml_updater.d.ts +62 -0
  89. package/dist/src/updaters/toml_updater.js +276 -0
  90. package/dist/src/workspace.d.ts +11 -1
  91. package/dist/src/workspace.js +3 -2
  92. package/package.json +34 -29
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  <h3>Usage</h3>
8
8
  <p>
9
9
 
10
- <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).
10
+ <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.
11
11
 
12
12
  <ul>
13
13
  <li>
@@ -103,14 +103,17 @@ Use as CLI Script
103
103
  ```shell
104
104
  $ npx @trustify-da/trustify-da-javascript-client help
105
105
 
106
- Usage: trustify-da-javascript-client {component|stack|image|validate-token|license}
106
+ Usage: trustify-da-javascript-client {component|stack|stack-batch|image|validate-token|license|sbom|remediate}
107
107
 
108
108
  Commands:
109
109
  trustify-da-javascript-client stack </path/to/manifest> [--workspace-dir <path>] [--html|--summary] produce stack report for manifest path
110
110
  trustify-da-javascript-client stack-batch </path/to/workspace-root> [--html|--summary] produce stack report for all packages/crates in workspace
111
111
  trustify-da-javascript-client component <path/to/manifest> [--workspace-dir <path>] produce component report for a manifest type and content
112
112
  trustify-da-javascript-client image <image-refs..> [--html|--summary] produce image analysis report for OCI image references
113
+ trustify-da-javascript-client validate-token <token-provider> [--token-value <value>] validate input token if authentic and authorized
113
114
  trustify-da-javascript-client license </path/to/manifest> display project license information from manifest and LICENSE file in JSON format
115
+ trustify-da-javascript-client sbom </path/to/manifest> [--output <file>] generate a CycloneDX SBOM from a manifest file
116
+ trustify-da-javascript-client remediate <path> [--dry-run] [--providers <list>] [--sources <list>] [--group-by <strategy>] scan and apply vulnerability remediations
114
117
 
115
118
  Options:
116
119
  --help Show help [boolean]
@@ -160,6 +163,27 @@ $ npx @trustify-da/trustify-da-javascript-client image httpd:2.4.49^^amd64
160
163
 
161
164
  # get project license information
162
165
  $ npx @trustify-da/trustify-da-javascript-client license /path/to/package.json
166
+
167
+ # generate a CycloneDX SBOM from a manifest file
168
+ $ npx @trustify-da/trustify-da-javascript-client sbom /path/to/pom.xml
169
+
170
+ # generate SBOM and write to a file
171
+ $ npx @trustify-da/trustify-da-javascript-client sbom /path/to/pom.xml --output sbom.json
172
+
173
+ # scan a manifest and apply vulnerability remediations
174
+ $ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml
175
+
176
+ # preview remediations without modifying files
177
+ $ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml --dry-run
178
+
179
+ # scan a directory for all supported manifests
180
+ $ npx @trustify-da/trustify-da-javascript-client remediate /path/to/project/
181
+
182
+ # filter by vulnerability providers (order determines priority)
183
+ $ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml --providers provider1,provider2
184
+
185
+ # group report output by bundle instead of per-dependency
186
+ $ npx @trustify-da/trustify-da-javascript-client remediate /path/to/pom.xml --dry-run --group-by bundle
163
187
  ```
164
188
  </li>
165
189
 
@@ -213,6 +237,27 @@ $ trustify-da-javascript-client image httpd:2.4.49^^amd64
213
237
 
214
238
  # get project license information
215
239
  $ trustify-da-javascript-client license /path/to/package.json
240
+
241
+ # generate a CycloneDX SBOM from a manifest file
242
+ $ trustify-da-javascript-client sbom /path/to/pom.xml
243
+
244
+ # generate SBOM and write to a file
245
+ $ trustify-da-javascript-client sbom /path/to/pom.xml --output sbom.json
246
+
247
+ # scan a manifest and apply vulnerability remediations
248
+ $ trustify-da-javascript-client remediate /path/to/pom.xml
249
+
250
+ # preview remediations without modifying files
251
+ $ trustify-da-javascript-client remediate /path/to/pom.xml --dry-run
252
+
253
+ # scan a directory for all supported manifests
254
+ $ trustify-da-javascript-client remediate /path/to/project/
255
+
256
+ # filter by vulnerability providers (order determines priority)
257
+ $ trustify-da-javascript-client remediate /path/to/pom.xml --providers provider1,provider2
258
+
259
+ # group report output by bundle instead of per-dependency
260
+ $ trustify-da-javascript-client remediate /path/to/pom.xml --dry-run --group-by bundle
216
261
  ```
217
262
  </li>
218
263
  </ul>
@@ -224,11 +269,24 @@ $ trustify-da-javascript-client license /path/to/package.json
224
269
  <li><a href="https://www.javascript.com/">JavaScript</a> - <a href="https://pnpm.io/">pnpm</a></li>
225
270
  <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>
226
271
  <li><a href="https://go.dev/">Golang</a> - <a href="https://go.dev/blog/using-go-modules/">Go Modules</a></li>
227
- <li><a href="https://www.python.org/">Python</a> - <a href="https://pypi.org/project/pip/">pip Installer</a></li>
272
+ <li><a href="https://www.python.org/">Python</a> - <a href="https://pypi.org/project/pip/">pip Installer</a> (<code>requirements.txt</code>)</li>
273
+ <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>
228
274
  <li><a href="https://gradle.org/">Gradle (Groovy and Kotlin DSL)</a> - <a href="https://gradle.org/install/">Gradle Installation</a></li>
229
275
  <li><a href="https://www.rust-lang.org/">Rust</a> - <a href="https://doc.rust-lang.org/cargo/">Cargo</a></li>
230
276
  </ul>
231
277
 
278
+ <h3>Dockerfile Analysis Prerequisites</h3>
279
+ <p>
280
+ 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>:
281
+ </p>
282
+ <ul>
283
+ <li><a href="https://github.com/anchore/syft">Syft</a> — generates the image SBOM.</li>
284
+ <li><a href="https://github.com/containers/skopeo">skopeo</a> — resolves the image digest and manifest from the registry.</li>
285
+ </ul>
286
+ <p>
287
+ <strong>Dockerfile analysis is not supported on Windows</strong>, because <code>skopeo</code> provides no native Windows binary.
288
+ </p>
289
+
232
290
  <h3>License Detection</h3>
233
291
  <p>
234
292
  The client automatically detects your project's license with intelligent fallback:
@@ -287,8 +345,11 @@ Excluding a package from any analysis can be achieved by marking the package for
287
345
  ]
288
346
  }
289
347
  ```
348
+ </li>
349
+
350
+ <li>
351
+ <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:
290
352
 
291
- <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:
292
353
  ```go
293
354
  module github.com/trustify-da/SaaSi/deployer
294
355
 
@@ -297,7 +358,7 @@ go 1.19
297
358
  require (
298
359
  github.com/gin-gonic/gin v1.9.1
299
360
  github.com/google/uuid v1.1.2
300
- github.com/jessevdk/go-flags v1.5.0 //exhortignore
361
+ github.com/jessevdk/go-flags v1.5.0 // exhortignore
301
362
  github.com/kr/pretty v0.3.1
302
363
  gopkg.in/yaml.v2 v2.4.0
303
364
  k8s.io/apimachinery v0.26.1
@@ -305,14 +366,20 @@ require (
305
366
  )
306
367
 
307
368
  require (
308
- github.com/davecgh/go-spew v1.1.1 // indirect exhortignore
369
+ github.com/davecgh/go-spew v1.1.1 // indirect; exhortignore
309
370
  github.com/emicklei/go-restful/v3 v3.9.0 // indirect
310
- github.com/go-logr/logr v1.2.3 // indirect //exhortignore
371
+ github.com/go-logr/logr v1.2.3 // indirect; exhortignore
311
372
 
312
373
  )
313
374
  ```
314
375
 
376
+ <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.
377
+ </li>
378
+
379
+
380
+ <li>
315
381
  <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:
382
+
316
383
  ```properties
317
384
  anyio==3.6.2
318
385
  asgiref==3.4.1
@@ -343,11 +410,14 @@ Werkzeug==2.0.3
343
410
  zipp==3.6.0
344
411
 
345
412
  ```
413
+ </li>
346
414
 
415
+ <li>
347
416
  <em>Gradle</em> users can add in build.gradle a comment with //exhortignore next to the package to be ignored:
417
+
348
418
  ```build.gradle
349
419
  plugins {
350
- id 'java'
420
+ id 'java'
351
421
  }
352
422
 
353
423
  group = 'groupName'
@@ -379,20 +449,42 @@ version = "1.10"
379
449
  log = "0.4" # trustify-da-ignore
380
450
  ```
381
451
 
382
- All of the 6 above examples are valid for marking a package to be ignored
383
- </li>
384
452
 
453
+ <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>.
454
+
455
+ PEP 621 style (<code>[project]</code> dependencies):
456
+ ```toml
457
+ [project]
458
+ dependencies = [
459
+ "flask>=2.0.3",
460
+ "requests>=2.25.1",
461
+ "uvicorn>=0.17.0", #exhortignore
462
+ "click>=8.0.4", # trustify-da-ignore
463
+ ]
464
+ ```
465
+
466
+ Poetry style (<code>[tool.poetry.dependencies]</code>):
467
+ ```toml
468
+ [tool.poetry.dependencies]
469
+ flask = "^2.0.3"
470
+ requests = "^2.25.1"
471
+ uvicorn = "^0.17.0" #exhortignore
472
+ click = "^8.0.4" # trustify-da-ignore
473
+ ```
474
+
475
+ All of the above examples are valid for marking a package to be ignored
476
+ </li>
385
477
  </ul>
386
478
 
387
479
  <h3>Customization</h3>
388
480
  <p>
389
- There are 2 approaches for customizing <em>Trustify Dependency Analytics JavaScript Client</em>. Whether you're using this API as a
481
+ There are two approaches for customizing <em>Trustify Dependency Analytics JavaScript Client</em>. Whether you're using this API as a
390
482
  <em>Global Module</em>, a <em>Remote Script</em>, or an <em>ESM Module</em>, you can use <em>Environment Variables</em>
391
- for various customization.
483
+ for various customization. <em>ESM Module</em> users can also pass programmatic options.
392
484
 
393
- <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.
485
+ <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.
394
486
 
395
- However, <em>ESM Module</em> users, can opt for customizing programmatically:
487
+ Example programmatic customization:
396
488
 
397
489
  ```javascript
398
490
  import client from '@trustify-da/trustify-da-javascript-client'
@@ -410,6 +502,8 @@ let options = {
410
502
  'TRUSTIFY_DA_PIP3_PATH' : '/path/to/pip3',
411
503
  'TRUSTIFY_DA_PYTHON_PATH' : '/path/to/python',
412
504
  'TRUSTIFY_DA_PIP_PATH' : '/path/to/pip',
505
+ 'TRUSTIFY_DA_UV_PATH' : '/path/to/uv',
506
+ 'TRUSTIFY_DA_POETRY_PATH' : '/path/to/poetry',
413
507
  'TRUSTIFY_DA_GRADLE_PATH' : '/path/to/gradle',
414
508
  'TRUSTIFY_DA_CARGO_PATH' : '/path/to/cargo',
415
509
  // Workspace root for monorepos (Cargo, npm/pnpm/yarn); lock file expected here
@@ -433,7 +527,7 @@ let imageAnalysisHtml = await client.imageAnalysis(['docker.io/library/node:18']
433
527
  // Specify architecture using ^^ notation (e.g., httpd:2.4.49^^amd64)
434
528
  let imageAnalysisWithArch = await client.imageAnalysis(['httpd:2.4.49^^amd64'], false, options)
435
529
  ```
436
- **_Environment variables takes precedence._**
530
+ **_Programmatic options take precedence over environment variables._**
437
531
  </p>
438
532
 
439
533
  <h4>Monorepo / Workspace Support</h4>
@@ -469,12 +563,14 @@ const options = {
469
563
  }
470
564
  ```
471
565
 
566
+ When both are supplied, <code>options.TRUSTIFY_DA_PROXY_URL</code> takes precedence over the environment variable.
567
+
472
568
  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.
473
569
  </p>
474
570
 
475
571
  <h4>License resolution and dependency license compliance</h4>
476
572
  <p>
477
- 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.
573
+ 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.
478
574
  </p>
479
575
 
480
576
  <h4>Customizing Executables</h4>
@@ -556,6 +652,16 @@ following keys for setting custom paths for the said executables.
556
652
  <td>TRUSTIFY_DA_CARGO_PATH</td>
557
653
  </tr>
558
654
  <tr>
655
+ <td><a href="https://docs.astral.sh/uv/">uv</a></td>
656
+ <td><em>uv</em></td>
657
+ <td>TRUSTIFY_DA_UV_PATH</td>
658
+ </tr>
659
+ <tr>
660
+ <td><a href="https://python-poetry.org/">Poetry</a></td>
661
+ <td><em>poetry</em></td>
662
+ <td>TRUSTIFY_DA_POETRY_PATH</td>
663
+ </tr>
664
+ <tr>
559
665
  <td>Workspace root (monorepos)</td>
560
666
  <td>—</td>
561
667
  <td>workspaceDir / TRUSTIFY_DA_WORKSPACE_DIR</td>
@@ -572,7 +678,7 @@ can cause a confusion for the user in the client consuming the API and leads to
572
678
 
573
679
  ##### Usage
574
680
 
575
- 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 )
681
+ 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.
576
682
  for two ecosystems:
577
683
  - Golang - Go Modules
578
684
  - Python - pip
@@ -608,6 +714,24 @@ TRUSTIFY_DA_GO_MVS_LOGIC_ENABLED=false
608
714
 
609
715
  #### Python Support
610
716
 
717
+ The client supports two Python manifest formats:
718
+
719
+ - **`requirements.txt`** — uses pip/pip3 to resolve dependencies
720
+ - **`pyproject.toml`** — uses [uv](https://docs.astral.sh/uv/) or [Poetry](https://python-poetry.org/) to resolve dependencies
721
+
722
+ ##### pyproject.toml
723
+
724
+ For `pyproject.toml` projects, the client detects which tool manages the project by checking for lock files:
725
+ - If `poetry.lock` is present and `[tool.poetry]` is defined, **Poetry** is used (`poetry show --tree` and `poetry show --all`)
726
+ - If `uv.lock` is present, **uv** is used (`uv export --format requirements.txt --frozen --no-hashes`)
727
+ - If neither lock file is found, an error is thrown
728
+
729
+ Both PEP 621 (`[project]` dependencies) and Poetry-style (`[tool.poetry.dependencies]`) are supported.
730
+
731
+ Custom executable paths can be set via `TRUSTIFY_DA_UV_PATH` and `TRUSTIFY_DA_POETRY_PATH`.
732
+
733
+ ##### requirements.txt
734
+
611
735
  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
612
736
  Binaries passed to environment variables. In any case, If the package is not installed , then an error will be thrown.
613
737
 
@@ -623,14 +747,14 @@ This increasing the chances and the probability that the automatic installation
623
747
  ###### Usage
624
748
  A New setting is introduced - `TRUSTIFY_DA_PYTHON_INSTALL_BEST_EFFORTS` (as both env variable/key in `options` object)
625
749
  1. `TRUSTIFY_DA_PYTHON_INSTALL_BEST_EFFORTS`="false" - install requirements.txt while respecting declared versions for all packages.
626
- 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'.
750
+ 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'.
627
751
 
628
752
  ##### Using `pipdeptree`
629
753
  By default, The API algorithm will use native commands of PIP installer as data source to build the dependency tree.
630
754
  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'.
631
755
 
632
756
  #### Toggle Red Hat Trusted Content recommendations
633
- 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.
757
+ 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.
634
758
 
635
759
  #### Additional CLI arguments
636
760
  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.
@@ -640,6 +764,135 @@ For some ecosystems we support passing additional CLI arguments to the underlyin
640
764
  |Maven |TRUSTIFY_DA_MVN_ARGS|
641
765
 
642
766
 
767
+ <h3>Remediation</h3>
768
+ <p>
769
+ 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.
770
+ </p>
771
+
772
+ <h4>Supported Manifest Formats</h4>
773
+ <ul>
774
+ <li><strong>Maven</strong> — <code>pom.xml</code> (single-module projects; updates dependency version elements and resolves property references)</li>
775
+ <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>
776
+ </ul>
777
+
778
+ <h4>CLI Flags</h4>
779
+ <table>
780
+ <tr>
781
+ <th>Flag</th>
782
+ <th>Alias</th>
783
+ <th>Type</th>
784
+ <th>Default</th>
785
+ <th>Description</th>
786
+ </tr>
787
+ <tr>
788
+ <td><code>&lt;path&gt;</code></td>
789
+ <td>—</td>
790
+ <td>string (positional)</td>
791
+ <td><em>required</em></td>
792
+ <td>Path to a manifest file or directory to scan recursively</td>
793
+ </tr>
794
+ <tr>
795
+ <td><code>--dry-run</code></td>
796
+ <td><code>-d</code></td>
797
+ <td>boolean</td>
798
+ <td><code>false</code></td>
799
+ <td>Preview changes without modifying files</td>
800
+ </tr>
801
+ <tr>
802
+ <td><code>--providers</code></td>
803
+ <td>—</td>
804
+ <td>string</td>
805
+ <td>—</td>
806
+ <td>Comma-separated list of vulnerability providers (env: <code>TRUSTIFY_DA_PROVIDERS</code>)</td>
807
+ </tr>
808
+ <tr>
809
+ <td><code>--sources</code></td>
810
+ <td>—</td>
811
+ <td>string</td>
812
+ <td>—</td>
813
+ <td>Comma-separated list of vulnerability sources (env: <code>TRUSTIFY_DA_SOURCES</code>)</td>
814
+ </tr>
815
+ <tr>
816
+ <td><code>--group-by</code></td>
817
+ <td>—</td>
818
+ <td>string</td>
819
+ <td><code>dependency</code></td>
820
+ <td>Report grouping strategy (<code>dependency</code> or <code>bundle</code>)</td>
821
+ </tr>
822
+ </table>
823
+
824
+ <h4>Provider Priority Resolution</h4>
825
+ <p>
826
+ 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.
827
+ </p>
828
+ <ul>
829
+ <li>The provider ordering in <code>--providers</code> determines rank (first = highest priority).</li>
830
+ <li>Trustify vendor trusted packages always take precedence over non-trusted content at equal provider rank.</li>
831
+ <li>Two version selection strategies are used internally:
832
+ <ul>
833
+ <li><strong>Closest coverage</strong> (default) — prefers the remediation version closest to the current version within the same major version.</li>
834
+ <li><strong>Highest</strong> — always selects the highest available remediation version.</li>
835
+ </ul>
836
+ </li>
837
+ </ul>
838
+
839
+ <h4>Exit Codes</h4>
840
+ <ul>
841
+ <li><code>0</code> — no remediations needed, or remediations applied successfully</li>
842
+ <li><code>1</code> — error during execution</li>
843
+ <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>
844
+ </ul>
845
+
846
+ <h4>Known Limitations</h4>
847
+ <ul>
848
+ <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>
849
+ <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>
850
+ </ul>
851
+
852
+ <h4>Example: GitHub Action Workflow</h4>
853
+ <p>
854
+ 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:
855
+ </p>
856
+
857
+ ```yaml
858
+ name: Trustify DA Remediation Scan
859
+
860
+ on:
861
+ schedule:
862
+ # Run weekly on Monday at 08:00 UTC
863
+ - cron: '0 8 * * 1'
864
+ workflow_dispatch:
865
+
866
+ permissions:
867
+ contents: write
868
+ pull-requests: write
869
+
870
+ jobs:
871
+ remediate:
872
+ runs-on: ubuntu-latest
873
+ steps:
874
+ - uses: actions/checkout@v4
875
+
876
+ - name: Run remediation scan
877
+ uses: docker://ghcr.io/guacsec/trustify-da-javascript-client:latest
878
+ env:
879
+ TRUSTIFY_DA_BACKEND_URL: ${{ secrets.TRUSTIFY_DA_BACKEND_URL }}
880
+ with:
881
+ entrypoint: trustify-da-javascript-client
882
+ args: remediate . --providers provider1,provider2
883
+
884
+ - name: Create pull request
885
+ uses: peter-evans/create-pull-request@v7
886
+ with:
887
+ title: 'fix(deps): apply Trustify DA vulnerability remediations'
888
+ body: |
889
+ Automated dependency version updates from Trustify Dependency Analytics.
890
+
891
+ This PR was generated by a scheduled remediation scan.
892
+ branch: trustify-da-remediation
893
+ commit-message: 'fix(deps): apply Trustify DA vulnerability remediations'
894
+ ```
895
+
643
896
  <!-- Badge links -->
644
897
  [0]: https://img.shields.io/github/v/release/guacsec/trustify-da-javascript-client?color=green&label=latest
645
898
  [1]: https://img.shields.io/github/v/release/guacsec/trustify-da-javascript-client?color=yellow&include_prereleases&label=early-access
package/dist/package.json CHANGED
@@ -25,7 +25,9 @@
25
25
  "provenance": true
26
26
  },
27
27
  "type": "module",
28
- "bin": "dist/src/cli.js",
28
+ "bin": {
29
+ "trustify-da": "dist/src/cli.js"
30
+ },
29
31
  "main": "dist/src/index.js",
30
32
  "module": "dist/src/index.js",
31
33
  "types": "dist/src/index.d.ts",
@@ -35,55 +37,57 @@
35
37
  "config/**/*"
36
38
  ],
37
39
  "scripts": {
38
- "lint": "eslint src test --ext js",
39
- "lint:fix": "eslint src test --ext js --fix",
40
+ "lint": "eslint src test",
41
+ "lint:fix": "eslint src test --fix",
40
42
  "test": "c8 npm run tests",
41
- "tests": "mocha --config .mocharc.json --grep \".*analysis module.*\" --invert",
43
+ "tests": "mocha --config .mocharc.json",
42
44
  "tests:rep": "mocha --reporter-option maxDiffSize=0 --reporter json > unit-tests-result.json",
43
- "pretest": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm src/providers/tree-sitter-requirements.wasm",
45
+ "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",
44
46
  "precompile": "rm -rf dist",
45
47
  "compile": "tsc -p tsconfig.json",
46
48
  "compile:dev": "tsc -p tsconfig.dev.json",
47
- "postcompile": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm dist/src/providers/tree-sitter-requirements.wasm"
49
+ "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"
48
50
  },
49
51
  "dependencies": {
50
- "@babel/core": "^7.23.2",
51
- "@cyclonedx/cyclonedx-library": "^6.13.0",
52
+ "@yarnpkg/parsers": "^3.1.0",
52
53
  "eslint-import-resolver-typescript": "^4.4.4",
53
54
  "fast-glob": "^3.3.3",
54
- "fast-toml": "^0.5.4",
55
55
  "fast-xml-parser": "^5.3.4",
56
56
  "help": "^3.0.2",
57
- "https-proxy-agent": "^7.0.6",
57
+ "https-proxy-agent": "^9.0.0",
58
58
  "js-yaml": "^4.1.1",
59
+ "jsonc-parser": "^3.3.1",
59
60
  "micromatch": "^4.0.8",
60
61
  "node-fetch": "^3.3.2",
61
- "p-limit": "^5.0.0",
62
+ "p-limit": "^7.3.0",
62
63
  "packageurl-js": "~1.0.2",
63
64
  "smol-toml": "^1.6.0",
65
+ "tree-sitter-containerfile": "^0.8.1",
66
+ "tree-sitter-gomod": "github:strum355/tree-sitter-go-mod#56326f2ad478892ace58ff247a97d492a3cbcdda",
64
67
  "tree-sitter-requirements": "github:Strum355/tree-sitter-requirements#d0261ee76b84253997fe70d7d397e78c006c3801",
65
- "web-tree-sitter": "^0.26.6",
68
+ "web-tree-sitter": "^0.26.7",
66
69
  "yargs": "^18.0.0"
67
70
  },
68
71
  "devDependencies": {
69
- "@babel/core": "^7.23.2",
70
- "@trustify-da/trustify-da-api-model": "^2.0.7",
71
- "@types/node": "^20.17.30",
72
+ "@cyclonedx/cyclonedx-library": "^10.2.0",
73
+ "@eslint/js": "^10.0.0",
74
+ "@trustify-da/trustify-da-api-model": "^2.0.12",
75
+ "@types/node": "^25.9.1",
72
76
  "@types/which": "^3.0.4",
73
- "babel-plugin-rewire": "^1.2.0",
77
+ "ajv": "^8.20.0",
74
78
  "c8": "^11.0.0",
75
- "chai": "^4.3.7",
76
- "eslint": "^8.42.0",
79
+ "chai": "^6.2.2",
80
+ "eslint": "^10.4.1",
77
81
  "eslint-import-resolver-typescript": "^4.4.4",
78
- "eslint-plugin-editorconfig": "^4.0.3",
79
- "eslint-plugin-import": "^2.29.1",
82
+ "eslint-plugin-import-x": "^4.16.2",
80
83
  "esmock": "^2.6.2",
81
- "mocha": "^10.2.0",
84
+ "globals": "^17.6.0",
85
+ "mocha": "^11.7.6",
82
86
  "msw": "^2.12.7",
83
- "sinon": "^15.1.2",
84
- "sinon-chai": "^3.7.0",
85
- "typescript": "^5.1.3",
86
- "which": "^5.0.0"
87
+ "sinon": "^22.0.0",
88
+ "sinon-chai": "^4.0.1",
89
+ "typescript": "^6.0.3",
90
+ "which": "^7.0.0"
87
91
  },
88
92
  "mocha": {
89
93
  "check-leaks": false,
@@ -111,12 +115,13 @@
111
115
  "reporter": [
112
116
  "html",
113
117
  "json",
118
+ "lcov",
114
119
  "text"
115
120
  ]
116
121
  },
117
- "eslintIgnore": [
118
- "index.js"
119
- ],
122
+ "overrides": {
123
+ "tree-sitter": "0.22.4"
124
+ },
120
125
  "resolutions": {
121
126
  "@hapi/joi": "17.1.1"
122
127
  }