adds documentation about unauthenticated scanning

timbastin · timbastin · commit 0d2cc7485fa6 · 2026-02-22T10:36:53.000+01:00
diff --git a/src/pages/how-to-guides/scanning/scan-dependencies.mdx b/src/pages/how-to-guides/scanning/scan-dependencies.mdx
@@ -100,6 +100,26 @@ The output shows each affected library with its vulnerabilities, the contextual
 
 **Verify it worked:** Navigate to your repository in DevGuard. You'll see detected vulnerabilities listed with severity scores, affected components, and fix recommendations. Learn more about [vulnerability types](/explanations/core-concepts/vulnerability-types) and the [vulnerability lifecycle](/explanations/vulnerability-management/vulnerability-lifecycle).
 
+## Scan Without Authentication
+
+You can run the scanner without a token or asset name to get vulnerability results without saving them to DevGuard. This is useful for a quick local scan or for trying out the scanner.
+
+```bash copy
+docker run -v "$(PWD):/dev/app" ghcr.io/l3montree-dev/devguard/scanner:main-latest \
+  devguard-scanner sca \
+    --path /dev/app/
+```
+
+When no `--token` and `--assetName` are provided, the scanner will print a warning and return the vulnerability results without persisting them:
+
+```
+Warning: You are scanning without saving the results. Provide --token and --assetName to save results to DevGuard.
+```
+
+<Callout type="info">
+  Unauthenticated scans check your dependencies against the vulnerability database and show results in the terminal, but findings are not tracked in DevGuard and will not appear in your repository's vulnerability dashboard.
+</Callout>
+
 ## CI/CD Integration
 
 For automated dependency scanning in CI/CD pipelines, DevGuard provides ready-to-use integrations:
diff --git a/src/pages/how-to-guides/scanning/upload-sbom.mdx b/src/pages/how-to-guides/scanning/upload-sbom.mdx
@@ -49,6 +49,47 @@ docker run -v "$(PWD):/dev/app" ghcr.io/l3montree-dev/devguard/scanner:main-late
 
 **Verify it worked:** Navigate to your repository in DevGuard. You'll see detected vulnerabilities listed with affected components and fix recommendations.
 
+## Scan Without Authentication
+
+You can upload an SBOM and scan it without a token or asset name to get vulnerability results without saving them to DevGuard.
+
+```bash copy
+docker run -v "$(PWD):/dev/app" ghcr.io/l3montree-dev/devguard/scanner:main-latest \
+  devguard-scanner sbom /dev/app/sbom.json
+```
+
+When no `--token` and `--assetName` are provided, the scanner will print a warning and return results without persisting them:
+
+```
+Warning: You are scanning without saving the results. Provide --token and --assetName to save results to DevGuard.
+```
+
+<Callout type="info">
+  Unauthenticated scans check your SBOM against the vulnerability database and show results in the terminal, but findings are not tracked in DevGuard and will not appear in your repository's vulnerability dashboard.
+</Callout>
+
+## Merge and Scan Multiple SBOMs
+
+Use `merge-sboms` to combine multiple CycloneDX SBOMs and pipe the result directly into the `sbom` command for scanning. Pass `-` as the file argument to read from stdin:
+
+```bash copy
+devguard-scanner merge-sboms config.json | devguard-scanner sbom -
+```
+
+The merge config file specifies the target purl and the list of SBOM files to merge:
+
+```json
+{ "purl": "pkg:foo/bar@1.2.3", "sboms": ["a.json", "b.json"] }
+```
+
+To save the merged scan results to DevGuard, add authentication flags:
+
+```bash copy
+devguard-scanner merge-sboms config.json | devguard-scanner sbom - \
+  --assetName="myorg/projects/myproject/assets/myrepo" \
+  --token="YOUR_TOKEN"
+```
+
 ## CI/CD Integration
 For automated SBOM uploads in CI/CD pipelines, DevGuard provides ready-to-use integrations:
 - **GitHub Actions**: See [Scan with GitHub Actions](./scan-with-github-actions) for setup instructions
