Berichte lesen

Jeder check-*-Lauf erzeugt genau einen Bericht im gewählten Format. Text, JSON und SARIF beruhen auf demselben Ergebnis: gleicher Exit-Code, gleiche Funde, gleiche Fingerprints. Alle Beispiele auf dieser Seite stammen aus echten Läufen von codeguard 0.3.5.

Die drei Fragen zuerst

Bevor du Funde liest, beantworte drei Fragen:

Wie ist der Lauf ausgegangen? Erste Zeile bzw. status und exit_code.
Ist das Ergebnis vollständig? complete oder partial. Bei partial wurde nicht alles geprüft, der Lauf ist kein Freibrief, auch wenn keine Funde dastehen.
Was lief wirklich? Completed bzw. validation.completed. Steht compile oder tests nur unter Requested und nicht unter Completed, wurde nicht gebaut bzw. nicht getestet.

Textbericht

Beispiel: Lauf auf einer iOS-App mit iPad-Unterstützung, ein Test schlägt fehl (gekürzt):

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.

Kopf

Zeile	Bedeutung
`CODEGUARD_PASSED`	Exit 0, keine blockierenden Funde
`CODEGUARD_FAILED`	Exit 1 (oder 7): blockierende Funde
`CODEGUARD_BLOCKED`	Exit 6: Policy hat blockiert (Trust, Pfad, geschützte Datei)
`CODEGUARD_ERROR`	Exit 2, 3, 4, 5 oder 9: Lauf konnte nicht vollständig prüfen
`CODEGUARD_CANCELLED`	Exit 8: abgebrochen
`N blocking violations found in M changed files.`	Anzahl blockierender, nicht gewaivter Funde und Anzahl der betrachteten Dateien. Bei `check-project` und `check-file` sind das alle geprüften Dateien.
`Validation: <stufe> (<vollständigkeit>)`	`complete` oder `partial` ist entscheidend (siehe oben).
`Exit: <code> (<grund>)`	Exit-Code und Abbruchgrund, z. B. `completed`, `no_changes`, `validation_failed`, `security_policy`, `scope_violation`, `protected_file`, `dependency_unavailable`, `tool_failure`, `timeout`, `cancelled`
`Requested:`	Schritte, die dieser Lauf ausführen sollte
`Completed:`	Schritte, die vollständig gelaufen sind
`Skipped:`	angeforderte, aber nicht (vollständig) gelaufene Schritte
`Konfiguration:`	nur mit Projektkonfiguration: `.codeguard.yml (auto, sha256 …)`, `externe Datei (explicit, …)` oder `Standardwerte (--no-project-config)`
`Plattformen:`	nur bei Nicht-macOS-Plattformen: gebaute und übersprungene Plattformen mit Schritt und Grund
`Simulatortests:`	nur bei Simulatorzielen: getestete Ziele mit Gerät und Runtime, übersprungene mit Grund
`Tool:`	je Werkzeuglauf: Werkzeug, Version, `[Lauf-ID]`, Status, Dauer, ob die Ausgabe abgeschnitten wurde
`Run:`	ID des Laufs

Mögliche Schritte in Requested/Completed/Skipped: security, platform, format, swiftlint, swiftlint_metrics, compile, tests.

Gründe für übersprungene Plattformen und Testziele:

Grund	Bedeutung
`platformUnavailable`	SDK lokal nicht installiert
`notConfigured`	erkannt, aber nicht in `project.platforms`
`buildFailed`	Tests übersprungen, weil ein Build fehlschlug
`matrixAborted`	Lauf vorher abgebrochen (Timeout, Abbruch, Werkzeugfehler)
`simulatorUnavailable`	keine passende Runtime oder kein Gerätetyp
`simulatorDisabled`	`checks.tests.simulator: false`
`simulatorDisabledByPolicy`	von der Organisation abgeschaltet

Funde

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

Teil	Bedeutung
`1.`	laufende Nummer. Sortiert: blockierende zuerst, dann nach Schwere, Datei, Zeile, Spalte, Regel.
`[iOS/iPhone, iOS/iPad]`	nur bei Nicht-macOS-Läufen: betroffene Plattformen bzw. Testziele
`ERROR`	Schwere: `CRITICAL`, `ERROR`, `WARNING`, `INFO`
`Tests/AppTests.swift:8:1`	Datei, Zeile, Spalte (Spalte in Unicode-Zeichen). Fehlt bei Funden ohne Ort.
`Rule:`	Regel-ID, siehe Prüfungen und Regeln
nächste Zeile	Meldung
letzte Zeile (optional)	Vorschlag zur Behebung

