Kommandos und Parameter

Diese Seite beschreibt jedes Kommando und jeden Parameter von codeguard 0.3.5.

Aufbau eines Aufrufs

codeguard [globale Optionen] <kommando> [kommando-optionen]

Globale Optionen stehen vor dem Kommando. Beispiel:

codeguard --format json --output build/codeguard.json check-diff --base main

Globale Optionen

Option	Werte	Standard	Bedeutung
--format	text, json, sarif, gitlab-sarif	text	Ausgabeformat. Nicht jedes Kommando unterstützt jedes Format (siehe unten).
--config	Dateipfad	–	Projektkonfiguration explizit angeben. Schaltet die automatische Suche ab. Ein relativer Pfad bezieht sich auf das aktuelle Verzeichnis.
--no-project-config	Schalter	aus	.codeguard.yml/.codeguard.yaml im Projektwurzelverzeichnis ignorieren und die Standardwerte nutzen.
--project-root	Verzeichnis	aktuelles Verzeichnis	Projektwurzel. Wird per realpath kanonisiert. Ein nicht auflösbarer Pfad ist Exit 2.
--output	Dateipfad	–	Bericht eines check-*-Laufs atomar in diese Datei schreiben. stdout bleibt leer.
--ci	Schalter	aus	Nicht-interaktives CI-Profil. Lokale Trust-Tickets gelten nicht, Builds und Tests brauchen eine attestierte Umgebung, trust grant ist verboten.
--color	auto, always, never	auto	Farbpolitik. JSON und SARIF enthalten nie ANSI-Sequenzen.
-h, --help	–	–	Hilfe anzeigen, auch je Kommando (codeguard check-diff --help).

--config und --no-project-config zusammen sind Exit 2:

--config and --no-project-config cannot be used together

Welche Formate jedes Kommando kann

Kommando	text	json	sarif / gitlab-sarif	--output
check-file, check-diff, check-project	ja	ja	ja	ja
version, config validate, doctor, trust …	ja	ja	nein	nein, Ausgabe immer auf stdout
schema	gibt immer das JSON-Schema aus			nein

Ein nicht unterstütztes Format bricht ab, zum Beispiel:

Error: version supports only text or json output

Exit 64 bei Bedienfehlern

Fehler, die schon beim Einlesen der Argumente auffallen (unbekannte Option, nicht unterstütztes Format bei version, doctor, config validate oder trust), enden mit Exit 64. Dieser Wert gehört nicht zum Exit-Vertrag 0–9. Werte in Skripten jeden Code ungleich 0 als Fehler.

version

Gibt Binary- und Schemaversionen aus.

codeguard version
codeguard --format json version

codeguard 0.3.5 (configuration schema 1, report schema 1)

{"configurationSchemaMajor":1,"reportSchemaMajor":1,"version":"0.3.5"}

schema

Gibt ein eingebettetes JSON-Schema aus.

Option	Werte	Pflicht
--kind	configuration, report, sarif	ja

codeguard schema --kind configuration > configuration.schema.json
codeguard schema --kind report > report.schema.json
codeguard schema --kind sarif > sarif.schema.json

Mit dem Konfigurationsschema kann dein Editor .codeguard.yml prüfen und vervollständigen. Das Berichtsschema beschreibt die JSON-Berichte.

config validate

Lädt Organisationsrichtlinie und Projektkonfiguration, führt sie zusammen und validiert sie. Es wird nichts geprüft.

codeguard config validate
codeguard --config pfad/zu/codeguard.yml config validate
codeguard --format json config validate

Textausgabe:

configuration valid (schema 1, sha256:8325303d9119ac4ae183fc91b89ae6ebdecd34e52fc14c27d79da8ceeaf72fdb)
policy: /Library/Application Support/CodeGuard/policy.yml (sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80)
metrics: rules.metrics.severity = error (built-in, locked: false)
metrics: rules.metrics.line_length.warning = 120 (project, locked: false)
metrics: rules.metrics.line_length.error = 160 (project, locked: false)

• Zeile 1: Schemaversion und configuration_hash der wirksamen Konfiguration.
• policy: Herkunft der Organisationsrichtlinie: built-in (keine Datei) oder der Dateipfad, jeweils mit policy_hash.
• metrics: erscheint nur, wenn mindestens eine Metrikregel einen Schwellenwert hat. Jede Zeile nennt Wert, Herkunft (built-in, organization, project) und ob der Wert gesperrt ist.
• project.platforms = … erscheint nur, wenn project.platforms gesetzt ist.

JSON-Ausgabe (Schlüssel in camelCase, projectSource nur mit Projektkonfiguration):

