Skip to content
Documentation
CI/CD Integration

CI/CD Integration

Integrate netbobr into your CI/CD pipeline to validate firewall rules automatically on every change. The CLI produces machine-readable output and exit codes that keep tool errors apart from policy failures.

npx --yes @netbobr/cli@2 analyze firewall-rules.csv --fail-on high

Pin the major version (@2) in pipelines, so a future major release cannot change your gate silently.

Exit Codes

Exit CodeMeaning
0Pass. The analysis completed, no flow has a finding at or above --fail-on, and no flow has a DENY verdict. Zero flows also pass, with a notice on stderr.
1Error. There is no trustworthy result. Causes: a bad flag, value or flag combination; missing, unreadable or unparseable input or config; input that does not match an explicit --cloud-format; an invalid config value; one or more invalid flows; a failure to write the report; a crash. npm/npx and Node.js errors are also 1.
2Policy failure. The analysis completed, and at least one flow has a finding at or above --fail-on or a DENY verdict (from a custom rule or a zone-matrix Deny policy).
2 is the only non-zero code you may tolerate. Any other code means netbobr did not finish, including signals (128 and above) and 1. A recipe that lets exit code 1 pass would also pass a missing file, a typo in a flag, or a crash.

When a run has both invalid flows and policy failures, it exits 1. Invalid flows can never hide behind a tolerated 2.

Gating with --fail-on

--fail-on <level> sets the gate. The default is medium. A flow fails the gate when one of its findings (framework, custom or built-in) is at or above the level, or when its verdict is DENY.

ValueExits 2 when a flow has...
criticala CRITICAL finding, or a DENY verdict
higha HIGH or CRITICAL finding, or a DENY verdict
medium (default)a MEDIUM, HIGH or CRITICAL finding, or a DENY verdict
lowa LOW or higher finding, or a DENY verdict
infoany finding, or a DENY verdict
nonenever: report only. Errors still exit 1.
  • Values are case-insensitive. An invalid value is an error (exit 1).
  • The overall risk level never gates. It is explained in each flow's verdictReason.
  • Every output format shows the same per-flow verdict (ALLOW, REVIEW or DENY) that drives the exit code.
Migrating from @netbobr/cli 1.x

1.x used graded exit codes: 1 MEDIUM, 2 HIGH, 3 CRITICAL, and every error was also 1. In 2.x:

1.x recipe2.x recipe
test $? -eq 3 (critical only)--fail-on critical, then test $? -eq 2
test $? -ge 2 (high or critical)--fail-on high; any non-zero code fails
GitLab allow_failure: exit_codes: [1]allow_failure: exit_codes: [2]
Jenkins rc == 1 → UNSTABLErc == 2 → UNSTABLE, any other non-zero code → FAILED
continue-on-error / || true to keep the SARIF file--output-file results.sarif (the file is written before the exit code is set)

Other changes:

  • Built-in findings (BUILTIN-*) now gate.
  • --fail-on low fails on LOW findings.
  • Unknown --frameworks names are errors.
  • Invalid flows exit 1.
  • The JSON output is always an object with results, invalidFlows, warnings and summary.

Output Formats for CI

FormatFlagUse Case
JSON--output jsonMachine parsing, custom integrations
SARIF--output sarifGitHub Code Scanning, GitLab SARIF reports, VS Code
CSV--output csvSpreadsheet import, data analysis
Table--output tableHuman-readable logs
PDF--output pdfCompliance reports, change tickets
  • Use --output-file <path> to write any format to a file instead of stdout. It removes the need for shell redirection and || true.
  • --quiet suppresses the stdout report and informational messages. Errors are always printed.
  • Parser warnings and invalid flows are included in every format.

Inputs and Configuration

  • Flows: CSV or JSON. The web app's CSV template works unchanged.
  • Cloud formats: pass --cloud-format aws-sg, azure-nsg, gcp-fw, tf-plan, tf-hcl (Terraform source files) or k8s-netpol, or --cloud-format auto to detect the format.
  • Configuration: --config netbobr-session.json applies a session saved in the web app (Session Control > Save): zones and zone policies, custom rules, zone attributes and disabled rules.
    • A session's old riskWeights block is ignored with a warning, as it is in the web app.
    • To override risk weights or thresholds in the CLI, add flat weights/thresholds keys (see Thresholds).
    • An invalid config is an error (exit 1).
  • Inline: --src, --dst, --proto, --port, plus --app-name "<purpose>". Without --app-name, the documentation rules report the flow as undocumented.

Platform Guides

GitHub Actions
Workflow examples with SARIF upload to Code Scanning and PDF artifact generation.
Azure DevOps
Pipeline YAML with severity gating and build artifact publishing.
GitLab CI
Blocking and report-only jobs, SARIF reports and exit code handling.
Jenkins
Declarative pipeline stages with Warnings NG SARIF import and custom exit code handling.