Observer CLI reference

Observer CLI generates Software Bill of Materials (SBOMs) from source code, container images, Kubernetes clusters, and build processes. It auto-detects most programming languages and produces standardized CycloneDX SBOMs. You can analyze SBOMs for vulnerabilities and policy violations, then integrate with CI/CD pipelines to break builds on findings.

You can also bring your own SBOMs from any tool as long as they're in CycloneDX or SPDX format. All SBOMs upload to SBOM Observer for analysis, compliance tracking, and supply chain visibility.

Free & Open SourceApache 2.0 License

View on GitHub

Report issues, suggest improvements, or contribute to the project on GitHub.

Core Capabilities

SBOM Generation & SCA

Generate SBOMs from source code (Software Composition Analysis), containers, Kubernetes clusters and build processes.

SBOM Analysis

Analyze for vulnerabilities and policy violations.

SBOM Upload & Monitoring

Upload to SBOM Observer for continuous monitoring, compliance tracking, and centralized visibility.

CI/CD Integration

Break builds on policy violations. Works with common platforms like Azure DevOps, GitHub Actions, GitLab CI, Jenkins and more.

How It Works

Observer intelligently analyzes your software assets and produces accurate, standardized SBOMs by:

Auto-detecting ecosystems — Identifies package managers and dependencies across most popular programming languages
Delegating to specialized tools — Uses best-of-breed scanners for each target type
Normalizing output — Converts all results to CycloneDX format for consistency
Supporting build-time analysis — Watches C/C++ builds to capture compiler dependencies and system libraries
Handling complexity — Manages monorepos, mixed-language projects, and multi-stage builds

Think of it as a universal SBOM generator that chooses the right scanner for each situation and delivers results in a standard format.

Installation

Get Observer CLI

Download the latest release for Linux, macOS, or Windows.

Command Overview

SBOM Generation & Capture

Command	Description
`observer fs [path]`	Scan filesystem directories (source code, binaries, monorepos)
`observer image [image]`	Scan container images (Docker, OCI)
`observer build [-- command]`	Observe build processes and capture dependencies (C/C++, mixed-language)
`observer k8s`	Create Kubernetes cluster snapshots and optional workload SBOMs Experimental

Analysis, Verification & Lifecycle

Command	Description
`observer analyze [sbom]`	Analyze SBOMs for vulnerabilities and policy violations
`observer upload [sbom...]`	Upload SBOMs to SBOM Observer with optional retention policies
`observer verify <sbom>`	Validate CycloneDX structure and optionally compare artifacts

Global Flags

--debug — Enable debug logging (implies silent mode)
--silent — Silent mode (no progress bars)
-v, --version — Display version information
-h, --help — Show help information

Command-specific flags are called out in each section below. Use the --help flag if you need the full CLI reference.

Getting Help

observer [command] --help

Examples:

observer fs --help
observer image --help
observer build --help

Authentication

The analyze command can be used without authentication, but providing an API token unlocks more advanced analysis capabilities and enables policy enforcement based on your defined rules.
The upload command, however, always requires authentication.

export OBSERVER_TOKEN=your-api-token

For details on generating and managing tokens, see Access Tokens.

Metadata configuration

Configure SBOM metadata fields by adding an observer.yaml file in the repository root:

component:
  type: application
  name: my-application
  group: my-group
  version: 1.0.0
  description: Description of component
  license: MIT
supplier:
  name: Supplier Name
  url: https://example.com
  contacts:
    - name: John Doe
      email: john.doe@example.com
      phone: "123"

Many SBOM generators focus on dependencies and vulnerabilities but leave critical context fields either empty or inconsistent (for example, supplier name, component owner, or contact details). The observer.yaml metadata configuration lets you enrich and normalize this information so that every SBOM includes:

Clear supplier and component identity (who is the supplier of this software?)
Contact details for remediation and security coordination
Consistent naming and versioning across monorepos and multiple pipelines

Well-populated metadata makes it much easier to map SBOMs to internal systems, satisfy regulatory requirements (such as NTIA minimum elements), and apply policies in SBOM Observer based on supplier or application.

For monorepos, place observer.yaml in the root of each component subdirectory.

