Reports · JSON · SARIF

Use the complete result for automation, not just the findings visible in the terminal preview.

Output formats

A preview and an export have different jobs

Scan output contracts
Format	Presentation	Complete-report handling
`auto`	Branded Ink in a wide interactive terminal; linear ANSI-free output in narrow, redirected, CI, dumb-terminal, or screen-reader use.	Always attempts a complete temporary JSON report, even with zero findings.
`ink`	Forced interactive-style preview with the configured finding limit.	Attempts a temporary report only when the preview overflows.
`text`	Complete human-readable export.	No finding cap or automatic sidecar. Redirect to save.
`json`	Complete versioned Zedbee machine output.	No finding cap or automatic sidecar. Redirect to save.
`sarif`	Complete SARIF 2.1.0 interchange output.	No finding cap or automatic sidecar. Redirect to save.

The default terminal limit is 25 findings, with blockers first. Counts, disclosures, incomplete checks, report warnings, guidance, and report paths are not abbreviated. reporting.terminalFindingLimit: "all" removes the finding preview limit.

Do not redirect default automatic output and assume it is a JSON document. Select --format json or --format sarif explicitly for a machine consumer.

Durable exports

Save the format your receiving system understands

All three explicit exports include the complete canonical result. Changing output format does not change policy, attribution, or the scan’s exit status.

For a clean CI checkout, add --base <ref> after preparing the comparison history. An ordinary scan compares the index and can correctly report zero changes when the checkout is clean.

Keep stdout and stderr separate for structured exports. Argument or startup failures may prevent a valid report from being produced; check the process status and parse the saved file before ingesting it. Redirecting stderr into JSON can corrupt the document.

Retain the scan status while saving a report

npx zedbee scan --format json --no-source > zedbee-report.json

Scan JSON fields

Read the envelope, then every check result

The current scan report uses schemaVersion: 1. Its fields are verified against the Zedbee 0.1.0 renderer. Timestamps and durations describe the run; deterministic ordering does not mean two runs are byte-identical.

Scan JSON field groups
Fields	How to use them
`schemaVersion, outcome, exitCode`	Check the contract version and gate decision. outcome is pass, blocked, or incomplete.
`repositoryRoot`	Serialized as a dot (.), not an absolute checkout path.
`mode, baseline, target, requestedBase`	Identify index or base mode and the compared Git state. requestedBase is optional. Unresolved commit identities can be null.
`changedFileCount, startedAt, durationMs`	Describe the run. changedFileCount can be null if change discovery failed.
`summary`	Counts for passed, warnings, failed, and incomplete. Read check details rather than treating one count as the full result.
`checks[]`	Check ID, optional workspace target, status, duration, findings, and optional error, skipReason, or incompleteDisposition.
`checks[].findings[]`	Stable ID, check, rule, severity, message, attribution, and optional location, remediation, sourceExcerpt, or automaticFix metadata.
`networkDisclosures[]`	The check, target, services, and metadata categories disclosed for online analysis.
`configuredPathExclusions, appliedPathExclusions`	Optional exclusion metadata; omitted when empty.

Check status is completed, skipped, or incomplete. An incomplete check can remain in a passing report when policy explicitly allows it. Inspect its error and incompleteDisposition, not only outcome.

Finding attribution includes kind, staged, and evidence. The compatibility field staged also appears in base-mode reports; use the report’s mode and source identities to understand the actual comparison. A finding ID is for tracking a result, not a patch to execute.

This schema is for scan. JSON from init, fix, checks, and doctor has a command-specific shape and should not be passed to a scan-report parser.

Understand why a finding belongs to the selected change

Enterprise interchange

Keep SARIF findings and execution diagnostics together

SARIF output has version: "2.1.0" and a Zedbee run with tool and rule metadata. It contains canonical findings in runs[].results, repository-relative locations, attribution properties, and stable IDs in partialFingerprints["zedbee/v1"].

Invocation properties retain the Zedbee outcome, exit code, comparison mode, source identities, timing, and network disclosures. Incomplete checks with diagnostics appear in toolExecutionNotifications; they are not ordinary vulnerability findings.

Do not use executionSuccessful as an all-checks-completed flag.

The current renderer sets it to false when the overall outcome is incomplete. A policy-allowed incomplete check can coexist with a passing outcome and a true executionSuccessful value. Read the notifications and their dispositions too.

SARIF output does not upload itself. Your CI provider or ingestion system controls upload permissions, artifact retention, and presentation. Preserve Swarm’s process status independently of whether the upload succeeds.

Source and retention

Temporary report paths are handoffs, not archives

Temporary reports become eligible for cleanup after the configured age, then are removed during a subsequent maintenance run. The operating system may remove them sooner. Use an explicit export for a durable file and configure CI retention separately.

Ordinary source is omitted from redirected exports and automatic report files by default. --include-source or policy always can permit it; --no-source suppresses it. Secret finding content remains redacted. Source-free reports still contain repository information and should be reviewed before sharing.

If report persistence fails, Swarm prints no false report path, restores every finding to terminal output, and shows REPORT UNAVAILABLE. Report-maintenance warnings do not replace the canonical scan decision. Snapshot cleanup failure is different and makes analysis incomplete.

Review report permissions and local data retention

{
  "schemaVersion": 1,
  "reporting": {
    "sourceExcerpts": "interactive",
    "terminalFindingLimit": 25,
    "temporaryReportMaxAge": "24h"
  }
}

Managed-fix output

A saved preview cannot be replayed as a patch

Managed fix JSON uses its own version-1 contract. It contains selected checks, counts, repository-relative paths, finding IDs, scopes, unstaged-change flags, approval state, and source-free issues. It omits source text, replacements, hashes, and private execution material.

fix --format json previews without writing project files. fix --yes --format json builds a fresh plan, applies approved operations, and includes the result. A plan file is not an input to a later apply command.

Use the managed-fix command safely

npx zedbee fix --format json > zedbee-fix-plan.json