Reading reports

Every check-* run produces exactly one report in the chosen format. Text, JSON and SARIF are based on the same result: same exit code, same findings, same fingerprints. All examples on this page come from real runs of codeguard 0.3.5.

The three questions first

Before you read findings, answer three questions:

1. How did the run end? The first line, or status and exit_code.
2. Is the result complete? complete or partial. With partial, not everything was checked. The run is not a clean bill of health, even if no findings are listed.
3. What actually ran? Completed or validation.completed. If compile or tests appears only under Requested and not under Completed, nothing was built or tested.

Text report

Example: run on an iOS app with iPad support, one test fails (shortened):

CODEGUARD_FAILED

1 blocking violations found in 3 changed files.
Validation: project (complete)
Exit: 1 (validation_failed)
Requested: compile, format, platform, security, swiftlint, tests
Completed: compile, format, platform, security, swiftlint, tests
Skipped: 
Plattformen: gebaut iOS/iPadOS
Simulatortests: getestet iOS/iPhone iPhone 18 Pro (Runtime 27.0), iOS/iPad iPad Pro 13-inch (M5) (16GB) (Runtime 27.0)
Tool: xcodebuild 1171.7.0 [tool_simctl_bootstatus] completed, 21870ms, truncated: false
Tool: xcodebuild 27.0.0 [tool_xcodebuild_build_ios] completed, 13174ms, truncated: false
Tool: xcodebuild 27.0.0 [tool_xcodebuild_test_ios_phone] completed, 13341ms, truncated: false
Tool: xcodebuild 0.4.0 [tool_xcresult_test_ios_phone] completed, 270ms, truncated: false
Run: cg_703370af-9cf1-4109-8175-b687b0c701ce

1. [iOS/iPhone, iOS/iPad] ERROR Tests/AppTests.swift:8:1
   Rule: swift-test-failure
   Expectation failed: 1 == 2

Next action: Fix the reported violations and run `codeguard check-diff` again.

Header

Line	Meaning
CODEGUARD_PASSED	Exit 0, no blocking findings
CODEGUARD_FAILED	Exit 1 (or 7): blocking findings
CODEGUARD_BLOCKED	Exit 6: blocked by policy (trust, path, protected file)
CODEGUARD_ERROR	Exit 2, 3, 4, 5 or 9: the run could not check everything
CODEGUARD_CANCELLED	Exit 8: cancelled
N blocking violations found in M changed files.	Number of blocking, non-waived findings and number of files considered. For check-project and check-file, these are all checked files.
Validation: <level> (<completeness>)	complete or partial is what matters (see above).
Exit: <code> (<reason>)	Exit code and termination reason, e.g. completed, no_changes, validation_failed, security_policy, scope_violation, protected_file, dependency_unavailable, tool_failure, timeout, cancelled
Requested:	Steps this run was supposed to perform
Completed:	Steps that ran completely
Skipped:	Requested steps that did not run (completely)
Konfiguration:	Only with a project configuration: .codeguard.yml (auto, sha256 …), externe Datei (explicit, …) or Standardwerte (--no-project-config)
Plattformen:	Only for non-macOS platforms: built and skipped platforms with step and reason
Simulatortests:	Only for simulator targets: tested targets with device and runtime, skipped ones with reason
Tool:	Per tool run: tool, version, [run ID], status, duration, whether the output was truncated
Run:	ID of the run

Possible steps in Requested/Completed/Skipped: security, platform, format, swiftlint, swiftlint_metrics, compile, tests.

Reasons for skipped platforms and test targets:

Reason	Meaning
platformUnavailable	SDK not installed locally
notConfigured	Detected, but not in project.platforms
buildFailed	Tests skipped because a build failed
matrixAborted	Run aborted earlier (timeout, cancellation, tool failure)
simulatorUnavailable	No matching runtime or device type
simulatorDisabled	checks.tests.simulator: false
simulatorDisabledByPolicy	Disabled by the organization

Findings

1. [iOS/iPhone, iOS/iPad] ERROR Tests/AppTests.swift:8:1
   Rule: swift-test-failure
   Expectation failed: 1 == 2

