Compatibility and versioning
What xgrep keeps stable across releases — the CLI, the output schemas, and the rule format — and what deliberately keeps evolving.
xgrep follows semantic versioning. Within a major version, the interfaces below are stable: you can build a pipeline, a dashboard, or a CI gate on them and trust that a minor or patch upgrade will not break it. A breaking change to any of them happens only in a new major version and is called out in the release notes.
The one thing that is not frozen is the set of findings itself — and that is deliberate. See What keeps evolving below.
Exit codes
The exit-code contract is stable within a major version: 0 when the run completed and
the policy passed, a distinct non-zero code when findings breach the configured gate,
and a separate non-zero code for an execution error. Scripts may branch on these.
Output formats
- JSON (
--json) carries aschema_versionfield. Additive changes (a new field) bump the minor schema version; a breaking change to an existing field's shape or meaning bumps the major schema version and is announced. Consumers should pin on the major and ignore unknown fields, so a minor bump never breaks a reader. A machine-readable JSON Schema is published for validation. - SARIF output targets SARIF 2.1.0.
- GitLab SAST output targets schema 15.0.6.
Fields are added, not repurposed. A field present in a 1.x release stays present with the same meaning for the rest of the 1.x line.
Rule format
xgrep reads Semgrep-compatible rule syntax, and that syntax is stable: rules you write against a 1.x release keep working across the 1.x line. xgrep-specific extensions are additive — they add capability without changing how an existing rule behaves. See Semgrep compatibility.
Command-line interface
The xgrep command and flag surface is stable within a major version. When a flag is
superseded it is deprecated, not removed: it keeps working as a no-op or an alias,
emits a deprecation notice, and is only dropped in a future major version. A script
that worked on 1.0 keeps working across the 1.x line. See the
CLI reference.
What keeps evolving
xgrep is a security scanner, and its job is to get more accurate over time. So the set of findings a scan reports is not part of the compatibility contract: rules are added and refined and the engine's analysis improves, which means a later 1.x release can legitimately report a finding an earlier one missed, or stop reporting one that was noise. That is the product working as intended, not a breaking change — freezing it would freeze the accuracy improvements that are the point of the tool. Finding content evolves; the formats and interfaces that carry it stay stable as described above.
Human-readable message text is likewise not an interface — do not parse it. Use the JSON/SARIF fields.
Last updated on
First scan
Find a real vulnerability with one command — no rules to write, no configuration.
Overview
Run xgrep's SAST (static application security testing) engine against your code — taint and dataflow analysis that traces untrusted input to dangerous sinks, plus output formats, supported languages, Semgrep parity, and custom rules.