Erste Schritte

Nach dieser Anleitung ist CodeGuard installiert, findet seine Werkzeuge und hat ein erstes Projekt geprüft.

Voraussetzungen

Was	Anforderung
Betriebssystem	macOS 15 oder neuer. Angestrebt ist 15.6 als Minimum, die Zertifizierung dafür steht noch aus.
Zum Bauen von CodeGuard	Swift-Toolchain mit `swift-tools-version` 6.3
Xcode	Für `swift-format`, `swift`, `xcodebuild` und `simctl`. `xcodebuild` muss eine Version `>= 26.0.0` und `< 28.0.0` haben.
`swift-format`	Aus der aktiven Xcode-Toolchain. Unterstützt sind 6.3.x und die unversionierte Fassung aus Xcode 27 (meldet sich als `main`).
`swiftlint`	Wird standardmäßig verlangt. Fehlt es, endet jeder Prüflauf mit Exit 3.
`git`	Für `check-diff`, aufgelöst aus einem vertrauenswürdigen Verzeichnis (z. B. `/usr/bin`).

Womit diese Hilfe erstellt wurde

Die Beispielausgaben in dieser Hilfe stammen aus echten Läufen von codeguard 0.3.5 auf macOS 27.0.1 (Apple Silicon) mit Xcode 27.0 (Build 27A266a), SwiftLint 0.65.1 und iOS-Simulator-Runtime 27.0. Auf anderen Versionen können Versionsnummern, Dauer und Gerätenamen abweichen.

Installation

CodeGuard wird aus dem Quellcode gebaut. Das Installationsskript baut im Release-Modus als dein Benutzer und kopiert danach per sudo das Binary und die drei Ressourcen-Bundles in dasselbe Verzeichnis, Eigentümer root:wheel.

Quellcode holen:

git clone <REPOSITORY-URL> CodeGuard   # Platzhalter: Repository-URL eintragen
cd CodeGuard

Bauen und installieren:

Scripts/install.sh                  # installiert nach /usr/local/bin
Scripts/install.sh --bindir DIR     # installiert nach DIR

Das Skript lehnt den Start als root ab. Es ruft sudo nur für das Kopieren auf.

Installation prüfen:

codeguard version

codeguard 0.3.5 (configuration schema 1, report schema 1)

Neben dem Binary müssen diese Bundles liegen:

CodeGuard_CodeGuardConfiguration.bundle
CodeGuard_CodeGuardReporting.bundle
CodeGuard_CodeGuardAnalysis.bundle

Fehlt eines, bricht jedes Kommando mit Exit 9 ab und meldet installation incomplete: resource bundle … not found next to the codeguard executable. Kopiere das Binary deshalb nie allein.

Organisationsrichtlinie einrichten

CodeGuard startet Werkzeuge nur aus vertrauenswürdigen Verzeichnissen (trusted_roots). Ohne eigene Richtlinie gelten diese Vorgaben:

/usr/bin
/usr/local/bin
/opt/homebrew/bin
/Applications/Xcode.app/Contents/Developer/usr/bin

Eine Standard-Xcode-Installation liefert swift-format und swift aber unter /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin. Ohne Richtlinie meldet doctor deshalb swift-format: unavailable, Prüfungen von .swift-Dateien enden mit Exit 6, und der SwiftPM-Build kann mit Exit 3 enden. Eine Projektkonfiguration kann das nicht beheben, die Werkzeugpfade gehören der Organisationsrichtlinie.

Richtlinie anlegen (Vorlage aus dem Repository, docs/help/policy.example.yml):

policy_version: 1
configuration_versions: [1]
enforcement:
  tools:
    trusted_roots:
      - /usr/bin
      - /usr/local/bin
      - /Applications/Xcode.app/Contents/Developer/usr/bin
      - /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

Mit den richtigen Rechten installieren. Datei und alle Verzeichnisse darüber müssen root gehören und dürfen nicht gruppen- oder weltbeschreibbar sein:

sudo mkdir -p "/Library/Application Support/CodeGuard"
sudo install -o root -g wheel -m 0644 docs/help/policy.example.yml \
  "/Library/Application Support/CodeGuard/policy.yml"

Prüfen:

codeguard config validate

Die Ausgabe nennt die Richtlinie mit ihrem Hash, zum Beispiel:

configuration valid (schema 1, sha256:b6d2da11a83b32a5c08fd1941bc85affa4a50ed7ec50c93d975457ff05a23dad)
policy: /Library/Application Support/CodeGuard/policy.yml (sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80)

Alle Schlüssel der Richtlinie stehen auf der Seite Organisationsrichtlinie.

SwiftLint bereitstellen