Bei Werkzeugfehlern kommen zwei Zeilen hinzu. Echtes Beispiel eines Xcode-Builds, dessen Ausgabe nicht erkannt wurde:

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 identifiziert die verworfene Ausgabe, ohne sie zu zeigen. Parser nennt Parserversion und Grund.

Der Textbericht zeigt höchstens 20 Funde. Weitere stehen als N additional diagnostics omitted. am Ende. Ob ein Fund gewaivt ist, zeigt nur JSON bzw. SARIF.

Nächster Schritt

`Next action:`	Bedeutung
`Fix the reported violations and run …`	Funde beheben, erneut prüfen
`Request human review for the reported findings.`	Policy-Block: ein Mensch muss entscheiden (Trust, geschützte Datei, Pfad)
`Inspect the failing tool invocation.`	Werkzeug- oder Umgebungsproblem
`Fix the compile errors …`, `Fix the failing tests …`	Build- bzw. Testfehler
`Do not retry until the reported condition changes.`	Wiederholen ohne Änderung bringt nichts

Bei Exit 0 fehlt die Zeile.

JSON-Bericht

Echter Bericht einer Prüfung mit check-file (Funde gekürzt):

{
  "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."
    }
  ]
}

Felder auf oberster Ebene

Feld	Bedeutung
`schema_version`	Version des Berichtsschemas, siehe unten
`status`	`passed`, `failed`, `blocked`, `error`, `cancelled`
`exit_code`	Exit-Code des Laufs (0–9)
`termination_reason`	Abbruchgrund wie in der Textzeile `Exit:`
`primary_failure`	der Fehler, der den Exit-Code bestimmt (fehlt bei Exit 0)
`secondary_failures`	weitere Fehler desselben Laufs, z. B. `["policy_blocked"]`
`completeness`	`complete` oder `partial`
`next_action`	z. B. `none`, `fix_reported_violations`, `request_human_review`, `inspect_tool_failure`
`changed_files`	betrachtete Dateien
`run`	`id`, `scope` (`file`, `diff`, `project`), `mode`, bei Builds `build_authorization` (`local_trust` oder `operator_attested`)
`project`	`root` ist immer `.`; `root_fingerprint` identifiziert die Projektwurzel, ohne den Pfad zu nennen
`configuration`	`configuration_hash`, `policy_hash` und ggf. `project_source` (`mode`, `path`, `sha256`)
`validation`	`requested`, `completed`, `skipped`, `level`
`summary`	`total`, `blocking`, `accepted_risk` (gewaivte Funde) und Anzahl je Schwere
`tool_runs`	je Werkzeuglauf `id`, `tool`, `version`, `status`, `exit_code`, `duration_ms`, `output_truncated`
`platforms`	nur bei Nicht-macOS: `detected`, `configured`, `built`, `skipped`, `tested`, `test_environment`
`redactions_applied`	`true`, wenn etwas geschwärzt wurde
`report_id`, `generated_at`, `duration_ms`	Kennung, Zeitpunkt (UTC) und Dauer

exit_code des Werkzeugs in tool_runs ist nicht der Exit-Code von CodeGuard. Im Beispiel endet swiftlint mit 2, weil es Fehler gefunden hat; das ist ein normaler, abgeschlossener Lauf.

Felder eines Funds (`violations[]`)

Feld	Bedeutung
`rule`	Regel-ID
`severity`	`info`, `warning`, `error`, `critical`
`blocking`	`true`, wenn der Fund den Lauf scheitern lässt (sofern nicht gewaivt)
`disposition`	`active` oder `accepted_risk` (durch einen Waiver akzeptiert)
`file`, `line`, `column`	Ort; fehlt bei Funden ohne Ort
`location_accuracy`	`exact`, wenn die Position auf den geprüften Bytes verifiziert wurde
`message`, `suggestion`	Meldung und Vorschlag
`phase`	z. B. `security`, `static-analysis`, `format`, `compile`, `test`, `preflight`
`source`	Herkunft: `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`	stabiler Schlüssel des Funds, wird für Waiver gebraucht
`id`	ID innerhalb des Berichts
`platforms`	betroffene Plattformen (nur bei Nicht-macOS-Läufen)
`test_targets`	betroffene Testziele, z. B. `["ios-phone", "ios-pad"]`
`autofix`	immer `false`