diff --git a/src/pages/reference/scanner/container-scanning.md b/src/pages/reference/scanner/container-scanning.md
@@ -29,23 +29,24 @@ devguard-scanner container-scanning [flags]
 ### Options
 
 ```shell
-      --apiUrl string                The url of the API to send the scan request to (default "https://api.devguard.org")
-      --artifactName string          The name of the artifact which was scanned. If not specified, it will default to the empty artifact name ''.
-      --assetName string             The id of the asset which is scanned
-      --defaultRef string            The default git reference to use. This can be a branch, tag, or commit hash. If not specified, it will check, if the current directory is a git repo. If it isn't, --ref will be used.
-      --failOnCVSS string            The risk level to fail the scan on. Can be 'low', 'medium', 'high' or 'critical'. Defaults to 'critical'. (default "critical")
-      --failOnRisk string            The risk level to fail the scan on. Can be 'low', 'medium', 'high' or 'critical'. Defaults to 'critical'. (default "critical")
-  -h, --help                         help for container-scanning
-      --ignoreExternalReferences     If an attestation does contain a external reference to an sbom or vex, this will be ignored. Useful when scanning your own image from the registry where your own attestations are attached.
-      --ignoreUpstreamAttestations   Ignores attestations from the scanned container image - if they exists
-      --image string                 OCI image reference to scan (e.g. ghcr.io/org/image:tag). If empty, --path or the first argument may be used to provide a tar or local files.
-      --isTag                        If the current git reference is a tag. If not specified, it will check if the current directory is a git repo. If it isn't, it will be set to false.
-      --origin string                Origin of the SBOM (how it was generated). Examples: 'source-scanning', 'container-scanning', 'base-image'. Default: 'container-scanning'. (default "DEFAULT")
-      --path string                  Path to a tar file or directory containing the container image to scan. If empty, --image must be provided or an argument.
-      --ref string                   The git reference to use. This can be a branch, tag, or commit hash. If not specified, it will first check for a git repository in the current directory. If not found, it will just use main.
-      --timeout int                  Set the timeout for scanner operations in seconds (default 300)
-      --token string                 The personal access token to authenticate the request
-      --webUI string                 The url of the web UI to show the scan results in. Defaults to 'https://app.devguard.org'. (default "https://app.devguard.org")
+      --apiUrl string                   The url of the API to send the scan request to (default "https://api.devguard.org")
+      --artifactName string             The name of the artifact which was scanned. If not specified, it will default to the empty artifact name ''.
+      --assetName string                The id of the asset which is scanned
+      --defaultRef string               The default git reference to use. This can be a branch, tag, or commit hash. If not specified, it will check, if the current directory is a git repo. If it isn't, --ref will be used.
+      --failOnCVSS string               The risk level to fail the scan on. Can be 'low', 'medium', 'high' or 'critical'. Defaults to 'critical'. (default "critical")
+      --failOnRisk string               The risk level to fail the scan on. Can be 'low', 'medium', 'high' or 'critical'. Defaults to 'critical'. (default "critical")
+  -h, --help                            help for container-scanning
+      --ignoreExternalReferences        If an attestation does contain a external reference to an sbom or vex, this will be ignored. Useful when scanning your own image from the registry where your own attestations are attached.
+      --ignoreUpstreamAttestations      Ignores attestations from the scanned container image - if they exists
+      --image string                    OCI image reference to scan (e.g. ghcr.io/org/image:tag). If empty, --path or the first argument may be used to provide a tar or local files.
+      --isTag                           If the current git reference is a tag. If not specified, it will check if the current directory is a git repo. If it isn't, it will be set to false.
+      --keepOriginalSbomRootComponent   Use this flag if you get software from a supplier and you want to identify vulnerabilities in the root component itself, not only in the dependencies
+      --origin string                   Origin of the SBOM (how it was generated). Examples: 'source-scanning', 'container-scanning', 'base-image'. Default: 'container-scanning'. (default "DEFAULT")
+      --path string                     Path to a tar file or directory containing the container image to scan. If empty, --image must be provided or an argument.
+      --ref string                      The git reference to use. This can be a branch, tag, or commit hash. If not specified, it will first check for a git repository in the current directory. If not found, it will just use main.
+      --timeout int                     Set the timeout for scanner operations in seconds (default 300)
+      --token string                    The personal access token to authenticate the request
+      --webUI string                    The url of the web UI to show the scan results in. Defaults to 'https://app.devguard.org'. (default "https://app.devguard.org")
 ```
 
 ### Options inherited from parent commands