SwiftLint kommt nicht mit Xcode. CodeGuard sucht es nur unter den vertrauenswürdigen Verzeichnissen.

Keine Homebrew-Pfade als vertrauenswürdige Verzeichnisse

/opt/homebrew/bin und /opt/homebrew/Cellar/… gehören dem Benutzer, der Homebrew installiert hat. Jeder Prozess dieses Benutzers, etwa ein SwiftPM-Plugin, könnte swiftlint dort austauschen, während die root-eigene Richtlinie ihm weiter vertraut. CodeGuard prüft den Eigentümer eines vertrauenswürdigen Verzeichnisses nicht selbst.

Lege stattdessen eine root-eigene Kopie an:

sudo install -o root -g wheel -m 0755 "$(realpath /opt/homebrew/bin/swiftlint)" /usr/local/bin/swiftlint

Wiederhole das nach jedem brew upgrade swiftlint. Auf Apple-Silicon-Macs gehört /usr/local/bin root. Auf Intel-Macs gehört es meist Homebrew; lege dann ein anderes root-eigenes Verzeichnis an und trage es in trusted_roots ein.

Nicht zwei Wurzeln für dasselbe Werkzeug

Findet CodeGuard ein Werkzeug unter zwei vertrauenswürdigen Verzeichnissen (zum Beispiel einen Symlink in einer Wurzel und sein Ziel in einer anderen), lehnt der Resolver es als mehrdeutig ab. doctor zeigt das Werkzeug dann als unavailable.

Umgebung prüfen

codeguard doctor

Ausgabe auf dem Referenzrechner, im Verzeichnis eines leeren Ordners (deshalb compile/tests: inactive):

ready: true
policy: /Library/Application Support/CodeGuard/policy.yml (sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80)
configuration: active
git-diff: active
path-policy: active
read-only-checks: active
reports: active
trust-state: active
swift-format: active (main)
swiftlint: active
compile: inactive
tests: inactive
autofix: inactive
agent-adapters: inactive
platform-checks: active (1)
content-rules: active (secret-detectors-v1)
unauthorized-network-destination: inactive
platform.macos: available (27.0)
platform.ios: available (27.0)
platform.watchos: available (27.0)
platform.tvos: available (27.0)
platform.visionos: available (27.0)
simctl: active (1171.7.0) /Applications/Xcode.app/Contents/Developer/usr/bin/simctl
simulator.ios: available (device type: iPhone 18 Pro)
simulator.ios.runtime: 27.0 (24A434)
simulator.ios.runtime: 26.5 (23F77)
simulator.ios.runtime: 18.5 (22F77)
simulator.watchos: unavailable
simulator.tvos: unavailable
simulator.visionos: unavailable
Verwaiste CodeGuard-Geräte: 0

So liest du die Ausgabe:

Status	Bedeutung
`active`	Fähigkeit steht zur Verfügung
`unavailable`	Werkzeug eingeschaltet, aber nicht auflösbar
`incompatible`	Werkzeug gefunden, Version passt nicht
`inactive`	Abgeschaltet oder in diesem Kontext nicht relevant

ready: true heißt: Jede eingeschaltete Format- und Lint-Prüfung ist einsatzbereit.
platform.<name> zeigt, ob das SDK installiert ist, simulator.<name>, ob dafür eine Simulator-Runtime existiert. Im Beispiel sind alle SDKs da, aber nur iOS-Runtimes. Tests für watchOS, tvOS und visionOS würden deshalb übersprungen.
doctor führt nie ein Lint und nie einen Build aus. Es ermittelt nur Pfade und Versionen.

Erster Prüflauf

Wechsle in die Wurzel deines Projekts (dort, wo Package.swift oder das .xcodeproj liegt).

Prüfe eine einzelne Datei:

codeguard check-file Sources/MeinModul/Datei.swift

Prüfe deine Git-Änderungen gegenüber main:
```
codeguard check-diff --base main --include-untracked
```
Ohne Trust-Ticket endet das bei Projekten mit Package.swift oder Xcode-Projekt mit CODEGUARD_BLOCKED und Exit 6, weil compile und tests Projektcode ausführen würden. Die statischen Prüfungen laufen trotzdem und stehen im Bericht.
Erteile dem Projekt Vertrauen (im Terminal, Bestätigung mit yes):
```
codeguard trust grant --duration 24h
```
Danach baut und testet check-diff das Projekt. Mehr dazu unter Trust und Sicherheit.

tipp

Der Ablauf im Alltag steht unter Manueller Einsatz, die Bedeutung jeder Zeile im Bericht unter Berichte lesen.

Voraussetzungen​

Installation​

Organisationsrichtlinie einrichten​

SwiftLint bereitstellen​

Umgebung prüfen​

Erster Prüflauf​

Siehe auch​