# Monorepo layout with per-component metadata
my-monorepo/
├─ apps/
│  ├─ web/
│  │  ├─ observer.yaml   # metadata for the web app
│  │  ├─ package.json
│  │  └─ src/
│  └─ api/
│     ├─ observer.yaml   # metadata for the API
│     ├─ go.mod
│     └─ cmd/
└─ libs/
   ├─ shared-ui/
   │  ├─ observer.yaml   # metadata for shared UI library
   │  ├─ package.json
   │  └─ src/
   └─ core/
      ├─ observer.yaml   # metadata for core library
      ├─ pyproject.toml
      └─ src/

Filesystem Scanning

Command: observer fs [path]

Scans source code directories to generate SBOMs by analyzing package managers and dependencies. Automatically detects ecosystems and scans component subdirectories.

Key Flags

-o, --output <path> — Write merged SBOM to a file or write multiple SBOMs into a directory
-m, --merge — Keep a single merged SBOM (true by default); set --merge=false to emit one SBOM per component
-r, --recursive / --depth <n> — Control how deep the scanner walks monorepo trees (default depth 1)
-v, --vendor <path> — Include vendor directories (can be repeated)
-a, --artifacts <path> — Attach build artifacts that represent the scanned software
-u, --upload — Send generated SBOMs directly to SBOM Observer

Observer runs Google’s osv-scalibr engine for each detected ecosystem to produce high-fidelity CycloneDX output. Keep the Trivy binary available even for filesystem scans—per Scanner Delegation, the CLI can fall back when Scalibr lacks coverage (for example, unknown binaries or certain npm edge cases).

Supported Ecosystems (SBOM generation via CLI)

Ecosystem	Package managers / targets
Go	modules, binaries
JavaScript	npm, yarn, pnpm
Python	pip, pyproject.toml, poetry, uv
Java	Maven, Gradle
.NET	NuGet
Ruby	Gem
PHP	Composer
Rust	Cargo
C/C++	Conan
Elixir	mix, hex
Dart	pub
Swift	swift build
Crystal	shards

This list reflects what observer fs can scan for SBOM generation. For the full set of ecosystems SBOM Observer analyzes for vulnerabilities, see Supported Ecosystems.

Examples

Scan an npm project:

cd ~/src/webapp
observer fs -o my-app.cdx.json .

Scan a Go binary with source code:

cd ~/src/my-go-app
observer fs -o my-app.cdx.json ./dist/my-app-binary

Scanning both source and compiled binaries produces more accurate SBOMs.

Monorepo Support

The fs command automatically scans each component in a monorepo and creates a separate SBOM per subdirectory. When multiple ecosystems exist in the same folder (e.g., go.mod + package-lock.json), SBOMs are automatically merged.

Container Image Scanning

Command: observer image [image]

Generates SBOMs from container images, analyzing OS packages and application dependencies.

Key Flags

-o, --output <file> — Write SBOM to a specific file (defaults to a temp file streamed to stdout)
-u, --upload — Upload the generated SBOM to SBOM Observer
--scanner trivy|syft — Choose the generator backend (trivy default, syft alternative)

Trivy is the default container scanner because it covers both OS packages and application dependencies. Set --scanner syft when you prefer Syft’s output or already have Syft in your pipeline; the CLI delegates to whichever backend you choose, as detailed in Scanner Delegation.

Examples

Scan a Docker image:

observer image -o my-app.cdx.json hello-world:latest

Scan from remote registry:

observer image --scanner syft -o app.cdx.json docker.io/library/nginx:latest

SBOM Analysis & Monitoring

Analyze Command

Command: observer analyze [sbom]

Sends SBOM to SBOM Observer service for vulnerability analysis and policy checking. The command exits non-zero only if the request fails or when --fail detects at least one violation configured with action: fail-build in your policies.

For details on how to set up policy enforcement to fail builds in CI/CD using the analyze command, see Enforce policies in CI/CD.

Key Flags

--summary, -s — Show only the summary table (hide detailed vulnerability/policy tables)
--fail — Exit with code 1 when policy violations configured to fail builds are present

observer analyze my-app.cdx.json

Example Output

The analyze command produces a detailed report with three sections: vulnerabilities, policy violations, and a summary.

Terminal Output

./observer analyze example-nextjs.cdx.json
Analyzed example-nextjs.cdx.json

 -- Vulnerabilities --
┌─────────────────┬─────────┬─────────────────────┬──────────┬──────────┬────────┬──────────────────┬─────────────────────────────────────────────────────────────────┐
│      Name       │ Version │     Identifier      │ Analysis │ Severity │  EPSS  │ Patched Versions │                              Title                              │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ @babel/runtime  │ 7.21.5  │ CVE-2025-27789      │          │ MEDIUM   │ 0.07%  │                  │ Babel has inefficient RegExp complexity in generated code       │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ brace-expansion │ 1.1.11  │ CVE-2025-5889       │          │ LOW      │ 0.03%  │                  │ brace-expansion: juliangruber brace-expansion index.js expand   │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ braces          │ 3.0.2   │ CVE-2024-4068       │          │ HIGH     │ 0.22%  │                  │ braces: fails to limit the number of characters it can handle   │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ cookie          │ 0.5.0   │ CVE-2024-47764      │          │ LOW      │ 0.07%  │                  │ cookie: cookie accepts cookie name with out of bounds chars     │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ cross-spawn     │ 7.0.3   │ CVE-2024-21538      │          │ HIGH     │ 0.13%  │                  │ cross-spawn: regular expression denial of service               │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ jose            │ 4.14.4  │ CVE-2024-28176      │          │ MEDIUM   │ 0.18%  │                  │ jose: resource exhaustion                                       │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ micromatch      │ 4.0.5   │ CVE-2024-4067       │          │ MEDIUM   │ 0.13%  │                  │ micromatch: vulnerable to Regular Expression Denial of Service  │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ nanoid          │ 3.3.6   │ CVE-2024-55565      │          │ MEDIUM   │ 0.04%  │                  │ nanoid: nanoid mishandles non-integer values                    │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ next            │ 13.5.3  │ CVE-2024-51479      │          │ HIGH     │ 78.00% │                  │ next.js: authorization bypass in Next.js                        │
│                 │         ├─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│                 │         │ CVE-2025-55173      │          │ MEDIUM   │ 0.12%  │                  │ nextjs: Content Injection Vulnerability for Image Optimization  │
│                 │         ├─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│                 │         │ CVE-2025-48068      │          │ MEDIUM   │ 0.01%  │                  │ next.js: Information exposure in dev server                     │
│                 │         ├─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│                 │         │ CVE-2024-34351      │          │ HIGH     │ 92.32% │                  │ Next.js Server-Side Request Forgery in Server Actions           │
│                 │         ├─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│                 │         │ CVE-2025-29927      │          │ CRITICAL │ 92.08% │                  │ nextjs: Authorization Bypass in Next.js Middleware              │
│                 │         ├─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│                 │         │ CVE-2024-47831      │          │ HIGH     │ 0.12%  │                  │ next.js: image optimization has Denial of Service condition     │
│                 │         ├─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│                 │         │ CVE-2024-46982      │          │ HIGH     │ 53.23% │                  │ Next.js Cache Poisoning                                         │
│                 │         ├─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│                 │         │ CVE-2024-56332      │          │ MEDIUM   │ 0.56%  │                  │ next.js: Vulnerable to Denial of Service (DoS)                  │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ next-auth       │ 4.23.1  │ CVE-2023-48309      │          │ MEDIUM   │ 0.22%  │                  │ Possible user mocking that bypasses basic authentication        │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ postcss         │ 8.4.14  │ CVE-2023-44270      │          │ MEDIUM   │ 0.15%  │                  │ PostCSS: Improper input validation in PostCSS                   │
├─────────────────┼─────────┼─────────────────────┼──────────┼──────────┼────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ zod             │ 3.21.4  │ CVE-2023-4316       │          │ HIGH     │ 0.14%  │                  │ Zod denial of service vulnerability                             │
└─────────────────┴─────────┴─────────────────────┴──────────┴──────────┴────────┴──────────────────┴─────────────────────────────────────────────────────────────────┘

 -- Policy Violations --