diff --git a/src/pages/reference/scanner/devguard-scanner.md b/src/pages/reference/scanner/devguard-scanner.md
@@ -0,0 +1,36 @@
+## devguard-scanner
+
+Secure your Software Supply Chain
+
+### Synopsis
+
+Secure your Software Supply Chain
+
+DevGuard Scanner is a small CLI to help generate, sign and upload SBOMs, SARIF
+reports and attestations to a DevGuard backend. Use commands like 'sca', 'sarif',
+and 'attest' to interact with the platform. Configuration can be provided via a
+./.devguard config file or environment variables (prefix DEVGUARD_).
+
+### Examples
+
+```shell
+  # Run Software Composition Analysis on a container image
+  devguard-scanner sca ghcr.io/org/image:tag
+
+  # Run SCA on a local project directory
+  devguard-scanner sca ./path/to/project
+
+  # Create and upload an attestation
+  devguard-scanner attest predicate.json ghcr.io/org/image:tag --predicateType https://cyclonedx.org/vex/1.0
+
+  # Upload a SARIF report
+  devguard-scanner sarif results.sarif.json
+```
+
+### Options
+
+```shell
+  -h, --help              help for devguard-scanner
+  -l, --logLevel string   Set the log level. Options: debug, info, warn, error (default "info")
+  -t, --toggle            Help message for toggle
+```
diff --git a/src/pages/reference/scanner/inspect.md b/src/pages/reference/scanner/inspect.md
@@ -0,0 +1,34 @@
+## inspect
+
+Inspect PURL for matching CVEs and vulnerabilities
+
+### Synopsis
+
+Inspects a Package URL (PURL) against the vulnerability database and displays
+detailed information about matching CVEs, affected components, and relationships.
+
+Shows both raw matches and deduplicated results (after alias resolution).
+
+Examples:
+  devguard-cli vulndb inspect "pkg:npm/lodash@4.17.20"
+  devguard-cli vulndb inspect "pkg:deb/debian/libc6@2.31-1"
+  devguard-cli vulndb inspect "pkg:pypi/requests@2.25.0"
+
+```shell
+devguard-scanner inspect <purl> [flags]
+```
+
+### Options
+
+```shell
+      --apiUrl string       The url of the API to send the request to (default "https://api.devguard.org")
+  -h, --help                help for inspect
+      --outputPath string   Path to save the inspection result as JSON file (optional)
+      --timeout int         Set the timeout for scanner operations in seconds (default 300)
+```
+
+### Options inherited from parent commands
+
+```shell
+  -l, --logLevel string   Set the log level. Options: debug, info, warn, error (default "info")
+```
diff --git a/src/pages/reference/scanner/kyverno2sarif.md b/src/pages/reference/scanner/kyverno2sarif.md
@@ -1,17 +1,16 @@
 ## kyverno2sarif
 
-Converts JSON output generated by the kyverno test command into SARIF format.
+Convert Kyverno test output to SARIF
 
-### How to use the command
+### Synopsis
 
-This is the basic command syntax to convert files:
+Converts JSON output generated by the kyverno test command into SARIF format.
 
 ```shell
 devguard-scanner kyverno2sarif [flags]
 ```
 
-The -i flag specifies the input file to be converted. By default, the resulting SARIF output is printed to the console.
-To save the SARIF output to a file instead, use the -o flag to specify the output file path and name.
+### Examples
 
 ```shell
   # Convert Kyverno output to SARIF
@@ -25,7 +24,7 @@ To save the SARIF output to a file instead, use the -o flag to specify the outpu
 
 ```shell
   -h, --help            help for kyverno2sarif
-  -i, --input string    Input file containing Kyverno test output (json)
+  -i, --input string    Input file containing Kyverno test output (must be json format)
   -o, --output string   Output SARIF file (default: stdout)
 ```
 
diff --git a/src/pages/reference/scanner/sbom.md b/src/pages/reference/scanner/sbom.md
@@ -6,20 +6,23 @@ Scan a CycloneDX SBOM for vulnerabilities
 
 Scan a CycloneDX Software Bill of Materials (SBOM) and upload it to DevGuard for vulnerability analysis.
 
-Only CycloneDX-formatted SBOMs are supported. The command signs the request using the configured token and returns scan results.
+Only CycloneDX-formatted SBOMs are supported. Pass a file path, '-' to read from stdin, or omit the argument to read from stdin.
 
 ```shell
-devguard-scanner sbom <sbom.json> [flags]
+devguard-scanner sbom [sbom.json|-] [flags]
 ```
 
 ### Examples
 
 ```shell
-  # Scan a CycloneDX SBOM
+  # Scan a CycloneDX SBOM from a file
   devguard-scanner sbom my-bom.json
 