Ein Testfund aus dem iOS-Lauf oben:

{
  "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"]
}

Und der zugehörige 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" }
  ]
}

Schemaversionen

`schema_version`	Wann
`1.1`	Standard (reines macOS, keine Projektkonfiguration)
`1.2`	Bericht enthält Plattformangaben für Nicht-macOS-Plattformen
`1.3`	zusätzlich Simulator-Angaben (`tested`, `test_environment`, `test_targets`)
`1.4`	Bericht enthält `configuration.project_source`, also immer mit `.codeguard.yml`, `--config` oder `--no-project-config`

Alle Versionen gehören zum Major 1. Ein Auswerter sollte jede 1.x akzeptieren. Das Schema liefert codeguard schema --kind report.

Auswerten mit `jq`

# Ergebnis und Vollständigkeit
jq '{status, exit_code, completeness, primary_failure, secondary_failures}' codeguard.json

# Blockierende, aktive Funde als Liste
jq -r '.violations[] | select(.blocking and .disposition == "active")
       | "\(.severity) \(.rule) \(.file // "-"):\(.line // "-") \(.message)"' codeguard.json

# Fingerprint für einen Waiver finden
jq '.violations[] | {rule, file, fingerprint}' codeguard.json

SARIF-Bericht

--format sarif erzeugt SARIF 2.1.0 (Profil portable). Echter Bericht eines Swift Packages mit einem fehlgeschlagenen Test (gekürzt):

{
  "$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" } }
          ]
        }
      }
    }
  ]
}

So bilden sich die Angaben ab:

SARIF	Bedeutung
`invocations[0].executionSuccessful`	`true` nur bei Status `passed`
`runs[0].properties["codeguard.exit_code"]`	Exit-Code von CodeGuard
`runs[0].properties["codeguard.completeness"]`, `["codeguard.validation"]`	wie im JSON-Bericht
`results[].level`	`critical`/`error` → `error`, `warning` → `warning`, `info` → `note`
`results[].properties["codeguard.critical"]`	`true` bei Schwere `critical`
`results[].locations`	Datei relativ zu `%SRCROOT%`, Zeile und Spalte (Unicode-Zeichen); fehlt bei Funden ohne Ort
`results[].baselineState`	`new` bei `introduced`, `unchanged` bei `pre_existing`
`results[].suppressions`	gesetzt bei gewaivten Funden (`status: accepted`)
`results[].partialFingerprints["codeguard/v1"]`	Fingerprint des Funds
`results[].properties["codeguard.platforms"]`, `["codeguard.test_targets"]`	Plattformen und Testziele
`runs[0].properties["codeguard.platforms"]`, `["codeguard.test_environment"]`	Plattform- und Simulatorangaben des Laufs
`runs[0].properties["codeguard.configuration.*"]`	Projektkonfiguration (`mode`, `path`, `sha256`)

Für Plattform- und Inhaltsregeln enthält tool.driver.rules zusätzlich Kurzbeschreibung und Hilfetext, für Metrikregeln eine Beschreibung mit den wirksamen Schwellen.

Variante `gitlab-sarif`

--format gitlab-sarif erzeugt dasselbe Format im Profil gitlab-security, mit diesen Unterschieden:

Es enthält nur Funde mit Datei und Position, die sicherheitsbezogen sind (Phase security oder Regel-ID mit secret, dependency oder security).
Höchstens 5000 Ergebnisse, sonst scheitert die Ausgabe.
Meldungen über 1024 Zeichen werden gekürzt und mit codeguard.message_shortened: true markiert.

Die drei Fragen zuerst​

Textbericht​

Kopf​

Funde​

Nächster Schritt​

JSON-Bericht​

Felder auf oberster Ebene​

Felder eines Funds (violations[])​

Schemaversionen​

Auswerten mit jq​

SARIF-Bericht​

Variante gitlab-sarif​

Siehe auch​