Skip to content
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
84 changes: 80 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -585,20 +588,22 @@ 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 <types> --bom-format <format>): <message> (<code>)`.
- `--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 `<artifact>-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.
- A type the server did not build, or a BOM too large to store, prints a
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: <tools>; <types> 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

Expand Down Expand Up @@ -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/<artifact>-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 <target> [tenant flags] [upload flags] --bom <types> [--bom-format <format>] [--bom-output <dir>]`.
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 `<path>`, to fill in. A request the server
refuses exits 1 with
`the server refused the BOM request (--type <types> --format <format>): <message> (<code>)`.

### 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]
Expand Down Expand Up @@ -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
Expand Down
13 changes: 13 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: <tools>; <types> 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 <target> ... --bom <types> ...`, 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 `<path>`.
- `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
Expand All @@ -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
Expand Down
28 changes: 26 additions & 2 deletions docs/FEATURES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -379,11 +382,29 @@ armis-cli scan image nginx:latest --bom all --bom-format cyclonedx-1.6 --bom-out
`all` (combined).
- Files are named `<artifact>-bom-<type>.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/<artifact>-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:
Expand Down Expand Up @@ -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

---
Expand Down
8 changes: 8 additions & 0 deletions docs/ci-examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading