sciath-cli

Command-line interface for Sciath — CRA compliance automation for embedded Linux.

See CHANGELOG.md for release notes.

Install

Requires Python 3.11 or newer. Scanning and reports require a Sciath account and access to the Sciath API.

pip install sciath-cli

For development (from this repo):

pip install -e ".[dev]"

Maintainers: see the release guide for PyPI setup and publishing. This release provides a Python package; standalone executables are not included.

Quickstart

1. Log in

sciath login

Follow the device-code prompt in your browser. Your API key is saved to ~/.sciath/config.json.

2. Select a project

sciath project list
sciath project select "IoT Gateway v3"

3. Run a scan

# Auto-detect: finds sbom.json, .config, *.dts in current directory
sciath scan

# Or specify everything explicitly
sciath scan run firmware.cdx.json \
  --kconfig .config \
  --dtb device.dts \
  --version v3.2.0

# Auto-discover from a Yocto build directory (finds all artifacts automatically)
sciath scan run --auto-discover --build-dir /home/build/poky/build

# With build system hint
sciath scan run --auto-discover --build-dir /home/build/poky/build --build-system yocto

4. Review results

# Table summary with suppression waterfall (default)
sciath scan run firmware.cdx.json

# With filter reasoning (why each CVE was suppressed/flagged)
sciath scan run firmware.cdx.json --explain

# CRA readiness check
sciath scan run firmware.cdx.json --cra-check

# JSON for scripting / LLM agents
sciath scan run firmware.cdx.json --format json | jq '.summary'

5. CI pipeline gating

# Exit 1 if any critical CVE is open
sciath scan run firmware.cdx.json \
  --severity-threshold critical \
  --format quiet

# Exit 1 if any CISA KEV entry is open
sciath scan run firmware.cdx.json \
  --fail-on-kev \
  --format quiet

# Exit 1 if not CRA-shippable
sciath scan cra-check <scan-id>

6. Export reports

# Article 13 Technical File (PDF)
sciath report <scan-id> --format pdf --output report.pdf

# CycloneDX VEX (JSON)
sciath vex <scan-id> --format vex_cdx --output vex.json

# SARIF 2.1.0 (GitHub Code Scanning compatible)
sciath vex <scan-id> --format sarif --output findings.sarif.json

# CSAF VEX (JSON)
sciath vex <scan-id> --format vex_csaf --output csaf.json

Command Reference

Authentication

Projects

Scanning

Scan Options

Build Setup

Assessments

Policies

Reports & Export

Export Formats

MCP Server (Editor Integration)

sciath mcp

Starts an MCP server with stdio transport for integration with Claude Code, Cursor, Windsurf, and other MCP-aware editors.

Available tools:

• scan_sbom — Upload and analyse an SBOM
• get_scan_status — Check scan status
• list_findings — List CVE findings with filter reasoning
• get_compliance_status — CRA readiness summary

Claude Code configuration (~/.claude/settings.json):

{
  "mcpServers": {
    "sciath": {
      "command": "sciath",
      "args": ["mcp"]
    }
  }
}

Exit Codes

Auto-Detection

When you run sciath scan without specifying files, the CLI searches the current directory for:

SBOM files (first match used):

• sbom.json, bom.json, sbom.xml, bom.xml
• sbom.cdx.json, sbom.spdx.json
• build/tmp/deploy/*/sbom-*.json (Yocto builds)

Kconfig (auto-detected if present):

• .config, build/.config

Device Tree (auto-detected if present):

• *.dts, *.dtb in current directory

Build Directory Discovery (--auto-discover)

For Yocto and other build systems, --auto-discover walks the entire build tree and extracts all available artifacts automatically:

• SBOM from tmp/deploy/spdx/, tmp/deploy/cve/, or CycloneDX output
• Kernel .config from staging or work directories
• DTBs from tmp/deploy/images/ (capped at 20 by default)
• Busybox .config from busybox work directory
• PACKAGECONFIG flags per recipe (with CVE suppression mapping)
• BSP patches from vendor layers (static analysis, no BitBake required)

PACKAGECONFIG suppressions are serialized into custom filter rules and submitted alongside the scan. This enables the suppression waterfall to show exactly which CVEs are eliminated by build configuration.

CRA Compliance

Evidence Pack

Download everything an auditor needs in one command:

sciath report <scan-id> --format evidence-pack

The ZIP contains: SBOM, VEX document, Article 13 PDF, suppression rationale CSV, CRA readiness verdict, and scan metadata.

Readiness Check

sciath scan cra-check <scan-id>

Returns SHIPPABLE or NOT READY with article-mapped checklist, compliance percentage, and blockers. Exits 1 if not shippable (useful for CI gating).

Input Caching

The CLI caches scan results locally at ~/.sciath/cache/. If you run the same scan with identical inputs (same SBOM + kconfig + DTB content), the CLI returns the cached result without re-uploading.

• Cache TTL: 1 hour
• Force fresh: --no-cache
• Cache key: SHA-256 of project ID + file contents

Configuration

Credentials stored at ~/.sciath/config.json (mode 0600).

Environment variable overrides:

Network & Proxy Configuration

The CLI needs outbound HTTPS access to the Sciath API. If your environment uses a corporate proxy or firewall allowlisting, see below.

Firewall allowlist

Allow outbound HTTPS (port 443) to:

Note: Sciath is hosted behind a load balancer without static IPs. Use domain-based (FQDN) rules, not IP-based rules.

HTTP/HTTPS proxy

The CLI uses httpx which respects standard proxy environment variables:

export HTTPS_PROXY=http://proxy.corp.example:8080

# With authentication
export HTTPS_PROXY=http://user:password@proxy.corp.example:8080

Custom TLS certificates

If your proxy performs TLS inspection (MITM), you need to trust its CA certificate:

export SSL_CERT_FILE=/path/to/corporate-ca-bundle.crt

REQUESTS_CA_BUNDLE and CURL_CA_BUNDLE are also supported.

Private / on-prem API endpoint

If you run a self-hosted Sciath instance, point the CLI at it:

# Persistent (saved to ~/.sciath/config.json)
sciath config set api_url https://sciath.internal.example.com

# Or per-session via environment variable
export SCIATH_API_URL=https://sciath.internal.example.com

Sample SBOM

Save as sbom.json and run sciath scan:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.5",
  "version": 1,
  "metadata": {
    "component": {
      "type": "firmware",
      "name": "imx8m-gateway",
      "version": "v3.2.0"
    }
  },
  "components": [
    {
      "type": "library",
      "name": "linux-kernel",
      "version": "5.15.32",
      "cpe": "cpe:2.3:o:linux:linux_kernel:5.15.32:*:*:*:*:*:*:*"
    },
    {
      "type": "library",
      "name": "openssl",
      "version": "3.0.7",
      "cpe": "cpe:2.3:a:openssl:openssl:3.0.7:*:*:*:*:*:*:*"
    },
    {
      "type": "application",
      "name": "busybox",
      "version": "1.35.0",
      "cpe": "cpe:2.3:a:busybox:busybox:1.35.0:*:*:*:*:*:*:*"
    }
  ]
}