Part	Meaning
1.	Sequential number. Sorted: blocking first, then by severity, file, line, column, rule.
[iOS/iPhone, iOS/iPad]	Only for non-macOS runs: affected platforms or test targets
ERROR	Severity: CRITICAL, ERROR, WARNING, INFO
Tests/AppTests.swift:8:1	File, line, column (column in Unicode characters). Missing for findings without a location.
Rule:	Rule ID, see Checks and rules
Next line	Message
Last line (optional)	Suggested fix

Tool failures add two lines. A real example of an Xcode build whose output was not recognized:

1. ERROR
   Rule: codeguard-tool-output-unparseable
   xcodebuild output could not be parsed reliably.
   Output fingerprint: sha256:925f8c6a0d1d0ae6cc3f8c0f96a17e53c456c67500e4e02c27ad779a277ace6a
   Parser: 1 (unrecognizedRecord), truncated: false

Output fingerprint identifies the discarded output without showing it. Parser gives the parser version and the reason.

The text report shows at most 20 findings. Any further ones appear as N additional diagnostics omitted. at the end. Only JSON and SARIF show whether a finding is waived.

Next step

Next action:	Meaning
Fix the reported violations and run …	Fix the findings, check again
Request human review for the reported findings.	Policy block: a human has to decide (trust, protected file, path)
Inspect the failing tool invocation.	Tool or environment problem
Fix the compile errors …, Fix the failing tests …	Build or test failures
Do not retry until the reported condition changes.	Retrying without a change is pointless

With exit 0, this line is missing.

JSON report

A real report of a check with check-file (findings shortened):

{
  "autofixes_applied": [],
  "changed_files": ["Sources/SwiftPMClean/Session.swift"],
  "completeness": "complete",
  "configuration": {
    "configuration_hash": "sha256:b6d2da11a83b32a5c08fd1941bc85affa4a50ed7ec50c93d975457ff05a23dad",
    "policy_hash": "sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80",
    "schema_version": 1
  },
  "duration_ms": 96,
  "exit_code": 1,
  "generated_at": "2026-10-02T06:50:45Z",
  "next_action": "fix_reported_violations",
  "primary_failure": "validation_failed",
  "project": {
    "identity": "project-5b0010d7f3d0a027414c3f3c",
    "root": ".",
    "root_fingerprint": "sha256:5b0010d7f3d0a027414c3f3cd2d9591054d0e134e1089978d34f1204b17bb6fd"
  },
  "redactions_applied": false,
  "report_id": "report_8bac14b9-c68c-44f5-a1be-be328bb6fe07",
  "run": { "id": "cg_ef3ce40b-25c8-40aa-8778-e3a25a54bcdf", "iteration": 0, "max_iterations": 2, "mode": "check", "scope": "file" },
  "schema_version": "1.1",
  "secondary_failures": [],
  "status": "failed",
  "summary": {
    "accepted_risk": 0,
    "blocking": 6,
    "by_severity": { "critical": 1, "error": 5, "info": 0, "warning": 0 },
    "total": 6
  },
  "termination_reason": "validation_failed",
  "tool_runs": [
    { "duration_ms": 9, "exit_code": 0, "id": "tool_swift_format", "output_truncated": false, "status": "completed", "tool": "swift-format", "version": "main" },
    { "duration_ms": 54, "exit_code": 2, "id": "tool_swiftlint", "output_truncated": false, "status": "completed", "tool": "swiftlint", "version": "0.65.1" }
  ],
  "validation": {
    "completed": ["format", "security", "swiftlint"],
    "level": "file",
    "requested": ["format", "security", "swiftlint"],
    "skipped": []
  },
  "violations": [
    {
      "autofix": false,
      "blocking": true,
      "certainty": "certain",
      "column": 9,
      "disposition": "active",
      "file": "Sources/SwiftPMClean/Session.swift",
      "fingerprint": "sha256:f660373d490db639484ec20a5905033d55fb2611dcf34ecaecd9bc5c8ae94b1a",
      "id": "diag_f660373d490db639484ec20a",
      "line": 8,
      "message": "Possible password is written to a log.",
      "phase": "security",
      "rule": "sensitive-data-in-log",
      "scope_relation": "touched",
      "severity": "critical",
      "source": "codeguard",
      "suggestion": "Do not log credentials or secrets; log a non-sensitive identifier or omit the value."
    }
  ]
}