{"configurationHash":"sha256:d6c09975a10d5760e687a744b97721503cfd86a89d3aadd331b08ccac078f41d","policyHash":"sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80","policySource":{"hash":"sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80","kind":"file","path":"/Library/Application Support/CodeGuard/policy.yml"},"projectSource":{"mode":"explicit","path":"waiver.yml","sha256":"sha256:60a5b5f47aa112f3521cbdcfb62882a915505396bc8c28052f7ff7bc08edb68d"},"redactionsApplied":true,"schemaVersion":1}

redactionsApplied: true heißt: In den Hash sind geschwärzte Felder eingeflossen (z. B. owner/reason von Waivern), die Werte selbst nicht.

Eine ungültige Konfiguration endet mit Exit 2 und nennt Quelle, Feld und Grund:

configuration validation failed: project:/checks/tests/required: required checks cannot be disabled by a lower-precedence source

doctor

Read-only-Diagnose: Welche Fähigkeiten und Werkzeuge stehen bereit? doctor führt kein Lint und keinen Build aus und braucht kein Trust-Ticket.

codeguard doctor
codeguard --format json doctor

Die vollständige Beispielausgabe und ihre Bedeutung stehen unter Erste Schritte. Ein gerenderter Befund endet mit Exit 0, eine ungültige Konfiguration mit Exit 2.

Wichtige Fähigkeiten:

Fähigkeit	Bedeutung
swift-format, swiftlint	Werkzeug gefunden und kompatibel; in Klammern die Version, falls ermittelbar
swiftlint-metrics	Nur sichtbar, wenn Metrikregeln konfiguriert sind
compile, tests	Build-Werkzeug für das Projekt im aktuellen Verzeichnis (inactive, wenn dort kein Paket und kein Xcode-Projekt liegt)
platform-checks	Plattform-Checks aktiv; in Klammern die Version des API-Katalogs
content-rules	Inhaltsregeln aktiv; in Klammern der Secret-Detektor-Katalog
unauthorized-network-destination	active nur bei nicht leerer Netzwerk-Allowlist
custom-rule:<id>	inactive für Custom Rules mit nicht unterstützter Engine
platform.<name>	SDK lokal verfügbar, in Klammern die SDK-Version
simctl, simulator.<name>	Simulator-Werkzeug, Runtimes und automatisch gewählter Gerätetyp
Verwaiste CodeGuard-Geräte	Simulatoren aus abgebrochenen Läufen. doctor meldet sie nur, es löscht nie.

trust status, trust grant, trust revoke

Zeigt oder ändert das lokale Projektvertrauen. Hintergrund unter Trust und Sicherheit.

codeguard trust status
codeguard trust grant --duration 24h
codeguard trust revoke

Kommando	Option	Werte	Standard
trust grant	--duration	positive Zahl plus m oder h, höchstens 24h (z. B. 30m, 8h)	24h

trust grant zeigt die Ausführungsoberflächen und fragt nach einer Bestätigung. Nur die Eingabe yes erteilt das Ticket. Es endet mit Exit 6, wenn

• --ci gesetzt ist (project trust cannot be granted in CI),
• stdin kein Terminal ist (project trust requires an interactive terminal),
• nicht yes eingegeben wird (project trust was not granted).

Ausgabe von trust status:

trust: not-trusted
surfaces: manifest:Package.swift

Mögliche Zustände: trusted, not-trusted, expired, invalid. Unter surfaces stehen die Dateien, an die das Ticket gebunden ist, mit ihrer Art (manifest, plugin, build-script, xcode-project, scheme).

check-file

Prüft eine oder mehrere Dateien.

codeguard check-file Sources/App/Login.swift Sources/App/Session.swift

• Pfade sind projektrelativ und kanonisch: kein absoluter Pfad, kein .., kein ./. Sonst Exit 2 (check-file paths must be canonical and project-relative).
• Ohne Pfad: Exit 2 (check-file requires at least one project-relative path).
• Ein Pfad außerhalb von paths.include oder in paths.exclude ergibt Exit 6 mit path-outside-allowed-scope.
• check-file führt nie compile oder tests aus, egal was konfiguriert ist. Es laufen nur security, platform, format, swiftlint und swiftlint_metrics. Deshalb braucht es kein Trust-Ticket.

check-diff

Prüft Git-Änderungen.

Option	Bedeutung
--base <rev>	Vergleicht den Stand <rev> mit dem Arbeitsverzeichnis (git diff <rev>). Erlaubt sind Branch, Tag, Remote-Branch oder Commit-SHA.
--staged	Prüft nur die Staging-Area (git diff --cached). Hat Vorrang vor --base.
--include-untracked	Nimmt unversionierte Dateien hinzu (git ls-files --others --exclude-standard). Standard: aus.