┌──────────┬──────────────────┬────────────────────────────────┬──────────────────────────────────────────────────────────────┬──────────┐
│   Name   │     Version      │             Policy             │                           Message                            │ Severity │
├──────────┼──────────────────┼────────────────────────────────┼──────────────────────────────────────────────────────────────┼──────────┤
│ frontend │ 85448d7aa1f38ad3 │ NTIA Minimum Elements for SBOM │ (CycloneDX) metadata.supplier is missing (NTIA Supplier Name)│ MEDIUM   │
│          │                  │                                ├──────────────────────────────────────────────────────────────┤          │
│          │                  │                                │ (CycloneDX) component 'package-lock.json' is missing version │          │
│          │                  │                                ├──────────────────────────────────────────────────────────────┤          │
│          │                  │                                │ (CycloneDX) component 'package-lock.json' is missing purl    │          │
└──────────┴──────────────────┴────────────────────────────────┴──────────────────────────────────────────────────────────────┴──────────┘

 -- Summary --
┌───────────────────┬──────────┬──────┬────────┬─────┬───────┐
│                   │ CRITICAL │ HIGH │ MEDIUM │ LOW │ Total │
├───────────────────┼──────────┼──────┼────────┼─────┼───────┤
│ Vulnerabilities   │ 1        │ 8    │ 12     │ 3   │ 24    │
├───────────────────┼──────────┼──────┼────────┼─────┼───────┤
│ Policy Violations │ 0        │ 0    │ 3      │ 0   │ 3     │
└───────────────────┴──────────┴──────┴────────┴─────┴───────┘

Verify Command

Command: observer verify <sbom>

Validates that a CycloneDX SBOM is well-formed and (optionally) that generated artifacts match the hashes recorded in the SBOM.

Key Flags

--artifacts <dir> — Directory of build artifacts that should be represented in the SBOM; every file is hashed and compared to CycloneDX entries

# Validate structure only
./observer verify sbom.cdx.json

# Validate against produced artifacts
./observer verify sbom.cdx.json --artifacts ./artifacts

The command exits with a non-zero status when the SBOM fails validation, an artifact is missing, or any hash mismatch is detected.

Upload Command

Command: observer upload [sbom...]

Uploads SBOMs to SBOM Observer for centralized tracking, compliance archiving, and continuous vulnerability monitoring.

Key Flags

-p, --retention-policy <name> — Apply a named retention policy server-side
-n, --retention-keep <count> — Keep only the latest N SBOM versions for the component (defaults to 1)
-d, --retention-keep-dependencies <true|false> — Keep SBOMs that introduce dependency changes even when pruning older versions

See Retention Policies for a detailed explanation of how these limits are enforced server-side.

export OBSERVER_TOKEN=your-api-token
observer upload my-app.cdx.json

CI/CD Integration

To integrate the Observer CLI into your CI/CD pipeline and fail builds on policy violations, use the analyze --fail command. This enables automated enforcement of your security policies before code reaches production.

For step-by-step setup instructions and platform-specific examples, see Enforce policies in CI/CD.

SBOM Formats & Tool Integration

Observer generates SBOMs in CycloneDX format (JSON or XML) by default. It also accepts and analyzes existing SBOMs in both CycloneDX and SPDX formats.

See the Supported Formats & Standards page for version details.

For build-time SBOM workflows (C/C++ and mixed-language projects), see the dedicated how-to: Build-time SBOMs.

Integration with Other SCA Tools

Observer seamlessly works with SBOMs from popular tools like Trivy, Syft, cdxgen, and others. You can:

Accept SBOMs from any CycloneDX or SPDX compliant tool
Upload to SBOM Observer for analysis
Compare and diff SBOMs from different generators

Scanner Delegation

When scanning filesystems, containers, or build processes, Observer acts as a meta-scanner for software composition analysis (SCA), picking the best backend for each target:

osv-scalibr — Primary engine for filesystem and build-time scans; understands package managers across ecosystems
Trivy — Default container scanner and fallback for filesystem/build targets that Scalibr cannot fully resolve (requires the Trivy binary)
Syft — Optional container/Kubernetes scanner; enabled by passing --scanner syft

This layered approach keeps language-aware accuracy while still supporting edge cases and user preferences.

View on GitHub

SBOM Generation & SCA

SBOM Analysis

SBOM Upload & Monitoring

CI/CD Integration

Get Observer CLI

On this page