diff --git a/CLAUDE.md b/CLAUDE.md index 76399eb..b60ee0f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,6 +38,7 @@ go test -v ./internal/output/... -run TestHumanFormatter - `scan.go` - Parent scan command with shared flags. Its `PersistentPreRunE` manually chains to `rootCmd.PersistentPreRunE` (Cobra does not auto-chain when a child also defines `PersistentPreRunE`). - `scan_repo.go` - Repository scanning subcommand - `scan_image.go` - Container image scanning subcommand (`--tarball` flag for pre-exported images) + - `bom.go`, `bom_repo.go`, `bom_image.go` - BOM-only scans (`bom repo`, `bom image`): `scan_type: "bom"`, BOM downloads through the `--bom` code, no findings - `auth.go` - Standalone `auth` command for testing JWT authentication (prints raw token) - `context.go` - Signal handling: `NewSignalContext()` creates context canceled on SIGINT/SIGTERM diff --git a/README.md b/README.md index e13108b..5146f9d 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ Enterprise-grade CLI for static application security scanning with Armis Cloud. - Multiple output formats: human, JSON, SARIF, JUnit XML - **SBOM generation**: Generate a Software Bill of Materials in CycloneDX (default) or SPDX 2.3 format - **VEX generation**: Generate Vulnerability Exploitability eXchange documents +- **BOMs without a security scan**: `armis-cli bom repo` and `armis-cli bom image` build a software BOM, AI-BOM, CBOM or combined BOM - **Supply chain protection**: Block packages published too recently (typosquatting, compromised maintainers, dependency confusion) across npm, Python, and Java — no Armis Cloud auth required - CI/CD ready: GitHub Actions, Jenkins, GitLab, Azure, Bitbucket, CircleCI - Configurable exit codes and fail-on severity @@ -502,6 +503,8 @@ Invoke-WebRequest -Uri "https://github.com/ArmisSecurity/armis-cli/releases/late > The `--sbom`, `--sbom-format`, `--vex`, `--sbom-output`, and `--vex-output` flags are specific to the `scan` commands — see [Scan Repository](#scan-repository). Their meaning differs on [Scan SBOM](#scan-sbom), which takes an SBOM as input rather than generating one. > > The `--bom`, `--bom-format`, and `--bom-output` flags apply to `scan repo` and `scan image` — see [BOMs](#boms-ai-bom-cbom-sbom). `scan sbom` and `scan status` ignore them; `--bom` prints a warning there. +> +> `bom repo` and `bom image` take these values as `--type`, `--format` and `--output`, and none of the findings flags — see [BOMs Without a Security Scan](#boms-without-a-security-scan). ### Scan Repository @@ -585,9 +588,9 @@ Notes: and `cbom` or `all` with any SPDX value. A format the server does not offer for a type fails the scan request after upload, with exit code 1 and `the server refused the BOM request (--bom --bom-format ): ()`. -- `--bom-output` names a directory (default `.armis`), or `-` to write one type to stdout. In Windows PowerShell 5.1, `>` saves stdout as UTF-16, which many JSON tools reject; use a directory there, or cmd.exe or PowerShell 7.4 or later, which keep the bytes as written. +- `--bom-output` names a directory (default `.armis`), or `-` to write one type to stdout. The CLI names the files in the directory, so each is written to a temp file and renamed over the old one, and a symlink or a non-regular file at that name is refused, as in `.armis`. The directory itself may be a symlink. In Windows PowerShell 5.1, `>` saves stdout as UTF-16, which many JSON tools reject; use a directory there, or cmd.exe or PowerShell 7.4 or later, which keep the bytes as written. - Without `--bom`, a non-default `--bom-format` prints `--bom-format is ignored without --bom flag`, any `--bom-output` prints the same for `--bom-output`, and the scan runs as without them. -- Each file holds the stored document, pretty-printed. On Linux and macOS, new files get mode 0600, and so does a file replaced in the default `.armis`; on Windows, they take the folder's permissions instead. SPDX files end in `.spdx.json`. With `--bom-output -`, stdout gets the document as the server stored it, without pretty-printing. +- Each file holds the stored document, pretty-printed. On Linux and macOS, new files get mode 0600, and so does a replaced file; on Windows, they take the folder's permissions instead. SPDX files end in `.spdx.json`. With `--bom-output -`, stdout gets the document as the server stored it, without pretty-printing. - `--sbom` is separate and unchanged: it still writes `-sbom.json`. - An empty BOM is still written, and stderr says so, such as `No AI components found in ./my-app`. The exit code does not change. @@ -595,10 +598,12 @@ Notes: warning and does not change the exit code. The warning says whether the type is not supported for this scan, failed on the server (with the tools that failed anywhere in the scan, if any), or was too large to store. +- A BOM written while BOM tools failed on the server, such as `generated` or `empty` with `failed_tools` set, prints `BOM tools failed on the server: ; may be incomplete` after the BOM lines; the exit code does not change. `bom repo` and `bom image` do the same. - A BOM that was built but cannot be downloaded prints a warning and the scan exits 2, unless `--fail-on` triggers first (see [Exit Codes](#exit-codes)). - With `--changed` or `--include-files`, BOMs cover only the uploaded files. - The same flags are available on `scan image`. +- To build BOMs without the security scan, use [`armis-cli bom`](#boms-without-a-security-scan). #### Scan Only Changed Files @@ -748,9 +753,80 @@ Either way, findings are printed as a table (same shape as `scan repo` / `scan i > > `--sbom` is a no-op on `scan sbom` (you can't generate an SBOM from an SBOM) and prints a warning if passed. +### BOMs Without a Security Scan + +`armis-cli bom` builds the BOMs of a repository or a container image and +downloads them, without running a security scan, so it takes less time than +`scan repo --bom` or `scan image --bom`. It uploads what those commands upload +and writes the same files. BOM generation must be enabled for your tenant; +without it, each requested type prints a "not available" warning, no BOM is +written, and the command exits 2. + +```bash +armis-cli bom repo [path] +armis-cli bom image [image-name] +armis-cli bom image --tarball [path-to-tarball] +``` + +**Examples**: + +```bash +# Combined BOM (the default) → .armis/-bom-all.json +armis-cli bom repo ./my-app + +# AI-BOM and CBOM as CycloneDX 1.6 into ./boms +armis-cli bom repo ./my-app --type aibom,cbom --format cyclonedx-1.6 --output ./boms + +# SPDX 2.3 software BOM of an image → .armis/python-3.12-slim-bom-sbom.spdx.json +armis-cli bom image python:3.12-slim --type sbom --format spdx + +# The CBOM of a tarball to stdout +armis-cli bom image --tarball ./image.tar --type cbom --output - > cbom.json +``` + +| Flag | Values | Default | +|------|--------|---------| +| `--type` | `sbom`, `aibom`, `cbom`, `all` (the combined BOM), comma-separated or repeated | `all` | +| `--format` | `cyclonedx-1.7`, `cyclonedx-1.6`, `spdx-2.3`, `spdx-3.0.1`, or the aliases `cyclonedx`, `spdx` | `cyclonedx-1.7` | +| `--output` | A directory, or `-` to write one BOM to stdout. A path that does not exist and ends in `.json` is refused, with a hint to use `--output -` (one type) or a directory | `.armis` | + +Notes: + +- The values and their rules are those of `--bom`, `--bom-format` and + `--bom-output` (see [BOMs](#boms-ai-bom-cbom-sbom)): `cbom` and `all` have no + SPDX form, so `--format spdx` needs `--type sbom` or `aibom`; without + `--type`, the message says `--type all (the default)`. A rejected value exits + 1 before upload. +- In an `--output` directory, as in `.armis`, each file is written to a temp + file and renamed over the old one, and a symlink or a non-regular file at its + name is refused. The directory itself may be a symlink. +- `bom repo` also takes `--include-files` and `--include-tests`, and sends the + git hints `scan repo` sends (see [Incremental Scan Git Hints](#incremental-scan-git-hints)), + so the BOMs name the repository and commit; `bom image` takes `--pull` and + `--tarball`, and sends the image name as `scan image` does. Both take + `--scan-timeout`, `--upload-timeout` and `--no-progress`. +- There is no findings report, and no `--fail-on`. stderr shows the progress + and one line per file written; stdout gets a BOM only with `--output -`. +- Exit codes: `0` when at least one BOM was written and none failed to download; `2` when no BOM was written or a built BOM could not be downloaded; `1` on errors; `130` on Ctrl+C. A type not offered only warns, + and `--output -` with nothing to write writes nothing and exits `2`. +- On a server that predates BOM-only scans, the command exits 1 after the + upload with + `this Armis server does not support BOM-only scans yet; run: armis-cli scan repo|image [tenant flags] [upload flags] --bom [--bom-format ] [--bom-output ]`. + The command after `run: ` is the matching `scan repo` or `scan image` with + `--bom`, which runs a security scan as well. It names the target, the + `--tenant-id`, `--region` and `--dev` flags you typed, `--include-files`, + `--include-tests` or `--pull`, the format and the directory you gave, and + single-quotes only the values a shell would read differently. It leaves + credentials (`--token`, `--client-id`, `--client-secret`) and values from + environment variables out of the line, so paste it into a shell where they + are set, and it uses them from there. A value with a control character is + shown as a placeholder such as ``, to fill in. A request the server + refuses exits 1 with + `the server refused the BOM request (--type --format ): ()`. + ### Check Scan Status -Fetch the current status of a scan initiated with `scan repo`, `scan image`, or `scan sbom`. +Fetch the current status of a scan initiated with `scan repo`, `scan image`, `scan sbom`, or `bom`. ```bash armis-cli scan status [scan_id] @@ -1365,7 +1441,7 @@ Before users can sign in with SSO, an IT admin registers the tenant's identity p - `0` - Scan completed with no blocking findings - `--exit-code` value (default `1`) - Scan found findings at a `--fail-on` severity - `1` - Error: invalid flags, authentication, upload, timeout, or a failed scan -- `2` - Scan completed, but its results or a requested BOM could not be downloaded +- `2` - Scan completed, but its results or a requested BOM could not be downloaded, or `bom` wrote no BOM - `130` - Scan cancelled with Ctrl+C With the default `--exit-code 1`, findings and errors share exit code `1`; set diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 45359b6..a4cdacd 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -9,6 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- `scan repo`/`scan image`/`bom repo`/`bom image`: a BOM written while BOM tools failed on the server (`bom_summary.failed_tools`) now prints `BOM tools failed on the server: ; may be incomplete` after the BOM lines, instead of passing silently. The exit code does not change. +- `bom repo`/`bom image`: new commands build BOMs without a security scan and download them, which takes less time than `scan repo|image --bom`. The upload, file names and `.armis` default are those of `--bom`; there is no findings report and no `--fail-on`. BOM generation must be enabled for the tenant. The ingest request carries `scan_type: "bom"`. +- `bom repo`/`bom image`: new `--type` flag takes `sbom`, `aibom`, `cbom` or `all`, comma-separated or repeated; the default is `all`, the combined BOM. A refused pair with the default says `--type all (the default)`. +- `bom repo`/`bom image`: new `--format` and `--output` flags take the values of `--bom-format` and `--bom-output`. A missing `--output` path that ends in `.json` is refused before upload, with a hint to use `--output -` (for one type) or a directory. +- `bom repo`/`bom image`: exit codes are 0 when at least one BOM was written and none failed to download, 2 when no BOM was written or a built BOM could not be downloaded, 1 on errors and 130 on Ctrl+C. +- `bom repo`/`bom image`: a server without BOM-only scans exits 1 with `run: armis-cli scan repo|image ... --bom ...`, the matching `scan --bom` command, which runs a security scan as well. It names the target, the `--tenant-id`, `--region` and `--dev` flags typed, `--include-files`, `--include-tests` or `--pull`, the format and the output directory given, and single-quotes only values a shell would read differently. Credentials and values from the environment are left out of the line, so it uses those of the shell it is pasted into; a value with a control character is shown as a placeholder such as ``. +- `bom repo`: takes `--include-files` and `--include-tests`, and sends the git hints `scan repo` sends (`repo_name`, `git_sha`, `origin_sha` for a full upload of a checkout), so the BOMs name the repository and commit. `bom image`: takes `--pull` and `--tarball`, and sends `image_ref` as `scan image --bom` does. + ### Changed ### Deprecated @@ -17,8 +25,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- `scan repo`/`bom repo`: the `repo_name` git hint drops the query and fragment of an `http` or `https` origin URL, so a remote such as `https://github.com/org/repo.git?access_token=...` gives `org/repo`, not `org/repo.git?access_token=...`. Other remotes keep `?` and `#`, which git reads as part of their path. + ### Security +- `scan repo`/`scan image`/`scan status`/`bom`: control characters, such as terminal escapes, are stripped from server text the CLI prints: an unknown scan status in the progress line, a failed scan's error, a scanner-skip reason, and every field of `scan status`. Line breaks and tabs in server text now become one space, so a multi-line error no longer runs its words together. +- `scan repo`/`scan image` `--bom-output` and `bom repo`/`bom image` `--output`: BOM files written into the directory are now written to a temp file and renamed over the old one, as in the default `.armis`, and a symlink or non-regular file at the BOM's file name is refused, so a link committed in a scanned repository cannot redirect the write. The directory itself is still used as given, a symlinked one included. File paths given in `--sbom-output`, `--vex-output` and `--bom-output -` are written in place as before. + --- ## [1.27.0] - 2026-11-17 diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 9597a33..457d97a 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -348,6 +348,9 @@ armis-cli scan image nginx:latest --sbom --vex | `--bom` | BOM types to download, comma-separated or repeated: `sbom`, `aibom`, `cbom`, `all` | none | | `--bom-format` | BOM format: `cyclonedx-1.7`, `cyclonedx-1.6`, `spdx-2.3`, `spdx-3.0.1`, or the aliases `cyclonedx`, `spdx`; without `--bom`, a non-default value is ignored with a warning | `cyclonedx-1.7` | | `--bom-output` | Directory for BOM files, or `-` to write one BOM to stdout; ignored with a warning without `--bom` | `.armis` | +| `--type` (`bom repo`, `bom image`) | BOM types to build without a security scan, comma-separated or repeated: `sbom`, `aibom`, `cbom`, `all` | `all` | +| `--format` (`bom repo`, `bom image`) | BOM format, the values of `--bom-format` | `cyclonedx-1.7` | +| `--output` (`bom repo`, `bom image`) | Directory for BOM files, or `-` to write one BOM to stdout; a missing path ending in `.json` is refused | `.armis` | ### Output Location @@ -379,11 +382,29 @@ armis-cli scan image nginx:latest --bom all --bom-format cyclonedx-1.6 --bom-out `all` (combined). - Files are named `-bom-.json`, or `.spdx.json` for an SPDX format. - `scan repo` and `scan image` take these flags; `scan sbom` and `scan status` ignore them. +- A BOM written while a BOM tool failed on the server prints a warning that it may be incomplete; the exit code does not change. - A BOM that was built but cannot be downloaded exits `2`, unless `--fail-on` triggers first. A type the server did not build only warns. See [BOMs in the README](../README.md#boms-ai-bom-cbom-sbom) for the full rules. +#### BOMs without a security scan + +`armis-cli bom repo` and `armis-cli bom image` build the same BOMs without +running a security scan, so they take less time. They print no findings and +take no `--fail-on`. Exit codes: `0` when at least one BOM was written and none failed to download; `2` when no BOM was written or a built BOM could not be downloaded; `1` on errors. Without `--type`, they build +the combined BOM. + +```bash +# Combined BOM → .armis/-bom-all.json +armis-cli bom repo . + +# SBOM and CBOM of an image into ./boms +armis-cli bom image nginx:latest --type sbom,cbom --output ./boms +``` + +See [BOMs Without a Security Scan](../README.md#boms-without-a-security-scan). + ### CI/CD Example Generate SBOM and VEX as part of your CI pipeline: @@ -423,8 +444,11 @@ Generate SBOM and VEX as part of your CI pipeline: - In `scan repo` and `scan image`, the default `.armis` output is refused when `.armis` is not a plain directory, such as a symlink (checked before upload), or the file there is not a regular file. Files there are written to a temp - file and renamed over the old one, with mode 0600 on Linux and macOS. A path - given in an output flag is written as given + file and renamed over the old one, with mode 0600 on Linux and macOS. BOM + files in a `--bom-output` directory are written the same way, and a symlink + or non-regular file at their name is refused; the directory itself is used + as given, a symlink included. A file path given in `--sbom-output` or + `--vex-output` is written as given - Maximum download size is 100MB per file --- diff --git a/docs/ci-examples/README.md b/docs/ci-examples/README.md index 0860685..d3c90f5 100644 --- a/docs/ci-examples/README.md +++ b/docs/ci-examples/README.md @@ -75,6 +75,14 @@ armis-cli scan repo . --bom aibom,cbom --bom-output ./artifacts A BOM that was built but cannot be downloaded exits `2`, unless `--fail-on` triggers first. See [AI-BOM, CBOM and other BOMs](../CI-INTEGRATION.md#ai-bom-cbom-and-other-boms). +A job that needs only the BOMs can skip the security scan with `armis-cli bom`, which takes less time and has no `--fail-on`: + +```bash +armis-cli bom repo . --type aibom,cbom --output ./artifacts +``` + +Exit codes: `0` when at least one BOM was written and none failed to download; `2` when no BOM was written or a built BOM could not be downloaded; `1` on errors, including a server that does not offer BOM-only scans yet. A tenant without BOM generation writes no BOM and exits `2`. See [BOMs Without a Security Scan](../../README.md#boms-without-a-security-scan). + ## Quick Start ### For GitHub Actions diff --git a/internal/api/client.go b/internal/api/client.go index 879f9c9..67d450e 100644 --- a/internal/api/client.go +++ b/internal/api/client.go @@ -330,8 +330,21 @@ type IngestOptions struct { BOMFormat string // ImageRef names the scanned image for its BOMs; empty is omitted. ImageRef string + // ScanType is the scan_type sent to /scan: ScanTypeBOM for a BOM-only + // scan (armis-cli bom); empty sends ScanTypeFull. + ScanType string } +// Values of the /scan request's scan_type field. +const ( + ScanTypeFull = "full" // a security scan, as before scan_type was settable + ScanTypeBOM = "bom" // builds the requested BOMs only, with no findings +) + +// ErrBOMScanUnsupported is returned by StartIngest when the server rejects +// scan_type "bom" as an unknown value: the server predates BOM-only scans. +var ErrBOMScanUnsupported = errors.New("this Armis server does not support BOM-only scans yet") + // StatusCallback is called on each poll with the current scan status. // It allows callers to react to status changes (e.g., updating a spinner). type StatusCallback func(status model.IngestStatusData) @@ -547,7 +560,7 @@ func (c *Client) startArtifactScan(ctx context.Context, scanID string, opts Inge body := model.IngestScanStartRequest{ ScanID: scanID, TenantID: opts.TenantID, - ScanType: "full", // matches the prior /tar behavior; flag-driven scan_type is a future change + ScanType: scanType(opts), SBOMGenerate: opts.GenerateSBOM, SBOMFormat: opts.SBOMFormat, VEXGenerate: opts.GenerateVEX, @@ -585,6 +598,9 @@ func (c *Client) startArtifactScan(ctx context.Context, scanID string, opts Inge } if resp.StatusCode != http.StatusOK { + if opts.ScanType == ScanTypeBOM && rejectsScanType(resp.StatusCode, respBytes) { + return nil, ErrBOMScanUnsupported + } if msg, ok := bomRefusal(resp.StatusCode, respBytes, opts); ok { return nil, errors.New(msg) } @@ -602,14 +618,49 @@ func (c *Client) startArtifactScan(ctx context.Context, scanID string, opts Inge return &result, nil } +// scanType returns the scan_type of a /scan request: ScanTypeFull unless +// opts asks for another. +func scanType(opts IngestOptions) string { + if opts.ScanType == "" { + return ScanTypeFull + } + return opts.ScanType +} + +// rejectsScanType reports whether a 422 answer is a request validation error +// on the scan_type field, such as +// {"detail":[{"loc":["body","scan_type"],"msg":"Input should be 'full' or 'custom'"}]}, +// which a server that predates BOM-only scans gives for scan_type "bom". +func rejectsScanType(status int, body []byte) bool { + if status != http.StatusUnprocessableEntity { + return false + } + var parsed struct { + Detail []struct { + Loc []any `json:"loc"` + } `json:"detail"` + } + if err := json.Unmarshal(body, &parsed); err != nil { + return false + } + for _, d := range parsed.Detail { + if n := len(d.Loc); n > 0 && d.Loc[n-1] == "scan_type" { + return true + } + } + return false +} + // bomRefusal reads a 422 answer to a /scan request with BOM fields, such as // {"detail":{"code":"export_format_unavailable","message":"..."}}, as "the // server refused the BOM request (--bom --bom-format ): -// ()", so the message says what was asked. Server text has +// ()", so the message says what was asked. A BOM-only scan +// names the flags of armis-cli bom, --type and --format. Server text has // control characters stripped. ok is false for any other answer, which keeps // the raw text. func bomRefusal(status int, body []byte, opts IngestOptions) (string, bool) { - if status != http.StatusUnprocessableEntity || len(opts.BOMTypes) == 0 { + bomOnly := opts.ScanType == ScanTypeBOM + if status != http.StatusUnprocessableEntity || (len(opts.BOMTypes) == 0 && !bomOnly) { return "", false } var parsed struct { @@ -621,11 +672,22 @@ func bomRefusal(status int, body []byte, opts IngestOptions) (string, bool) { if err := json.Unmarshal(body, &parsed); err != nil || parsed.Detail.Message == "" { return "", false } - asked := "--bom " + strings.Join(opts.BOMTypes, ",") + typeFlag, formatFlag := "--bom", "--bom-format" + if bomOnly { + typeFlag, formatFlag = "--type", "--format" + } + var asked []string + if len(opts.BOMTypes) > 0 { + asked = append(asked, typeFlag+" "+strings.Join(opts.BOMTypes, ",")) + } if opts.BOMFormat != "" { - asked += " --bom-format " + opts.BOMFormat + asked = append(asked, formatFlag+" "+opts.BOMFormat) + } + msg := "the server refused the BOM request" + if len(asked) > 0 { + msg += " (" + strings.Join(asked, " ") + ")" } - msg := "the server refused the BOM request (" + asked + "): " + util.StripControl(parsed.Detail.Message) + msg += ": " + util.StripControl(parsed.Detail.Message) if code := util.StripControl(parsed.Detail.Code); code != "" { msg += " (" + code + ")" } @@ -719,7 +781,7 @@ func (c *Client) WaitForIngest(ctx context.Context, tenantID, scanID string, pol if statusUpper == "FAILED" { if status.LastError != nil && *status.LastError != "" { - return nil, fmt.Errorf("scan failed: %s", *status.LastError) + return nil, fmt.Errorf("scan failed: %s", util.StripControl(*status.LastError)) } return nil, fmt.Errorf("scan failed with no error message (scan_id: %s)", scanID) } diff --git a/internal/api/client_test.go b/internal/api/client_test.go index 97cecbc..7b8414d 100644 --- a/internal/api/client_test.go +++ b/internal/api/client_test.go @@ -608,6 +608,72 @@ func TestClient_StartIngest(t *testing.T) { } }) + t.Run("BOM-only scans send scan_type bom and read the 422 answers", func(t *testing.T) { + const oldServer = `{"detail":[{"type":"enum","loc":["body","scan_type"],"msg":"Input should be 'full' or 'custom'","input":"bom"}]}` + rows := []struct { + name string + scanType string + status int + body string + wantScanType string + wantErr string // "" for success + wantOld bool // want ErrBOMScanUnsupported + }{ + {name: "a full scan sends full", wantScanType: "full"}, + {name: "a BOM-only scan sends bom", scanType: ScanTypeBOM, wantScanType: "bom"}, + {name: "an old server rejects scan_type bom", scanType: ScanTypeBOM, status: http.StatusUnprocessableEntity, body: oldServer, + wantScanType: "bom", wantErr: "failed to trigger scan: this Armis server does not support BOM-only scans yet", wantOld: true}, + {name: "a scan_type error on a full scan keeps the raw text", status: http.StatusUnprocessableEntity, body: oldServer, + wantScanType: "full", wantErr: `/scan returned 422 Unprocessable Entity: {"detail":[`}, + {name: "a validation error on another field keeps the raw text", scanType: ScanTypeBOM, status: http.StatusUnprocessableEntity, + body: `{"detail":[{"loc":["body","bom_format"],"msg":"bad"}]}`, wantScanType: "bom", wantErr: `/scan returned 422 Unprocessable Entity: {"detail":[`}, + {name: "a 400 naming scan_type keeps the raw text", scanType: ScanTypeBOM, status: http.StatusBadRequest, body: oldServer, + wantScanType: "bom", wantErr: "/scan returned 400 Bad Request"}, + {name: "a refusal names the bom flags", scanType: ScanTypeBOM, status: http.StatusUnprocessableEntity, + body: `{"detail":{"code":"sbom_vex_not_allowed","message":"SBOM and VEX are not built by a BOM-only scan"}}`, wantScanType: "bom", + wantErr: "the server refused the BOM request (--type aibom,cbom --format spdx): SBOM and VEX are not built by a BOM-only scan (sbom_vex_not_allowed)"}, + {name: "a refusal without types still names the bom flags", scanType: ScanTypeBOM, status: http.StatusUnprocessableEntity, + body: `{"detail":{"code":"bom_types_required","message":"bom_types must not be empty"}}`, wantScanType: "bom", + wantErr: "the server refused the BOM request: bom_types must not be empty (bom_types_required)"}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + t.Parallel() + srv, state := newIngestFlowServer(t) + if row.status != 0 { + state.overrideScan = func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(row.status) + _, _ = io.WriteString(w, row.body) + } + } + client := newIngestFlowClient(t, srv.URL) + opts := IngestOptions{ + TenantID: "tenant-456", ArtifactType: "repo", Filename: "test.tar.gz", + Data: bytes.NewReader([]byte("test")), Size: 4, ScanType: row.scanType, + } + if !strings.Contains(row.name, "without types") { + opts.BOMTypes, opts.BOMFormat = []string{"aibom", "cbom"}, "spdx" + } + _, err := client.StartIngest(context.Background(), opts) + if got := scanBody(t, state)["scan_type"]; got != row.wantScanType { + t.Errorf("scan_type = %v, want %s", got, row.wantScanType) + } + if row.wantErr == "" { + if err != nil { + t.Fatalf("StartIngest: %v", err) + } + return + } + if err == nil || !strings.Contains(err.Error(), row.wantErr) { + t.Fatalf("error = %v, want it to contain %q", err, row.wantErr) + } + if errors.Is(err, ErrBOMScanUnsupported) != row.wantOld { + t.Errorf("errors.Is(err, ErrBOMScanUnsupported) = %v, want %v", !row.wantOld, row.wantOld) + } + }) + } + }) + t.Run("the raw /scan error has no control characters", func(t *testing.T) { t.Parallel() srv, state := newIngestFlowServer(t) @@ -620,7 +686,7 @@ func TestClient_StartIngest(t *testing.T) { TenantID: "tenant-456", ArtifactType: "repo", Filename: "test.tar.gz", Data: bytes.NewReader([]byte("test")), Size: 4, }) - if err == nil || !strings.Contains(err.Error(), "/scan returned 409 Conflict: upload[2J not foundretry") { + if err == nil || !strings.Contains(err.Error(), "/scan returned 409 Conflict: upload[2J not found retry") { t.Fatalf("error = %v, want the body without control characters", err) } if strings.ContainsAny(err.Error(), "\x1b\x07\r\n\u009b") { diff --git a/internal/cmd/bom.go b/internal/cmd/bom.go new file mode 100644 index 0000000..3a4c631 --- /dev/null +++ b/internal/cmd/bom.go @@ -0,0 +1,243 @@ +package cmd + +import ( + "context" + "errors" + "fmt" + "strings" + "time" + "unicode" + "unicode/utf8" + + "github.com/ArmisSecurity/armis-cli/internal/api" + "github.com/ArmisSecurity/armis-cli/internal/cmd/cmdutil" + "github.com/ArmisSecurity/armis-cli/internal/model" + "github.com/ArmisSecurity/armis-cli/internal/output" + "github.com/ArmisSecurity/armis-cli/internal/scan" + "github.com/spf13/cobra" +) + +// The --type, --format and --output values of bom repo and bom image. They +// are not the scan --bom variables: --type has a default, --bom has none. +var ( + bomOnlyTypes []string + bomOnlyFormat string + bomOnlyOutput string +) + +// defaultBOMOnlyTypes is the --type default: the combined BOM, one file. It +// is applied when --type is not given, not as the flag's default, so that +// --type= stays an error, as --bom= is. +func defaultBOMOnlyTypes() []string { return []string{scan.BOMTypeAll} } + +// bomTenantNote says what every bom command needs from the tenant. +const bomTenantNote = `BOM generation must be enabled for your tenant; without it, each type +prints a "not available" warning and no BOM is written. + +Exit codes: 0 when at least one BOM was written and none failed to download; +2 when no BOM was written or a built BOM could not be downloaded; 1 on errors; +130 on Ctrl+C.` + +var bomCmd = &cobra.Command{ + Use: "bom", + Short: "Build BOMs without a security scan", + Long: `Build the BOMs (bills of materials) of a repository or a container image and +download them, without a security scan: a software BOM (sbom), an AI-BOM +(aibom), a CBOM (cbom), or the combined BOM of all three (all). + +Without --type, the combined BOM is built: one file with every type. +` + bomTenantNote, + Example: ` $ armis-cli bom repo . + $ armis-cli bom repo . --type aibom,cbom + $ armis-cli bom image python:3.12-slim --type sbom --format spdx + $ armis-cli bom image --tarball ./image.tar --output -`, + PersistentPreRunE: func(cmd *cobra.Command, args []string) error { + // Cobra does not chain PersistentPreRunE to the root's; see scanCmd. + if rootCmd != nil && rootCmd.PersistentPreRunE != nil { + if err := rootCmd.PersistentPreRunE(cmd, args); err != nil { + return err + } + } + typeFlag := cmd.Flag("type") + if err := checkBOMOnlyFlags(typeFlag != nil && typeFlag.Changed); err != nil { + return err + } + return validateTimeouts() + }, +} + +// checkBOMOnlyFlags checks --type, --format and --output before auth and +// upload, normalizing the types and format in place, with the checks scan +// repo and scan image run on --bom: the values, each type and format pair, +// the output, and a default .armis that is not a plain directory. typeSet +// reports whether --type was given; without it the type is all. +func checkBOMOnlyFlags(typeSet bool) error { + names := cmdutil.BOMCommandFlags + if !typeSet { + bomOnlyTypes = defaultBOMOnlyTypes() + names.DefaultTypes = true + } + types, format, err := cmdutil.NormalizeBOMFlags(names, bomOnlyTypes, true, bomOnlyFormat) + if err != nil { + return err + } + bomOnlyTypes, bomOnlyFormat = types, format + if err := cmdutil.ValidateBOMFlags(names, bomOnlyTypes, bomOnlyFormat, bomOnlyOutput); err != nil { + return err + } + if err := cmdutil.RefuseFileNameOutput(names, bomOnlyOutput, bomOnlyTypes); err != nil { + return err + } + if bomOnlyOutput == "" { + return scan.CheckDefaultOutputDir(scan.BOMLabel(bomOnlyTypes[0])) + } + return nil +} + +// bomOnlyOptions returns the options of a BOM-only scan of target, as typed. +func bomOnlyOptions(target string) *scan.SBOMVEXOptions { + return &scan.SBOMVEXOptions{BOM: &scan.BOMOptions{ + Types: bomOnlyTypes, + Format: bomOnlyFormat, + Output: bomOnlyOutput, + Target: target, + Only: true, + }} +} + +// newBOMClient authenticates and returns the API client and tenant ID, as +// the scan subcommands do. +func newBOMClient(ctx context.Context) (*api.Client, string, error) { + authProvider, err := getAuthProvider(ctx) + if err != nil { + return nil, "", err + } + // Defensive nil-check, as in scan repo: getAuthProvider returns + // (non-nil, nil) on success. + if authProvider == nil { + return nil, "", fmt.Errorf("internal error: nil auth provider") + } + tid, err := authProvider.GetTenantID(ctx) + if err != nil { + return nil, "", err + } + baseURL := resolveDataPlaneURL(ctx, authProvider) + client, err := api.NewClient(baseURL, authProvider, debug, time.Duration(uploadTimeout)*time.Minute, + clientOptionsForBaseURL(baseURL)...) + if err != nil { + return nil, "", fmt.Errorf("failed to create API client: %w", err) + } + return client, tid, nil +} + +// bomOnlyExit is the exit error of a finished BOM-only scan: bomExit's for a +// built BOM that could not be downloaded, and exit 2 as well when no +// requested BOM was written, since writing them is all the command does. +func bomOnlyExit(result *model.ScanResult) error { + if err := bomExit(result, nil); err != nil { + return err + } + if result != nil && len(result.BOMWritten) > 0 { + return nil + } + labels := make([]string, 0, len(bomOnlyTypes)) + for _, t := range bomOnlyTypes { + labels = append(labels, scan.BOMLabel(t)) + } + var scanID string + if result != nil { + scanID = result.ScanID + } + return &output.ErrBOMIncomplete{ScanID: scanID, Labels: labels, NotWritten: true} +} + +// bomScanError returns the error handler of a BOM-only scan of kind (repo or +// image). target and flags are as scanBOMCommand takes them. A server that +// predates BOM-only scans gets a plain message ending in the scan command +// that gives the same BOMs, unquoted after "run: " so it can be pasted into +// a shell as printed; any other error is handled as a failed scan. +func bomScanError(kind, target string, flags []string) func(context.Context, error) error { + return func(ctx context.Context, err error) error { + if errors.Is(err, api.ErrBOMScanUnsupported) { + return fmt.Errorf("%w; run: %s", api.ErrBOMScanUnsupported, scanBOMCommand(kind, target, flags)) + } + return handleScanError(ctx, err) + } +} + +// bomTenantFlags are the global flags typed on the command line that choose +// the tenant and the environment (--tenant-id, --region, --dev), for the scan +// command of an older server. Values from the environment stay implicit, and +// credentials (--token, --client-id, --client-secret) are never repeated. +func bomTenantFlags(cmd *cobra.Command) []string { + typed := func(name string) bool { + f := cmd.Flag(name) + return f != nil && f.Changed + } + var flags []string + if typed("tenant-id") { + flags = append(flags, "--tenant-id", shellArg(tenantID, "")) + } + if typed("region") { + flags = append(flags, "--region", shellArg(region, "")) + } + if typed("dev") && useDev { + flags = append(flags, "--dev") + } + return flags +} + +// scanBOMCommand is the scan command that downloads the requested BOMs with +// a security scan: target as typed (a path, an image name, or --tarball and +// a file), then flags (the tenant flags typed, and the upload flags given +// that change what is uploaded, such as --include-files or --pull), then the +// types, and the format and output directory when they are not the +// defaults. target and flags are already quoted with shellArg. +func scanBOMCommand(kind, target string, flags []string) string { + parts := append([]string{"armis-cli", "scan", kind, target}, flags...) + parts = append(parts, "--bom", strings.Join(bomOnlyTypes, ",")) + if bomOnlyFormat != scan.BOMFormatCycloneDX17 { + parts = append(parts, "--bom-format", bomOnlyFormat) + } + if bomOnlyOutput != "" { + parts = append(parts, "--bom-output", shellArg(bomOnlyOutput, "")) + } + return strings.Join(parts, " ") +} + +// shellArg returns s ready to paste into a POSIX shell command line. A value +// that is not valid UTF-8 or has a control character, such as a tab, a line +// break or a C1 byte that 8-bit terminals read as an escape, cannot be +// printed as typed, so placeholder (such as ) stands in for it rather +// than a different value. Otherwise s is printed as is when it holds only +// letters, digits and _ . / : @ + , -, which no shell treats specially, else +// in single quotes. So = and ~ are always quoted, as zsh can expand them +// anywhere in a word (MAGIC_EQUAL_SUBST), and so is a leading #. Inside +// single quotes only the quote character is special: each one closes the +// quotes, adds a backslash-escaped quote and opens them again. Single quotes +// also keep bash's ! history expansion off. +func shellArg(s, placeholder string) string { + if !utf8.ValidString(s) || strings.ContainsFunc(s, unicode.IsControl) { + return placeholder + } + const plain = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_./:@+,-" + if s != "" && strings.Trim(s, plain) == "" { + return s + } + return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'" +} + +func init() { + bomCmd.PersistentFlags().StringSliceVar(&bomOnlyTypes, "type", nil, + "BOM types, comma-separated or repeated: sbom, aibom, cbom, all (the combined BOM, one file) (default: all)") + bomCmd.PersistentFlags().StringVar(&bomOnlyFormat, "format", scan.BOMFormatCycloneDX17, + "BOM format: cyclonedx-1.7, cyclonedx-1.6, spdx-2.3, spdx-3.0.1, or the aliases cyclonedx, spdx") + bomCmd.PersistentFlags().StringVar(&bomOnlyOutput, "output", "", + "Directory for BOM files, or - to write one BOM to stdout (default: .armis)") + _ = bomCmd.RegisterFlagCompletionFunc("type", bomTypeCompletions()) + _ = bomCmd.RegisterFlagCompletionFunc("format", bomFormatCompletions()) + addUploadFlags(bomCmd) + if rootCmd != nil { + rootCmd.AddCommand(bomCmd) + } +} diff --git a/internal/cmd/bom_hint_test.go b/internal/cmd/bom_hint_test.go new file mode 100644 index 0000000..d1b30d3 --- /dev/null +++ b/internal/cmd/bom_hint_test.go @@ -0,0 +1,392 @@ +package cmd + +import ( + "context" + "fmt" + "net/http" + "os/exec" + "path/filepath" + "reflect" + "runtime" + "strings" + "testing" + + "github.com/ArmisSecurity/armis-cli/internal/api" + "github.com/ArmisSecurity/armis-cli/internal/scan" + "github.com/ArmisSecurity/armis-cli/internal/testutil" + "github.com/spf13/cobra" +) + +// TestShellArg: a value pastes back into a POSIX shell, and zsh, as the same +// argument; a value with a control character becomes the placeholder. +func TestShellArg(t *testing.T) { + rows := []struct{ in, want string }{ + {"./my-app", "./my-app"}, + {"ghcr.io/org/app:1.2", "ghcr.io/org/app:1.2"}, + {"a,b.go", "a,b.go"}, + {"a=b", "'a=b'"}, + {"a==ls", "'a==ls'"}, + {"x=a:=ls", "'x=a:=ls'"}, + {"a~b", "'a~b'"}, + {"my app", "'my app'"}, + {"wow!", "'wow!'"}, + {"$HOME/x", "'$HOME/x'"}, + {"a`id`b", "'a`id`b'"}, + {"it's", `'it'\''s'`}, + {`back\slash "q"`, `'back\slash "q"'`}, + {"=t1", "'=t1'"}, + {"~/boms", "'~/boms'"}, + {"#tag", "'#tag'"}, + {"", "''"}, + {"my\tapp", ""}, + {"two\nlines", ""}, + {"esc\x1b[2J", ""}, + {"c1\x9bbyte", ""}, + {"bad\xffutf8", ""}, + {"ok ünïcode 服务", "'ok ünïcode 服务'"}, + } + // Each shell reads the value back; zsh also with MAGIC_EQUAL_SUBST, + // which expands = and ~ inside a word. + type shell struct{ path, setup string } + var shells []shell + if runtime.GOOS != "windows" { + if path, err := exec.LookPath("sh"); err == nil { + shells = append(shells, shell{path, ""}) + } + if path, err := exec.LookPath("zsh"); err == nil { + shells = append(shells, shell{path, ""}, shell{path, "setopt MAGIC_EQUAL_SUBST; "}) + } + } + for _, row := range rows { + t.Run(row.in, func(t *testing.T) { + got := shellArg(row.in, "") + if got != row.want { + t.Fatalf("shellArg(%q) = %s, want %s", row.in, got, row.want) + } + if got == "" { + return + } + for _, sh := range shells { + out, err := exec.Command(sh.path, "-c", sh.setup+"printf %s "+got).CombinedOutput() //nolint:gosec // test input from the table + if err != nil || string(out) != row.in { + t.Errorf("%s %sread %s back as %q (%v), want %q", sh.path, sh.setup, got, out, err, row.in) + } + } + }) + } +} + +// TestScanBOMCommand covers the scan command named for an older server: the +// target, the upload flags that change what is uploaded, then the BOM flags. +func TestScanBOMCommand(t *testing.T) { + setupBOMRunEnv(t, "https://127.0.0.1:1") + rows := []struct { + name string + set func() + build func() string + want string + }{ + {"repo defaults", func() {}, func() string { return scanBOMCommand("repo", ".", bomRepoUploadFlags()) }, + "armis-cli scan repo . --bom all"}, + {"repo with every flag", func() { + includeFiles, includeTests = []string{"src/a.go", "my file.go"}, true + bomOnlyTypes, bomOnlyFormat, bomOnlyOutput = []string{"sbom", "cbom"}, "cyclonedx-1.6", "out dir" + }, func() string { return scanBOMCommand("repo", shellArg("./my app", ""), bomRepoUploadFlags()) }, + "armis-cli scan repo './my app' --include-files 'src/a.go,my file.go' --include-tests --bom sbom,cbom --bom-format cyclonedx-1.6 --bom-output 'out dir'"}, + {"image by name with --pull", func() { pullPolicy = "always" }, + func() string { + return scanBOMCommand("image", bomImageTarget([]string{"nginx:1.27"}), bomImagePullFlags()) + }, + "armis-cli scan image nginx:1.27 --pull always --bom all"}, + {"image by name, default --pull", func() {}, + func() string { + return scanBOMCommand("image", bomImageTarget([]string{"nginx:1.27"}), bomImagePullFlags()) + }, + "armis-cli scan image nginx:1.27 --bom all"}, + {"--tarball ignores --pull", func() { tarballPath, pullPolicy = "./img.tar", "never" }, + func() string { return scanBOMCommand("image", bomImageTarget(nil), bomImagePullFlags()) }, + "armis-cli scan image --tarball ./img.tar --bom all"}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + bomOnlyTypes, bomOnlyFormat, bomOnlyOutput = defaultBOMOnlyTypes(), scan.BOMFormatCycloneDX17, "" + includeFiles, includeTests, tarballPath, pullPolicy = nil, false, "", defaultPullPolicy + row.set() + if got := row.build(); got != row.want { + t.Errorf("got %s\nwant %s", got, row.want) + } + }) + } +} + +// TestOldServerHint checks the whole message for an older server: the exact +// text for a plain path and a path with a space, and that everything after +// "run: " is a command line a POSIX shell splits back into the arguments. +func TestOldServerHint(t *testing.T) { + setupBOMRunEnv(t, "https://127.0.0.1:1") + const prefix = "this Armis server does not support BOM-only scans yet; run: " + rows := []struct { + name string + kind string + target string + set func() + flags func() []string + wantText string // checked when set + wantArgs []string + }{ + {name: "a plain path", kind: "repo", target: "./app", flags: bomRepoUploadFlags, + wantText: prefix + "armis-cli scan repo ./app --bom all", + wantArgs: []string{"armis-cli", "scan", "repo", "./app", "--bom", "all"}}, + {name: "a path with a space", kind: "repo", target: "my app", flags: bomRepoUploadFlags, + wantText: prefix + "armis-cli scan repo 'my app' --bom all", + wantArgs: []string{"armis-cli", "scan", "repo", "my app", "--bom", "all"}}, + {name: "shell characters everywhere", kind: "repo", target: "it's $HOME `x` wow!", + set: func() { + includeFiles, includeTests = []string{"a b.go", "c$d.go"}, true + bomOnlyTypes, bomOnlyFormat, bomOnlyOutput = []string{"sbom", "cbom"}, "cyclonedx-1.6", "out 'dir'!" + }, + flags: bomRepoUploadFlags, + wantArgs: []string{"armis-cli", "scan", "repo", "it's $HOME `x` wow!", "--include-files", "a b.go,c$d.go", "--include-tests", + "--bom", "sbom,cbom", "--bom-format", "cyclonedx-1.6", "--bom-output", "out 'dir'!"}}, + {name: "a path with a tab is a placeholder", kind: "repo", target: "my\tapp", flags: bomRepoUploadFlags, + wantText: prefix + "armis-cli scan repo --bom all"}, + {name: "a path with a line break is a placeholder", kind: "repo", target: "my\napp", flags: bomRepoUploadFlags, + wantText: prefix + "armis-cli scan repo --bom all"}, + {name: "an image with a control character is a placeholder", kind: "image", target: "app\x1b:1", flags: bomImagePullFlags, + wantText: prefix + "armis-cli scan image --bom all"}, + {name: "an image by name with --pull", kind: "image", target: "nginx:1.27", + set: func() { pullPolicy = "always" }, + flags: bomImagePullFlags, + wantText: prefix + "armis-cli scan image nginx:1.27 --pull always --bom all", + wantArgs: []string{"armis-cli", "scan", "image", "nginx:1.27", "--pull", "always", "--bom", "all"}}, + } + sh, shErr := exec.LookPath("sh") + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + bomOnlyTypes, bomOnlyFormat, bomOnlyOutput = defaultBOMOnlyTypes(), scan.BOMFormatCycloneDX17, "" + includeFiles, includeTests, tarballPath, pullPolicy = nil, false, "", defaultPullPolicy + if row.set != nil { + row.set() + } + placeholder := "" + if row.kind == "image" { + placeholder = "" + } + err := bomScanError(row.kind, shellArg(row.target, placeholder), row.flags())(context.Background(), + fmt.Errorf("failed to trigger scan: %w", api.ErrBOMScanUnsupported)) + text := err.Error() + if row.wantText != "" && text != row.wantText { + t.Errorf("message = %q\nwant %q", text, row.wantText) + } + command, ok := strings.CutPrefix(text, prefix) + if !ok { + t.Fatalf("message = %q, want it to start with %q", text, prefix) + } + if row.wantArgs == nil { + return // a placeholder is for the user to fill in + } + if shErr != nil || runtime.GOOS == "windows" { + t.Skip("no POSIX shell to split the command") + } + // As if typed: sh -c 'printf "%s\n" "$@"' _ + out, err := exec.Command(sh, "-c", `sh -c 'printf "%s\n" "$@"' _ `+command).Output() //nolint:gosec // test input from the table + if err != nil { + t.Fatalf("sh: %v", err) + } + got := strings.Split(strings.TrimSuffix(string(out), "\n"), "\n") + if !reflect.DeepEqual(got, row.wantArgs) { + t.Errorf("sh split %s into\n%q\nwant\n%q", command, got, row.wantArgs) + } + }) + } +} + +// TestOldServerHintTenantFlags runs the real command line against an older +// server: --tenant-id, --region and --dev typed on the command line are in +// the suggested command, values from the environment are not, and no +// credential ever is. +func TestOldServerHintTenantFlags(t *testing.T) { + const secret = "s3cr3t-token-value" + const prefix = "this Armis server does not support BOM-only scans yet; run: " + rows := []struct { + name string + image bool + region string // ARMIS_REGION + args []string + want string // after the target + }{ + {name: "from the environment", want: " --bom all"}, + {name: "a region from the environment stays out", region: "eu1", want: " --bom all"}, + {name: "typed tenant, region and dev", args: []string{"--tenant-id", "tenant 7", "--region", "eu1", "--dev", "--token", secret}, + want: " --tenant-id 'tenant 7' --region eu1 --dev --bom all"}, + {name: "--dev=false is left out", args: []string{"--dev=false", "--tenant-id", "t-1"}, want: " --tenant-id t-1 --bom all"}, + {name: "bom image with a typed tenant", image: true, args: []string{"--tenant-id", "t-1", "--token", secret}, + want: " --tenant-id t-1 --bom all"}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, testutil.MockAPIConfig{ + ScanStatus: http.StatusUnprocessableEntity, ScanBody: oldServerBody, + })) + t.Setenv("ARMIS_API_TOKEN", secret) + t.Setenv("ARMIS_TENANT_ID", "env-tenant") + t.Setenv("ARMIS_REGION", row.region) + origDev, origRegion := useDev, region + t.Cleanup(func() { + resetBOMFlags(t) + for _, name := range []string{"tenant-id", "region", "dev", "token"} { + resetParsedFlag(t, rootCmd.PersistentFlags(), name) + } + useDev, region = origDev, origRegion + rootCmd.SetArgs(nil) + }) + t.Chdir(t.TempDir()) + resetBOMFlags(t) + args := []string{"bom", "repo", createTestRepo(t)} + want := prefix + "armis-cli scan repo " + shellArg(args[2], "") + row.want + if row.image { + tarball := writeDockerSaveTar(t, "app.tar") + args = []string{"bom", "image", "--tarball", tarball} + want = prefix + "armis-cli scan image --tarball " + shellArg(tarball, "") + row.want + } + rootCmd.SetArgs(append(append(args, "--no-progress", "--poll-interval", "10ms"), row.args...)) + var err error + _ = testutil.CaptureStderr(t, func() { err = Execute() }) + if err == nil || err.Error() != want { + t.Fatalf("error = %v\nwant %s", err, want) + } + for _, leak := range []string{secret, "--token", "--client-id", "--client-secret", "env-tenant"} { + if strings.Contains(err.Error(), leak) { + t.Errorf("hint %q holds %q", err, leak) + } + } + }) + } +} + +// TestBOMTenantFlagsNeverNameCredentials: with every credential flag typed, +// the tenant flags hold none of them. +func TestBOMTenantFlagsNeverNameCredentials(t *testing.T) { + origTenant, origRegion, origDev := tenantID, region, useDev + origToken, origID, origSecret := token, clientID, clientSecret + t.Cleanup(func() { + for _, name := range []string{"tenant-id", "region", "dev", "token", "client-id", "client-secret"} { + resetParsedFlag(t, rootCmd.PersistentFlags(), name) + } + tenantID, region, useDev = origTenant, origRegion, origDev + token, clientID, clientSecret = origToken, origID, origSecret + }) + for name, value := range map[string]string{ + "token": "tok-SECRET", "client-id": "id-SECRET", "client-secret": "secret-SECRET", + "tenant-id": "t-1", "region": "eu1", "dev": "true", + } { + if err := rootCmd.PersistentFlags().Set(name, value); err != nil { + t.Fatalf("set --%s: %v", name, err) + } + } + got := strings.Join(bomTenantFlags(bomRepoCmd), " ") + if got != "--tenant-id t-1 --region eu1 --dev" { + t.Errorf("bomTenantFlags = %q, want the tenant flags only", got) + } + if strings.Contains(got, "SECRET") || strings.Contains(got, "--token") || strings.Contains(got, "--client") { + t.Errorf("bomTenantFlags = %q names a credential", got) + } +} + +// TestWantGitHints: scan repo and bom repo send git hints for a full upload +// only, not with --include-files or --changed. +func TestWantGitHints(t *testing.T) { + origFiles, origChanged := includeFiles, changedRef + t.Cleanup(func() { + includeFiles, changedRef = origFiles, origChanged + _ = scanRepoCmd.Flags().Set("changed", "") + scanRepoCmd.Flags().Lookup("changed").Changed = false + }) + rows := []struct { + name string + cmd *cobra.Command + files []string + changed bool + want bool + }{ + {"scan repo, full upload", scanRepoCmd, nil, false, true}, + {"scan repo --include-files", scanRepoCmd, []string{"a.go"}, false, false}, + {"scan repo --changed", scanRepoCmd, nil, true, false}, + {"bom repo, full upload", bomRepoCmd, nil, false, true}, + {"bom repo --include-files", bomRepoCmd, []string{"a.go"}, false, false}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + includeFiles = row.files + _ = scanRepoCmd.Flags().Set("changed", "") + scanRepoCmd.Flags().Lookup("changed").Changed = false + if row.changed { + if err := scanRepoCmd.Flags().Set("changed", "staged"); err != nil { + t.Fatalf("set --changed: %v", err) + } + } + if got := wantGitHints(row.cmd); got != row.want { + t.Errorf("wantGitHints = %v, want %v", got, row.want) + } + }) + } +} + +// TestOldServerHintDashTargets: a repo path that starts with - is printed as +// ./-x, which cobra parses as the same path, not as a flag; an image name +// that starts with - is a placeholder. +func TestOldServerHintDashTargets(t *testing.T) { + setupBOMRunEnv(t, "https://127.0.0.1:1") + const prefix = "this Armis server does not support BOM-only scans yet; run: " + rows := []struct { + name string + image bool + target string + wantText string + wantTarget string // "" for a placeholder + }{ + {name: "repo -x", target: "-x", wantText: prefix + "armis-cli scan repo ./-x --bom all", wantTarget: "-x"}, + {name: "repo --weird dir", target: "--weird dir", wantText: prefix + "armis-cli scan repo './--weird dir' --bom all", wantTarget: "--weird dir"}, + {name: "repo ./-x stays", target: "./-x", wantText: prefix + "armis-cli scan repo ./-x --bom all", wantTarget: "-x"}, + {name: "image -x", image: true, target: "-x", wantText: prefix + "armis-cli scan image --bom all"}, + } + sh, shErr := exec.LookPath("sh") + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + kind, target := "repo", repoTargetArg(row.target) + if row.image { + kind, target = "image", bomImageTarget([]string{row.target}) + } + err := bomScanError(kind, target, nil)(context.Background(), api.ErrBOMScanUnsupported) + if err.Error() != row.wantText { + t.Fatalf("message = %q\nwant %q", err, row.wantText) + } + if row.wantTarget == "" || shErr != nil || runtime.GOOS == "windows" { + return + } + command := strings.TrimPrefix(err.Error(), prefix) + out, runErr := exec.Command(sh, "-c", `sh -c 'printf "%s\n" "$@"' _ `+command).Output() //nolint:gosec // test input from the table + if runErr != nil { + t.Fatalf("sh: %v", runErr) + } + args := strings.Split(strings.TrimSuffix(string(out), "\n"), "\n") + // Parse what follows "armis-cli scan repo" as cobra does, with the + // flags the line can hold. + var got []string + c := &cobra.Command{Use: "repo [path]", Args: cobra.MaximumNArgs(1), SilenceErrors: true, SilenceUsage: true, + RunE: func(_ *cobra.Command, a []string) error { got = a; return nil }} + c.Flags().StringSlice("bom", nil, "") + c.Flags().String("bom-format", "", "") + c.Flags().String("bom-output", "", "") + c.Flags().StringSlice("include-files", nil, "") + c.Flags().Bool("include-tests", false, "") + c.SetArgs(args[3:]) + if err := c.Execute(); err != nil { + t.Fatalf("cobra rejects %q: %v", args[3:], err) + } + if len(got) != 1 || filepath.Clean(got[0]) != filepath.Clean(row.wantTarget) { + t.Errorf("cobra read the target as %q, want %q", got, row.wantTarget) + } + }) + } +} diff --git a/internal/cmd/bom_image.go b/internal/cmd/bom_image.go new file mode 100644 index 0000000..350f36e --- /dev/null +++ b/internal/cmd/bom_image.go @@ -0,0 +1,85 @@ +package cmd + +import ( + "strings" + "time" + + "github.com/ArmisSecurity/armis-cli/internal/scan/image" + "github.com/spf13/cobra" +) + +var bomImageCmd = &cobra.Command{ + Use: "image [image-name]", + Short: "Build the BOMs of a container image", + Long: `Build the BOMs of a container image without a security scan, and download +them to .armis/-bom-.json (.spdx.json for SPDX). The image is +read as scan image reads it: exported with Docker or Podman by name, or from +--tarball, and the BOMs name it. + +Without --type, the combined BOM is built: one file with every type. +` + bomTenantNote, + Example: ` $ armis-cli bom image python:3.12-slim + $ armis-cli bom image nginx:1.27 --type sbom,cbom --pull always + $ armis-cli bom image --tarball ./image.tar --type sbom --format spdx + $ armis-cli bom image --tarball ./image.tar --output -`, + Args: cobra.MaximumNArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + // PersistentPreRunE has checked --type, --format and --output. + if err := checkImageTarget(args); err != nil { + return err + } + + client, tid, err := newBOMClient(cmd.Context()) + if err != nil { + return err + } + // No findings are fetched, so there is no page limit and no + // exploitability filter. + scanner := image.NewScanner(client, noProgress, tid, 0, false, time.Duration(scanTimeout)*time.Minute, false). + WithPullPolicy(pullPolicy). + WithSBOMVEXOptions(bomOnlyOptions(imageTarget(args))) + if pollInterval > 0 { + scanner = scanner.WithPollInterval(pollInterval) + } + + ctx, cancel := NewSignalContext() + defer cancel() + + result, err := scanImageTarget(ctx, scanner, args, bomScanError("image", bomImageTarget(args), append(bomTenantFlags(cmd), bomImagePullFlags()...))) + if err != nil { + return err + } + return bomOnlyExit(result) + }, +} + +// bomImageTarget is the target of bom image for the scan image command line: +// --tarball and the file, which wins over an image name, or the name. A name +// that starts with - would read as a flag, and is no valid image name, so +// the placeholder stands in for it. +func bomImageTarget(args []string) string { + if tarballPath != "" { + return "--tarball " + shellArg(tarballPath, "") + } + name := imageTarget(args) + if strings.HasPrefix(name, "-") { + return "" + } + return shellArg(name, "") +} + +// bomImagePullFlags is --pull as given to bom image, for the scan image +// command of an older server: none for --tarball, which ignores it, or for +// the default policy. +func bomImagePullFlags() []string { + if tarballPath != "" || pullPolicy == defaultPullPolicy { + return nil + } + return []string{"--pull", shellArg(pullPolicy, "")} +} + +func init() { + bomImageCmd.Flags().StringVar(&tarballPath, "tarball", "", tarballUsage) + bomImageCmd.Flags().StringVar(&pullPolicy, "pull", defaultPullPolicy, pullUsage) + bomCmd.AddCommand(bomImageCmd) +} diff --git a/internal/cmd/bom_repo.go b/internal/cmd/bom_repo.go new file mode 100644 index 0000000..e5d0937 --- /dev/null +++ b/internal/cmd/bom_repo.go @@ -0,0 +1,102 @@ +package cmd + +import ( + "strings" + "time" + + "github.com/ArmisSecurity/armis-cli/internal/cli" + "github.com/ArmisSecurity/armis-cli/internal/scan/repo" + "github.com/spf13/cobra" +) + +var bomRepoCmd = &cobra.Command{ + Use: "repo [path]", + Short: "Build the BOMs of a local repository", + Long: `Build the BOMs of a local repository without a security scan, and download +them to .armis/-bom-.json (.spdx.json for SPDX). The upload is the +one scan repo makes. + +Without --type, the combined BOM is built: one file with every type. +` + bomTenantNote, + Example: ` $ armis-cli bom repo . + $ armis-cli bom repo . --type aibom,cbom + $ armis-cli bom repo . --type sbom --format spdx + $ armis-cli bom repo . --type all --format cyclonedx-1.6 --output ./boms + $ armis-cli bom repo . --type cbom --output - > cbom.json`, + // The path is optional and defaults to the current directory, as in scan repo. + Args: cobra.MaximumNArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + // PersistentPreRunE has checked --type, --format and --output. + repoPath := repoArg(args) + if err := checkRepoPath(repoPath); err != nil { + return err + } + var fileList *repo.FileList + if len(includeFiles) > 0 { + var err error + if fileList, err = parseIncludeFiles(repoPath); err != nil { + return err + } + } + + client, tid, err := newBOMClient(cmd.Context()) + if err != nil { + return err + } + // No findings are fetched, so there is no page limit and no + // exploitability filter. Git hints are sent as scan repo sends them: + // the server names the BOM root after the repository and commit. + scanner := repo.NewScanner(client, noProgress, tid, 0, includeTests, time.Duration(scanTimeout)*time.Minute, false). + WithSBOMVEXOptions(bomOnlyOptions(repoPath)) + if wantGitHints(cmd) { + scanner = scanner.WithGitHints() + } + if pollInterval > 0 { + scanner = scanner.WithPollInterval(pollInterval) + } + if fileList != nil { + scanner = scanner.WithIncludeFiles(fileList) + // The BOMs are built from the upload, which holds only these files. + cli.PrintWarning("BOMs cover only the uploaded files") + } + + ctx, cancel := NewSignalContext() + defer cancel() + + // armis:ignore cwe:22 reason:repoPath is from direct CLI argument; validated as existing directory above + result, err := scanner.Scan(ctx, repoPath) + if err != nil { + return bomScanError("repo", repoTargetArg(repoPath), append(bomTenantFlags(cmd), bomRepoUploadFlags()...))(ctx, err) + } + return bomOnlyExit(result) + }, +} + +// repoTargetArg is the repository path for the scan repo command of an +// older server. A path that starts with - would read as a flag there, so it +// gets a ./ prefix, which names the same directory. +func repoTargetArg(path string) string { + if strings.HasPrefix(path, "-") { + path = "./" + path + } + return shellArg(path, "") +} + +// bomRepoUploadFlags are the flags given to bom repo that change the upload, +// for the scan repo command of an older server. +func bomRepoUploadFlags() []string { + var flags []string + if len(includeFiles) > 0 { + flags = append(flags, "--include-files", shellArg(strings.Join(includeFiles, ","), "")) + } + if includeTests { + flags = append(flags, "--include-tests") + } + return flags +} + +func init() { + bomRepoCmd.Flags().StringSliceVar(&includeFiles, "include-files", nil, includeFilesUsage) + bomRepoCmd.Flags().BoolVar(&includeTests, "include-tests", false, includeTestsUsage) + bomCmd.AddCommand(bomRepoCmd) +} diff --git a/internal/cmd/bom_test.go b/internal/cmd/bom_test.go new file mode 100644 index 0000000..1bca105 --- /dev/null +++ b/internal/cmd/bom_test.go @@ -0,0 +1,913 @@ +package cmd + +import ( + "archive/tar" + "bytes" + "context" + "encoding/json" + "errors" + "net/http" + "os" + "os/exec" + "path/filepath" + "reflect" + "runtime" + "strings" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/ArmisSecurity/armis-cli/internal/api" + "github.com/ArmisSecurity/armis-cli/internal/cli" + "github.com/ArmisSecurity/armis-cli/internal/model" + "github.com/ArmisSecurity/armis-cli/internal/output" + "github.com/ArmisSecurity/armis-cli/internal/scan" + "github.com/ArmisSecurity/armis-cli/internal/scan/repo" + "github.com/ArmisSecurity/armis-cli/internal/scan/testhelpers" + "github.com/ArmisSecurity/armis-cli/internal/testutil" + "github.com/spf13/cobra" +) + +// oldServerBody is the 422 a server that predates BOM-only scans gives for +// scan_type "bom": a request validation error, not the detail.code shape. +const oldServerBody = `{"detail":[{"type":"enum","loc":["body","scan_type"],"msg":"Input should be 'full' or 'custom'","input":"bom"}]}` + +// setupBOMRunEnv points the bom commands at serverURL, as setupScanRunEnv +// does for scan, and restores every global the bom commands read. +func setupBOMRunEnv(t *testing.T, serverURL string) { + t.Helper() + setupScanRunEnv(t, serverURL) + origTypes, origFormat, origOutput := bomOnlyTypes, bomOnlyFormat, bomOnlyOutput + origFiles, origTests, origTarball, origPull := includeFiles, includeTests, tarballPath, pullPolicy + origScanTimeout, origUploadTimeout := scanTimeout, uploadTimeout + t.Cleanup(func() { + bomOnlyTypes, bomOnlyFormat, bomOnlyOutput = origTypes, origFormat, origOutput + includeFiles, includeTests, tarballPath, pullPolicy = origFiles, origTests, origTarball, origPull + scanTimeout, uploadTimeout = origScanTimeout, origUploadTimeout + }) + bomOnlyTypes, bomOnlyFormat, bomOnlyOutput = defaultBOMOnlyTypes(), scan.BOMFormatCycloneDX17, "" + includeFiles, includeTests, tarballPath, pullPolicy = nil, false, "", defaultPullPolicy + scanTimeout, uploadTimeout = defaultScanTimeout, defaultUploadTimeout +} + +// runBOM runs c's RunE with args, as the RunE tests of scan do, and returns +// stdout, stderr and the error. The caller sets the normalized flag values. +func runBOM(t *testing.T, c *cobra.Command, args ...string) (stdout, stderr string, err error) { + t.Helper() + stderr = testutil.CaptureStderr(t, func() { + stdout = captureStdout(t, func() { err = c.RunE(c, args) }) + }) + return stdout, stderr, err +} + +// mainExitCode is the exit code cmd/armis-cli/main.go gives for err. +func mainExitCode(err error) int { + var findingsErr *output.ErrFindingsExceeded + var incompleteErr *output.ErrResultsIncomplete + var bomErr *output.ErrBOMIncomplete + switch { + case err == nil: + return 0 + case errors.As(err, &findingsErr): + return findingsErr.ExitCode + case errors.As(err, &incompleteErr), errors.As(err, &bomErr): + return 2 + case errors.Is(err, ErrScanCancelled): + return ExitCodeCancelled + } + return 1 +} + +// scanRecorder records the /scan bodies and the paths a mock server sees. +type scanRecorder struct { + mu sync.Mutex + bodies [][]byte + paths []string +} + +func (r *scanRecorder) hook(config testutil.MockAPIConfig) testutil.MockAPIConfig { + config.OnScanRequest = func(body []byte) { + r.mu.Lock() + defer r.mu.Unlock() + r.bodies = append(r.bodies, body) + } + config.OnRequest = func(req *http.Request) { + r.mu.Lock() + defer r.mu.Unlock() + r.paths = append(r.paths, req.URL.Path) + } + return config +} + +// body returns the one /scan body as a map, so tests see the keys on the wire. +func (r *scanRecorder) body(t *testing.T) map[string]any { + t.Helper() + r.mu.Lock() + defer r.mu.Unlock() + if len(r.bodies) != 1 { + t.Fatalf("got %d /scan requests, want 1", len(r.bodies)) + } + var got map[string]any + if err := json.Unmarshal(r.bodies[0], &got); err != nil { + t.Fatalf("decode /scan body %s: %v", r.bodies[0], err) + } + return got +} + +// called reports whether any request path contained part. +func (r *scanRecorder) called(part string) bool { + r.mu.Lock() + defer r.mu.Unlock() + for _, p := range r.paths { + if strings.Contains(p, part) { + return true + } + } + return false +} + +// writeDockerSaveTar writes a tarball with a docker save manifest.json that +// lists tags, and returns its path. +func writeDockerSaveTar(t *testing.T, name string, tags ...string) string { + t.Helper() + manifest, err := json.Marshal([]map[string]any{{"Config": "config.json", "RepoTags": tags, "Layers": []string{}}}) + if err != nil { + t.Fatal(err) + } + var buf bytes.Buffer + tw := tar.NewWriter(&buf) + if err := tw.WriteHeader(&tar.Header{Name: "manifest.json", Mode: 0600, Size: int64(len(manifest)), Format: tar.FormatUSTAR}); err != nil { + t.Fatal(err) + } + if _, err := tw.Write(manifest); err != nil { + t.Fatal(err) + } + if err := tw.Close(); err != nil { + t.Fatal(err) + } + path := filepath.Join(t.TempDir(), name) + if err := os.WriteFile(path, buf.Bytes(), 0600); err != nil { + t.Fatal(err) + } + return path +} + +// resetBOMFlags undoes what Execute parsed for the bom commands. +func resetBOMFlags(t *testing.T) { + t.Helper() + for _, name := range []string{"type", "format", "output", "no-progress", "scan-timeout", "upload-timeout", "poll-interval"} { + resetParsedFlag(t, bomCmd.PersistentFlags(), name) + } + for _, name := range []string{"include-files", "include-tests"} { + resetParsedFlag(t, bomRepoCmd.Flags(), name) + } + for _, name := range []string{"tarball", "pull"} { + resetParsedFlag(t, bomImageCmd.Flags(), name) + } +} + +// TestBOMCommandFlagErrorsStopBeforeUpload runs the real command line: every +// rejected input exits 1 before auth, so the API server sees no request. +func TestBOMCommandFlagErrorsStopBeforeUpload(t *testing.T) { + var requests atomic.Int32 + server := testutil.NewTestServer(t, func(w http.ResponseWriter, _ *http.Request) { + requests.Add(1) + w.WriteHeader(http.StatusInternalServerError) + }) + setupBOMRunEnv(t, server.URL) + t.Setenv("ARMIS_API_TOKEN", testToken) + t.Setenv("ARMIS_TENANT_ID", testTenantID) + t.Cleanup(func() { rootCmd.SetArgs(nil) }) + + repoDir := t.TempDir() + tarball := filepath.Join(t.TempDir(), "image.tar") + testhelpers.WriteMinimalTar(t, tarball) + + rows := []struct { + name string + args []string + wantErr string + }{ + {"--type=", []string{"bom", "repo", repoDir, "--type="}, "--type requires a value: one of [sbom aibom cbom all]"}, + {"only empty items", []string{"bom", "repo", repoDir, "--type", ","}, "--type requires a value"}, + {"unknown type", []string{"bom", "repo", repoDir, "--type", "aibom,xbom"}, `invalid --type value "xbom"`}, + {"unknown format", []string{"bom", "repo", repoDir, "--format", "xml"}, `invalid --format value "xml"`}, + {"the default type with spdx", []string{"bom", "repo", repoDir, "--format", "spdx"}, + "--format spdx is not available for --type all (the default): the Combined BOM has no SPDX form"}, + {"a typed all with spdx", []string{"bom", "repo", repoDir, "--type", "all", "--format", "spdx"}, + "--format spdx is not available for --type all: the Combined BOM has no SPDX form"}, + {"aibom with spdx-2.3", []string{"bom", "repo", repoDir, "--type", "aibom", "--format", "spdx-2.3"}, + "--format spdx-2.3 is not available for --type aibom: the AI-BOM's SPDX form is spdx-3.0.1"}, + {"cbom with SPDX-3.0.1 on an image", []string{"bom", "image", "--tarball", tarball, "--type", "cbom", "--format", "SPDX-3.0.1"}, + "the CBOM has no SPDX form"}, + {"stdout with two types", []string{"bom", "repo", repoDir, "--type", "cbom", "--type", "aibom", "--output", "-"}, + "--output - takes one BOM type, got 2: aibom,cbom"}, + {"output is a file", []string{"bom", "repo", repoDir, "--output", tarball}, "not a directory"}, + {"output with ..", []string{"bom", "repo", repoDir, "--output", "../boms"}, "path traversal detected"}, + {"output names a new .json file", []string{"bom", "repo", repoDir, "--output", filepath.Join(repoDir, "sbom.JSON")}, + "--output takes a directory, not a file name; use --output - to write the BOM to stdout, or name a directory"}, + {"output names a new .json file for two types", []string{"bom", "repo", repoDir, "--type", "sbom,cbom", "--output", filepath.Join(repoDir, "boms.json")}, + "--output takes a directory, not a file name; name a directory for the 2 BOM files"}, + {"scan timeout 0", []string{"bom", "repo", repoDir, "--scan-timeout", "0"}, "invalid --scan-timeout value 0"}, + {"upload timeout over 2 hours", []string{"bom", "image", "--tarball", tarball, "--upload-timeout", "121"}, "must not exceed 120 minutes"}, + {"repo path missing", []string{"bom", "repo", filepath.Join(repoDir, "none")}, "path does not exist"}, + {"repo path is a file", []string{"bom", "repo", tarball}, "path is not a directory"}, + {"--include-files outside the repo", []string{"bom", "repo", repoDir, "--include-files", "../x.go"}, "invalid --include-files"}, + {"image without a target", []string{"bom", "image"}, "missing target: specify an image name or use --tarball"}, + {"bad --pull", []string{"bom", "image", "app:1", "--pull", "sometimes"}, `invalid --pull value "sometimes"`}, + {"tarball missing", []string{"bom", "image", "--tarball", tarball + ".none"}, "tarball does not exist"}, + {"no --fail-on on bom", []string{"bom", "repo", repoDir, "--fail-on", "HIGH"}, "unknown flag: --fail-on"}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + // A slice flag appends after its first Set in this process, so + // start each row from the flag defaults. + resetBOMFlags(t) + t.Cleanup(func() { resetBOMFlags(t) }) + rootCmd.SetArgs(row.args) + err := Execute() + if err == nil || !strings.Contains(err.Error(), row.wantErr) { + t.Fatalf("error = %v, want it to contain %q", err, row.wantErr) + } + if code := mainExitCode(err); code != 1 { + t.Errorf("exit code = %d, want 1", code) + } + if n := requests.Load(); n != 0 { + t.Fatalf("server saw %d requests, want none before the error", n) + } + }) + } +} + +// TestBOMDefaultOutputDirStopsBeforeUpload: a default .armis that is a +// symlink, as a scanned repository can commit, stops bom before any request. +func TestBOMDefaultOutputDirStopsBeforeUpload(t *testing.T) { + var requests atomic.Int32 + server := testutil.NewTestServer(t, func(w http.ResponseWriter, _ *http.Request) { + requests.Add(1) + w.WriteHeader(http.StatusInternalServerError) + }) + setupBOMRunEnv(t, server.URL) + t.Setenv("ARMIS_API_TOKEN", testToken) + t.Setenv("ARMIS_TENANT_ID", testTenantID) + t.Cleanup(func() { rootCmd.SetArgs(nil) }) + repoDir := t.TempDir() + t.Chdir(t.TempDir()) + outside := t.TempDir() + if err := os.Symlink(outside, ".armis"); err != nil { + t.Skipf("cannot create symlink: %v", err) + } + + rows := []struct { + name string + args []string + wantErr string // "" passes the check + }{ + {"default output", []string{"bom", "repo", repoDir}, "invalid Combined BOM output path: .armis is not a plain directory"}, + {"default output, cbom", []string{"bom", "repo", repoDir, "--type", "cbom"}, "invalid CBOM output path: .armis is not a plain directory"}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + // A slice flag appends after its first Set in this process, so + // start each row from the flag defaults. + resetBOMFlags(t) + t.Cleanup(func() { resetBOMFlags(t) }) + rootCmd.SetArgs(row.args) + err := Execute() + if err == nil || !strings.Contains(err.Error(), row.wantErr) { + t.Fatalf("error = %v, want it to contain %q", err, row.wantErr) + } + if n := requests.Load(); n != 0 { + t.Fatalf("server saw %d requests, want none", n) + } + }) + } + if entries, _ := os.ReadDir(outside); len(entries) != 0 { + t.Errorf("wrote through the link: %v", entries) + } +} + +// TestBOMCommandLine runs the real command line against the mock API: the +// default type is all, the request is a BOM-only scan, no findings are +// fetched, and one file is written. +func TestBOMCommandLine(t *testing.T) { + const allDoc = `{"bomFormat":"CycloneDX","components":[{"name":"a"}]}` + var rec scanRecorder + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, rec.hook(testutil.MockAPIConfig{ + BOMContent: map[string]string{"bom_results": allDoc}, + }))) + t.Setenv("ARMIS_API_TOKEN", testToken) + t.Setenv("ARMIS_TENANT_ID", testTenantID) + t.Cleanup(func() { + resetBOMFlags(t) + rootCmd.SetArgs(nil) + }) + repoDir := createTestRepo(t) + dir := t.TempDir() + // A process starts with the flag's own default, nil; the command applies all. + resetBOMFlags(t) + + rootCmd.SetArgs([]string{"bom", "repo", repoDir, "--output", dir, "--no-progress", "--poll-interval", "10ms"}) + var err error + var stdout string + stderr := testutil.CaptureStderr(t, func() { stdout = captureStdout(t, func() { err = Execute() }) }) + if err != nil { + t.Fatalf("bom repo: %v\nstderr: %s", err, stderr) + } + got := rec.body(t) + if got["scan_type"] != "bom" { + t.Errorf("scan_type = %v, want bom", got["scan_type"]) + } + if types, _ := got["bom_types"].([]any); len(types) != 1 || types[0] != "all" { + t.Errorf("bom_types = %v, want [all] by default", got["bom_types"]) + } + if rec.called("/normalized-results") { + t.Error("a BOM-only scan fetched findings") + } + if stdout != "" { + t.Errorf("stdout = %q, want nothing outside --output -", stdout) + } + if _, err := os.Stat(filepath.Join(dir, filepath.Base(repoDir)+"-bom-all.json")); err != nil { + t.Errorf("expected the combined BOM file: %v", err) + } + if !strings.Contains(stderr, "Combined BOM saved to:") { + t.Errorf("stderr = %q, want the saved line", stderr) + } +} + +// TestBOMRepoRunE_RequestBody checks the /scan body of bom repo: scan_type +// bom, the types and the format as typed, nothing a security scan alone +// sends, and the git hints of a full upload of a checkout, as scan repo sends +// them. +func TestBOMRepoRunE_RequestBody(t *testing.T) { + rows := []struct { + name string + types []string + format string + files []string + gitRepo bool + wantTypes []any + wantFormat string + wantWarn string + wantHints bool + }{ + {name: "default", types: []string{"all"}, format: "cyclonedx-1.7", wantTypes: []any{"all"}, wantFormat: "cyclonedx-1.7"}, + {name: "two types, cyclonedx-1.6", types: []string{"aibom", "cbom"}, format: "cyclonedx-1.6", + wantTypes: []any{"aibom", "cbom"}, wantFormat: "cyclonedx-1.6"}, + {name: "the spdx alias as typed", types: []string{"sbom"}, format: "spdx", wantTypes: []any{"sbom"}, wantFormat: "spdx"}, + {name: "--include-files warns", types: []string{"all"}, format: "cyclonedx-1.7", files: []string{"main.go"}, + wantTypes: []any{"all"}, wantFormat: "cyclonedx-1.7", wantWarn: "BOMs cover only the uploaded files"}, + {name: "a git checkout sends its git hints", types: []string{"all"}, format: "cyclonedx-1.7", gitRepo: true, + wantTypes: []any{"all"}, wantFormat: "cyclonedx-1.7", wantHints: true}, + {name: "a git checkout with --include-files sends none", types: []string{"all"}, format: "cyclonedx-1.7", gitRepo: true, + files: []string{"main.go"}, wantTypes: []any{"all"}, wantFormat: "cyclonedx-1.7", wantWarn: "BOMs cover only the uploaded files"}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + var rec scanRecorder + doc := `{"bomFormat":"CycloneDX","components":[{"name":"a"}]}` + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, rec.hook(testutil.MockAPIConfig{ + BOMContent: map[string]string{"bom_results": doc, "aibom_cdx16_results": doc, "cbom_cdx16_results": doc, + "bom_sbom_spdx23_results": `{"spdxVersion":"SPDX-2.3","packages":[{"name":"p"}]}`}, + }))) + repoDir := createTestRepo(t) + if row.gitRepo { + initGitCheckout(t, repoDir) + } + bomOnlyTypes, bomOnlyFormat, bomOnlyOutput, includeFiles = row.types, row.format, t.TempDir(), row.files + _, stderr, err := runBOM(t, bomRepoCmd, repoDir) + if err != nil { + t.Fatalf("bom repo: %v", err) + } + got := rec.body(t) + if got["scan_type"] != "bom" { + t.Errorf("scan_type = %v, want bom", got["scan_type"]) + } + if !reflect.DeepEqual(got["bom_types"], row.wantTypes) { + t.Errorf("bom_types = %v, want %v", got["bom_types"], row.wantTypes) + } + if got["bom_format"] != row.wantFormat { + t.Errorf("bom_format = %v, want %s", got["bom_format"], row.wantFormat) + } + if got["sbom_generate"] != false || got["vex_generate"] != false { + t.Errorf("sbom_generate = %v, vex_generate = %v, want false", got["sbom_generate"], got["vex_generate"]) + } + for _, key := range []string{"custom_scans", "sbom_format", "image_ref"} { + if v, ok := got[key]; ok { + t.Errorf("%s = %v, want it omitted", key, v) + } + } + if row.wantHints { + hints := repo.DetectGitHints(repoDir) + if got["repo_name"] != "example/app" || got["git_sha"] != hints.GitSHA { + t.Errorf("repo_name = %v, git_sha = %v; want example/app and %s", got["repo_name"], got["git_sha"], hints.GitSHA) + } + } else { + for _, key := range []string{"repo_name", "git_sha", "origin_sha"} { + if v, ok := got[key]; ok { + t.Errorf("%s = %v, want it omitted", key, v) + } + } + } + if rec.called("/normalized-results") { + t.Error("a BOM-only scan fetched findings") + } + if row.wantWarn != "" && !strings.Contains(stderr, row.wantWarn) { + t.Errorf("stderr = %q, want %q", stderr, row.wantWarn) + } + if row.wantWarn == "" && strings.Contains(stderr, "BOMs cover only") { + t.Errorf("stderr = %q, want no partial-upload warning", stderr) + } + }) + } +} + +// initGitCheckout makes dir a clean git checkout with an origin remote, from +// which scan repo would send git hints. +func initGitCheckout(t *testing.T, dir string) { + t.Helper() + if _, err := exec.LookPath("git"); err != nil { + t.Skip("git not available") + } + for _, args := range [][]string{ + {"init", "-q"}, {"config", "user.email", "test@example.com"}, {"config", "user.name", "Test User"}, + {"remote", "add", "origin", "https://github.com/example/app.git"}, {"add", "."}, {"commit", "-q", "-m", "init"}, + } { + if err := runTestGitCmd(dir, args...); err != nil { + t.Fatalf("git %v: %v", args, err) + } + } + if hints := repo.DetectGitHints(dir); hints.RepoName == "" || hints.GitSHA == "" { + t.Fatalf("the checkout gives no git hints (%+v), so the test proves nothing", hints) + } +} + +// TestBOMImageRunE_RequestBody checks bom image --tarball: image_ref from the +// manifest tag, as scan image --bom sends it, and the file name. +func TestBOMImageRunE_RequestBody(t *testing.T) { + const cbomDoc = `{"bomFormat":"CycloneDX","components":[{"name":"AES"}]}` + rows := []struct { + name string + tags []string + wantRef any // nil: image_ref omitted + withImage bool + }{ + {name: "the manifest tag", tags: []string{"myorg/app:2.0"}, wantRef: "myorg/app:2.0"}, + {name: "no tag sends no image_ref"}, + {name: "--tarball wins over an image name", tags: []string{"myorg/app:2.0"}, wantRef: "myorg/app:2.0", withImage: true}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + var rec scanRecorder + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, rec.hook(testutil.MockAPIConfig{ + BOMContent: map[string]string{"cbom_results": cbomDoc}, + }))) + tarballPath = writeDockerSaveTar(t, "app.tar", row.tags...) + dir := t.TempDir() + bomOnlyTypes, bomOnlyOutput = []string{"cbom"}, dir + var args []string + if row.withImage { + args = []string{"other:1"} + } + _, stderr, err := runBOM(t, bomImageCmd, args...) + if err != nil { + t.Fatalf("bom image: %v", err) + } + got := rec.body(t) + if got["scan_type"] != "bom" { + t.Errorf("scan_type = %v, want bom", got["scan_type"]) + } + if got["image_ref"] != row.wantRef { + t.Errorf("image_ref = %v, want %v", got["image_ref"], row.wantRef) + } + if rec.called("/normalized-results") { + t.Error("a BOM-only scan fetched findings") + } + if _, err := os.Stat(filepath.Join(dir, "app-bom-cbom.json")); err != nil { + t.Errorf("expected app-bom-cbom.json: %v", err) + } + if row.withImage && !strings.Contains(stderr, "using tarball (image name ignored)") { + t.Errorf("stderr = %q, want the tarball warning", stderr) + } + }) + } +} + +// TestBOMRunE_ServerRefusals covers the /scan answers that end a bom command +// with exit 1: an old server's enum error, read as a plain message, and the +// new server's refusal codes, printed in the scan --bom form. +func TestBOMRunE_ServerRefusals(t *testing.T) { + refusal := func(code, msg string) string { + return `{"detail":{"code":"` + code + `","message":"` + msg + `"}}` + } + const oldPrefix = "this Armis server does not support BOM-only scans yet; run: " + rows := []struct { + name string + image bool + types []string + format string + output string + files []string + tests bool + body string + wantErr string // and stand for the target as typed + wantOld bool + }{ + {name: "old server, repo", body: oldServerBody, + wantErr: oldPrefix + "armis-cli scan repo --bom all", wantOld: true}, + {name: "old server, repo, types, format and output", types: []string{"aibom", "cbom"}, format: "cyclonedx-1.6", + output: "./my boms", body: oldServerBody, + wantErr: oldPrefix + "armis-cli scan repo --bom aibom,cbom --bom-format cyclonedx-1.6 --bom-output './my boms'", wantOld: true}, + {name: "old server, repo, upload flags", files: []string{"main.go"}, tests: true, body: oldServerBody, + wantErr: oldPrefix + "armis-cli scan repo --include-files main.go --include-tests --bom all", wantOld: true}, + {name: "old server, image tarball", image: true, types: []string{"sbom"}, format: "spdx", body: oldServerBody, + wantErr: oldPrefix + "armis-cli scan image --tarball --bom sbom --bom-format spdx", wantOld: true}, + {name: "a validation error on another field", body: `{"detail":[{"loc":["body","bom_format"],"msg":"bad"}]}`, + wantErr: "/scan returned 422 Unprocessable Entity"}, + {name: "bom_types_required", body: refusal("bom_types_required", "bom_types is required"), + wantErr: "the server refused the BOM request (--type all --format cyclonedx-1.7): bom_types is required (bom_types_required)"}, + {name: "custom_scans_not_allowed", body: refusal("custom_scans_not_allowed", "custom_scans is not allowed"), + wantErr: "the server refused the BOM request (--type all --format cyclonedx-1.7): custom_scans is not allowed (custom_scans_not_allowed)"}, + {name: "sbom_vex_not_allowed", body: refusal("sbom_vex_not_allowed", "SBOM and VEX are not built"), + wantErr: "the server refused the BOM request (--type all --format cyclonedx-1.7): SBOM and VEX are not built (sbom_vex_not_allowed)"}, + {name: "artifact_type_not_supported", image: true, body: refusal("artifact_type_not_supported", "not for this artifact"), + wantErr: "the server refused the BOM request (--type all --format cyclonedx-1.7): not for this artifact (artifact_type_not_supported)"}, + {name: "export_format_unavailable", types: []string{"sbom"}, format: "spdx-3.0.1", body: refusal("export_format_unavailable", "not offered"), + wantErr: "the server refused the BOM request (--type sbom --format spdx-3.0.1): not offered (export_format_unavailable)"}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + var rec scanRecorder + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, rec.hook(testutil.MockAPIConfig{ + ScanStatus: http.StatusUnprocessableEntity, ScanBody: row.body, + }))) + if row.types != nil { + bomOnlyTypes, bomOnlyFormat = row.types, row.format + } + bomOnlyOutput, includeFiles, includeTests = row.output, row.files, row.tests + var err error + want := row.wantErr + if row.image { + tarballPath = writeDockerSaveTar(t, "app.tar") + want = strings.ReplaceAll(want, "", shellArg(tarballPath, "")) + _, _, err = runBOM(t, bomImageCmd) + } else { + repoDir := createTestRepo(t) + want = strings.ReplaceAll(want, "", shellArg(repoDir, "")) + _, _, err = runBOM(t, bomRepoCmd, repoDir) + } + if err == nil || !strings.Contains(err.Error(), want) { + t.Fatalf("error = %v, want it to contain %q", err, want) + } + if row.wantOld && err.Error() != want { + t.Errorf("error = %q, want exactly %q", err, want) + } + if errors.Is(err, api.ErrBOMScanUnsupported) != row.wantOld { + t.Errorf("errors.Is(err, ErrBOMScanUnsupported) = %v, want %v", !row.wantOld, row.wantOld) + } + if code := mainExitCode(err); code != 1 { + t.Errorf("exit code = %d, want 1", code) + } + if rec.called("/status") || rec.called("/results") { + t.Error("polled or fetched results after /scan refused") + } + }) + } +} + +// TestBOMRepoRunE_Files covers the outputs: the default .armis, a typed +// directory, SPDX and CycloneDX 1.6 keys, stdout, types not offered (exit 2 +// when nothing is written) and an empty BOM. +func TestBOMRepoRunE_Files(t *testing.T) { + const allDoc = `{"bomFormat":"CycloneDX","specVersion":"1.7","components":[{"name":"a"}]}` + const aibomDoc = `{"bomFormat":"CycloneDX","components":[{"name":"m"}]}` + const cbomDoc = `{"bomFormat":"CycloneDX","components":[{"name":"AES"}]}` + const spdxDoc = `{"spdxVersion":"SPDX-2.3","packages":[{"name":"p"}]}` + const cdx16Doc = `{"bomFormat":"CycloneDX","specVersion":"1.6","components":[{"name":"m"}]}` + rows := []struct { + name string + docs map[string]string + types []string + format string + output string // "default" for .armis in the working directory + wantFiles map[string]string + wantOut string + wantErr []string // stderr lines + wantNoErr []string + wantCode int + }{ + {name: "the default .armis", docs: map[string]string{"bom_results": allDoc}, types: []string{"all"}, output: "default", + wantFiles: map[string]string{"-bom-all.json": allDoc}, wantErr: []string{"Combined BOM saved to:", ".armis"}}, + {name: "two types into a directory", docs: map[string]string{"aibom_results": aibomDoc, "cbom_results": cbomDoc}, + types: []string{"aibom", "cbom"}, wantFiles: map[string]string{"-bom-aibom.json": aibomDoc, "-bom-cbom.json": cbomDoc}, + wantErr: []string{"AI-BOM saved to:", "CBOM saved to:"}}, + {name: "spdx gives the SPDX 2.3 SBOM", docs: map[string]string{"bom_sbom_spdx23_results": spdxDoc}, types: []string{"sbom"}, + format: "spdx", wantFiles: map[string]string{"-bom-sbom.spdx.json": spdxDoc}}, + {name: "cyclonedx-1.6 reads the _cdx16_ key", docs: map[string]string{"aibom_results": aibomDoc, "aibom_cdx16_results": cdx16Doc}, + types: []string{"aibom"}, format: "cyclonedx-1.6", wantFiles: map[string]string{"-bom-aibom.json": cdx16Doc}}, + {name: "stdout gets only the document", docs: map[string]string{"cbom_results": cbomDoc}, types: []string{"cbom"}, output: "-", + wantOut: cbomDoc, wantErr: []string{"CBOM written to stdout"}, wantNoErr: []string{"saved to:"}}, + {name: "a tenant without BOMs: every type warns and exit 2", types: []string{"aibom", "cbom"}, + wantErr: []string{"AI-BOM was requested but not available in results", "CBOM was requested but not available in results"}, + wantNoErr: []string{"saved to:"}, wantCode: 2}, + {name: "one type written, one not offered: exit 0", docs: map[string]string{"cbom_results": cbomDoc}, + types: []string{"aibom", "cbom"}, wantFiles: map[string]string{"-bom-cbom.json": cbomDoc}, + wantErr: []string{"AI-BOM was requested but not available in results", "CBOM saved to:"}}, + {name: "stdout with nothing to write: exit 2 and no output", types: []string{"cbom"}, output: "-", + wantErr: []string{"CBOM was requested but not available in results"}, wantNoErr: []string{"written to stdout"}, wantCode: 2}, + {name: "an empty BOM is written and named", docs: map[string]string{"cbom_results": `{"bomFormat":"CycloneDX","components":[]}`}, + types: []string{"cbom"}, wantFiles: map[string]string{"-bom-cbom.json": `{"bomFormat":"CycloneDX","components":[]}`}, + wantErr: []string{"No crypto components found in "}}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, testutil.MockAPIConfig{BOMContent: row.docs})) + t.Chdir(t.TempDir()) + repoDir := createTestRepo(t) + dir := t.TempDir() + switch row.output { + case "default": + dir = scan.DefaultBOMDir + bomOnlyOutput = "" + case "-": + bomOnlyOutput = scan.BOMOutputStdout + default: + bomOnlyOutput = dir + } + bomOnlyTypes = row.types + if row.format != "" { + bomOnlyFormat = row.format + } + stdout, stderr, err := runBOM(t, bomRepoCmd, repoDir) + if code := mainExitCode(err); code != row.wantCode { + t.Fatalf("exit code = %d (%v), want %d", code, err, row.wantCode) + } + if stdout != row.wantOut { + t.Errorf("stdout = %q, want %q", stdout, row.wantOut) + } + for suffix, doc := range row.wantFiles { + path := filepath.Join(dir, filepath.Base(repoDir)+suffix) + data, err := os.ReadFile(path) //nolint:gosec // test path + if err != nil { + t.Fatalf("expected %s: %v", path, err) + } + if !bytes.Equal(data, scan.IndentJSON([]byte(doc))) { + t.Errorf("%s = %s, want the stored document pretty-printed", path, data) + } + if info, err := os.Stat(path); err == nil && runtime.GOOS != "windows" && info.Mode().Perm() != 0600 { + t.Errorf("%s mode = %v, want 0600", path, info.Mode().Perm()) + } + } + if len(row.wantFiles) == 0 && row.output != "-" { + if entries, _ := os.ReadDir(dir); len(entries) != 0 { + t.Errorf("wrote %v, want no files", entries) + } + } + if row.output == "-" { + if _, err := os.Stat(scan.DefaultBOMDir); err == nil { + t.Error("stdout mode created .armis") + } + } + for _, w := range row.wantErr { + w = strings.ReplaceAll(w, "", repoDir) + if !strings.Contains(stderr, w) { + t.Errorf("stderr = %q, want %q", stderr, w) + } + } + for _, w := range row.wantNoErr { + if strings.Contains(stderr, w) { + t.Errorf("stderr = %q, want no %q", stderr, w) + } + } + if strings.Contains(stderr, "Retrieving results") || strings.Contains(stderr, "SCAN SUMMARY") { + t.Errorf("stderr = %q, want no findings report", stderr) + } + }) + } +} + +// TestBOMRepoRunE_ExitCodes: 0 when at least one BOM is written, 2 when none +// is or a built BOM cannot be downloaded, findings or not. +func TestBOMRepoRunE_ExitCodes(t *testing.T) { + critical := []model.NormalizedFinding{ + testhelpers.CreateNormalizedFinding("f-1", "CRITICAL", "sql_injection", nil, []string{"CWE-89"}), + } + const doc = `{"bomFormat":"CycloneDX","components":[{"name":"a"}]}` + rows := []struct { + name string + config testutil.MockAPIConfig + types []string + wantCode int + wantLabels []string + wantMsg string + }{ + {name: "written", config: testutil.MockAPIConfig{BOMContent: map[string]string{"bom_results": doc}}, types: []string{"all"}, wantCode: 0}, + {name: "one of two written", config: testutil.MockAPIConfig{BOMContent: map[string]string{"cbom_results": doc}}, + types: []string{"sbom", "cbom"}, wantCode: 0}, + {name: "none offered", config: testutil.MockAPIConfig{}, types: []string{"sbom", "cbom"}, wantCode: 2, wantLabels: []string{"SBOM", "CBOM"}, + wantMsg: "scan completed but no BOM was written: SBOM, CBOM not available (scan ID: test-scan-001)"}, + {name: "not supported in the summary", config: testutil.MockAPIConfig{BOMSummary: map[string]interface{}{ + "types": map[string]interface{}{"aibom": map[string]interface{}{"status": "not_supported"}}}}, + types: []string{"aibom"}, wantCode: 2, wantLabels: []string{"AI-BOM"}}, + {name: "findings on the server do not count", config: testutil.MockAPIConfig{Findings: critical, + BOMContent: map[string]string{"bom_results": doc}}, types: []string{"all"}, wantCode: 0}, + {name: "a download fails", config: testutil.MockAPIConfig{BOMContent: map[string]string{"aibom_results": doc, "cbom_results": doc}, + BOMDownloadStatus: http.StatusNotFound}, types: []string{"aibom", "cbom"}, wantCode: 2, wantLabels: []string{"AI-BOM", "CBOM"}}, + {name: "not valid JSON", config: testutil.MockAPIConfig{BOMContent: map[string]string{"cbom_results": "{not json"}}, + types: []string{"cbom"}, wantCode: 2, wantLabels: []string{"CBOM"}}, + {name: "the scan fails on the server", config: testutil.MockAPIConfig{FinalStatus: "FAILED", LastError: "boom"}, + types: []string{"all"}, wantCode: 1}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, row.config)) + bomOnlyTypes, bomOnlyOutput = row.types, t.TempDir() + _, _, err := runBOM(t, bomRepoCmd, createTestRepo(t)) + if code := mainExitCode(err); code != row.wantCode { + t.Fatalf("exit code = %d (%v), want %d", code, err, row.wantCode) + } + if row.wantLabels != nil { + var bomErr *output.ErrBOMIncomplete + if !errors.As(err, &bomErr) || !reflect.DeepEqual(bomErr.Labels, row.wantLabels) { + t.Errorf("error = %v, want ErrBOMIncomplete for %v", err, row.wantLabels) + } + } + if row.wantMsg != "" && (err == nil || err.Error() != row.wantMsg) { + t.Errorf("error = %v, want %q", err, row.wantMsg) + } + }) + } +} + +// TestBOMRepoScan_CancelDuringDownload: Ctrl+C during a BOM download of a +// BOM-only scan exits 130, not 2. +func TestBOMRepoScan_CancelDuringDownload(t *testing.T) { + t.Setenv("ARMIS_HISTORY_DIR", t.TempDir()) + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + serverURL := testutil.GetMockServerURLWithConfig(t, testutil.MockAPIConfig{ + BOMContent: map[string]string{"bom_results": `{"components":[]}`}, + OnBOMDownload: func(r *http.Request) { + cancel() + <-r.Context().Done() // hold the answer until the client gives up + }, + }) + client, err := api.NewClient(serverURL, testutil.NewTestAuthProvider("test-token"), false, 0, api.WithAllowLocalURLs(true)) + if err != nil { + t.Fatalf("NewClient: %v", err) + } + scanner := repo.NewScanner(client, true, testTenantID, 0, false, time.Minute, false). + WithPollInterval(10 * time.Millisecond). + WithSBOMVEXOptions(&scan.SBOMVEXOptions{BOM: &scan.BOMOptions{ + Types: []string{scan.BOMTypeAll}, Format: scan.BOMFormatCycloneDX17, Output: t.TempDir(), Only: true, + }}) + + var result *model.ScanResult + _ = testutil.CaptureStderr(t, func() { result, err = scanner.Scan(ctx, createTestRepo(t)) }) + if result != nil || !errors.Is(err, context.Canceled) { + t.Fatalf("Scan = %v, %v; want a cancelled scan", result, err) + } + _ = testutil.CaptureStderr(t, func() { err = bomScanError("repo", ".", nil)(ctx, err) }) + if code := mainExitCode(err); code != ExitCodeCancelled { + t.Errorf("exit code = %d (%v), want %d", code, err, ExitCodeCancelled) + } +} + +// TestBOMHelp renders the help of bom, bom repo and bom image: the tenant +// requirement, the default type, the flags with their defaults, examples in +// the $ armis-cli style, and none of the findings flags of scan. +func TestBOMHelp(t *testing.T) { + cli.InitColors(cli.ColorModeNever) + output.SyncColors() + for _, c := range []*cobra.Command{bomCmd, bomRepoCmd, bomImageCmd} { + t.Run(c.Name(), func(t *testing.T) { + var buf bytes.Buffer + c.SetOut(&buf) + t.Cleanup(func() { c.SetOut(nil) }) + c.HelpFunc()(c, nil) + help := buf.String() + for _, want := range []string{ + "BOM generation must be enabled for your tenant", + "Exit codes: 0 when at least one BOM was written and none failed to download;", + "2 when no BOM was written or a built BOM could not be downloaded; 1 on errors;", + "Without --type, the combined BOM is built: one file with every type.", + "--type strings", "(default: all)", "sbom, aibom, cbom, all", + "--format string", `(default "cyclonedx-1.7")`, + "--output string", "or - to write one BOM to stdout (default: .armis)", + "--scan-timeout int", "--upload-timeout int", "--no-progress", + " $ armis-cli bom ", + } { + if !strings.Contains(help, want) { + t.Errorf("help is missing %q:\n%s", want, help) + } + } + for _, unwanted := range []string{"--fail-on", "--min-severity", "--group-by", "--sbom", "--bom-format", "--page-limit", "--poll-interval"} { + if strings.Contains(help, unwanted) { + t.Errorf("help shows %s:\n%s", unwanted, help) + } + } + for _, line := range strings.Split(c.Example, "\n") { + if !strings.HasPrefix(line, " $ armis-cli bom ") { + t.Errorf("example %q is not in the $ armis-cli style", line) + } + } + }) + } + if f := bomRepoCmd.Flags().Lookup("include-files"); f == nil { + t.Error("bom repo has no --include-files") + } + if f := bomRepoCmd.Flags().Lookup("include-tests"); f == nil { + t.Error("bom repo has no --include-tests") + } + for _, name := range []string{"tarball", "pull"} { + if f := bomImageCmd.Flags().Lookup(name); f == nil { + t.Errorf("bom image has no --%s", name) + } + } +} + +// TestTypedBOMDirRefusesLinkedFile: in a directory from --bom-output or +// bom --output, a link committed at a BOM's file name is refused, its target +// is left alone, and the command exits 2. +func TestTypedBOMDirRefusesLinkedFile(t *testing.T) { + const doc = `{"bomFormat":"CycloneDX","components":[{"name":"a"}]}` + rows := []struct { + name string + run func(t *testing.T, repoDir, dir string) error + }{ + {"scan repo --bom-output", func(t *testing.T, repoDir, dir string) error { + bomTypes, bomOutput = []string{scan.BOMTypeSBOM}, dir + _, _, err := runRepoScanIn(t, repoDir) + return err + }}, + {"bom repo --output", func(t *testing.T, repoDir, dir string) error { + bomOnlyTypes, bomOnlyOutput = []string{scan.BOMTypeSBOM}, dir + _, _, err := runBOM(t, bomRepoCmd, repoDir) + return err + }}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, testutil.MockAPIConfig{ + BOMContent: map[string]string{"bom_sbom_results": doc}, + })) + repoDir := createTestRepo(t) + dir := t.TempDir() + victim := filepath.Join(t.TempDir(), "victim") + if err := os.WriteFile(victim, []byte("keep"), 0600); err != nil { + t.Fatalf("write victim: %v", err) + } + if err := os.Symlink(victim, filepath.Join(dir, filepath.Base(repoDir)+"-bom-sbom.json")); err != nil { + t.Skipf("cannot create symlink: %v", err) + } + err := row.run(t, repoDir, dir) + if code := mainExitCode(err); code != 2 { + t.Errorf("exit code = %d (%v), want 2", code, err) + } + if got, _ := os.ReadFile(victim); string(got) != "keep" { //nolint:gosec // test path + t.Errorf("link target = %q, want it untouched", got) + } + }) + } +} + +// TestFailedToolsWarning: scan repo --bom and bom repo share the warning for +// a BOM written while a BOM tool failed, and both still exit 0. +func TestFailedToolsWarning(t *testing.T) { + const doc = `{"bomFormat":"CycloneDX","components":[{"name":"AES"}]}` + const want = "Warning: BOM tools failed on the server: opengrep_bom; CBOM may be incomplete" + rows := []struct { + name string + run func(t *testing.T, repoDir, dir string) (string, error) + }{ + {"scan repo --bom", func(t *testing.T, repoDir, dir string) (string, error) { + bomTypes, bomOutput = []string{scan.BOMTypeCBOM}, dir + _, stderr, err := runRepoScanIn(t, repoDir) + return stderr, err + }}, + {"bom repo", func(t *testing.T, repoDir, dir string) (string, error) { + bomOnlyTypes, bomOnlyOutput = []string{scan.BOMTypeCBOM}, dir + _, stderr, err := runBOM(t, bomRepoCmd, repoDir) + return stderr, err + }}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + setupBOMRunEnv(t, testutil.GetMockServerURLWithConfig(t, testutil.MockAPIConfig{ + BOMContent: map[string]string{"cbom_results": doc}, + BOMSummary: map[string]interface{}{ + "types": map[string]interface{}{"cbom": map[string]interface{}{"status": "generated"}}, + "failed_tools": []string{"opengrep_bom"}, + }, + })) + stderr, err := row.run(t, createTestRepo(t), t.TempDir()) + if code := mainExitCode(err); code != 0 { + t.Errorf("exit code = %d (%v), want 0", code, err) + } + if strings.Count(stderr, want) != 1 { + t.Errorf("stderr = %q, want %q once", stderr, want) + } + }) + } +} diff --git a/internal/cmd/cmdutil/bom.go b/internal/cmd/cmdutil/bom.go index e44b387..ffe3850 100644 --- a/internal/cmd/cmdutil/bom.go +++ b/internal/cmd/cmdutil/bom.go @@ -4,6 +4,7 @@ import ( "errors" "fmt" "os" + "path/filepath" "slices" "strings" @@ -11,19 +12,35 @@ import ( "github.com/ArmisSecurity/armis-cli/internal/util" ) -// NormalizeBOMFlags checks the --bom and --bom-format values before any +// BOMFlagNames names the flags that carry the BOM types, format and output, +// for the messages of NormalizeBOMFlags and ValidateBOMFlags. DefaultTypes +// marks types the user did not give, so a refused pair says they are the +// default. +type BOMFlagNames struct { + Types, Format, Output string + DefaultTypes bool +} + +// ScanBOMFlags are the BOM flags of the scan commands. +var ScanBOMFlags = BOMFlagNames{Types: "--bom", Format: "--bom-format", Output: "--bom-output"} + +// BOMCommandFlags are the flags of bom repo and bom image. +var BOMCommandFlags = BOMFlagNames{Types: "--type", Format: "--format", Output: "--output"} + +// NormalizeBOMFlags checks the BOM type and format values before any // network call. Every scan subcommand runs it, as it does the --sbom-format -// check. bomSet reports whether --bom was given at all, so that "--bom=" is -// told apart from no --bom. It returns the BOM types lower-cased, deduplicated -// and in scan.BOMTypeOrder (nil without --bom), and the lower-cased format. -// --bom-format and --bom-output without --bom are not errors; the caller warns -// about them. -func NormalizeBOMFlags(types []string, bomSet bool, format string) ([]string, string, error) { +// check, and so do the bom subcommands. bomSet reports whether the types flag +// was given at all, so that "--bom=" is told apart from no --bom. It returns +// the BOM types lower-cased, deduplicated and in scan.BOMTypeOrder (nil +// without types), and the lower-cased format. --bom-format and --bom-output +// without --bom are not errors; the caller warns about them. names gives the +// flag names for the messages. +func NormalizeBOMFlags(names BOMFlagNames, types []string, bomSet bool, format string) ([]string, string, error) { // The server's format values are case-sensitive, so normalize first, as // --sbom-format is. format = strings.ToLower(format) if !slices.Contains(scan.BOMFormats, format) { - return nil, format, fmt.Errorf("invalid --bom-format value %q: must be one of %v", format, scan.BOMFormats) + return nil, format, fmt.Errorf("invalid %s value %q: must be one of %v", names.Format, format, scan.BOMFormats) } if !bomSet { return nil, format, nil @@ -36,12 +53,12 @@ func NormalizeBOMFlags(types []string, bomSet bool, format string) ([]string, st continue } if !slices.Contains(scan.BOMTypeOrder, t) { - return nil, format, fmt.Errorf("invalid --bom value %q: must be one of %v", raw, scan.BOMTypeOrder) + return nil, format, fmt.Errorf("invalid %s value %q: must be one of %v", names.Types, raw, scan.BOMTypeOrder) } seen[t] = true } if len(seen) == 0 { - return nil, format, fmt.Errorf("--bom requires a value: one of %v", scan.BOMTypeOrder) + return nil, format, fmt.Errorf("%s requires a value: one of %v", names.Types, scan.BOMTypeOrder) } normalized := make([]string, 0, len(seen)) for _, t := range scan.BOMTypeOrder { @@ -53,61 +70,87 @@ func NormalizeBOMFlags(types []string, bomSet bool, format string) ([]string, st } // ValidateBOMFlags checks what a BOM download needs, before any network call: -// each type and format pair, and --bom-output. types and format come from -// NormalizeBOMFlags; without types there is nothing to check. Only scan repo -// and scan image run it, as the other scan subcommands ignore the BOM flags. -func ValidateBOMFlags(types []string, format, output string) error { +// each type and format pair, and the output. types and format come from +// NormalizeBOMFlags; without types there is nothing to check. scan repo, scan +// image and the bom subcommands run it; the other scan subcommands ignore the +// BOM flags. names gives the flag names for the messages. +func ValidateBOMFlags(names BOMFlagNames, types []string, format, output string) error { if len(types) == 0 { return nil } for _, t := range types { - if err := checkBOMPair(t, format); err != nil { + if err := checkBOMPair(names, t, format); err != nil { return err } } - return checkBOMOutput(output, types) + return checkBOMOutput(names, output, types) } // checkBOMPair rejects the type and format pairs the server answers with 422 // export_format_unavailable. spdx-3.0.1, and spdx for aibom, pass here: the // server rejects them until it offers SPDX 3.0.1. -func checkBOMPair(bomType, format string) error { +func checkBOMPair(names BOMFlagNames, bomType, format string) error { + typeArg := names.Types + " " + bomType + if names.DefaultTypes { + typeArg += " (the default)" + } switch { case bomType == scan.BOMTypeAIBOM && format == scan.BOMFormatSPDX23: - return fmt.Errorf("--bom-format %s is not available for --bom %s: the %s's SPDX form is %s", - format, bomType, scan.BOMLabel(bomType), scan.BOMFormatSPDX301) + return fmt.Errorf("%s %s is not available for %s: the %s's SPDX form is %s", + names.Format, format, typeArg, scan.BOMLabel(bomType), scan.BOMFormatSPDX301) case (bomType == scan.BOMTypeCBOM || bomType == scan.BOMTypeAll) && scan.IsSPDXFormat(format): - return fmt.Errorf("--bom-format %s is not available for --bom %s: the %s has no SPDX form", - format, bomType, scan.BOMLabel(bomType)) + return fmt.Errorf("%s %s is not available for %s: the %s has no SPDX form", + names.Format, format, typeArg, scan.BOMLabel(bomType)) } return nil } -// checkBOMOutput checks --bom-output: "-" takes one type, and a path must not +// checkBOMOutput checks the output: "-" takes one type, and a path must not // traverse upward or name an existing file. A missing directory is created at // download time. -func checkBOMOutput(output string, types []string) error { +func checkBOMOutput(names BOMFlagNames, output string, types []string) error { if output == "" { return nil } if output == scan.BOMOutputStdout { if len(types) > 1 { - return fmt.Errorf("--bom-output - takes one BOM type, got %d: %s", len(types), strings.Join(types, ",")) + return fmt.Errorf("%s - takes one BOM type, got %d: %s", names.Output, len(types), strings.Join(types, ",")) } return nil } - // armis:ignore cwe:22 reason:SanitizePath IS the path traversal prevention; output is the user's own --bom-output flag + // armis:ignore cwe:22 reason:SanitizePath IS the path traversal prevention; output is the user's own output flag cleaned, err := util.SanitizePath(output) if err != nil { - return fmt.Errorf("invalid --bom-output value %q: %w", output, err) + return fmt.Errorf("invalid %s value %q: %w", names.Output, output, err) } // armis:ignore cwe:22 reason:read-only existence check on a sanitized path from the user's own flag info, err := os.Stat(cleaned) if err == nil && !info.IsDir() { - return fmt.Errorf("invalid --bom-output value %q: not a directory", output) + return fmt.Errorf("invalid %s value %q: not a directory", names.Output, output) } if err != nil && !errors.Is(err, os.ErrNotExist) { - return fmt.Errorf("invalid --bom-output value %q: %w", output, err) + return fmt.Errorf("invalid %s value %q: %w", names.Output, output, err) } return nil } + +// RefuseFileNameOutput refuses an output directory that does not exist and +// ends in .json: it is most likely meant as a file name, and would be created +// as a directory holding the BOM file. An existing directory passes, as do +// "" and "-". The hint offers stdout only for one type, the only case it +// takes. bom repo and bom image run it after ValidateBOMFlags. +func RefuseFileNameOutput(names BOMFlagNames, output string, types []string) error { + if output == "" || output == scan.BOMOutputStdout || !strings.EqualFold(filepath.Ext(output), ".json") { + return nil + } + // armis:ignore cwe:22 reason:read-only existence check; ValidateBOMFlags has sanitized the user's own flag + if _, err := os.Stat(output); !errors.Is(err, os.ErrNotExist) { + return nil + } + if len(types) == 1 { + return fmt.Errorf("invalid %s value %q: %s takes a directory, not a file name; use %s - to write the BOM to stdout, or name a directory", + names.Output, output, names.Output, names.Output) + } + return fmt.Errorf("invalid %s value %q: %s takes a directory, not a file name; name a directory for the %d BOM files", + names.Output, output, names.Output, len(types)) +} diff --git a/internal/cmd/cmdutil/bom_test.go b/internal/cmd/cmdutil/bom_test.go index 8ada623..64ced4c 100644 --- a/internal/cmd/cmdutil/bom_test.go +++ b/internal/cmd/cmdutil/bom_test.go @@ -12,11 +12,11 @@ import ( // checkBOMFlags runs the checks of scan repo and scan image: NormalizeBOMFlags // in PersistentPreRunE, then ValidateBOMFlags. func checkBOMFlags(types []string, bomSet bool, format, output string) ([]string, string, error) { - types, format, err := NormalizeBOMFlags(types, bomSet, format) + types, format, err := NormalizeBOMFlags(ScanBOMFlags, types, bomSet, format) if err != nil { return nil, format, err } - return types, format, ValidateBOMFlags(types, format, output) + return types, format, ValidateBOMFlags(ScanBOMFlags, types, format, output) } func TestValidateBOMFlags(t *testing.T) { @@ -165,19 +165,111 @@ func TestNormalizeBOMFlagsLeavesPairsAndOutput(t *testing.T) { } for _, row := range rows { t.Run(row.name, func(t *testing.T) { - types, format, err := NormalizeBOMFlags(row.types, true, row.format) + types, format, err := NormalizeBOMFlags(ScanBOMFlags, row.types, true, row.format) if err != nil { t.Fatalf("NormalizeBOMFlags: %v, want no error", err) } - if err := ValidateBOMFlags(types, format, row.output); err == nil { + if err := ValidateBOMFlags(ScanBOMFlags, types, format, row.output); err == nil { t.Fatalf("ValidateBOMFlags passed %s, want an error", row.name) } }) } t.Run("ValidateBOMFlags without types checks nothing", func(t *testing.T) { - if err := ValidateBOMFlags(nil, "spdx", file); err != nil { + if err := ValidateBOMFlags(ScanBOMFlags, nil, "spdx", file); err != nil { t.Fatalf("ValidateBOMFlags without types: %v, want nil", err) } }) } + +// TestBOMCommandFlagMessages runs the same checks with the flag names of the +// bom subcommands: every message names --type, --format and --output, never +// the scan flags. +func TestBOMCommandFlagMessages(t *testing.T) { + file := filepath.Join(t.TempDir(), "boms.json") + if err := os.WriteFile(file, []byte("{}"), 0600); err != nil { + t.Fatalf("write file: %v", err) + } + rows := []struct { + name string + types []string + format string + output string + wantErr string + }{ + {"no value", []string{""}, "cyclonedx-1.7", "", "--type requires a value: one of [sbom aibom cbom all]"}, + {"unknown type", []string{"xbom"}, "cyclonedx-1.7", "", `invalid --type value "xbom": must be one of [sbom aibom cbom all]`}, + {"unknown format", []string{"all"}, "xml", "", `invalid --format value "xml": must be one of [cyclonedx-1.7 cyclonedx-1.6 spdx-2.3 spdx-3.0.1 cyclonedx spdx]`}, + {"aibom with spdx-2.3", []string{"aibom"}, "spdx-2.3", "", "--format spdx-2.3 is not available for --type aibom: the AI-BOM's SPDX form is spdx-3.0.1"}, + {"all with spdx", []string{"all"}, "spdx", "", "--format spdx is not available for --type all: the Combined BOM has no SPDX form"}, + {"stdout with two types", []string{"cbom", "sbom"}, "cyclonedx-1.7", "-", "--output - takes one BOM type, got 2: sbom,cbom"}, + {"output is a file", []string{"all"}, "cyclonedx-1.7", file, fmt.Sprintf("invalid --output value %q: not a directory", file)}, + {"output with ..", []string{"all"}, "cyclonedx-1.7", "../boms", `invalid --output value "../boms": path traversal detected`}, + {"accepted", []string{"sbom", "aibom"}, "spdx", "", ""}, + } + t.Run("the default type says so", func(t *testing.T) { + names := BOMCommandFlags + names.DefaultTypes = true + err := ValidateBOMFlags(names, []string{"all"}, "spdx", "") + want := "--format spdx is not available for --type all (the default): the Combined BOM has no SPDX form" + if err == nil || err.Error() != want { + t.Fatalf("error = %v, want %q", err, want) + } + }) + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + types, format, err := NormalizeBOMFlags(BOMCommandFlags, row.types, true, row.format) + if err == nil { + err = ValidateBOMFlags(BOMCommandFlags, types, format, row.output) + } + if row.wantErr == "" { + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + return + } + if err == nil || err.Error() != row.wantErr { + t.Fatalf("error = %v, want %q", err, row.wantErr) + } + if strings.Contains(err.Error(), "--bom") { + t.Errorf("error %q names a scan flag", err) + } + }) + } +} + +func TestRefuseFileNameOutput(t *testing.T) { + dir := t.TempDir() + jsonDir := filepath.Join(dir, "boms.json") + if err := os.Mkdir(jsonDir, 0750); err != nil { + t.Fatalf("mkdir: %v", err) + } + const oneTypeHint = "--output takes a directory, not a file name; use --output - to write the BOM to stdout, or name a directory" + rows := []struct { + name string + output string + types []string + wantHint string // "" for no error + }{ + {"unset", "", []string{"all"}, ""}, + {"stdout", "-", []string{"all"}, ""}, + {"a new directory", filepath.Join(dir, "boms"), []string{"all"}, ""}, + {"a new .json path", filepath.Join(dir, "sbom.json"), []string{"sbom"}, oneTypeHint}, + {"a new .JSON path", filepath.Join(dir, "sbom.JSON"), []string{"all"}, oneTypeHint}, + {"an existing directory ending in .json", jsonDir, []string{"all"}, ""}, + {"a new .spdx.json path", filepath.Join(dir, "sbom.spdx.json"), []string{"sbom"}, oneTypeHint}, + {"two types get no stdout hint", filepath.Join(dir, "out.json"), []string{"sbom", "cbom"}, + "--output takes a directory, not a file name; name a directory for the 2 BOM files"}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + err := RefuseFileNameOutput(BOMCommandFlags, row.output, row.types) + if (err != nil) != (row.wantHint != "") { + t.Fatalf("RefuseFileNameOutput(%q) = %v, want error %v", row.output, err, row.wantHint != "") + } + if err != nil && !strings.HasSuffix(err.Error(), row.wantHint) { + t.Errorf("error = %q, want it to end with %q", err, row.wantHint) + } + }) + } +} diff --git a/internal/cmd/completion_test.go b/internal/cmd/completion_test.go index fd125bf..5177b8d 100644 --- a/internal/cmd/completion_test.go +++ b/internal/cmd/completion_test.go @@ -71,6 +71,8 @@ func TestFlagCompletionsMatchValidators(t *testing.T) { {"group-by", scanCmd, "group-by", validGroupBy}, {"bom", scanCmd, "bom", scan.BOMTypeOrder}, {"bom-format", scanCmd, "bom-format", scan.BOMFormats}, + {"bom command type", bomCmd, "type", scan.BOMTypeOrder}, + {"bom command format", bomCmd, "format", scan.BOMFormats}, } for _, tt := range tests { @@ -104,6 +106,8 @@ func TestFlagCompletionsHaveDescriptions(t *testing.T) { {"group-by", scanCmd, "group-by"}, {"bom", scanCmd, "bom"}, {"bom-format", scanCmd, "bom-format"}, + {"bom command type", bomCmd, "type"}, + {"bom command format", bomCmd, "format"}, } for _, tt := range tests { diff --git a/internal/cmd/scan.go b/internal/cmd/scan.go index 50549b5..3d5f814 100644 --- a/internal/cmd/scan.go +++ b/internal/cmd/scan.go @@ -117,7 +117,7 @@ var scanCmd = &cobra.Command{ // format pairs and --bom-output are checked by scan repo and scan // image only: scan status and scan sbom ignore the BOM flags. bomFlag := cmd.Flag("bom") - normalizedBOMTypes, normalizedBOMFormat, err := cmdutil.NormalizeBOMFlags(bomTypes, bomFlag != nil && bomFlag.Changed, bomFormat) + normalizedBOMTypes, normalizedBOMFormat, err := cmdutil.NormalizeBOMFlags(cmdutil.ScanBOMFlags, bomTypes, bomFlag != nil && bomFlag.Changed, bomFormat) if err != nil { return err } @@ -128,20 +128,8 @@ var scanCmd = &cobra.Command{ return fmt.Errorf("invalid --exit-code value %d: must be between 1 and 255", exitCode) } - // Validate timeout values: must be positive and bounded - if scanTimeout < 1 { - return fmt.Errorf("invalid --scan-timeout value %d: must be at least 1 minute", scanTimeout) - } - const maxScanTimeout = 1440 // 24 hours - if scanTimeout > maxScanTimeout { - return fmt.Errorf("invalid --scan-timeout value %d: must not exceed %d minutes (24 hours)", scanTimeout, maxScanTimeout) - } - if uploadTimeout < 1 { - return fmt.Errorf("invalid --upload-timeout value %d: must be at least 1 minute", uploadTimeout) - } - const maxUploadTimeout = 120 // 2 hours - if uploadTimeout > maxUploadTimeout { - return fmt.Errorf("invalid --upload-timeout value %d: must not exceed %d minutes", uploadTimeout, maxUploadTimeout) + if err := validateTimeouts(); err != nil { + return err } // Validate --fail-on early so a typo (e.g. HIGHT) surfaces as a flag error @@ -164,6 +152,80 @@ var scanCmd = &cobra.Command{ }, } +// Defaults of --scan-timeout and --upload-timeout, in minutes. +const ( + defaultScanTimeout = 60 + defaultUploadTimeout = 10 +) + +// Usage of --include-tests and --include-files, which scan and bom share. +const ( + includeTestsUsage = "Include test files in the scan (test files are excluded by default)" + includeFilesUsage = "Comma-separated list of file paths to include in scan (relative to repository root)" +) + +// validateTimeouts checks --scan-timeout and --upload-timeout: they must be +// positive and bounded. +func validateTimeouts() error { + if scanTimeout < 1 { + return fmt.Errorf("invalid --scan-timeout value %d: must be at least 1 minute", scanTimeout) + } + const maxScanTimeout = 1440 // 24 hours + if scanTimeout > maxScanTimeout { + return fmt.Errorf("invalid --scan-timeout value %d: must not exceed %d minutes (24 hours)", scanTimeout, maxScanTimeout) + } + if uploadTimeout < 1 { + return fmt.Errorf("invalid --upload-timeout value %d: must be at least 1 minute", uploadTimeout) + } + const maxUploadTimeout = 120 // 2 hours + if uploadTimeout > maxUploadTimeout { + return fmt.Errorf("invalid --upload-timeout value %d: must not exceed %d minutes", uploadTimeout, maxUploadTimeout) + } + return nil +} + +// addUploadFlags registers the persistent flags of a command whose +// subcommands upload an artifact and wait for the server: --no-progress, +// --scan-timeout, --upload-timeout and the hidden --poll-interval. scan and +// bom both call it, binding the same variables with the same defaults, so the +// order of their init functions does not matter. +func addUploadFlags(cmd *cobra.Command) { + fs := cmd.PersistentFlags() + fs.BoolVar(&noProgress, "no-progress", false, "Suppress progress output (for CI/scripts)") + fs.IntVar(&scanTimeout, "scan-timeout", defaultScanTimeout, "Maximum time in minutes to wait for scan analysis to complete") + fs.IntVar(&uploadTimeout, "upload-timeout", defaultUploadTimeout, "Maximum time in minutes to wait for artifact upload to complete") + // poll-interval overrides the Scanner's default status-poll interval (5s in + // repo/image/sbom Scanners). Hidden: it exists solely so RunE-level tests can + // avoid burning a real poll tick, the same way package-level tests already do + // via each Scanner's WithPollInterval builder, without going through cobra + // flag parsing (RunE tests call scanXCmd.RunE directly, not cmd.Execute()). + fs.DurationVar(&pollInterval, "poll-interval", 0, "Override the scan status poll interval (0 = use default)") + _ = fs.MarkHidden("poll-interval") +} + +// bomTypeCompletions and bomFormatCompletions return the completion functions +// for the BOM type and format flags: --bom and --bom-format on scan, --type +// and --format on bom. +func bomTypeCompletions() cobra.CompletionFunc { + return fixedCompletions(scan.BOMTypeOrder, map[string]string{ + scan.BOMTypeSBOM: "Software BOM", + scan.BOMTypeAIBOM: "AI BOM: models, AI services and MCP servers", + scan.BOMTypeCBOM: "Cryptographic BOM", + scan.BOMTypeAll: "Combined BOM of all types", + }) +} + +func bomFormatCompletions() cobra.CompletionFunc { + return fixedCompletions(scan.BOMFormats, map[string]string{ + scan.BOMFormatCycloneDX17: "CycloneDX 1.7 JSON (default)", + scan.BOMFormatCycloneDX16: "CycloneDX 1.6 JSON", + scan.BOMFormatSPDX23: "SPDX 2.3 JSON, sbom only", + scan.BOMFormatSPDX301: "SPDX 3.0.1 JSON, sbom and aibom", + scan.BOMFormatCycloneDX: "Alias of cyclonedx-1.7", + scan.BOMFormatSPDX: "Alias: spdx-2.3 for sbom, spdx-3.0.1 for aibom", + }) +} + // warnOnUnusedSBOMVEXFlags emits a warning when --sbom-output / --vex-output // are set without their corresponding generation flag. Called by the // subcommands that treat the flags as "output for a generated artifact" @@ -291,7 +353,7 @@ func init() { // registrations. `supply-chain check` re-registers the subset it consumes // locally (see supply_chain_check.go), since it is a sibling of scan. scanCmd.PersistentFlags().StringVarP(&format, "format", "f", getEnvOrDefault("ARMIS_FORMAT", "human"), "Output format: human, json, sarif, junit") - scanCmd.PersistentFlags().BoolVar(&noProgress, "no-progress", false, "Suppress progress output (for CI/scripts)") + addUploadFlags(scanCmd) scanCmd.PersistentFlags().StringSliceVar(&failOn, "fail-on", defaultFailOn(), "Exit with error on findings at these severity levels: INFO, LOW, MEDIUM, HIGH, CRITICAL") scanCmd.PersistentFlags().IntVar(&exitCode, "exit-code", 1, "Exit code when --fail-on triggers") scanCmd.PersistentFlags().StringVar(&minSeverity, "min-severity", "", "Only display findings at or above this severity: INFO, LOW, MEDIUM, HIGH, CRITICAL (display only: --fail-on still evaluates all findings, and SARIF output always includes them all)") @@ -302,9 +364,7 @@ func init() { _ = scanCmd.RegisterFlagCompletionFunc("fail-on", severityCompletions()) _ = scanCmd.RegisterFlagCompletionFunc("min-severity", severityCompletions()) - scanCmd.PersistentFlags().BoolVar(&includeTests, "include-tests", false, "Include test files in the scan (test files are excluded by default)") - scanCmd.PersistentFlags().IntVar(&scanTimeout, "scan-timeout", 60, "Maximum time in minutes to wait for scan analysis to complete") - scanCmd.PersistentFlags().IntVar(&uploadTimeout, "upload-timeout", 10, "Maximum time in minutes to wait for artifact upload to complete") + scanCmd.PersistentFlags().BoolVar(&includeTests, "include-tests", false, includeTestsUsage) scanCmd.PersistentFlags().BoolVar(&includeNonExploitable, "include-non-exploitable", false, "Show low/medium exploitability findings (hidden by default; high and ungraded findings always shown)") scanCmd.PersistentFlags().StringVar(&groupBy, "group-by", "none", "Group findings by: none, cwe, severity, file") _ = scanCmd.RegisterFlagCompletionFunc("group-by", fixedCompletions(validGroupBy, map[string]string{ @@ -324,30 +384,11 @@ func init() { scanCmd.PersistentFlags().StringVar(&vexOutput, "vex-output", "", "Output file path for VEX (default: .armis/-vex.json)") scanCmd.PersistentFlags().StringSliceVar(&bomTypes, "bom", nil, "Download BOMs of these types, comma-separated or repeated: sbom, aibom, cbom, all (combined); BOM generation must be enabled for your tenant") scanCmd.PersistentFlags().StringVar(&bomFormat, "bom-format", scan.BOMFormatCycloneDX17, "BOM format: cyclonedx-1.7, cyclonedx-1.6, spdx-2.3, spdx-3.0.1, or the aliases cyclonedx, spdx (requires --bom; BOM generation must be enabled for your tenant)") - _ = scanCmd.RegisterFlagCompletionFunc("bom", fixedCompletions(scan.BOMTypeOrder, map[string]string{ - scan.BOMTypeSBOM: "Software BOM", - scan.BOMTypeAIBOM: "AI BOM: models, AI services and MCP servers", - scan.BOMTypeCBOM: "Cryptographic BOM", - scan.BOMTypeAll: "Combined BOM of all types", - })) - _ = scanCmd.RegisterFlagCompletionFunc("bom-format", fixedCompletions(scan.BOMFormats, map[string]string{ - scan.BOMFormatCycloneDX17: "CycloneDX 1.7 JSON (default)", - scan.BOMFormatCycloneDX16: "CycloneDX 1.6 JSON", - scan.BOMFormatSPDX23: "SPDX 2.3 JSON, sbom only", - scan.BOMFormatSPDX301: "SPDX 3.0.1 JSON, sbom and aibom", - scan.BOMFormatCycloneDX: "Alias of cyclonedx-1.7", - scan.BOMFormatSPDX: "Alias: spdx-2.3 for sbom, spdx-3.0.1 for aibom", - })) + _ = scanCmd.RegisterFlagCompletionFunc("bom", bomTypeCompletions()) + _ = scanCmd.RegisterFlagCompletionFunc("bom-format", bomFormatCompletions()) scanCmd.PersistentFlags().StringVar(&bomOutput, "bom-output", "", "Directory for BOM files, or - to write one BOM to stdout (default: .armis; requires --bom; BOM generation must be enabled for your tenant)") scanCmd.PersistentFlags().BoolVar(&summaryTop, "summary-top", false, "Display summary at the top of output (before findings)") scanCmd.PersistentFlags().StringVarP(&outputFile, "output", "o", "", "Write output to file (auto-detects format from extension: .json, .sarif, .xml)") - // poll-interval overrides the Scanner's default status-poll interval (5s in - // repo/image/sbom Scanners). Hidden: it exists solely so RunE-level tests can - // avoid burning a real poll tick, the same way package-level tests already do - // via each Scanner's WithPollInterval builder, without going through cobra - // flag parsing (RunE tests call scanXCmd.RunE directly, not cmd.Execute()). - scanCmd.PersistentFlags().DurationVar(&pollInterval, "poll-interval", 0, "Override the scan status poll interval (0 = use default)") - _ = scanCmd.PersistentFlags().MarkHidden("poll-interval") if rootCmd != nil { rootCmd.AddCommand(scanCmd) } diff --git a/internal/cmd/scan_image.go b/internal/cmd/scan_image.go index 11d6746..762261d 100644 --- a/internal/cmd/scan_image.go +++ b/internal/cmd/scan_image.go @@ -1,6 +1,7 @@ package cmd import ( + "context" "fmt" "os" "time" @@ -19,6 +20,13 @@ import ( var tarballPath string var pullPolicy string +// The --tarball and --pull flags, which scan image and bom image share. +const ( + tarballUsage = "Path to a container image tarball" + defaultPullPolicy = "missing" + pullUsage = "Image pull policy: 'always', 'missing' (default), or 'never'. Ignored when --tarball is used" +) + var scanImageCmd = &cobra.Command{ Use: "image [image-name]", Short: "Scan a container image", @@ -35,56 +43,15 @@ var scanImageCmd = &cobra.Command{ // The BOM type and format pairs, --bom-output, and a default .armis // that is not a plain directory fail before any network call; // PersistentPreRunE has normalized the values. - if err := cmdutil.ValidateBOMFlags(bomTypes, bomFormat, bomOutput); err != nil { + if err := cmdutil.ValidateBOMFlags(cmdutil.ScanBOMFlags, bomTypes, bomFormat, bomOutput); err != nil { return err } if err := checkDefaultOutputDir(); err != nil { return err } - // Validate --pull before auth so a bad value (e.g. "badvalue") surfaces as a - // flag error rather than hiding behind an auth failure. This mirrors the - // allowlist in determinePullBehavior, which only runs after auth + the docker - // check; "" is excluded here because the flag default is "missing". - // - // Only validate on the image-name path: --pull is documented as "Ignored - // when --tarball is used" (tarball scans never pull), so rejecting a bad - // --pull alongside --tarball would contradict the flag's contract. - if tarballPath == "" { - switch pullPolicy { - case "always", "missing", "never": - // valid - default: - return fmt.Errorf("invalid --pull value %q: must be one of [always missing never]", pullPolicy) - } - } - - if tarballPath == "" && len(args) == 0 { - return fmt.Errorf("missing target: specify an image name or use --tarball") - } - - // Validate tarball path exists before making network calls - if tarballPath != "" { - // armis:ignore cwe:22 reason:os.Stat is read-only existence check; path sanitized via util.SanitizePath() before filesystem write - // armis:ignore cwe:367 reason:TOCTOU benign here; tarball read later via docker/podman, not direct open after stat - info, err := os.Stat(tarballPath) - if err != nil { - if os.IsNotExist(err) { - return fmt.Errorf("tarball does not exist: %s", tarballPath) - } - return fmt.Errorf("cannot access tarball %s: %w", tarballPath, err) - } - if info.IsDir() { - return fmt.Errorf("tarball path is a directory, not a file: %s", tarballPath) - } - } - - // Surface a missing container runtime before auth. Scanning by image name - // exports via Docker/Podman, so a dev with no runtime would otherwise hit - // the auth error first and never learn the real blocker. --tarball bypasses - // the daemon, so skip this check on that path. - if tarballPath == "" && !image.IsDockerAvailable() { - return image.ErrRuntimeNotFound + if err := checkImageTarget(args); err != nil { + return err } authProvider, err := getAuthProvider(cmd.Context()) @@ -146,30 +113,9 @@ var scanImageCmd = &cobra.Command{ ctx, cancel := NewSignalContext() defer cancel() - var result *model.ScanResult - - // Warn if both tarball and image name are provided - if tarballPath != "" && len(args) > 0 { - cli.PrintWarning("both --tarball and image name provided; using tarball (image name ignored)") - } - - if tarballPath != "" { - // armis:ignore cwe:22 reason:tarballPath is immediately sanitized by SanitizePath; only sanitizedPath is used - sanitizedPath, pathErr := util.SanitizePath(tarballPath) - if pathErr != nil { - return fmt.Errorf("invalid tarball path: %w", pathErr) - } - result, err = scanner.ScanTarball(ctx, sanitizedPath) - if err != nil { - return handleScanError(ctx, err) - } - } else { - // armis:ignore cwe:20 reason:imageName validated by distribution/reference.ParseNormalizedNamed in ScanImage - imageName := args[0] - result, err = scanner.ScanImage(ctx, imageName) // armis:ignore cwe:20 reason:validated by reference.ParseNormalizedNamed in ScanImage - if err != nil { - return handleScanError(ctx, err) - } + result, err := scanImageTarget(ctx, scanner, args, handleScanError) + if err != nil { + return err } // Resolve output destination and format (handles file creation, format auto-detection, colors) @@ -196,6 +142,85 @@ var scanImageCmd = &cobra.Command{ }, } +// checkImageTarget checks the target of scan image and bom image before auth +// and upload: --pull, a target to scan, the --tarball file, and a container +// runtime to export an image name. +func checkImageTarget(args []string) error { + // Validate --pull before auth so a bad value (e.g. "badvalue") surfaces as a + // flag error rather than hiding behind an auth failure. This mirrors the + // allowlist in determinePullBehavior, which only runs after auth + the docker + // check; "" is excluded here because the flag default is "missing". + // + // Only validate on the image-name path: --pull is documented as "Ignored + // when --tarball is used" (tarball scans never pull), so rejecting a bad + // --pull alongside --tarball would contradict the flag's contract. + if tarballPath == "" { + switch pullPolicy { + case "always", "missing", "never": + // valid + default: + return fmt.Errorf("invalid --pull value %q: must be one of [always missing never]", pullPolicy) + } + } + + if tarballPath == "" && len(args) == 0 { + return fmt.Errorf("missing target: specify an image name or use --tarball") + } + + // Validate tarball path exists before making network calls + if tarballPath != "" { + // armis:ignore cwe:22 reason:os.Stat is read-only existence check; path sanitized via util.SanitizePath() before filesystem write + // armis:ignore cwe:367 reason:TOCTOU benign here; tarball read later via docker/podman, not direct open after stat + info, err := os.Stat(tarballPath) + if err != nil { + if os.IsNotExist(err) { + return fmt.Errorf("tarball does not exist: %s", tarballPath) + } + return fmt.Errorf("cannot access tarball %s: %w", tarballPath, err) + } + if info.IsDir() { + return fmt.Errorf("tarball path is a directory, not a file: %s", tarballPath) + } + } + + // Surface a missing container runtime before auth. Scanning by image name + // exports via Docker/Podman, so a dev with no runtime would otherwise hit + // the auth error first and never learn the real blocker. --tarball bypasses + // the daemon, so skip this check on that path. + if tarballPath == "" && !image.IsDockerAvailable() { + return image.ErrRuntimeNotFound + } + return nil +} + +// scanImageTarget scans the --tarball, which wins over an image name, or the +// image named in args. onScanErr gives the command's error for a failed scan. +func scanImageTarget(ctx context.Context, scanner *image.Scanner, args []string, onScanErr func(context.Context, error) error) (*model.ScanResult, error) { + // Warn if both tarball and image name are provided + if tarballPath != "" && len(args) > 0 { + cli.PrintWarning("both --tarball and image name provided; using tarball (image name ignored)") + } + + var result *model.ScanResult + var err error + if tarballPath != "" { + // armis:ignore cwe:22 reason:tarballPath is immediately sanitized by SanitizePath; only sanitizedPath is used + sanitizedPath, pathErr := util.SanitizePath(tarballPath) + if pathErr != nil { + return nil, fmt.Errorf("invalid tarball path: %w", pathErr) + } + result, err = scanner.ScanTarball(ctx, sanitizedPath) + } else { + // armis:ignore cwe:20 reason:imageName validated by distribution/reference.ParseNormalizedNamed in ScanImage + imageName := args[0] + result, err = scanner.ScanImage(ctx, imageName) // armis:ignore cwe:20 reason:validated by reference.ParseNormalizedNamed in ScanImage + } + if err != nil { + return nil, onScanErr(ctx, err) + } + return result, nil +} + // imageTarget returns the scan target as typed: the --tarball path, which // wins over an image name, else the image name. func imageTarget(args []string) string { @@ -206,7 +231,7 @@ func imageTarget(args []string) string { } func init() { - scanImageCmd.Flags().StringVar(&tarballPath, "tarball", "", "Path to a container image tarball") - scanImageCmd.Flags().StringVar(&pullPolicy, "pull", "missing", "Image pull policy: 'always', 'missing' (default), or 'never'. Ignored when --tarball is used") + scanImageCmd.Flags().StringVar(&tarballPath, "tarball", "", tarballUsage) + scanImageCmd.Flags().StringVar(&pullPolicy, "pull", defaultPullPolicy, pullUsage) scanCmd.AddCommand(scanImageCmd) } diff --git a/internal/cmd/scan_repo.go b/internal/cmd/scan_repo.go index 784338a..29aa557 100644 --- a/internal/cmd/scan_repo.go +++ b/internal/cmd/scan_repo.go @@ -44,29 +44,16 @@ var scanRepoCmd = &cobra.Command{ // The BOM type and format pairs, --bom-output, and a default .armis // that is not a plain directory fail before any network call; // PersistentPreRunE has normalized the values. - if err := cmdutil.ValidateBOMFlags(bomTypes, bomFormat, bomOutput); err != nil { + if err := cmdutil.ValidateBOMFlags(cmdutil.ScanBOMFlags, bomTypes, bomFormat, bomOutput); err != nil { return err } if err := checkDefaultOutputDir(); err != nil { return err } - repoPath := "." - if len(args) > 0 { - repoPath = args[0] - } - - // Validate path exists and is a directory before making network calls - // armis:ignore cwe:22 reason:os.Stat is read-only existence check; path is from direct CLI arg, not untrusted input - info, err := os.Stat(repoPath) - if err != nil { - if os.IsNotExist(err) { - return fmt.Errorf("path does not exist: %s", repoPath) - } - return fmt.Errorf("cannot access path %s: %w", repoPath, err) - } - if !info.IsDir() { - return fmt.Errorf("path is not a directory: %s", repoPath) + repoPath := repoArg(args) + if err := checkRepoPath(repoPath); err != nil { + return err } authProvider, err := getAuthProvider(cmd.Context()) @@ -124,29 +111,15 @@ var scanRepoCmd = &cobra.Command{ scanner = scanner.WithSBOMVEXOptions(sbomVEXOpts) } - // Enable best-effort git-hint detection (repo_name / git_sha / origin_sha) - // for incremental-scan baseline resolution — but only for a full-repo-root - // upload. A --changed or --include-files partial upload is not a faithful - // whole-repo snapshot, so a full-repo baseline diff against it would be - // meaningless; skip detection entirely in those modes. DetectGitHints - // additionally verifies the target is the repository root. - if len(includeFiles) == 0 && !cmd.Flags().Changed("changed") { + if wantGitHints(cmd) { scanner = scanner.WithGitHints() } // Handle --include-files flag for targeted file scanning - // Security: Path traversal protection is enforced by ParseFileList which - // validates all paths using SafeJoinPath to ensure they don't escape the - // repository root. Invalid or traversal paths are rejected with an error. if len(includeFiles) > 0 { - absPath, err := filepath.Abs(repoPath) // armis:ignore cwe:770 reason:no bound needed here, this only resolves a path; scanner flags this line but the actual MaxFiles=1000 bound is enforced by ParseFileList below - if err != nil { - return fmt.Errorf("failed to resolve path: %w", err) - } - // armis:ignore cwe:22 cwe:770 reason:absPath is derived from filepath.Abs() immediately above; ParseFileList validates paths via SafeJoinPath and enforces MaxFiles=1000 - fileList, err := repo.ParseFileList(absPath, includeFiles) + fileList, err := parseIncludeFiles(repoPath) if err != nil { - return fmt.Errorf("invalid --include-files: %w", err) + return err } scanner = scanner.WithIncludeFiles(fileList) } @@ -232,9 +205,65 @@ var scanRepoCmd = &cobra.Command{ }, } +// repoArg returns the repository path of scan repo and bom repo: the +// argument, or the current directory. +func repoArg(args []string) string { + if len(args) > 0 { + return args[0] + } + return "." +} + +// wantGitHints reports whether a repo upload sends git hints. It enables +// best-effort git-hint detection (repo_name / git_sha / origin_sha) for +// incremental-scan baseline resolution, and for the name and version at the +// root of the BOMs, but only for a full-repo-root upload. A --changed or +// --include-files partial upload is not a faithful whole-repo snapshot, so a +// full-repo baseline diff against it would be meaningless; skip detection +// entirely in those modes. DetectGitHints additionally verifies the target +// is the repository root. bom repo has no --changed, which then reads as +// not given. +func wantGitHints(cmd *cobra.Command) bool { + return len(includeFiles) == 0 && !cmd.Flags().Changed("changed") +} + +// checkRepoPath checks that repoPath is an existing directory, before any +// network call. +func checkRepoPath(repoPath string) error { + // armis:ignore cwe:22 reason:os.Stat is read-only existence check; path is from direct CLI arg, not untrusted input + info, err := os.Stat(repoPath) + if err != nil { + if os.IsNotExist(err) { + return fmt.Errorf("path does not exist: %s", repoPath) + } + return fmt.Errorf("cannot access path %s: %w", repoPath, err) + } + if !info.IsDir() { + return fmt.Errorf("path is not a directory: %s", repoPath) + } + return nil +} + +// parseIncludeFiles returns the --include-files list for the repository at +// repoPath. +// Security: Path traversal protection is enforced by ParseFileList which +// validates all paths using SafeJoinPath to ensure they don't escape the +// repository root. Invalid or traversal paths are rejected with an error. +func parseIncludeFiles(repoPath string) (*repo.FileList, error) { + absPath, err := filepath.Abs(repoPath) // armis:ignore cwe:770 reason:no bound needed here, this only resolves a path; scanner flags this line but the actual MaxFiles=1000 bound is enforced by ParseFileList below + if err != nil { + return nil, fmt.Errorf("failed to resolve path: %w", err) + } + // armis:ignore cwe:22 cwe:770 reason:absPath is derived from filepath.Abs() immediately above; ParseFileList validates paths via SafeJoinPath and enforces MaxFiles=1000 + fileList, err := repo.ParseFileList(absPath, includeFiles) + if err != nil { + return nil, fmt.Errorf("invalid --include-files: %w", err) + } + return fileList, nil +} + func init() { - scanRepoCmd.Flags().StringSliceVar(&includeFiles, "include-files", nil, - "Comma-separated list of file paths to include in scan (relative to repository root)") + scanRepoCmd.Flags().StringSliceVar(&includeFiles, "include-files", nil, includeFilesUsage) scanRepoCmd.Flags().BoolVar(&showSuppressed, "show-suppressed", false, "Show findings suppressed by .armisignore directives") scanRepoCmd.Flags().StringVar(&changedRef, "changed", "", diff --git a/internal/cmd/scan_status.go b/internal/cmd/scan_status.go index 7a8067f..ee12de5 100644 --- a/internal/cmd/scan_status.go +++ b/internal/cmd/scan_status.go @@ -15,6 +15,7 @@ import ( "github.com/ArmisSecurity/armis-cli/internal/output" "github.com/ArmisSecurity/armis-cli/internal/scan" "github.com/ArmisSecurity/armis-cli/internal/scan/history" + "github.com/ArmisSecurity/armis-cli/internal/util" "github.com/spf13/cobra" ) @@ -218,6 +219,7 @@ const statusLabelWidth = 15 // each other whether or not color is enabled. func renderHumanStatus(w io.Writer, d model.IngestStatusData, historyEntry *history.Entry) { styles := output.GetStyles() + d = stripStatusText(d) statusVal := strings.ToUpper(d.ScanStatus) statusRendered := styles.Bold.Render(statusVal) @@ -276,6 +278,23 @@ func renderHumanStatus(w io.Writer, d model.IngestStatusData, historyEntry *hist } } +// stripStatusText returns d with control characters, such as terminal +// escapes, stripped from every string the server sent, before the human +// block prints them. The JSON output encodes them instead. +func stripStatusText(d model.IngestStatusData) model.IngestStatusData { + for _, f := range []*string{&d.ArtifactType, &d.ExpirationTime, &d.FileName, &d.ScanID, + &d.ScanStatus, &d.ScanType, &d.StartedAt, &d.TenantID, &d.UpdatedAt} { + *f = util.StripControl(*f) + } + for _, f := range []**string{&d.CompletedAt, &d.LastError} { + if *f != nil { + v := util.StripControl(**f) + *f = &v + } + } + return d +} + // scanStatusHint returns a one-line, user-facing description of the current // state. It covers every ArtifactScanStatus enum value defined by the API // so the caller always sees something useful (never an empty hint). diff --git a/internal/cmd/scan_status_test.go b/internal/cmd/scan_status_test.go index 3664001..d6f2591 100644 --- a/internal/cmd/scan_status_test.go +++ b/internal/cmd/scan_status_test.go @@ -9,7 +9,9 @@ import ( "strings" "testing" + "github.com/ArmisSecurity/armis-cli/internal/cli" "github.com/ArmisSecurity/armis-cli/internal/model" + "github.com/ArmisSecurity/armis-cli/internal/output" "github.com/ArmisSecurity/armis-cli/internal/scan/history" "github.com/ArmisSecurity/armis-cli/internal/testutil" ) @@ -393,3 +395,41 @@ func TestScanStatus_HistoryScopedByEnv(t *testing.T) { t.Errorf("cross-env scan_id leaked into fallback: %v", err) } } + +// TestScanStatus_StripsServerText: every server string in the human block +// loses its control characters, such as terminal escapes. +func TestScanStatus_StripsServerText(t *testing.T) { + // Plain styles, so the only escapes left would be the server's. + cli.InitColors(cli.ColorModeNever) + output.SyncColors() + const esc = "\x1b[2J\x1b]0;t\x07\u009b" + lastError := "upload\nrejected" + esc + completed := "2026-07-27T10:09:00Z" + esc + cleanup := setupStatusEnv(t, statusServer(t, "FAILED"+esc, func(d *model.IngestStatusData) { + d.ArtifactType += esc + d.ScanType += esc + d.FileName += esc + d.StartedAt += esc + d.UpdatedAt += esc + d.ExpirationTime += esc + d.CompletedAt = &completed + d.LastError = &lastError + })) + defer cleanup() + origFormat := format + t.Cleanup(func() { format = origFormat }) + format = statusFormatHuman + + out, err := runStatus(t, []string{"507f1f77bcf86cd799439011"}) + if err != nil { + t.Fatalf("scan status: %v", err) + } + if strings.ContainsAny(out, "\x1b\x07\u009b") { + t.Errorf("output holds a control character: %q", out) + } + for _, want := range []string{"FAILED[2J]0;T", "repo[2J]0;t", "example.tar.gz[2J]0;t", "upload rejected[2J]0;t", "2026-07-27T10:09:00Z[2J]0;t"} { + if !strings.Contains(out, want) { + t.Errorf("output = %q, want %q", out, want) + } + } +} diff --git a/internal/model/finding.go b/internal/model/finding.go index 7cd8c9c..77d9e69 100644 --- a/internal/model/finding.go +++ b/internal/model/finding.go @@ -82,6 +82,9 @@ type ScanResult struct { // could not be downloaded; a non-empty list makes the scan exit 2. Kept // out of the JSON report. BOMFailures []string `json:"-"` + // BOMWritten lists the BOM types written to a file or stdout. A BOM-only + // scan that wrote none exits 2. Kept out of the JSON report. + BOMWritten []string `json:"-"` } // Summary provides aggregate statistics about scan findings. diff --git a/internal/output/output.go b/internal/output/output.go index 5212760..9918e3e 100644 --- a/internal/output/output.go +++ b/internal/output/output.go @@ -40,16 +40,21 @@ func (e *ErrResultsIncomplete) Error() string { } // ErrBOMIncomplete indicates the scan completed but one or more BOMs requested -// with --bom could not be downloaded. Like ErrResultsIncomplete it exits 2, so -// CI does not pass without the files it asked for. Labels are the BOM type -// labels (such as "AI-BOM"), given by the caller since output cannot import -// scan. +// with --bom could not be downloaded, or, with NotWritten, that a BOM-only +// scan wrote none of the BOMs it asked for. Like ErrResultsIncomplete it exits +// 2, so CI does not pass without the files it asked for. Labels are the BOM +// type labels (such as "AI-BOM"), given by the caller since output cannot +// import scan. type ErrBOMIncomplete struct { - ScanID string - Labels []string + ScanID string + Labels []string + NotWritten bool } func (e *ErrBOMIncomplete) Error() string { + if e.NotWritten { + return fmt.Sprintf("scan completed but no BOM was written: %s not available (scan ID: %s)", strings.Join(e.Labels, ", "), e.ScanID) + } return fmt.Sprintf("scan completed but %s could not be downloaded (scan ID: %s)", strings.Join(e.Labels, ", "), e.ScanID) } diff --git a/internal/scan/bom.go b/internal/scan/bom.go index 5f0d84d..ab65df6 100644 --- a/internal/scan/bom.go +++ b/internal/scan/bom.go @@ -50,13 +50,46 @@ var BOMFormats = []string{ const DefaultBOMDir = ".armis" // BOMOptions configures the BOM downloads of a scan (--bom, --bom-format, -// --bom-output). +// --bom-output), or of a BOM-only scan (armis-cli bom: --type, --format, +// --output). type BOMOptions struct { Types []string // normalized by cmdutil.NormalizeBOMFlags, in BOMTypeOrder Format string // as typed, alias included; resolved per type Output string // directory, BOMOutputStdout, or "" for DefaultBOMDir Target string // the scan target as typed, for the empty-BOM line Stdout io.Writer // stdout mode destination; nil means os.Stdout + // Only makes the scan BOM-only: the server builds the BOMs and runs no + // security scan, and the scanner fetches no findings. + Only bool +} + +// Progress messages for the wait on the server. +const ( + scanningMessage = "Scanning for security issues..." + buildingBOMsMessage = "Building BOMs..." +) + +// BOMOnly reports whether opts asks for a BOM-only scan. +func (o *SBOMVEXOptions) BOMOnly() bool { + return o != nil && o.BOM != nil && o.BOM.Only +} + +// ScanType returns the scan_type to send for opts: api.ScanTypeBOM for a +// BOM-only scan, else "" for the default. +func (o *SBOMVEXOptions) ScanType() string { + if o.BOMOnly() { + return api.ScanTypeBOM + } + return "" +} + +// WaitMessage is the progress message while the server works on a scan +// with opts: "Building BOMs..." for a BOM-only scan. +func (o *SBOMVEXOptions) WaitMessage() string { + if o.BOMOnly() { + return buildingBOMsMessage + } + return scanningMessage } // BOMDownloadError lists the BOM types that could not be downloaded. Err is diff --git a/internal/scan/image/image.go b/internal/scan/image/image.go index 8b92145..65aae00 100644 --- a/internal/scan/image/image.go +++ b/internal/scan/image/image.go @@ -213,6 +213,7 @@ func (s *Scanner) ScanTarball(ctx context.Context, tarballPath string) (*model.S ingestOpts.BOMFormat = s.sbomVEXOpts.BOM.Format ingestOpts.ImageRef = s.imageRef(ctx, tarballPath) } + ingestOpts.ScanType = s.sbomVEXOpts.ScanType() } scanID, err := s.client.StartIngest(ctx, ingestOpts) @@ -233,13 +234,14 @@ func (s *Scanner) ScanTarball(ctx context.Context, tarballPath string) (*model.S styles.MutedText.Render("Scan initiated with ID:"), styles.ScanID.Render(scanID)) - spinner := progress.NewSpinnerWithContext(ctx, "Scanning for security issues...", s.noProgress) + waitMessage := s.sbomVEXOpts.WaitMessage() + spinner := progress.NewSpinnerWithContext(ctx, waitMessage, s.noProgress) spinner.Start() defer spinner.Stop() _, err = s.client.WaitForIngest(ctx, s.tenantID, scanID, s.pollInterval, s.timeout, func(status model.IngestStatusData) { - spinner.Update(scan.FormatScanStatus(status.ScanStatus, "Scanning for security issues...")) + spinner.Update(scan.FormatScanStatus(status.ScanStatus, waitMessage)) }) elapsed := spinner.GetElapsed() if err != nil { @@ -251,6 +253,11 @@ func (s *Scanner) ScanTarball(ctx context.Context, tarballPath string) (*model.S styles.MutedText.Render("Scan completed in"), styles.Duration.Render(scan.FormatElapsed(elapsed))) + // A BOM-only scan has no findings to fetch. + if s.sbomVEXOpts.BOMOnly() { + return scan.BOMOnlyResult(ctx, s.client, s.tenantID, scanID, s.fileArtifactName(tarballPath), s.sbomVEXOpts) + } + fetchSpinner := progress.NewSpinnerWithContext(ctx, "Retrieving results...", s.noProgress) fetchSpinner.Start() @@ -280,24 +287,9 @@ func (s *Scanner) ScanTarball(ctx context.Context, tarballPath string) (*model.S // (e.g. appsec-v2 skipped for exceeding a file-count limit) even when the // user didn't request SBOM/VEX generation. Download() no-ops the SBOM/VEX // download steps when s.sbomVEXOpts is nil. - artifactName := s.artifactName - if artifactName == "" { - artifactName = filepath.Base(tarballPath) - if ext := filepath.Ext(artifactName); ext != "" { - artifactName = artifactName[:len(artifactName)-len(ext)] - } - } - downloader := scan.NewSBOMVEXDownloader(s.client, s.tenantID, s.sbomVEXOpts) - skipReason, err := downloader.Download(ctx, scanID, artifactName) - bomFailures, err := scan.SplitBOMError(err) + skipReason, bomFailures, err := scan.DownloadArtifacts(ctx, s.client, s.tenantID, scanID, s.fileArtifactName(tarballPath), s.sbomVEXOpts) if err != nil { - // Log warning but don't fail the scan - cli.PrintWarningf("%v", err) - } - if len(bomFailures) > 0 && ctx.Err() != nil { - // Ctrl+C during the BOM downloads: exit as cancelled, not as a - // failed download. - return nil, ctx.Err() + return nil, err } result := buildScanResult(scanID, findings, s.client.IsDebug(), s.includeNonExploitable) @@ -306,6 +298,17 @@ func (s *Scanner) ScanTarball(ctx context.Context, tarballPath string) (*model.S return result, nil } +// fileArtifactName starts the names of the SBOM, VEX and BOM files: the +// name ScanImage set from the image reference, else the tarball's file name +// without its extension. +func (s *Scanner) fileArtifactName(tarballPath string) string { + if s.artifactName != "" { + return s.artifactName + } + name := filepath.Base(tarballPath) + return strings.TrimSuffix(name, filepath.Ext(name)) +} + func (s *Scanner) exportImage(ctx context.Context, imageName, outputPath string) error { // Defense-in-depth: validate image name even though callers should have validated. // This prevents command injection even if this method is called from a new code path. diff --git a/internal/scan/image/manifest_test.go b/internal/scan/image/manifest_test.go index dd8d9f3..88a4c23 100644 --- a/internal/scan/image/manifest_test.go +++ b/internal/scan/image/manifest_test.go @@ -355,6 +355,83 @@ func TestScanTarball_ImageRef(t *testing.T) { }) } +// TestScanTarball_BOMOnly covers the request of bom image: scan_type bom, +// the BOM fields and image_ref as scan image --bom sends them, and no SBOM or +// VEX generation. +func TestScanTarball_BOMOnly(t *testing.T) { + rows := []struct { + name string + byName string // set: bom image , as ScanImage records it + tags []string + wantRef string + wantNoRef bool + }{ + {name: "by name sends the normalized reference", byName: "python:3.12-slim", wantRef: "python:3.12-slim"}, + {name: "--tarball sends the manifest tag", tags: []string{"myorg/app:2.0"}, wantRef: "myorg/app:2.0"}, + {name: "--tarball without a tag sends no image_ref", wantNoRef: true}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + t.Setenv("ARMIS_HISTORY_DIR", t.TempDir()) + server, get := newScanBodyServer(t) + httpClient := httpclient.NewClient(httpclient.Config{Timeout: 5 * time.Second}) + uploadClient := httpclient.NewClient(httpclient.Config{Timeout: 5 * time.Second, DisableRetry: true}) + c, err := api.NewClient(server.URL, testutil.NewTestAuthProvider("token123"), false, time.Minute, + api.WithHTTPClient(httpClient), api.WithUploadHTTPClient(uploadClient), api.WithAllowLocalURLs(true)) + if err != nil { + t.Fatalf("NewClient: %v", err) + } + s := NewScanner(c, true, "tenant-456", 0, false, time.Minute, false).WithPollInterval(10 * time.Millisecond). + WithSBOMVEXOptions(&scan.SBOMVEXOptions{BOM: &scan.BOMOptions{ + Types: []string{scan.BOMTypeSBOM, scan.BOMTypeCBOM}, Format: scan.BOMFormatCycloneDX16, Output: t.TempDir(), Only: true, + }}) + tarball := writeImageTar(t, "app.tar", dockerSave(row.tags...)) + if row.byName != "" { + normalized, err := validateImageName(row.byName) + if err != nil { + t.Fatal(err) + } + s.useImageName(row.byName, normalized) + } + + var result *model.ScanResult + _ = testutil.CaptureStderr(t, func() { result, err = s.ScanTarball(context.Background(), tarball) }) + if err != nil { + t.Fatalf("ScanTarball: %v", err) + } + if len(result.Findings) != 0 { + t.Errorf("findings = %v, want none", result.Findings) + } + got := get() + if got["scan_type"] != "bom" { + t.Errorf("scan_type = %v, want bom", got["scan_type"]) + } + if types, _ := got["bom_types"].([]any); len(types) != 2 || types[0] != "sbom" || types[1] != "cbom" { + t.Errorf("bom_types = %v, want [sbom cbom]", got["bom_types"]) + } + if got["bom_format"] != scan.BOMFormatCycloneDX16 { + t.Errorf("bom_format = %v, want %s", got["bom_format"], scan.BOMFormatCycloneDX16) + } + if got["sbom_generate"] != false || got["vex_generate"] != false { + t.Errorf("sbom_generate = %v, vex_generate = %v, want false", got["sbom_generate"], got["vex_generate"]) + } + for _, key := range []string{"custom_scans", "sbom_format"} { + if _, ok := got[key]; ok { + t.Errorf("%s = %v, want it omitted", key, got[key]) + } + } + ref, ok := got["image_ref"] + if row.wantNoRef { + if ok { + t.Errorf("image_ref = %v, want it omitted", ref) + } + } else if ref != row.wantRef { + t.Errorf("image_ref = %v, want %s", ref, row.wantRef) + } + }) + } +} + func TestImageArtifactName(t *testing.T) { const digest = "sha256:05a9f2b1c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c4177" tests := []struct { diff --git a/internal/scan/repo/githints.go b/internal/scan/repo/githints.go index 5056f83..c61457c 100644 --- a/internal/scan/repo/githints.go +++ b/internal/scan/repo/githints.go @@ -126,6 +126,7 @@ func detectDefaultBranch(repoRoot string) string { // - https://github.com/org/repo.git (https) // - https://user@host/org/repo.git (https with userinfo) // - ssh://git@host:22/org/repo.git (ssh with port) +// - https://host/org/repo.git?x=1#y (http(s) URL with a query or fragment) func normalizeRepoName(rawURL string) string { s := strings.TrimSpace(rawURL) if s == "" { @@ -138,9 +139,19 @@ func normalizeRepoName(rawURL string) string { // detection silently drops repo_name. Harmless for genuine URLs. s = strings.ReplaceAll(s, "\\", "/") - // Strip a scheme prefix ("https://", "ssh://", "git://", ...). + // Strip a scheme prefix ("https://", "ssh://", "git://", ...). For http + // and https, also drop the query and fragment, which can carry a token + // (?access_token=...) and are no part of the repository's name. git + // reads ? and # as path characters in ssh://, git:// and file:// URLs, + // scp-like remotes and local paths, so those are left alone. if i := strings.Index(s, "://"); i != -1 { + scheme := strings.ToLower(s[:i]) s = s[i+3:] + if scheme == "http" || scheme == "https" { + if j := strings.IndexAny(s, "?#"); j != -1 { + s = s[:j] + } + } } // Strip userinfo ("git@", "user@"). diff --git a/internal/scan/repo/githints_test.go b/internal/scan/repo/githints_test.go index 45042ff..b657b4b 100644 --- a/internal/scan/repo/githints_test.go +++ b/internal/scan/repo/githints_test.go @@ -326,6 +326,12 @@ func TestNormalizeRepoName(t *testing.T) { {"whitespace only", " ", ""}, {"host only no path", "https://github.com", ""}, {"single segment path", "https://github.com/repo.git", ""}, + {"query with a token", "https://github.com/org/repo.git?access_token=X", "org/repo"}, + {"fragment", "https://github.com/org/repo.git#main", "org/repo"}, + {"query and fragment after userinfo", "https://user:pw@github.com/org/repo?a=b@c#frag", "org/repo"}, + {"query without .git", "https://gitlab.com/group/repo?private_token=X", "group/repo"}, + {"http with a query", "http://git.example.com/org/repo.git?token=X", "org/repo"}, + {"HTTPS in capitals", "HTTPS://github.com/org/repo.git?access_token=X", "org/repo"}, } for _, tt := range tests { @@ -334,6 +340,34 @@ func TestNormalizeRepoName(t *testing.T) { if got != tt.want { t.Errorf("normalizeRepoName(%q) = %q, want %q", tt.url, got, tt.want) } + if strings.ContainsAny(got, "?#") || strings.Contains(got, "token") { + t.Errorf("normalizeRepoName(%q) = %q keeps a query or fragment", tt.url, got) + } + }) + } +} + +// TestNormalizeRepoNameKeepsPathCharacters: outside http and https, git reads +// ? and # as part of the path, so the name keeps them, as it always has. +func TestNormalizeRepoNameKeepsPathCharacters(t *testing.T) { + tests := []struct { + name string + url string + want string + }{ + {"ssh with ?", "ssh://git@host/org/re?po.git", "org/re?po"}, + {"ssh with #", "ssh://git@host:22/org/re#po.git", "org/re#po"}, + {"git protocol with ?", "git://host/org/re?po.git", "org/re?po"}, + {"file URL with #", "file:///srv/git/org/re#po.git", "org/re#po"}, + {"scp-like with ?", "git@host:org/re?po.git", "org/re?po"}, + {"scp-like with #", "git@host:org/re#po", "org/re#po"}, + {"local path with #", "/srv/git/c#/repo", "c#/repo"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := normalizeRepoName(tt.url); got != tt.want { + t.Errorf("normalizeRepoName(%q) = %q, want %q", tt.url, got, tt.want) + } }) } } diff --git a/internal/scan/repo/repo.go b/internal/scan/repo/repo.go index 5c4abc7..aca185e 100644 --- a/internal/scan/repo/repo.go +++ b/internal/scan/repo/repo.go @@ -229,6 +229,7 @@ func (s *Scanner) Scan(ctx context.Context, path string) (*model.ScanResult, err ingestOpts.BOMTypes = s.sbomVEXOpts.BOM.Types ingestOpts.BOMFormat = s.sbomVEXOpts.BOM.Format } + ingestOpts.ScanType = s.sbomVEXOpts.ScanType() } // Best-effort git hints for incremental-scan baseline resolution. Detection @@ -265,13 +266,14 @@ func (s *Scanner) Scan(ctx context.Context, path string) (*model.ScanResult, err styles.MutedText.Render("Scan initiated with ID:"), styles.ScanID.Render(scanID)) - analysisSpinner := progress.NewSpinnerWithContext(ctx, "Scanning for security issues...", s.noProgress) + waitMessage := s.sbomVEXOpts.WaitMessage() + analysisSpinner := progress.NewSpinnerWithContext(ctx, waitMessage, s.noProgress) analysisSpinner.Start() defer analysisSpinner.Stop() _, err = s.client.WaitForIngest(ctx, s.tenantID, scanID, s.pollInterval, s.timeout, func(status model.IngestStatusData) { - analysisSpinner.Update(scan.FormatScanStatus(status.ScanStatus, "Scanning for security issues...")) + analysisSpinner.Update(scan.FormatScanStatus(status.ScanStatus, waitMessage)) }) elapsed := analysisSpinner.GetElapsed() analysisSpinner.Stop() @@ -283,6 +285,11 @@ func (s *Scanner) Scan(ctx context.Context, path string) (*model.ScanResult, err styles.MutedText.Render("Scan completed in"), styles.Duration.Render(scan.FormatElapsed(elapsed))) + // A BOM-only scan has no findings to fetch. + if s.sbomVEXOpts.BOMOnly() { + return scan.BOMOnlyResult(ctx, s.client, s.tenantID, scanID, filepath.Base(absPath), s.sbomVEXOpts) + } + fetchSpinner := progress.NewSpinnerWithContext(ctx, "Retrieving results...", s.noProgress) fetchSpinner.Start() defer fetchSpinner.Stop() @@ -315,17 +322,9 @@ func (s *Scanner) Scan(ctx context.Context, path string) (*model.ScanResult, err // (e.g. appsec-v2 skipped for exceeding a file-count limit) even when the // user didn't request SBOM/VEX generation. Download() no-ops the SBOM/VEX // download steps when s.sbomVEXOpts is nil. - downloader := scan.NewSBOMVEXDownloader(s.client, s.tenantID, s.sbomVEXOpts) - skipReason, err := downloader.Download(ctx, scanID, filepath.Base(absPath)) - bomFailures, err := scan.SplitBOMError(err) + skipReason, bomFailures, err := scan.DownloadArtifacts(ctx, s.client, s.tenantID, scanID, filepath.Base(absPath), s.sbomVEXOpts) if err != nil { - // Log warning but don't fail the scan - cli.PrintWarningf("%v", err) - } - if len(bomFailures) > 0 && ctx.Err() != nil { - // Ctrl+C during the BOM downloads: exit as cancelled, not as a - // failed download. - return nil, ctx.Err() + return nil, err } result := buildScanResult(scanID, findings, s.client.IsDebug(), s.includeNonExploitable) diff --git a/internal/scan/repo/repo_test.go b/internal/scan/repo/repo_test.go index ec197c7..18328df 100644 --- a/internal/scan/repo/repo_test.go +++ b/internal/scan/repo/repo_test.go @@ -2016,7 +2016,14 @@ func TestGenerateFindingTitle(t *testing.T) { // upload, and a deferred Remove() must run even when the context is // cancelled mid-flight. func TestScan_TempFileCleanedUpOnCancel(t *testing.T) { - t.Parallel() + // Point the scanner's temp files at a directory of this test's own: other + // tests and packages that scan at the same time create armis-repo-* + // files in the shared temp directory, which the glob below would report + // as leaks. t.Setenv rules out t.Parallel. + privateTmp := t.TempDir() + for _, name := range []string{"TMPDIR", "TMP", "TEMP"} { // Unix, Windows + t.Setenv(name, privateTmp) + } tmpDir := t.TempDir() if err := os.WriteFile(filepath.Join(tmpDir, "main.go"), []byte("package main"), 0600); err != nil { t.Fatalf("create main.go: %v", err) diff --git a/internal/scan/sbom_vex.go b/internal/scan/sbom_vex.go index cde2a8c..6414460 100644 --- a/internal/scan/sbom_vex.go +++ b/internal/scan/sbom_vex.go @@ -18,6 +18,7 @@ import ( "github.com/ArmisSecurity/armis-cli/internal/api" "github.com/ArmisSecurity/armis-cli/internal/cli" + "github.com/ArmisSecurity/armis-cli/internal/model" "github.com/ArmisSecurity/armis-cli/internal/output" "github.com/ArmisSecurity/armis-cli/internal/util" ) @@ -52,6 +53,8 @@ type SBOMVEXDownloader struct { client *api.Client tenantID string opts *SBOMVEXOptions + // bomWritten lists the BOM types Download wrote, to a file or stdout. + bomWritten []string } // NewSBOMVEXDownloader creates a new downloader instance. @@ -124,12 +127,14 @@ func (d *SBOMVEXDownloader) Download(ctx context.Context, scanID, artifactName s if bom != nil { var failed []string // A 403 refetch hands back fresher links, for --sbom and --vex too. - if results, failed = d.downloadBOMs(ctx, scanID, results, sanitizedName); len(failed) > 0 { + if results, failed, d.bomWritten = d.downloadBOMs(ctx, scanID, results, sanitizedName); len(failed) > 0 { bomErr = &BOMDownloadError{Types: failed} } } if msg, skipped := results.SkipMessage(); skipped { + // Server text, printed here and in the scan summary. + msg = util.StripControl(msg) cli.PrintWarningf("Scanner skipped: %s", msg) fmt.Fprintln(os.Stderr) return msg, bomErr @@ -155,7 +160,7 @@ func (d *SBOMVEXDownloader) Download(ctx context.Context, scanID, artifactName s if outputPath == "" { outputPath = filepath.Join(".armis", defaultName) } - if err := d.downloadAndSave(ctx, sbomURL, outputPath, "SBOM", d.opts.SBOMOutput == ""); err != nil { + if err := d.downloadAndSave(ctx, sbomURL, outputPath, "SBOM", filePathMode(d.opts.SBOMOutput)); err != nil { cli.PrintWarningf("%v", err) } } else { @@ -171,7 +176,7 @@ func (d *SBOMVEXDownloader) Download(ctx context.Context, scanID, artifactName s if outputPath == "" { outputPath = filepath.Join(".armis", sanitizedName+"-vex.json") } - if err := d.downloadAndSave(ctx, vexURL, outputPath, "VEX", d.opts.VEXOutput == ""); err != nil { + if err := d.downloadAndSave(ctx, vexURL, outputPath, "VEX", filePathMode(d.opts.VEXOutput)); err != nil { cli.PrintWarningf("%v", err) } } else { @@ -182,14 +187,58 @@ func (d *SBOMVEXDownloader) Download(ctx context.Context, scanID, artifactName s return "", bomErr } +// DownloadArtifacts runs the downloads of a finished scan: the SBOM, VEX and +// BOM files opts asks for, and the scanner-skip warning. It returns the skip +// reason and the BOM types that could not be downloaded; any other error only +// warns. Ctrl+C during the BOM downloads returns the context's error, so the +// scan exits as cancelled, not as a failed download. +func DownloadArtifacts(ctx context.Context, client *api.Client, tenantID, scanID, artifactName string, opts *SBOMVEXOptions) (string, []string, error) { + skipReason, bomFailures, _, err := downloadArtifacts(ctx, client, tenantID, scanID, artifactName, opts) + return skipReason, bomFailures, err +} + +// downloadArtifacts is DownloadArtifacts that also returns the BOM types +// written. +func downloadArtifacts(ctx context.Context, client *api.Client, tenantID, scanID, artifactName string, opts *SBOMVEXOptions) (string, []string, []string, error) { + d := NewSBOMVEXDownloader(client, tenantID, opts) + skipReason, err := d.Download(ctx, scanID, artifactName) + bomFailures, err := SplitBOMError(err) + if err != nil { + // Log warning but don't fail the scan + cli.PrintWarningf("%v", err) + } + if len(bomFailures) > 0 && ctx.Err() != nil { + return "", nil, nil, ctx.Err() + } + return skipReason, bomFailures, d.bomWritten, nil +} + +// BOMOnlyResult downloads the BOMs of a finished BOM-only scan and returns +// its result: no findings, the BOM types written, and those that could not +// be downloaded. +func BOMOnlyResult(ctx context.Context, client *api.Client, tenantID, scanID, artifactName string, opts *SBOMVEXOptions) (*model.ScanResult, error) { + skipReason, bomFailures, bomWritten, err := downloadArtifacts(ctx, client, tenantID, scanID, artifactName, opts) + if err != nil { + return nil, err + } + return &model.ScanResult{ + ScanID: scanID, + Status: "completed", + Summary: model.Summary{ScannerSkipReason: skipReason}, + BOMFailures: bomFailures, + BOMWritten: bomWritten, + }, nil +} + // downloadBOMs downloads each requested BOM type and returns the results it -// ended with and the types that failed. A type the server did not store (a -// key not offered, too_large, or a format left out of bom_summary) only warns. +// ended with, the types that failed and the types written. A type the server +// did not store (a key not offered, too_large, or a format left out of +// bom_summary) only warns. // A 403, likely an expired presigned link, refetches the results once and // retries that type once; the refetched results then serve the remaining // types and are returned. -func (d *SBOMVEXDownloader) downloadBOMs(ctx context.Context, scanID string, results *api.ArtifactScanResultsResponse, artifact string) (*api.ArtifactScanResultsResponse, []string) { - var failed []string +func (d *SBOMVEXDownloader) downloadBOMs(ctx context.Context, scanID string, results *api.ArtifactScanResultsResponse, artifact string) (*api.ArtifactScanResultsResponse, []string, []string) { + var failed, written []string opts := d.opts.BOM for _, bomType := range opts.Types { label := BOMLabel(bomType) @@ -236,11 +285,46 @@ func (d *SBOMVEXDownloader) downloadBOMs(ctx context.Context, scanID string, res failed = append(failed, bomType) continue } + written = append(written, bomType) if bomIsEmpty(results.BOMSummary, bomType, data, format) { _, _ = fmt.Fprintln(os.Stderr, emptyBOMMessage(bomType, opts.Target)) } } - return results, failed + if len(written) > 0 { + warnFailedTools(results.BOMSummary, written) + } + return results, failed, written +} + +// warnFailedTools warns, after the BOM lines, that BOMs were written while +// BOM tools failed on the server: a generated or empty BOM may then lack what +// the failed tools would have found. failed_tools covers the whole scan, so +// the warning names the written types. A type whose status is failed and +// that wrote nothing has said so in its own warning. The exit code does not +// change. +func warnFailedTools(summary *api.BOMSummary, written []string) { + if summary == nil { + return + } + seen := make(map[string]bool) + var tools []string + for _, tool := range summary.FailedTools { + tool = strings.TrimSpace(util.StripControl(tool)) + if tool != "" && !seen[tool] { + seen[tool] = true + tools = append(tools, tool) + } + } + if len(tools) == 0 { + return + } + slices.Sort(tools) + labels := make([]string, 0, len(written)) + for _, t := range written { + labels = append(labels, BOMLabel(t)) + } + cli.PrintWarningf("BOM tools failed on the server: %s; %s may be incomplete", + strings.Join(tools, ", "), strings.Join(labels, ", ")) } // refetchBOMURL fetches the results again for a fresh presigned link to key. @@ -295,7 +379,8 @@ func warnBOMNotOffered(summary *api.BOMSummary, bomType, format string) { // writeBOM writes one BOM to stdout as fetched, or to its file under the // --bom-output directory (DefaultBOMDir when unset) pretty-printed by -// indentBOM. +// indentBOM. The CLI picks the file name in either directory, so the file is +// replaced, never written through. func (d *SBOMVEXDownloader) writeBOM(opts *BOMOptions, artifact, bomType, format string, data []byte) error { label := BOMLabel(bomType) if opts.Output == BOMOutputStdout { @@ -310,7 +395,11 @@ func (d *SBOMVEXDownloader) writeBOM(opts *BOMOptions, artifact, bomType, format _, _ = fmt.Fprintln(os.Stderr, styles.SuccessText.Render(label+" written to stdout")) return nil } - return d.saveArtifact(bomFilePath(opts, artifact, bomType, format), label, indentBOM(data), opts.Output == "") + mode := writeInTypedDir + if opts.Output == "" { + mode = writeDefaultDir + } + return d.saveArtifact(bomFilePath(opts, artifact, bomType, format), label, indentBOM(data), mode) } // bomFilePath is the file of one BOM under the --bom-output directory, or @@ -337,17 +426,42 @@ func warnEarlierBOMFile(opts *BOMOptions, artifact, bomType, format string) { } } +// writeMode says how saveArtifact writes a file, by who chose its path. +type writeMode int + +const ( + // writeInPlace writes a file path from an output flag (--sbom-output, + // --vex-output) as given, so /dev/stdout, a FIFO or a device still work. + writeInPlace writeMode = iota + // writeDefaultDir replaces a file the CLI named in DefaultBOMDir, which + // must be a plain directory. + writeDefaultDir + // writeInTypedDir replaces a file the CLI named in a directory from an + // output flag (--bom-output, bom --output). The directory is used as + // given, a symbolic link included. + writeInTypedDir +) + +// filePathMode is the write mode of an --sbom-output or --vex-output value: +// a typed file path is written in place, and unset is the default .armis. +func filePathMode(output string) writeMode { + if output == "" { + return writeDefaultDir + } + return writeInPlace +} + // downloadAndSave downloads from a URL and saves to a file. The output path // is checked before the download, so a bad path costs no request. -func (d *SBOMVEXDownloader) downloadAndSave(ctx context.Context, url, outputPath, docType string, defaultDir bool) error { - if _, err := prepareOutputPath(outputPath, docType, defaultDir); err != nil { +func (d *SBOMVEXDownloader) downloadAndSave(ctx context.Context, url, outputPath, docType string, mode writeMode) error { + if _, err := prepareOutputPath(outputPath, docType, mode); err != nil { return err } data, err := d.fetchArtifact(ctx, url, docType) if err != nil { return err } - return d.saveArtifact(outputPath, docType, IndentJSON(data), defaultDir) + return d.saveArtifact(outputPath, docType, IndentJSON(data), mode) } // fetchArtifact checks a presigned link and downloads it, within the client's @@ -367,19 +481,23 @@ func (d *SBOMVEXDownloader) fetchArtifact(ctx context.Context, url, docType stri } // saveArtifact writes content to outputPath, creating its directory with -// mode 0750. A path from an output flag is the user's own and is written in -// place with mode 0600, as before, so /dev/stdout, a FIFO or a device still -// work. A path the CLI picked itself under .armis (defaultDir) goes through -// replaceInDefaultDir. -func (d *SBOMVEXDownloader) saveArtifact(outputPath, docType string, content []byte, defaultDir bool) error { - outputPath, err := prepareOutputPath(outputPath, docType, defaultDir) +// mode 0750. A file path from an output flag is the user's own and is +// written in place with mode 0600 (writeInPlace), as before, so /dev/stdout, +// a FIFO or a device still work. A file the CLI named goes through +// replaceInDefaultDir under .armis (writeDefaultDir), or replaceInTypedDir in +// a directory from an output flag (writeInTypedDir). +func (d *SBOMVEXDownloader) saveArtifact(outputPath, docType string, content []byte, mode writeMode) error { + outputPath, err := prepareOutputPath(outputPath, docType, mode) if err != nil { return err } - if defaultDir { + switch mode { + case writeDefaultDir: err = replaceInDefaultDir(outputPath, content) - } else { + case writeInTypedDir: + err = replaceInTypedDir(outputPath, content) + default: // Write with secure permissions (owner read/write only) err = os.WriteFile(outputPath, content, 0600) } @@ -395,11 +513,11 @@ func (d *SBOMVEXDownloader) saveArtifact(outputPath, docType string, content []b } // prepareOutputPath sanitizes an output path and creates its parent -// directory. For a path the CLI picked itself (defaultDir), the directory is +// directory. For a path the CLI picked itself (writeDefaultDir), the directory is // .armis, which a scanned repository can commit as a symbolic link or another // non-directory, so it is checked before MkdirAll could follow it. A path from // an output flag is trusted, as before. -func prepareOutputPath(outputPath, docType string, defaultDir bool) (string, error) { +func prepareOutputPath(outputPath, docType string, mode writeMode) (string, error) { // armis:ignore cwe:22 reason:SanitizePath IS the path traversal prevention; outputPath from user flag then sanitized sanitizedPath, err := util.SanitizePath(outputPath) if err != nil { @@ -407,7 +525,7 @@ func prepareOutputPath(outputPath, docType string, defaultDir bool) (string, err } dir := filepath.Dir(sanitizedPath) - if defaultDir { + if mode == writeDefaultDir { if err := checkDefaultDir(dir, docType); err != nil { return "", err } @@ -464,12 +582,10 @@ var beforeDefaultDirOpen func(dir string) // replaceInDefaultDir writes data to path, in the directory the CLI picked // itself. The directory must be a plain directory, and the one os.OpenRoot -// then opens, so a swap between the check and the open is refused. Inside it, -// an existing target must be a regular file. data goes to a new 0600 temp file -// that is renamed over the target, so the target is replaced, never written -// through, and ends with mode 0600. +// then opens, so a swap between the check and the open is refused. The file +// is then written by replaceInRoot. func replaceInDefaultDir(path string, data []byte) error { - dir, name := filepath.Dir(path), filepath.Base(path) + dir := filepath.Dir(path) checked, err := plainDir(dir) if err != nil { return err @@ -489,7 +605,28 @@ func replaceInDefaultDir(path string, data []byte) error { if !os.SameFile(checked, opened) { return fmt.Errorf("%s changed while it was opened", dir) } + return replaceInRoot(root, path, data) +} + +// replaceInTypedDir writes data to path, a file name the CLI picked in a +// directory from an output flag. The directory is the user's own and is +// opened as given, through a symbolic link too; the file in it is written by +// replaceInRoot, since a scanned repository can commit a link at that name. +func replaceInTypedDir(path string, data []byte) error { + root, err := os.OpenRoot(filepath.Dir(path)) + if err != nil { + return err + } + defer root.Close() //nolint:errcheck // directory handle only + return replaceInRoot(root, path, data) +} +// replaceInRoot writes data to the file of path in root. An existing target +// must be a regular file. data goes to a new 0600 temp file that is renamed +// over the target, so the target is replaced, never written through, and +// ends with mode 0600. +func replaceInRoot(root *os.Root, path string, data []byte) error { + name := filepath.Base(path) if info, err := root.Lstat(name); err == nil && !info.Mode().IsRegular() { return fmt.Errorf("%s is not a regular file", path) } else if err != nil && !errors.Is(err, fs.ErrNotExist) { diff --git a/internal/scan/sbom_vex_test.go b/internal/scan/sbom_vex_test.go index 181670e..6fa7d09 100644 --- a/internal/scan/sbom_vex_test.go +++ b/internal/scan/sbom_vex_test.go @@ -20,6 +20,7 @@ import ( "github.com/ArmisSecurity/armis-cli/internal/api" "github.com/ArmisSecurity/armis-cli/internal/httpclient" + "github.com/ArmisSecurity/armis-cli/internal/model" "github.com/ArmisSecurity/armis-cli/internal/testutil" ) @@ -578,10 +579,10 @@ func TestIndentJSON(t *testing.T) { func TestSaveArtifactOutputPaths(t *testing.T) { const doc = `{"bomFormat":"CycloneDX"}` d := &SBOMVEXDownloader{} - save := func(t *testing.T, path string, defaultDir bool) error { + save := func(t *testing.T, path string, mode writeMode) error { t.Helper() var err error - _ = testutil.CaptureStderr(t, func() { err = d.saveArtifact(path, "SBOM", IndentJSON([]byte(doc)), defaultDir) }) + _ = testutil.CaptureStderr(t, func() { err = d.saveArtifact(path, "SBOM", IndentJSON([]byte(doc)), mode) }) return err } defaultPath := filepath.Join(".armis", "repo-sbom.json") @@ -592,7 +593,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { if err := os.Symlink(outside, ".armis"); err != nil { t.Skipf("cannot create symlink: %v", err) } - err := save(t, defaultPath, true) + err := save(t, defaultPath, writeDefaultDir) if err == nil || !strings.Contains(err.Error(), ".armis is not a plain directory") { t.Fatalf("error = %v, want the symlinked .armis refused", err) } @@ -606,7 +607,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { if err := os.WriteFile(".armis", []byte("keep"), 0600); err != nil { t.Fatalf("write .armis: %v", err) } - err := save(t, defaultPath, true) + err := save(t, defaultPath, writeDefaultDir) if err == nil || !strings.Contains(err.Error(), ".armis is not a plain directory") { t.Fatalf("error = %v, want the non-directory .armis refused", err) } @@ -629,7 +630,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { } } t.Cleanup(func() { beforeDefaultDirOpen = nil }) - err := save(t, defaultPath, true) + err := save(t, defaultPath, writeDefaultDir) if err == nil || !strings.Contains(err.Error(), ".armis changed while it was opened") { t.Fatalf("error = %v, want the swapped .armis refused", err) } @@ -645,7 +646,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { if err := os.MkdirAll(defaultPath, 0750); err != nil { t.Fatalf("mkdir: %v", err) } - err := save(t, defaultPath, true) + err := save(t, defaultPath, writeDefaultDir) if err == nil || !strings.Contains(err.Error(), "repo-sbom.json is not a regular file") { t.Fatalf("error = %v, want the non-regular target refused", err) } @@ -663,7 +664,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { if err := os.Symlink(victim, defaultPath); err != nil { t.Skipf("cannot create symlink: %v", err) } - err := save(t, defaultPath, true) + err := save(t, defaultPath, writeDefaultDir) if err == nil || !strings.Contains(err.Error(), "repo-sbom.json is not a regular file") { t.Fatalf("error = %v, want the symlinked target refused", err) } @@ -678,7 +679,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { } t.Chdir(t.TempDir()) path := filepath.Join(".armis", strings.Repeat("n", 235)+".json") - if err := save(t, path, true); err != nil { + if err := save(t, path, writeDefaultDir); err != nil { t.Fatalf("saveArtifact with a 240-byte name failed: %v", err) } assertBOMFile(t, path, doc) @@ -698,7 +699,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { if err := os.Chmod(defaultPath, 0644); err != nil { //nolint:gosec // test sets a loose mode on purpose t.Fatalf("chmod: %v", err) } - if err := save(t, defaultPath, true); err != nil { + if err := save(t, defaultPath, writeDefaultDir); err != nil { t.Fatalf("saveArtifact failed: %v", err) } assertBOMFile(t, defaultPath, doc) @@ -710,13 +711,13 @@ func TestSaveArtifactOutputPaths(t *testing.T) { // On macOS t.TempDir is under /var, a link to /private/var, as /tmp is. t.Run("t.TempDir paths are used, from a flag and as the default", func(t *testing.T) { path := filepath.Join(t.TempDir(), "repo-sbom.json") - if err := save(t, path, false); err != nil { + if err := save(t, path, writeInPlace); err != nil { t.Fatalf("saveArtifact with a flag path failed: %v", err) } assertBOMFile(t, path, doc) t.Chdir(t.TempDir()) - if err := save(t, defaultPath, true); err != nil { + if err := save(t, defaultPath, writeDefaultDir); err != nil { t.Fatalf("saveArtifact with the default .armis failed: %v", err) } assertBOMFile(t, defaultPath, doc) @@ -726,7 +727,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { if runtime.GOOS == "windows" { t.Skip("no /dev/stdout on Windows") } - if err := save(t, "/dev/stdout", false); err != nil { + if err := save(t, "/dev/stdout", writeInPlace); err != nil { t.Fatalf("saveArtifact to /dev/stdout failed: %v", err) } }) @@ -734,7 +735,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { t.Run("a FIFO from a flag is written in place and stays a FIFO", func(t *testing.T) { fifo := filepath.Join(t.TempDir(), "sbom.fifo") r := openFIFO(t, fifo) - if err := save(t, fifo, false); err != nil { + if err := save(t, fifo, writeInPlace); err != nil { t.Fatalf("saveArtifact to a FIFO failed: %v", err) } got, err := io.ReadAll(r) @@ -755,10 +756,77 @@ func TestSaveArtifactOutputPaths(t *testing.T) { if err := os.Symlink(target, link); err != nil { t.Skipf("cannot create symlink: %v", err) } - if err := save(t, filepath.Join(link, "repo-sbom.json"), false); err != nil { + for _, mode := range []writeMode{writeInPlace, writeInTypedDir} { + if err := save(t, filepath.Join(link, "repo-sbom.json"), mode); err != nil { + t.Fatalf("saveArtifact (mode %d) failed: %v", mode, err) + } + assertBOMFile(t, filepath.Join(target, "repo-sbom.json"), doc) + } + }) + + t.Run("a symlinked target in a typed directory is refused and its target untouched", func(t *testing.T) { + dir := t.TempDir() + victim := filepath.Join(t.TempDir(), "victim") + if err := os.WriteFile(victim, []byte("keep"), 0600); err != nil { + t.Fatalf("write victim: %v", err) + } + path := filepath.Join(dir, "repo-bom-sbom.json") + if err := os.Symlink(victim, path); err != nil { + t.Skipf("cannot create symlink: %v", err) + } + err := save(t, path, writeInTypedDir) + if err == nil || !strings.Contains(err.Error(), "repo-bom-sbom.json is not a regular file") { + t.Fatalf("error = %v, want the symlinked target refused", err) + } + if got, _ := os.ReadFile(victim); string(got) != "keep" { //nolint:gosec // test path from t.TempDir() + t.Errorf("link target = %q, want it untouched", got) + } + if info, err := os.Lstat(path); err != nil || info.Mode()&fs.ModeSymlink == 0 { + t.Errorf("link is now %v (%v), want it left a link", info, err) + } + if entries, _ := os.ReadDir(dir); len(entries) != 1 { + t.Errorf("%s holds %v, want only the link", dir, entries) + } + }) + + t.Run("a directory as the target in a typed directory is refused", func(t *testing.T) { + path := filepath.Join(t.TempDir(), "repo-bom-sbom.json") + if err := os.Mkdir(path, 0750); err != nil { + t.Fatalf("mkdir: %v", err) + } + err := save(t, path, writeInTypedDir) + if err == nil || !strings.Contains(err.Error(), "is not a regular file") { + t.Fatalf("error = %v, want the non-regular target refused", err) + } + }) + + t.Run("a typed directory that does not exist is created", func(t *testing.T) { + path := filepath.Join(t.TempDir(), "new", "repo-bom-sbom.json") + if err := save(t, path, writeInTypedDir); err != nil { + t.Fatalf("saveArtifact failed: %v", err) + } + assertBOMFile(t, path, doc) + }) + + t.Run("an existing 0644 file in a typed directory is replaced with mode 0600", func(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("file modes are not POSIX on Windows") + } + dir := t.TempDir() + path := filepath.Join(dir, "repo-bom-sbom.json") + if err := os.WriteFile(path, []byte("old"), 0600); err != nil { + t.Fatalf("write old file: %v", err) + } + if err := os.Chmod(path, 0644); err != nil { //nolint:gosec // test sets a loose mode on purpose + t.Fatalf("chmod: %v", err) + } + if err := save(t, path, writeInTypedDir); err != nil { t.Fatalf("saveArtifact failed: %v", err) } - assertBOMFile(t, filepath.Join(target, "repo-sbom.json"), doc) + assertBOMFile(t, path, doc) + if entries, _ := os.ReadDir(dir); len(entries) != 1 { + t.Errorf("%s holds %v, want only the output file", dir, entries) + } }) t.Run("a symlinked target from a flag is written through, as before", func(t *testing.T) { @@ -767,7 +835,7 @@ func TestSaveArtifactOutputPaths(t *testing.T) { if err := os.Symlink(victim, link); err != nil { t.Skipf("cannot create symlink: %v", err) } - if err := save(t, link, false); err != nil { + if err := save(t, link, writeInPlace); err != nil { t.Fatalf("saveArtifact failed: %v", err) } assertBOMFile(t, victim, doc) @@ -949,6 +1017,50 @@ func TestSBOMVEXDownloader_DownloadBOMs(t *testing.T) { } }) + t.Run("a link committed at the file name in a typed directory is refused", func(t *testing.T) { + const sbomDoc = `{"bomFormat":"CycloneDX","components":[{"name":"a"}]}` + dir := t.TempDir() + victim := filepath.Join(t.TempDir(), "victim") + if err := os.WriteFile(victim, []byte("keep"), 0600); err != nil { + t.Fatalf("write victim: %v", err) + } + if err := os.Symlink(victim, filepath.Join(dir, "test-artifact-bom-sbom.json")); err != nil { + t.Skipf("cannot create symlink: %v", err) + } + srv := &bomServer{docs: map[string]string{"bom_sbom_results": sbomDoc, "cbom_results": cbomDoc}} + client := srv.start(t) + _, stderr, err := downloadBOMs(t, client, &SBOMVEXOptions{BOM: &BOMOptions{ + Types: []string{"sbom", "cbom"}, Format: "cyclonedx-1.7", Output: dir, + }}) + var bomErr *BOMDownloadError + if !errors.As(err, &bomErr) || !reflect.DeepEqual(bomErr.Types, []string{"sbom"}) { + t.Fatalf("error = %v, want the SBOM refused", err) + } + if !strings.Contains(stderr, "test-artifact-bom-sbom.json is not a regular file") { + t.Errorf("stderr = %q, want the refusal", stderr) + } + if got, _ := os.ReadFile(victim); string(got) != "keep" { //nolint:gosec // test path from t.TempDir() + t.Errorf("link target = %q, want it untouched", got) + } + assertBOMFile(t, filepath.Join(dir, "test-artifact-bom-cbom.json"), cbomDoc) + }) + + t.Run("a symlinked typed directory is written through", func(t *testing.T) { + target := t.TempDir() + link := filepath.Join(t.TempDir(), "boms") + if err := os.Symlink(target, link); err != nil { + t.Skipf("cannot create symlink: %v", err) + } + srv := &bomServer{docs: map[string]string{"cbom_results": cbomDoc}} + client := srv.start(t) + if _, _, err := downloadBOMs(t, client, &SBOMVEXOptions{BOM: &BOMOptions{ + Types: []string{"cbom"}, Format: "cyclonedx-1.7", Output: link, + }}); err != nil { + t.Fatalf("Download failed: %v", err) + } + assertBOMFile(t, filepath.Join(target, "test-artifact-bom-cbom.json"), cbomDoc) + }) + t.Run("cyclonedx-1.6 reads the _cdx16_ key", func(t *testing.T) { const cdx16 = `{"bomFormat":"CycloneDX","specVersion":"1.6","components":[{"name":"m"}]}` dir := t.TempDir() @@ -1340,7 +1452,7 @@ func TestSBOMVEXDownloader_DownloadBOMs(t *testing.T) { Types: []string{"aibom"}, Format: "cyclonedx-1.7", Output: t.TempDir(), }}) assertBOMFailed(t, err, []string{"aibom"}, "") - if !strings.Contains(stderr, "refetching expired link: fetch results failed with status 400: bad[2J]0;title31mrequest") { + if !strings.Contains(stderr, "refetching expired link: fetch results failed with status 400: bad[2J]0;title31m request") { t.Errorf("stderr = %q, want the server text without control characters", stderr) } if strings.ContainsAny(stderr, "\x1b\x07\u009b\r") { @@ -1481,3 +1593,186 @@ func TestSBOMVEXDownloader_DownloadBOMs(t *testing.T) { } }) } + +func TestSBOMVEXOptionsBOMOnly(t *testing.T) { + rows := []struct { + name string + opts *SBOMVEXOptions + wantOnly bool + wantScanType string + wantMessage string + }{ + {"no options", nil, false, "", "Scanning for security issues..."}, + {"--sbom only", &SBOMVEXOptions{GenerateSBOM: true}, false, "", "Scanning for security issues..."}, + {"scan --bom", &SBOMVEXOptions{BOM: &BOMOptions{Types: []string{"cbom"}}}, false, "", "Scanning for security issues..."}, + {"bom command", &SBOMVEXOptions{BOM: &BOMOptions{Types: []string{"all"}, Only: true}}, true, "bom", "Building BOMs..."}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + if got := row.opts.BOMOnly(); got != row.wantOnly { + t.Errorf("BOMOnly() = %v, want %v", got, row.wantOnly) + } + if got := row.opts.ScanType(); got != row.wantScanType { + t.Errorf("ScanType() = %q, want %q", got, row.wantScanType) + } + if got := row.opts.WaitMessage(); got != row.wantMessage { + t.Errorf("WaitMessage() = %q, want %q", got, row.wantMessage) + } + }) + } +} + +func TestBOMOnlyResult(t *testing.T) { + const cbomDoc = `{"bomFormat":"CycloneDX","components":[{"name":"AES"}]}` + skip := "a scanner was skipped" + controlSkip := "a scanner\x1b[2J was\u009b skipped\x07" + rows := []struct { + name string + srv *bomServer + types []string + wantFailures []string + wantSkip string + wantFile bool + }{ + {name: "built and written", srv: &bomServer{docs: map[string]string{"cbom_results": cbomDoc}}, types: []string{"cbom"}, wantFile: true}, + {name: "one written, one not offered", srv: &bomServer{docs: map[string]string{"cbom_results": cbomDoc}}, + types: []string{"aibom", "cbom"}, wantFile: true}, + {name: "not offered only warns", srv: &bomServer{docs: map[string]string{}}, types: []string{"aibom", "cbom"}}, + {name: "a failed download is a failure", srv: &bomServer{docs: map[string]string{"cbom_results": cbomDoc}, + downloadCode: func(string, int) int { return http.StatusNotFound }}, types: []string{"cbom"}, wantFailures: []string{"cbom"}}, + {name: "results not available fails every type", srv: &bomServer{resultsCode: http.StatusNotFound}, + types: []string{"sbom", "all"}, wantFailures: []string{"sbom", "all"}}, + {name: "the skip reason is kept", srv: &bomServer{docs: map[string]string{"cbom_results": cbomDoc}, skipReason: &skip}, + types: []string{"cbom"}, wantSkip: skip, wantFile: true}, + {name: "the skip reason loses control characters", srv: &bomServer{docs: map[string]string{"cbom_results": cbomDoc}, skipReason: &controlSkip}, + types: []string{"cbom"}, wantSkip: "a scanner[2J was skipped", wantFile: true}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + dir := t.TempDir() + client := row.srv.start(t) + opts := &SBOMVEXOptions{BOM: &BOMOptions{Types: row.types, Format: BOMFormatCycloneDX17, Output: dir, Only: true}} + var result *model.ScanResult + var err error + _ = testutil.CaptureStderr(t, func() { + result, err = BOMOnlyResult(context.Background(), client, "tenant-123", "scan-456", "app", opts) + }) + if err != nil { + t.Fatalf("BOMOnlyResult: %v", err) + } + if result.ScanID != "scan-456" || len(result.Findings) != 0 || result.Summary.Total != 0 { + t.Errorf("result = %+v, want scan-456 with no findings", result) + } + if !reflect.DeepEqual(result.BOMFailures, row.wantFailures) { + t.Errorf("BOMFailures = %v, want %v", result.BOMFailures, row.wantFailures) + } + if result.Summary.ScannerSkipReason != row.wantSkip { + t.Errorf("skip reason = %q, want %q", result.Summary.ScannerSkipReason, row.wantSkip) + } + if _, statErr := os.Stat(filepath.Join(dir, "app-bom-cbom.json")); (statErr == nil) != row.wantFile { + t.Errorf("app-bom-cbom.json exists = %v, want %v", statErr == nil, row.wantFile) + } + var wantWritten []string + if row.wantFile { + wantWritten = []string{"cbom"} + } + if !reflect.DeepEqual(result.BOMWritten, wantWritten) { + t.Errorf("BOMWritten = %v, want %v", result.BOMWritten, wantWritten) + } + }) + } + + t.Run("Ctrl+C during a download returns the context error", func(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + srv := &bomServer{docs: map[string]string{"cbom_results": cbomDoc}, + downloadCode: func(string, int) int { cancel(); return http.StatusNotFound }} + client := srv.start(t) + opts := &SBOMVEXOptions{BOM: &BOMOptions{Types: []string{"cbom"}, Format: BOMFormatCycloneDX17, Output: t.TempDir(), Only: true}} + var result *model.ScanResult + var err error + _ = testutil.CaptureStderr(t, func() { + result, err = BOMOnlyResult(ctx, client, "tenant-123", "scan-456", "app", opts) + }) + if result != nil || !errors.Is(err, context.Canceled) { + t.Fatalf("BOMOnlyResult = %v, %v; want a cancelled result", result, err) + } + }) +} + +// TestDownloadBOMsWarnsOnFailedTools: a BOM written while BOM tools failed on +// the server gets one warning after the BOM lines, naming the tools (control +// characters stripped, deduplicated, sorted) and the written types; the +// download still succeeds. +func TestDownloadBOMsWarnsOnFailedTools(t *testing.T) { + const cbomDoc = `{"bomFormat":"CycloneDX","components":[{"name":"AES"}]}` + const emptyAIBOM = `{"bomFormat":"CycloneDX","components":[]}` + const prefix = "BOM tools failed on the server: " + status := func(types map[string]string, tools ...string) *api.BOMSummary { + s := &api.BOMSummary{Types: map[string]api.BOMTypeStatus{}, FailedTools: tools} + for t, st := range types { + s.Types[t] = api.BOMTypeStatus{Status: st} + } + return s + } + rows := []struct { + name string + docs map[string]string + summary *api.BOMSummary + types []string + want string // the whole warning line; "" for none + wantAlso string + }{ + {name: "generated with a failed tool", docs: map[string]string{"cbom_results": cbomDoc}, + summary: status(map[string]string{"cbom": api.BOMStatusGenerated}, "opengrep_bom"), types: []string{"cbom"}, + want: prefix + "opengrep_bom; CBOM may be incomplete"}, + {name: "empty with failed tools, deduplicated and sorted", docs: map[string]string{"aibom_results": emptyAIBOM}, + summary: status(map[string]string{"aibom": api.BOMStatusEmpty}, "zz_tool", "a_tool\x1b[2J", "zz_tool", " "), types: []string{"aibom"}, + want: prefix + "a_tool[2J, zz_tool; AI-BOM may be incomplete", wantAlso: "No AI components found"}, + {name: "a failed type only: its own warning, no extra line", + summary: status(map[string]string{"cbom": api.BOMStatusFailed}, "opengrep_bom"), types: []string{"cbom"}, + wantAlso: "CBOM failed on the server (tools that failed in this scan: opengrep_bom)"}, + {name: "a failed type beside a written one names the written one", docs: map[string]string{"cbom_results": cbomDoc}, + summary: status(map[string]string{"aibom": api.BOMStatusFailed, "cbom": api.BOMStatusGenerated}, "opengrep_bom"), + types: []string{"aibom", "cbom"}, want: prefix + "opengrep_bom; CBOM may be incomplete"}, + {name: "no failed tools", docs: map[string]string{"cbom_results": cbomDoc}, + summary: status(map[string]string{"cbom": api.BOMStatusGenerated}), types: []string{"cbom"}}, + {name: "no summary", docs: map[string]string{"cbom_results": cbomDoc}, types: []string{"cbom"}}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + srv := &bomServer{docs: row.docs, summary: row.summary} + if srv.docs == nil { + srv.docs = map[string]string{} + } + client := srv.start(t) + _, stderr, err := downloadBOMs(t, client, &SBOMVEXOptions{BOM: &BOMOptions{ + Types: row.types, Format: BOMFormatCycloneDX17, Output: t.TempDir(), Target: ".", + }}) + if err != nil { + t.Fatalf("Download = %v, want no failure", err) + } + wantCount := 0 + if row.want != "" { + wantCount = 1 + } + if n := strings.Count(stderr, prefix); n != wantCount { + t.Errorf("stderr has %d failed-tools warnings, want %d:\n%s", n, wantCount, stderr) + } + if row.want != "" { + if !strings.Contains(stderr, "Warning: "+row.want+"\n") { + t.Errorf("stderr = %q, want the line %q", stderr, row.want) + } + if saved := strings.LastIndex(stderr, "saved to:"); saved > strings.Index(stderr, prefix) { + t.Errorf("the warning comes before a BOM line:\n%s", stderr) + } + } + if row.wantAlso != "" && !strings.Contains(stderr, row.wantAlso) { + t.Errorf("stderr = %q, want %q", stderr, row.wantAlso) + } + if strings.ContainsAny(stderr, "\x1b") { + t.Errorf("stderr holds a control character: %q", stderr) + } + }) + } +} diff --git a/internal/scan/status.go b/internal/scan/status.go index 8353936..d91358e 100644 --- a/internal/scan/status.go +++ b/internal/scan/status.go @@ -7,6 +7,7 @@ import ( "time" "github.com/ArmisSecurity/armis-cli/internal/model" + "github.com/ArmisSecurity/armis-cli/internal/util" ) // FormatScanStatus returns a human-readable message for the current scan phase. @@ -26,7 +27,9 @@ func FormatScanStatus(scanStatus, inProgressMsg string) string { case "STOPPED": return "Scan was stopped" default: - return fmt.Sprintf("Scanning... [%s]", strings.ToUpper(scanStatus)) + // The status is server text; drop control characters such as + // terminal escapes before the spinner prints it. + return fmt.Sprintf("Scanning... [%s]", strings.ToUpper(util.StripControl(scanStatus))) } } diff --git a/internal/scan/status_test.go b/internal/scan/status_test.go index fb827cd..d023347 100644 --- a/internal/scan/status_test.go +++ b/internal/scan/status_test.go @@ -23,6 +23,7 @@ func TestFormatScanStatus(t *testing.T) { {"stopped", "STOPPED", "Scanning...", "Scan was stopped"}, {"unknown", "UNKNOWN", "Scanning...", "Scanning... [UNKNOWN]"}, {"empty", "", "Scanning...", "Scanning... []"}, + {"control characters from the server", "queued\x1b[2J\x07\u009b", "Scanning...", "Scanning... [QUEUED[2J]"}, } for _, tt := range tests { diff --git a/internal/testutil/mockapi.go b/internal/testutil/mockapi.go index 03641e3..6383539 100644 --- a/internal/testutil/mockapi.go +++ b/internal/testutil/mockapi.go @@ -2,6 +2,7 @@ package testutil import ( + "io" "net/http" "strings" "sync/atomic" @@ -47,6 +48,16 @@ type MockAPIConfig struct { // OnBOMDownload, when set, runs before a /_bom/ download is answered, // such as to cancel the scan's context mid-download. OnBOMDownload func(r *http.Request) + // OnRequest, when set, runs first for every request, such as to count + // the calls to one endpoint. + OnRequest func(r *http.Request) + // OnScanRequest, when set, receives the body of each POST + // /api/v1/ingest/scan. + OnScanRequest func(body []byte) + // ScanStatus, when non-zero, answers POST /api/v1/ingest/scan with this + // status and ScanBody instead of starting the scan. + ScanStatus int + ScanBody string } // NewMockScanServer creates a mock Armis API server for integration testing. @@ -97,6 +108,10 @@ func createMockHandler(t *testing.T, config MockAPIConfig) http.HandlerFunc { var pollCount int32 return func(w http.ResponseWriter, r *http.Request) { + if config.OnRequest != nil { + config.OnRequest(r) + } + // POST /api/v1/ingest/presigned-url — reserves scan_id, returns a // presigned POST that points back at this same server's /_s3/... path. // `host` is set when the handler runs since httptest's URL is @@ -136,6 +151,19 @@ func createMockHandler(t *testing.T, config MockAPIConfig) http.HandlerFunc { // POST /api/v1/ingest/scan — confirms upload and triggers scan. if strings.Contains(r.URL.Path, "/api/v1/ingest/scan") && r.Method == http.MethodPost { AssertHasAuthorization(t, r) + if config.OnScanRequest != nil { + body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20)) + if err != nil { + t.Errorf("read /scan body: %v", err) + } + config.OnScanRequest(body) + } + if config.ScanStatus != 0 { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(config.ScanStatus) + _, _ = w.Write([]byte(config.ScanBody)) + return + } JSONResponse(t, w, http.StatusOK, model.IngestUploadResponse{ ScanID: config.ScanID, ScanStatus: "INITIATED", diff --git a/internal/util/control.go b/internal/util/control.go index 85dc623..e02bc8c 100644 --- a/internal/util/control.go +++ b/internal/util/control.go @@ -6,12 +6,38 @@ import ( ) // StripControl removes C0 and C1 control characters, such as terminal -// escapes, from text a server sent before it reaches the terminal. +// escapes, from text a server sent before it reaches the terminal. Line +// breaks and tabs separate words, so a run of whitespace that holds a \n, \r +// or \t becomes one space between words and is dropped at either end. Other +// text, spaces and non-ASCII letters included, is kept as sent. func StripControl(s string) string { - return strings.Map(func(r rune) rune { - if unicode.IsControl(r) { - return -1 + var b strings.Builder + b.Grow(len(s)) + var run strings.Builder // spaces seen since the last word, not yet written + breaks := false // the run holds a \n, \r or \t + for _, r := range s { + switch { + case r == '\n' || r == '\r' || r == '\t': + breaks = true + case r == ' ': + run.WriteRune(r) + case unicode.IsControl(r): + // Dropped; it does not end a run of whitespace. + default: + if breaks { + if b.Len() > 0 { + b.WriteByte(' ') + } + } else { + b.WriteString(run.String()) + } + run.Reset() + breaks = false + b.WriteRune(r) } - return r - }, s) + } + if !breaks { + b.WriteString(run.String()) + } + return b.String() } diff --git a/internal/util/control_test.go b/internal/util/control_test.go index 1d27387..299468f 100644 --- a/internal/util/control_test.go +++ b/internal/util/control_test.go @@ -8,16 +8,27 @@ import ( func TestStripControl(t *testing.T) { tests := []struct { - in, want string + name, in, want string }{ - {"plain text", "plain text"}, - {"bad\x1b[2J\x1b]0;title\x07\u009b31m\r\nrequest", "bad[2J]0;title31mrequest"}, - {"tab\tand\x00nul\x7fdel", "tabandnuldel"}, - {"ünïcode ✓", "ünïcode ✓"}, + {"plain text", "plain text", "plain text"}, + {"terminal escapes", "bad\x1b[2J\x1b]0;title\x07\u009b31m\r\nrequest", "bad[2J]0;title31m request"}, + {"NUL and DEL inside a word", "tab\tand\x00nul\x7fdel", "tab andnuldel"}, + {"a multi-line body", "upload failed\nbucket refused the policy\r\n\r\n\tretry later\n", + "upload failed bucket refused the policy retry later"}, + {"spaces around a line break collapse", "first line \n second", "first line second"}, + {"a break mixed with dropped controls", "a\r\x00\n\x1bb", "a b"}, + {"leading and trailing breaks are dropped", "\n\t error \r\n", "error"}, + {"spaces without a break are kept", " two spaces ", " two spaces "}, + {"Latin, Cyrillic and CJK", "ünïcode ✓ Ошибка сервера 服务器错误", "ünïcode ✓ Ошибка сервера 服务器错误"}, + {"emoji, with a ZWJ sequence and a variation selector", "done 🎉 👩‍💻 ❤️", "done 🎉 👩‍💻 ❤️"}, + {"empty", "", ""}, + {"only controls", "\r\n\x1b\t", ""}, } for _, tt := range tests { - if got := util.StripControl(tt.in); got != tt.want { - t.Errorf("StripControl(%q) = %q, want %q", tt.in, got, tt.want) - } + t.Run(tt.name, func(t *testing.T) { + if got := util.StripControl(tt.in); got != tt.want { + t.Errorf("StripControl(%q) = %q, want %q", tt.in, got, tt.want) + } + }) } }