firmis ci - CI Pipeline Command

Every PR that touches agent configuration is a potential security regression. firmis ci blocks threats before they reach production - one command, four stages, zero setup beyond a YAML file.

Synopsis

firmis ci [path] [options]

If [path] is omitted, Firmis runs the pipeline in the current directory.

Description

firmis ci runs four sequential stages: auto-detect platforms, generate an Agent Bill of Materials (CycloneDX), scan all 324 detection rules against every discovered component, and write a structured report. It always prints a one-line machine-parseable summary to stdout regardless of --quiet.

When a .firmis-policy.yml file exists in the project (or is provided via --policy), policy evaluation runs as a fifth stage and the exit code is determined by policy pass/fail rather than --fail-on. Without a policy file, --fail-on controls the exit code. Without either, the command exits 0 regardless of findings.

For quick local checks, firmis scan is faster. Use ci when you want the full pipeline with BOM generation and structured output baked in.

When to use this

• PR gates: Block merges when high or critical findings are introduced
• Nightly audits: Run a full pipeline on schedule to catch newly discovered threats against existing code
• Release checks: Gate deployments - require a clean scan before any release that includes agent changes
• Audit artifacts: Generate a BOM and SARIF report as CI artifacts for compliance evidence

For quick local checks, firmis scan is faster. Use ci when you want the full pipeline with BOM generation and structured output baked in.

Pipeline stages

The ci command runs stages sequentially. Each stage feeds the next:

1. Scan      ->  Run all 324 detection rules against every discovered component
2. BOM       ->  Generate Agent Bill of Materials (CycloneDX)
3. Report    ->  Output findings in your chosen format
4. Policy    ->  Evaluate .firmis-policy.yml if present (optional)

If any stage fails, the pipeline stops and exits with code 2. If findings exceed your --fail-on threshold (or policy fails), it exits with code 1.

Options

Flag	Type	Default	Description
--platform <name>	string	auto-detect	Scope the pipeline to a specific platform - useful in monorepos where only one platform changed
--fail-on <level>	enum	-	Fail the build when findings at this severity or above exist. Use high for most teams.
--format <type>	enum	sarif	Report format: json for custom tooling, sarif for GitHub Security tab, html for human review
--output <file>	string	-	Save the scan report to a file. Required for uploading to GitHub Security tab.
--bom-output <file>	string	-	Save the Agent BOM to a separate file. Required for compliance artifact storage.
--policy <file>	string	auto-discover	Path to a policy YAML file. If not provided, Firmis looks for .firmis-policy.yml in the project root.
--quiet	boolean	false	Suppress terminal output. The exit code is your signal.
--verbose	boolean	false	Print detailed progress for every stage - helpful when debugging why the pipeline is failing

Examples

Basic CI scan with SARIF output

Terminal

npx firmis ci --fail-on high --format sarif --output results.sarif

Full pipeline: scan + BOM artifact

Terminal

npx firmis ci --fail-on critical --bom-output agent-bom.json --output scan.sarif

Quiet mode - exit code only

Terminal

npx firmis ci --fail-on high --quiet

Enforce a policy file

Terminal

npx firmis ci --policy .firmis-policy.yml --output scan.sarif

GitHub Actions example

Drop this into your repo. It runs on every push and pull request, uploads findings to the GitHub Security tab, and fails the check if any high or critical issues are found.

.github/workflows/firmis.yml

name: Firmis Security Scan
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    permissions:
      security-events: write   # required to upload SARIF
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run Firmis CI pipeline
        run: npx firmis ci --fail-on high --format sarif --output results.sarif

      - name: Upload SARIF to GitHub Security tab
        if: always()   # upload even if the scan found issues
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab CI example

.gitlab-ci.yml

firmis-scan:
  image: node:20
  script:
    - npx firmis ci --fail-on high --format sarif --output results.sarif
  artifacts:
    when: always
    paths:
      - results.sarif
    reports:
      sast: results.sarif

Default output files

The CI command always saves two files by default:

• firmis-bom.json - Agent Bill of Materials (CycloneDX)
• firmis-report.sarif - Scan report in SARIF format

Use --bom-output and --output to customize the file paths.

Exit codes

Code	Meaning
0	Pipeline completed. No findings above your --fail-on threshold, or neither --fail-on nor policy is set.
1	Findings found at or above your --fail-on threshold, or policy check failed. Fix them before merging.
2	Pipeline error - bad path, unreadable config, or unexpected failure in a stage.

See also

• GitHub Actions integration - detailed CI setup guide with branch protection rules
• SARIF output - understanding the SARIF format and how GitHub surfaces findings
• scan - standalone scan without the full pipeline
• Threat Categories - all 21 categories across 324 detection rules