Top-level fields

Field	Meaning
schema_version	Version of the report schema, see below
status	passed, failed, blocked, error, cancelled
exit_code	Exit code of the run (0–9)
termination_reason	Termination reason, as in the text line Exit:
primary_failure	The failure that determines the exit code (missing with exit 0)
secondary_failures	Further failures of the same run, e.g. ["policy_blocked"]
completeness	complete or partial
next_action	e.g. none, fix_reported_violations, request_human_review, inspect_tool_failure
changed_files	Files considered
run	id, scope (file, diff, project), mode, for builds build_authorization (local_trust or operator_attested)
project	root is always .; root_fingerprint identifies the project root without revealing the path
configuration	configuration_hash, policy_hash and, if present, project_source (mode, path, sha256)
validation	requested, completed, skipped, level
summary	total, blocking, accepted_risk (waived findings) and count per severity
tool_runs	Per tool run: id, tool, version, status, exit_code, duration_ms, output_truncated
platforms	Only for non-macOS: detected, configured, built, skipped, tested, test_environment
redactions_applied	true if something was redacted
report_id, generated_at, duration_ms	Identifier, timestamp (UTC) and duration

The tool's exit_code in tool_runs is not the CodeGuard exit code. In the example, swiftlint ends with 2 because it found errors; that is a normal, completed run.

Fields of a finding (violations[])

Field	Meaning
rule	Rule ID
severity	info, warning, error, critical
blocking	true if the finding makes the run fail (unless waived)
disposition	active or accepted_risk (accepted by a waiver)
file, line, column	Location; missing for findings without a location
location_accuracy	exact if the position was verified against the checked bytes
message, suggestion	Message and suggestion
phase	e.g. security, static-analysis, format, compile, test, preflight
source	Origin: codeguard, swift-format, swiftlint, swiftc, xcodebuild, swift-testing, xctest …
certainty	certain, probable, possible
scope_relation	introduced, touched, pre_existing, project_wide, operation, configuration, unknown
fingerprint	Stable key of the finding, needed for waivers
id	ID within the report
platforms	Affected platforms (only for non-macOS runs)
test_targets	Affected test targets, e.g. ["ios-phone", "ios-pad"]
autofix	Always false

A test finding from the iOS run above:

{
  "blocking": true,
  "column": 1,
  "file": "Tests/AppTests.swift",
  "line": 8,
  "message": "Expectation failed: 1 == 2",
  "phase": "test",
  "platforms": ["ios"],
  "rule": "swift-test-failure",
  "severity": "error",
  "source": "swift-testing",
  "test_targets": ["ios-phone", "ios-pad"]
}

And the matching platforms block:

"platforms": {
  "built": ["ios"],
  "detected": ["ios"],
  "skipped": [],
  "tested": ["ios-phone", "ios-pad"],
  "test_environment": [
    { "device_type_name": "iPhone 18 Pro", "runtime_build": "24A434", "runtime_version": "27.0", "target": "ios-phone" },
    { "device_type_name": "iPad Pro 13-inch (M5) (16GB)", "runtime_build": "24A434", "runtime_version": "27.0", "target": "ios-pad" }
  ]
}

Schema versions

schema_version	When
1.1	Default (macOS only, no project configuration)
1.2	Report contains platform data for non-macOS platforms
1.3	Additionally simulator data (tested, test_environment, test_targets)
1.4	Report contains configuration.project_source, so always with .codeguard.yml, --config or --no-project-config

All versions belong to major version 1. A consumer should accept any 1.x. codeguard schema --kind report returns the schema.

Evaluating with jq

# Result and completeness
jq '{status, exit_code, completeness, primary_failure, secondary_failures}' codeguard.json

# Blocking, active findings as a list
jq -r '.violations[] | select(.blocking and .disposition == "active")
       | "\(.severity) \(.rule) \(.file // "-"):\(.line // "-") \(.message)"' codeguard.json

# Find the fingerprint for a waiver
jq '.violations[] | {rule, file, fingerprint}' codeguard.json