+  # Scan from stdin (pipe from merge-sboms)
+  devguard-scanner merge-sboms config.json | devguard-scanner sbom -
+
   # Scan with custom asset name
-  devguard-scanner sbom my-bom.json --assetName my-app
+  devguard-scanner sbom my-bom.json --assetName my-app --token YOUR_TOKEN
 
   # Fail on high risk vulnerabilities
   devguard-scanner sbom my-bom.json --failOnRisk high
@@ -28,20 +31,21 @@ devguard-scanner sbom <sbom.json> [flags]
 ### Options
 
 ```shell
-      --apiUrl string              The url of the API to send the scan request to (default "https://api.devguard.org")
-      --artifactName string        The name of the artifact which was scanned. If not specified, it will default to the empty artifact name ''.
-      --assetName string           The id of the asset which is scanned
-      --defaultRef string          The default git reference to use. This can be a branch, tag, or commit hash. If not specified, it will check, if the current directory is a git repo. If it isn't, --ref will be used.
-      --failOnCVSS string          The risk level to fail the scan on. Can be 'low', 'medium', 'high' or 'critical'. Defaults to 'critical'. (default "critical")
-      --failOnRisk string          The risk level to fail the scan on. Can be 'low', 'medium', 'high' or 'critical'. Defaults to 'critical'. (default "critical")
-  -h, --help                       help for sbom
-      --ignoreExternalReferences   If an attestation does contain a external reference to an sbom or vex, this will be ignored. Useful when scanning your own image from the registry where your own attestations are attached.
-      --isTag                      If the current git reference is a tag. If not specified, it will check if the current directory is a git repo. If it isn't, it will be set to false.
-      --origin string              Origin of the SBOM (how it was generated). Examples: 'source-scanning', 'container-scanning', 'base-image'. Default: 'container-scanning'. (default "DEFAULT")
-      --ref string                 The git reference to use. This can be a branch, tag, or commit hash. If not specified, it will first check for a git repository in the current directory. If not found, it will just use main.
-      --timeout int                Set the timeout for scanner operations in seconds (default 300)
-      --token string               The personal access token to authenticate the request
-      --webUI string               The url of the web UI to show the scan results in. Defaults to 'https://app.devguard.org'. (default "https://app.devguard.org")
+      --apiUrl string                   The url of the API to send the scan request to (default "https://api.devguard.org")
+      --artifactName string             The name of the artifact which was scanned. If not specified, it will default to the empty artifact name ''.
+      --assetName string                The id of the asset which is scanned
+      --defaultRef string               The default git reference to use. This can be a branch, tag, or commit hash. If not specified, it will check, if the current directory is a git repo. If it isn't, --ref will be used.
+      --failOnCVSS string               The risk level to fail the scan on. Can be 'low', 'medium', 'high' or 'critical'. Defaults to 'critical'. (default "critical")
+      --failOnRisk string               The risk level to fail the scan on. Can be 'low', 'medium', 'high' or 'critical'. Defaults to 'critical'. (default "critical")
+  -h, --help                            help for sbom
+      --ignoreExternalReferences        If an attestation does contain a external reference to an sbom or vex, this will be ignored. Useful when scanning your own image from the registry where your own attestations are attached.
+      --isTag                           If the current git reference is a tag. If not specified, it will check if the current directory is a git repo. If it isn't, it will be set to false.
+      --keepOriginalSbomRootComponent   Use this flag if you get software from a supplier and you want to identify vulnerabilities in the root component itself, not only in the dependencies
+      --origin string                   Origin of the SBOM (how it was generated). Examples: 'source-scanning', 'container-scanning', 'base-image'. Default: 'container-scanning'. (default "DEFAULT")
+      --ref string                      The git reference to use. This can be a branch, tag, or commit hash. If not specified, it will first check for a git repository in the current directory. If not found, it will just use main.
+      --timeout int                     Set the timeout for scanner operations in seconds (default 300)
+      --token string                    The personal access token to authenticate the request
+      --webUI string                    The url of the web UI to show the scan results in. Defaults to 'https://app.devguard.org'. (default "https://app.devguard.org")
 ```
 
 ### Options inherited from parent commands
diff --git a/src/pages/reference/scanner/sca.md b/src/pages/reference/scanner/sca.md
diff --git a/src/pages/reference/scanner/vex.md b/src/pages/reference/scanner/vex.md