Ohne --base und ohne --staged vergleicht CodeGuard das Arbeitsverzeichnis mit dem Index (git diff). Bereits gestagte Änderungen fallen dann heraus.

Regeln, die du kennen solltest:

• Die Projektwurzel muss die Wurzel des Git-Repositorys sein. Liegt das Projekt in einem Unterordner des Repositorys, bricht der Lauf ab (Git repository root differs from requested project root).
• Eine unbekannte Referenz ist Exit 2, eine mehrdeutige ebenfalls. Ein Commit-SHA, dessen Objekt lokal fehlt (z. B. bei flachem Klon), ist Exit 3.
• Umbenennungen und Kopien werden erkannt und am neuen Pfad geprüft. Gelöschte Dateien, Binärdateien, Symlinks und Submodule werden nicht inhaltlich geprüft.
• Ohne Änderungen endet der Lauf mit Exit 0 und termination_reason: no_changes.
• compile und tests laufen (Standardkonfiguration) und brauchen ein Trust-Ticket bzw. in der CI eine Attestierung.

Beispiel für eine unbekannte Referenz:

check failed before report creation (cause: CodeGuardTooling.GitDiffError: missingBase("doesnotexist"))

check-project

Prüft alle konfigurierten, lesbaren Dateien des Projekts und baut und testet es.

codeguard check-project

check-project braucht wie check-diff ein Trust-Ticket für compile/tests. Für große Projekte eignet es sich eher als nächtlicher Lauf.

Exit-Codes

Der Exit-Code ist in allen Formaten gleich.

Code	Symbol	Status im Bericht	Bedeutung
0	CG_OK	passed	Lauf abgeschlossen, keine blockierenden Funde
1	CG_VALIDATION_FAILED	failed	Blockierender Fund (Regel, Format, Lint, Compile-Fehler, Testfehler)
2	CG_USAGE_CONFIG	error	Ungültige Eingabe, Referenz, Pfad oder Konfiguration
3	CG_DEPENDENCY_UNAVAILABLE	error	Werkzeug, SDK, Runtime oder Abhängigkeit fehlt, oder eine verpflichtende Prüfung blieb unvollständig
4	CG_TOOL_FAILURE	error	Werkzeugabsturz, unerwarteter Exit, unbekannte oder abgeschnittene Ausgabe
5	CG_TIMEOUT	error	Zeitlimit überschritten
6	CG_POLICY_BLOCKED	blocked	Pfad-, Schutz-, Trust- oder Werkzeug-Policy hat blockiert
7	CG_ITERATION_LIMIT	failed	Reserviert für die nicht aktiven Fix-Abläufe
8	CG_CANCELLED	cancelled	Lauf abgebrochen
9	CG_INTERNAL_ERROR	error	Invariante, Aufräumen oder atomares Schreiben gescheitert, unvollständige Installation

Treten mehrere Fehler auf, gewinnt der zuerst festgestellte. Interne Fehler (Exit 9) haben immer Vorrang. Die übrigen stehen im JSON-Bericht unter secondary_failures. Beispiel aus einem echten Lauf: Ein Diff mit Inhaltsfunden in einem Projekt ohne Trust-Ticket endet mit Exit 1, primary_failure: validation_failed und secondary_failures: ["policy_blocked"]. Ohne die Inhaltsfunde endet derselbe Lauf mit Exit 6.

So reagierst du in einem Skript:

codeguard --format json --output codeguard.json check-diff --base main
rc=$?
case $rc in
  0) echo "sauber" ;;
  1) echo "blockierende Funde, Bericht ansehen" ;;
  2) echo "Aufruf oder Konfiguration falsch" ;;
  3) echo "Werkzeug, SDK oder Abhängigkeit fehlt" ;;
  6) echo "Policy hat blockiert (Trust, Pfad, geschützte Datei)" ;;
  *) echo "Lauf unvollständig oder Bedienfehler (Code $rc)" ;;
esac
exit $rc

Ausgabe und Streams

• Ein vollständig erzeugter Bericht geht nach stdout oder exakt in die --output-Datei, auch wenn der Exit-Code ungleich 0 ist.
• Maschinelle Ausgabe (JSON, SARIF) ist genau ein Dokument ohne Logzeilen davor oder danach.
• Meldungen zu Bedien-, Konfigurations- und Renderfehlern gehen nach stderr. In diesen Fällen gibt es keinen Bericht.
• --output schreibt über eine temporäre Datei im Zielverzeichnis und benennt sie atomar um. Scheitert das, ist der Exit-Code 9.
• Die Textausgabe zeigt höchstens 20 Funde. Weitere stehen als N additional diagnostics omitted. am Ende. JSON und SARIF enthalten alle.

Siehe auch

• Berichte lesen
• Projektkonfiguration
• Häufige Fragen