SARIF report

--format sarif produces SARIF 2.1.0 (profile portable). A real report of a Swift package with a failed test (shortened):

{
  "$schema": "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "columnKind": "unicodeCodePoints",
      "invocations": [{ "endTimeUtc": "2026-10-02T07:01:19Z", "executionSuccessful": false }],
      "originalUriBaseIds": { "%SRCROOT%": { "uri": "./" } },
      "properties": {
        "codeguard.completeness": "complete",
        "codeguard.configuration.mode": "auto",
        "codeguard.configuration.path": ".codeguard.yml",
        "codeguard.configuration.sha256": "sha256:5967f32a8672b7d183a962125a566393f7ac40a1831106ace048b7cabde992b2",
        "codeguard.exit_code": 1,
        "codeguard.profile": "portable",
        "codeguard.redactions_applied": true,
        "codeguard.report_id": "report_acad0357-51f0-4703-b40f-428a9c16e073",
        "codeguard.root_fingerprint": "sha256:5b0010d7f3d0a027414c3f3cd2d9591054d0e134e1089978d34f1204b17bb6fd",
        "codeguard.tool_runs": [ "…" ],
        "codeguard.validation": {
          "completed": ["compile", "format", "security", "swiftlint", "swiftlint_metrics", "tests"],
          "requested": ["compile", "format", "security", "swiftlint", "swiftlint_metrics", "tests"],
          "skipped": []
        }
      },
      "results": [
        {
          "level": "error",
          "message": { "text": "[SwiftPMCleanTests.addReturnsSum()] Expectation failed: add(2, 3) == 6 (error)" },
          "partialFingerprints": { "codeguard/v1": "sha256:36e7b17c1bd0dfe5d2a2c36214c090f198576132b825240831e34de77f140cc9" },
          "properties": {
            "codeguard.autofix": false,
            "codeguard.certainty": "certain",
            "codeguard.disposition": "active",
            "codeguard.fingerprint": "sha256:36e7b17c1bd0dfe5d2a2c36214c090f198576132b825240831e34de77f140cc9",
            "codeguard.phase": "test",
            "codeguard.scope_relation": "touched"
          },
          "ruleId": "swift-test-failure"
        }
      ],
      "tool": {
        "driver": {
          "name": "CodeGuard",
          "semanticVersion": "0.3.5",
          "rules": [
            { "id": "swift-test-failure", "name": "swift-test-failure", "defaultConfiguration": { "level": "error" },
              "properties": { "codeguard.phase": "test" }, "shortDescription": { "text": "swift-test-failure" } }
          ]
        }
      }
    }
  ]
}

How the data maps:

SARIF	Meaning
invocations[0].executionSuccessful	true only with status passed
runs[0].properties["codeguard.exit_code"]	CodeGuard exit code
runs[0].properties["codeguard.completeness"], ["codeguard.validation"]	Same as in the JSON report
results[].level	critical/error → error, warning → warning, info → note
results[].properties["codeguard.critical"]	true for severity critical
results[].locations	File relative to %SRCROOT%, line and column (Unicode characters); missing for findings without a location
results[].baselineState	new for introduced, unchanged for pre_existing
results[].suppressions	Set for waived findings (status: accepted)
results[].partialFingerprints["codeguard/v1"]	Fingerprint of the finding
results[].properties["codeguard.platforms"], ["codeguard.test_targets"]	Platforms and test targets
runs[0].properties["codeguard.platforms"], ["codeguard.test_environment"]	Platform and simulator data of the run
runs[0].properties["codeguard.configuration.*"]	Project configuration (mode, path, sha256)

For platform and content rules, tool.driver.rules additionally contains a short description and help text; for metric rules, a description with the effective thresholds.

gitlab-sarif variant

--format gitlab-sarif produces the same format in the gitlab-security profile, with these differences:

• It contains only security-related findings with a file and position (phase security, or a rule ID containing secret, dependency or security).
• At most 5000 results, otherwise the output fails.
• Messages longer than 1024 characters are shortened and marked with codeguard.message_shortened: true.

See also

• Commands and parameters
• Checks and rules
• FAQ