Skip to content
Firmis

firmis policy - Policy Engine

Synopsis

Section titled “Synopsis”
Terminal window
firmis policy validate <file> [options]
firmis policy check [path] [options]

Description

Section titled “Description”

Every team has security standards. Most of them live in a document nobody reads. firmis policy puts them in code and enforces them in CI.

firmis policy validate checks a policy YAML file for schema correctness, valid condition values, and structural integrity. It does not run a scan. Use it in development to catch mistakes before a policy reaches CI.

firmis policy check runs a full scan and evaluates the results against a policy file. It exits non-zero if any policy rule is violated. This is the CI gate: write what your project must and must not have, wire policy check into your pipeline, and the standard is enforced automatically on every run.

Policy files define conditions such as zero tolerance for specific threat categories, a maximum count of high-severity findings, or a requirement that a particular platform be present and scanned. If no --policy flag is provided, Firmis looks for .firmis/policy.yaml in the project root.

Examples

Section titled “Examples”

Validate a policy file before using it in CI

Section titled “Validate a policy file before using it in CI”
Terminal
npx firmis policy validate firmis-policy.yaml

Run a policy check against the current directory

Section titled “Run a policy check against the current directory”
Terminal
npx firmis policy check . --policy firmis-policy.yaml

Policy check with JSON output for CI artifact storage

Section titled “Policy check with JSON output for CI artifact storage”
Terminal
npx firmis policy check . --policy firmis-policy.yaml --format json

Scope check to one platform with quiet output

Section titled “Scope check to one platform with quiet output”
Terminal
npx firmis policy check . --policy firmis-policy.yaml --platform mcp --quiet

Validate silently - exit code only

Section titled “Validate silently - exit code only”
Terminal
npx firmis policy validate firmis-policy.yaml --quiet

Options

Section titled “Options”

policy validate

Section titled “policy validate”
FlagTypeDefaultDescription
--quietbooleanfalseSuppress output. Only the exit code indicates pass or fail.

policy check

Section titled “policy check”
FlagTypeDefaultDescription
--policy <file>string.firmis/policy.yamlPath to the policy YAML file to enforce. If omitted, Firmis looks for .firmis/policy.yaml in the project root.
--platform <name>stringall platformsScope the underlying scan to a specific platform only.
--format <type>stringterminalOutput format. terminal for human-readable output. json for CI systems and artifact storage.
--quietbooleanfalseSuppress all terminal output. Only the exit code indicates pass or fail.
--verbosebooleanfalseShow detailed scan and evaluation output.

Policy File Format

Section titled “Policy File Format”
.firmis/policy.yaml
name: "Production Agent Policy"
version: "1.0"
description: "Security baseline for all agent deployments"


rules:
  - id: no-critical-findings
    description: "No critical severity findings allowed"
    condition:
      severity: critical
      count: 0


  - id: no-hardcoded-secrets
    description: "No hardcoded API keys or credentials"
    condition:
      category: secret-detection
      count: 0


  - id: bounded-high-findings
    description: "No more than 3 unresolved high severity findings"
    condition:
      severity: high
      max_count: 3

Exit Codes

Section titled “Exit Codes”
CodeMeaning
0All policy rules passed.
1One or more policy rules violated (policy check).
1Policy file is invalid (policy validate).
1No policy file found and none specified via --policy (policy check).
1Scan or evaluation failed with an error.

See Also

Section titled “See Also”
  • scan - the underlying scan that policy check runs
  • Custom Rules - write detection rules that your policies can reference
  • CI Pipeline - full discover, BOM, scan, and policy check pipeline