{"meta":{"title":"Verwenden von Hooks mit Copilot CLI für vorhersehbare, richtlinienkonforme Ausführung","intro":"Verwenden Sie Hooks, um Benutzeraufforderungen zu protokollieren und zu steuern, welche Tools Copilot CLI in einem Repository ausgeführt werden können, damit Teams die Sicherheits- und Complianceanforderungen Ihrer Organisation sicher automatisieren können.","product":"GitHub Copilot","breadcrumbs":[{"href":"/de/copilot","title":"GitHub Copilot"},{"href":"/de/copilot/tutorials","title":"Anleitungen"},{"href":"/de/copilot/tutorials/copilot-cli-hooks","title":"Verwenden von Hooks mit Copilot CLI"}],"documentType":"article"},"body":"# Verwenden von Hooks mit Copilot CLI für vorhersehbare, richtlinienkonforme Ausführung\n\nVerwenden Sie Hooks, um Benutzeraufforderungen zu protokollieren und zu steuern, welche Tools Copilot CLI in einem Repository ausgeführt werden können, damit Teams die Sicherheits- und Complianceanforderungen Ihrer Organisation sicher automatisieren können.\n\nDieses Lernprogramm richtet sich an DevOps-Ingenieure, Plattformteams und Ingenieurleiter, die Entwickler bei der Nutzung von Copilot CLI unterstützen.\n\nHooks sind benutzerdefinierte Skripts, die an bestimmten Punkten während einer Copilot CLI Sitzung ausgeführt werden. Sie können Eingabeaufforderungen und Toolaufrufe prüfen, Informationen zur Überwachung protokollieren und sogar die Ausführung bestimmter Befehle blockieren.\n\nSie konfigurieren Repository-spezifische Hooks, die:\n\n* Bieten Sie Einblicke in Eingabeaufforderungen und die Verwendung von Tools.\n* Blockieren Von Befehlsmustern mit hohem Risiko vor der Ausführung.\n* Helfen Sie Entwicklern, Organisationsrichtlinien mit klaren Nachrichten zu verstehen.\n\n## Voraussetzungen\n\n* Vertrautheit mit Shellskripting (Bash oder PowerShell).\n* Grundlegendes Verständnis von JSON-Konfigurationsdateien.\n* Zugriff auf ein Repository, in dem Copilot CLI verwendet wird.\n* Für die Bash-Beispiele: `jq` muss installiert werden.\n* Für die PowerShell-Beispiele: PowerShell 7.0 oder höher muss installiert werden.\n\n## 1. Definieren einer Organisationsrichtlinie\n\nBevor Sie Hook-Skripts schreiben, entscheiden Sie, welche Aktionen automatisch zugelassen werden sollen und welche eine menschliche Überprüfung erfordern sollten.\n\nEine klare Richtlinie hilft Ihnen, die Übersperrung zu vermeiden und gleichzeitig das Risiko zu verringern.\n\n### Identifizieren von Befehlen, für die immer eine Überprüfung erforderlich ist\n\nBeginnen Sie mit der Identifizierung von Mustern, die niemals automatisch von Copilot CLI ausgeführt werden sollen. Häufige Beispiele sind:\n\n* **Berechtigungseskalation**: `sudo`, `su``runas`\n* **Destruktive Systemvorgänge**: `rm -rf /`, `mkfs`, `dd``format`\n* **Download- und Ausführungsmuster**: `curl ... | bash`, `wget ... | sh`, PowerShell `iex (irm ...)`\n\nDiese Befehle können unwiderrufliche Auswirkungen haben, wenn sie unbeabsichtigt ausgeführt werden.\n\n### Entscheiden, was protokolliert werden soll\n\nWenn Sie Hooks verwenden, können Sie Informationen darüber erfassen, wie Copilot CLI in einem Repository verwendet wird, einschließlich der von Benutzern und Tools übermittelten Eingabeaufforderungen, die Copilot CLI auszuführen versuchen.\n\nMindestens protokollieren die meisten Organisationen:\n\n* Der Zeitstempel und der Repository-Pfad\n* Der Text der Eingabeaufforderung (oder in redigierter Form)\n* Der Toolname und die Toolargumente\n* Jede Richtlinienentscheidung (z. B. ein verweigerter Befehl und sein Grund)\n\nVermeiden Sie die Protokollierung geheimer Schlüssel oder Anmeldeinformationen. Wenn Eingabeaufforderungen oder Befehle möglicherweise vertrauliche Daten enthalten, entfernen Sie diese Informationen, bevor Sie Protokolle schreiben.\n\nIn diesem Lernprogramm wird ein lokales `.github/hooks/logs` Verzeichnis als einfaches, illustratives Beispiel verwendet. Diese Protokolldateien sind **nicht für das Repository vorgesehen** und befinden sich in der Regel nur auf dem Computer eines Entwicklers.\n\nIn Produktionsumgebungen leiten viele Organisationen Hook-Ereignisse an ein zentralisiertes Protokollierungs- oder Observability-System weiter, anstatt Protokolle lokal zu schreiben. Auf diese Weise können Teams konsistente Schwärzungen, Zugriffssteuerungen, Aufbewahrungsrichtlinien und Überwachung für Repositories und Benutzer anwenden.\n\n### Abstimmung mit Interessengruppen\n\nBevor Sie Richtlinien erzwingen, überprüfen Sie sie mit:\n\n* Sicherheits- oder Complianceteams, um Risikogrenzen zu bestätigen\n* Plattform- oder Infrastrukturteams, die möglicherweise umfassendere Berechtigungen benötigen\n* Entwicklungsteams, damit sie verstehen, was blockiert wird und warum\n\nKlare Erwartungen machen die Durchsetzung von Richtlinien einfacher zu übernehmen und aufrechtzuerhalten.\n\n## 2. Einrichten von Repository-Hookdateien\n\nIn diesem Lernprogramm verwenden Sie **repository-scoped hooks**, die im Repository unter `.github/hooks/` gespeichert sind. Diese Hooks gelten immer dann, wenn Copilot CLI innerhalb dieses Repositories ausgeführt wird.\n\n> \\[!NOTE]\n> Copilot Agenten laden Hook-Konfigurationen aus `.github/hooks/*.json`-Dateien im Repository. Hooks werden synchron ausgeführt und können die Ausführung blockieren.\n\n### Erstellen der Verzeichnisstruktur\n\nErstellen Sie im Repositorystamm Verzeichnisse für Ihre Hook-Konfiguration, Skripts und Protokolle:\n\n```bash copy\nmkdir -p .github/hooks/scripts\nmkdir -p .github/hooks/logs\n```\n\nFügen Sie `.github/hooks/logs/` zur .gitignore hinzu, damit lokale Audit-Logs nicht committed werden.\n\n```bash copy\necho \".github/hooks/logs/\" >> .gitignore\n```\n\nIn diesem Lernprogramm wird die folgende Struktur verwendet:\n\n```text\n.github/\n└── hooks/\n    ├── copilot-cli-policy.json\n    ├── logs/\n    │   └── audit.jsonl\n    └── scripts/\n        ├── session-banner.sh\n        ├── session-banner.ps1\n        ├── log-prompt.sh\n        ├── log-prompt.ps1\n        ├── pre-tool-policy.sh\n        └── pre-tool-policy.ps1\n```\n\n> \\[!NOTE]\n> In diesem Lernprogramm wird versucht, portable Hook-Konfigurationen und Skripts zu erstellen, die für Windows, Linux und macOS verwendet werden können. Das `scripts` Verzeichnis enthält daher sowohl Bash- als auch PowerShell-Skripts, und die Hook-Konfigurationsdateien enthalten `bash` und `powershell` Einträge. Die CLI verwendet den entsprechenden Eintrag basierend auf Ihrem Betriebssystem.\n\n### Erstellen einer Hook-Konfigurationsdatei\n\nErstellen Sie eine Hook-Konfigurationsdatei unter `.github/hooks/copilot-cli-policy.json`.\n\nDiese Datei definiert, welche Hooks ausgeführt werden, wann sie ausgeführt werden und welche Skripts ausgeführt werden.\n\n```json copy\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"sessionStart\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/session-banner.sh\",\n        \"powershell\": \"./scripts/session-banner.ps1\",\n        \"cwd\": \".github/hooks\",\n        \"timeoutSec\": 10\n      }\n    ],\n    \"userPromptSubmitted\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/log-prompt.sh\",\n        \"powershell\": \"./scripts/log-prompt.ps1\",\n        \"cwd\": \".github/hooks\",\n        \"timeoutSec\": 10\n      }\n    ],\n    \"preToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/pre-tool-policy.sh\",\n        \"powershell\": \"./scripts/pre-tool-policy.ps1\",\n        \"cwd\": \".github/hooks\",\n        \"timeoutSec\": 15\n      }\n    ]\n  }\n}\n```\n\n### Grundlegendes zur Funktionsweise dieser Konfiguration\n\nDiese Konfiguration richtet drei Hooks ein:\n\n* `sessionStart`: Zeigt eine Informationsmeldung an, wenn eine neue Agentsitzung gestartet oder fortgesetzt wird.\n* `userPromptSubmitted`: Wird ausgeführt, wenn ein Benutzer eine Eingabeaufforderung sendet.\n* `preToolUse`: Wird ausgeführt, bevor ein Tool ausgeführt wird und die Ausführung explizit zulassen oder verweigern kann.\n\n### Hook-Konfiguration speichern und teilen\n\nWenn Sie bereit sind, die Hook-Konfiguration für Mitarbeiter freizugeben (z. B. über eine Pullanforderung oder in einem Test-Repository), übernehmen Sie die Hook-Konfiguration und Skripts. Übergeben Sie keine lokalen Überwachungsprotokolle.\n\n```bash copy\ngit add .github/hooks/copilot-cli-policy.json .github/hooks/scripts\ngit commit -m \"Add Copilot CLI hook configuration\"\ngit push\n```\n\nAn diesem Punkt Copilot CLI können Sie Ihre Hook-Konfiguration ermitteln, obwohl Sie die Hook-Skripts noch nicht erstellt haben.\n\n## 3. Hinzufügen eines Richtlinienbanners beim Start der Sitzung\n\nVerwenden Sie einen `sessionStart` Hook, um ein Banner anzuzeigen, wenn eine neue Copilot CLI Sitzung gestartet oder fortgesetzt wird. Dadurch wird Entwicklern klar, dass Organisationsrichtlinien aktiv sind.\n\nDer `sessionStart` Hook empfängt kontextbezogene Informationen wie das aktuelle Arbeitsverzeichnis und die erste Eingabeaufforderung. Jegliche Ausgabe dieses Hooks wird von Copilot CLI ignoriert, wodurch er für Informationsnachrichten geeignet ist.\n\n### Erstellen des Sitzungsbannerskripts (Bash)\n\nErstellen Sie `.github/hooks/scripts/session-banner.sh`:\n\n```bash copy\n#!/bin/bash\nset -euo pipefail\n\ncat << 'EOF'\nCOPILOT CLI POLICY ACTIVE\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n• Prompts and tool use may be logged for auditing\n• High-risk commands may be blocked automatically\n• If something is blocked, follow the guidance shown\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nEOF\nexit 0\n```\n\n### Erstellen des Sitzungsbannerskripts (PowerShell)\n\nErstellen Sie `.github/hooks/scripts/session-banner.ps1`:\n\n```powershell copy\n$ErrorActionPreference = \"Stop\"\n\nWrite-Host @\"\nCOPILOT CLI POLICY ACTIVE\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n• Prompts and tool use may be logged for auditing\n• High-risk commands may be blocked automatically\n• If something is blocked, follow the guidance shown\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\"@\nexit 0\n```\n\n### Testen des Sitzungsbanners\n\nSie können die Bannerskripts direkt testen:\n\n```bash\n.github/hooks/scripts/session-banner.sh\n# or, for PowerShell\n.github/hooks/scripts/session-banner.ps1\n```\n\nWenn Sie eines der Skripts ausführen, sollte das Richtlinienbanner in Ihrem Terminal angezeigt werden.\n\n## 4. Protokollieren von Aufforderungen zur Prüfung\n\nVerwenden Sie den `userPromptSubmitted` Hook, um aufzuzeichnen, wenn Benutzer Eingabeaufforderungen an Copilot CLI senden. Dieser Hook wird immer ausgeführt, wenn eine Eingabeaufforderung gesendet wird, bevor tools aufgerufen werden.\n\nDer Hook empfängt strukturierte JSON-Eingaben, die den Zeitstempel, das aktuelle Arbeitsverzeichnis und den vollständigen Eingabeaufforderungstext enthalten. Die Ausgabe dieses Hooks wird ignoriert.\n\n> \\[!IMPORTANT]\n> Eingabeaufforderungen können vertrauliche Informationen enthalten. Wenden Sie Redaction an, und befolgen Sie die Datenverarbeitungs- und Aufbewahrungsrichtlinien Ihrer Organisation beim Protokollieren dieser Daten.\n\n### Skript zur Prompt-Protokollierung erstellen (Bash)\n\nErstellen Sie `.github/hooks/scripts/log-prompt.sh`:\n\n```bash copy\n#!/bin/bash\nset -euo pipefail\n\nINPUT=\"$(cat)\"\n\nTIMESTAMP_MS=\"$(echo \"$INPUT\" | jq -r '.timestamp // empty')\"\nCWD=\"$(echo \"$INPUT\" | jq -r '.cwd // empty')\"\n\n# This example logs only metadata, not the full prompt, to avoid storing\n# potentially sensitive data. Adjust to match your organization’s needs.\nLOG_DIR=\".github/hooks/logs\"\nmkdir -p \"$LOG_DIR\"\nchmod 700 \"$LOG_DIR\"\n\njq -n \\\n  --arg ts \"$TIMESTAMP_MS\" \\\n  --arg cwd \"$CWD\" \\\n  '{event:\"userPromptSubmitted\", timestampMs:$ts, cwd:$cwd}' \\\n  >> \"$LOG_DIR/audit.jsonl\"\n\nexit 0\n```\n\n### Erstellen Sie das Skript zur Protokollierung der Eingabeaufforderung (PowerShell)\n\nErstellen Sie `.github/hooks/scripts/log-prompt.ps1`:\n\n```powershell copy\n$ErrorActionPreference = \"Stop\"\n\n$inputObj = [Console]::In.ReadToEnd() | ConvertFrom-Json\n\n$timestampMs = $inputObj.timestamp\n$cwd = $inputObj.cwd\n$prompt = $inputObj.prompt\n\n# Optional example redaction. Adjust to match your organization’s needs.\n$redactedPrompt = $prompt -replace 'ghp_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]'\n\n$logDir = \".github/hooks/logs\"\nif (-not (Test-Path $logDir)) {\n  New-Item -ItemType Directory -Path $logDir -Force | Out-Null\n}\n\n$logEntry = @{\n  event       = \"userPromptSubmitted\"\n  timestampMs = $timestampMs\n  cwd         = $cwd\n  prompt      = $redactedPrompt\n} | ConvertTo-Json -Compress\n\nAdd-Content -Path \"$logDir/audit.jsonl\" -Value $logEntry\nexit 0\n```\n\n### Das Skript zur Protokollierung von Prompts testen\n\nSie können die Skripte direkt testen, indem Sie Beispiel-Eingaben über eine Pipeline verwenden.\n\n```bash\necho '{\"timestamp\":1704614500000,\"cwd\":\"/repo\",\"prompt\":\"List all branches\"}' \\\n  | .github/hooks/scripts/log-prompt.sh\n# or, for PowerShell\necho '{\"timestamp\":1704614500000,\"cwd\":\"/repo\",\"prompt\":\"List all branches\"}' |\n  .github/hooks/scripts/log-prompt.ps1\n```\n\nÜberprüfen Sie nach dem Ausführen des Skripts `.github/hooks/logs/audit.jsonl` auf einen neuen Protokolleintrag.\n\n```bash copy\ncat .github/hooks/logs/audit.jsonl\n```\n\nZu diesem Zeitpunkt werden die an Copilot CLI übermittelten Eingabeaufforderungen in diesem Repository zur Prüfung aufgezeichnet.\n\n## 5. Richtlinien erzwingen mit `preToolUse`\n\nVerwenden Sie den `preToolUse` Hook, um einen Toolaufruf **auszuwerten, bevor er ausgeführt wird**. Dieser Hook kann die Ausführung erlauben (indem nichts unternommen wird) oder die Ausführung verweigern (durch Zurückgeben einer strukturierten Antwort).\n\n### Verstehen Sie die `preToolUse` Eingabe\n\nDie `preToolUse` Hookeingabe umfasst:\n\n* `toolName`: Das Tool, das Copilot CLI in Kürze ausführt (z. B. `bash`).\n* `toolArgs`: Eine **JSON-Zeichenfolge** , die die Argumente dieses Tools enthält\n\nDa `toolArgs` eine JSON-Zeichenfolge ist, muss Ihr Skript sie parsen, bevor es Felder wie `command` liest.\n\n> \\[!IMPORTANT]\n> Toolargumente und -befehle können vertrauliche Informationen wie API-Token, Kennwörter oder andere Anmeldeinformationen enthalten. Wenden Sie Schwärzung an, bevor Sie diese Daten protokollieren, und befolgen Sie die Sicherheitsrichtlinien Ihrer Organisation. Erwägen Sie die Protokollierung nur nicht vertraulicher Metadaten (Toolname, Zeitstempel, Richtlinienentscheidung) und das Weiterleiten von Überwachungsereignissen an ein gesichertes, zentralisiertes Protokollierungssystem mit entsprechenden access Steuerelementen und Aufbewahrungsrichtlinien.\n\n### Erstellen des Richtlinienskripts\n\nErstellen Sie als Nächstes ein Richtlinienskript. Dieses Beispiel:\n\n* Protokolliert alle versuchten Toolverwendungen.\n* Wendet Verweigerungsregeln nur auf Bash-Befehle an.\n* Blockiert Hochrisikomuster wie Berechtigungseskalation, destruktive Vorgänge und Download- und Ausführungsbefehle.\n\nDamit Sie den Verweigerungsfluss sicher überprüfen können, enthält das Skript auch eine temporäre Demoregel, die einen harmlosen Testbefehl blockiert. Nachdem Sie bestätigt haben, dass Hooks wie erwartet funktionieren, entfernen Sie die Demoregel, und ersetzen Sie sie durch Muster, die die Richtlinien Ihrer Organisation widerspiegeln.\n\n#### Beispielskript (Bash)\n\nErstellen Sie `.github/hooks/scripts/pre-tool-policy.sh`:\n\n```bash copy\n#!/bin/bash\nset -euo pipefail\n\nINPUT=\"$(cat)\"\n\nTOOL_NAME=\"$(echo \"$INPUT\" | jq -r '.toolName // empty')\"\nTOOL_ARGS_RAW=\"$(echo \"$INPUT\" | jq -r '.toolArgs // empty')\"  # JSON string\n\nLOG_DIR=\".github/hooks/logs\"\nmkdir -p \"$LOG_DIR\"\n\n# Example redaction logic.\n# GitHub does not currently provide built-in secret redaction for hooks.\n# This example shows one possible approach; many organizations prefer to\n# forward events to a centralized logging system that handles redaction.\n# Redact sensitive patterns before logging.\n# Adjust these patterns to match your organization's needs.\nREDACTED_TOOL_ARGS=\"$(echo \"$TOOL_ARGS_RAW\" | \\\n  sed -E 's/ghp_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \\\n  sed -E 's/gho_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \\\n  sed -E 's/ghu_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \\\n  sed -E 's/ghs_[A-Za-z0-9\\._\\-]{20,}/[REDACTED_TOKEN]/g' | \\\n  sed -E 's/Bearer [A-Za-z0-9_\\-\\.]+/Bearer [REDACTED]/g' | \\\n  sed -E 's/--password[= ][^ ]+/--password=[REDACTED]/g' | \\\n  sed -E 's/--token[= ][^ ]+/--token=[REDACTED]/g')\"\n\n# Log attempted tool use with redacted toolArgs.\njq -n \\\n  --arg tool \"$TOOL_NAME\" \\\n  --arg toolArgs \"$REDACTED_TOOL_ARGS\" \\\n  '{event:\"preToolUse\", toolName:$tool, toolArgs:$toolArgs}' \\\n  >> \"$LOG_DIR/audit.jsonl\"\n\n# Only enforce command rules for bash.\nif [ \"$TOOL_NAME\" != \"bash\" ]; then\n  exit 0\nfi\n\n# Parse toolArgs JSON string.\n# If toolArgs isn't valid JSON for some reason, allow (and rely on logs).\nif ! echo \"$TOOL_ARGS_RAW\" | jq -e . >/dev/null 2>&1; then\n  exit 0\nfi\n\nCOMMAND=\"$(echo \"$TOOL_ARGS_RAW\" | jq -r '.command // empty')\"\n\n# ---------------------------------------------------------------------------\n# Demo-only deny rule for safe testing.\n# This blocks a harmless test command so you can validate the deny flow.\n# Remove this rule after confirming your hooks work as expected.\n# ---------------------------------------------------------------------------\nif echo \"$COMMAND\" | grep -q \"COPILOT_HOOKS_DENY_DEMO\"; then\n  deny \"Blocked demo command (test rule). Remove this rule after validating hooks.\"\nfi\n\ndeny() {\n  local reason=\"$1\"\n\n  # Redact sensitive patterns from command before logging.\n  local redacted_cmd=\"$(echo \"$COMMAND\" | \\\n    sed -E 's/ghp_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \\\n    sed -E 's/gho_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \\\n    sed -E 's/ghu_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \\\n    sed -E 's/ghs_[A-Za-z0-9\\.\\-_]{20,}/[REDACTED_TOKEN]/g' | \\\n    sed -E 's/Bearer [A-Za-z0-9_\\-\\.]+/Bearer [REDACTED]/g' | \\\n    sed -E 's/--password[= ][^ ]+/--password=[REDACTED]/g' | \\\n    sed -E 's/--token[= ][^ ]+/--token=[REDACTED]/g')\"\n\n  # Log the denial decision with redacted command.\n  jq -n \\\n    --arg cmd \"$redacted_cmd\" \\\n    --arg r \"$reason\" \\\n    '{event:\"policyDeny\", toolName:\"bash\", command:$cmd, reason:$r}' \\\n    >> \"$LOG_DIR/audit.jsonl\"\n\n  # Return a denial response.\n  jq -n \\\n    --arg r \"$reason\" \\\n    '{permissionDecision:\"deny\", permissionDecisionReason:$r}'\n\n  exit 0\n}\n\n# Privilege escalation\nif echo \"$COMMAND\" | grep -qE '\\b(sudo|su|runas)\\b'; then\n  deny \"Privilege escalation requires manual approval.\"\nfi\n\n# Destructive filesystem operations targeting root\nif echo \"$COMMAND\" | grep -qE 'rm\\s+-rf\\s*/($|\\s)|rm\\s+.*-rf\\s*/($|\\s)'; then\n  deny \"Destructive operations targeting the filesystem root require manual approval.\"\nfi\n\n# System-level destructive operations\nif echo \"$COMMAND\" | grep -qE '\\b(mkfs|dd|format)\\b'; then\n  deny \"System-level destructive operations are not allowed via automated execution.\"\nfi\n\n# Download-and-execute patterns\nif echo \"$COMMAND\" | grep -qE 'curl.*\\|\\s*(bash|sh)|wget.*\\|\\s*(bash|sh)'; then\n  deny \"Download-and-execute patterns require manual approval.\"\nfi\n\n# Allow by default\nexit 0\n```\n\n#### Erstellen des Richtlinienskripts (PowerShell)\n\nErstellen Sie `.github/hooks/scripts/pre-tool-policy.ps1`:\n\n```powershell copy\n$ErrorActionPreference = \"Stop\"\n\n$inputObj = [Console]::In.ReadToEnd() | ConvertFrom-Json\n$toolName = $inputObj.toolName\n$toolArgsRaw = $inputObj.toolArgs  # JSON string\n\n$logDir = \".github/hooks/logs\"\nif (-not (Test-Path $logDir)) { New-Item -ItemType Directory -Path $logDir -Force | Out-Null }\n\n# Example redaction logic.\n# GitHub does not currently provide built-in secret redaction for hooks.\n# This example shows one possible approach; many organizations prefer to\n# forward events to a centralized logging system that handles redaction.\n# Redact sensitive patterns before logging.\n# Adjust these patterns to match your organization's needs.\n$redactedToolArgs = $toolArgsRaw `\n  -replace 'ghp_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `\n  -replace 'gho_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `\n  -replace 'ghu_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `\n  -replace 'ghs_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `\n  -replace 'Bearer [A-Za-z0-9_\\-\\.]+', 'Bearer [REDACTED]' `\n  -replace '--password[= ][^ ]+', '--password=[REDACTED]' `\n  -replace '--token[= ][^ ]+', '--token=[REDACTED]'\n\n# Log attempted tool use with redacted toolArgs.\n(@{\n  event    = \"preToolUse\"\n  toolName = $toolName\n  toolArgs = $redactedToolArgs\n} | ConvertTo-Json -Compress) | Add-Content -Path \"$logDir/audit.jsonl\"\n\nif ($toolName -ne \"bash\") { exit 0 }\n\n# Parse toolArgs JSON string.\n$toolArgs = $null\ntry { $toolArgs = $toolArgsRaw | ConvertFrom-Json } catch { exit 0 }\n\n$command = $toolArgs.command\n\n# ---------------------------------------------------------------------------\n# Demo-only deny rule for safe testing.\n# This blocks a harmless test command so you can validate the deny flow.\n# Remove this rule after confirming your hooks work as expected.\n# ---------------------------------------------------------------------------\nif ($command -match 'COPILOT_HOOKS_DENY_DEMO') {\n  Deny \"Blocked demo command (test rule). Remove this rule after validating hooks.\"\n}\n\nfunction Deny([string]$reason) {\n  # Redact sensitive patterns from command before logging.\n  $redactedCommand = $command `\n    -replace 'ghp_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `\n    -replace 'gho_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `\n    -replace 'ghu_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `\n    -replace 'ghs_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `\n    -replace 'Bearer [A-Za-z0-9_\\-\\.]+', 'Bearer [REDACTED]' `\n    -replace '--password[= ][^ ]+', '--password=[REDACTED]' `\n    -replace '--token[= ][^ ]+', '--token=[REDACTED]'\n\n  # Log the denial decision with redacted command.\n  (@{\n    event    = \"policyDeny\"\n    toolName = \"bash\"\n    command  = $redactedCommand\n    reason   = $reason\n  } | ConvertTo-Json -Compress) | Add-Content -Path \"$logDir/audit.jsonl\"\n\n  (@{\n    permissionDecision = \"deny\"\n    permissionDecisionReason = $reason\n  } | ConvertTo-Json -Compress)\n\n  exit 0\n}\n\nif ($command -match '\\b(sudo|su|runas)\\b') { Deny \"Privilege escalation requires manual approval.\" }\nif ($command -match 'rm\\s+-rf\\s*/(\\s|$)|rm\\s+.*-rf\\s*/(\\s|$)') { Deny \"Destructive operations targeting the filesystem root require manual approval.\" }\nif ($command -match '\\b(mkfs|dd|format)\\b') { Deny \"System-level destructive operations are not allowed via automated execution.\" }\nif ($command -match 'curl.*\\|\\s*(bash|sh)|wget.*\\|\\s*(bash|sh)') { Deny \"Download-and-execute patterns require manual approval.\" }\n\nexit 0\n```\n\n### Testen des Richtlinienskripts\n\nSie können die Skripts testen, indem Sie Beispiel-Eingaben über eine Pipe `preToolUse` eingeben.\n\nBeispiel zulassen:\n\n```bash\necho '{\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"git status\\\"}\"}' \\\n  | .github/hooks/scripts/pre-tool-policy.sh\n# or, for PowerShell\necho '{\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"git status\\\"}\"}' |\n  .github/hooks/scripts/pre-tool-policy.ps1\n```\n\nBeispiel für Ablehnung:\n\n```bash\necho '{\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"sudo rm -rf /\\\"}\"}' \\\n  | .github/hooks/scripts/pre-tool-policy.sh\n# or, for PowerShell\necho '{\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"sudo rm -rf /\\\"}\"}' |\n  .github/hooks/scripts/pre-tool-policy.ps1\n```\n\nÜberprüfen Sie nach dem Ausführen des Ablehnungsbeispiels `.github/hooks/logs/audit.jsonl` auf einen neuen Denialprotokolleintrag.\n\n```json\n{\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Privilege escalation requires manual approval.\"}\n```\n\nAn diesem Punkt werden Hochrisikobefehle `bash` von der automatischen Ausführung in diesem Repository blockiert.\n\n## 6. Durchführung eines End-to-End-Tests im gesamten Repository\n\nNachdem Sie die Konfigurationsdatei und Skripts erstellt haben, überprüfen Sie, ob Hooks wie erwartet ausgeführt werden, wenn Sie in diesem Repository verwenden Copilot CLI .\n\n### Überprüfen der Hook-Konfigurationsdatei\n\nÜberprüfen Sie, ob die Hook-Konfigurationsdatei eine gültige JSON-Datei ist:\n\n```bash copy\njq '.' < .github/hooks/copilot-cli-policy.json\n```\n\n### Überprüfen von Skriptberechtigungen (Unix-basierte Systeme)\n\nVergewissern Sie sich unter macOS und Linux, dass Ihre Bash-Skripts ausführbar sind:\n\n```bash copy\nchmod +x .github/hooks/scripts/*.sh\n```\n\n### Ausführen einer einfachen Sitzung\n\nStarten Sie eine neue Copilot CLI Sitzung im Repository:\n\n```bash copy\ncopilot -p \"Show me the status of this repository\"\n```\n\nErwartete Ergebnisse:\n\n* Sie sehen das Richtlinienbanner (von `sessionStart`).\n* Ein neuer Eintrag wird zu `.github/hooks/logs/audit.jsonl` (von `userPromptSubmitted`) hinzugefügt.\n\n### Trigger-Tool verwenden und Protokollierung überprüfen\n\nFühren Sie einen Befehl aus, der Copilot CLI dazu bringt, ein Tool zu verwenden (z. B. bash):\n\n```bash copy\ncopilot -p \"Show me the last 5 git commits\"\n```\n\nErwartete Ergebnisse:\n\n* Ein `preToolUse` Eintrag wird zu `.github/hooks/logs/audit.jsonl` hinzugefügt.\n* Wenn der Toolaufruf zulässig ist, wird die Ausführung normal fortgesetzt.\n\n### Testen eines verweigerten Befehls\n\nDas Beispielrichtlinienskript enthält eine temporäre Demoregel, die Befehle blockiert, die die Zeichenfolge `COPILOT_HOOKS_DENY_DEMO`enthalten. Auf diese Weise können Sie den Verweigerungsfluss sicher überprüfen, ohne destruktive Befehle auszuführen.\n\nFühren Sie eine Eingabeaufforderung aus, die einen verweigerten Befehl auslöst:\n\n```bash copy\ncopilot -p \"Run a test command: echo COPILOT_HOOKS_DENY_DEMO\"\n```\n\nErwartete Ergebnisse:\n\n* Copilot CLI führt den Befehl nicht aus.\n* Ihr Hook liefert eine Ablehnungsantwort mit einer klaren Begründung zurück.\n* Ein `policyDeny` Eintrag wird in `.github/hooks/logs/audit.jsonl` geschrieben.\n\nNachdem Sie bestätigt haben, dass der Verweigerungsfluss ordnungsgemäß funktioniert, entfernen Sie die Demoregel aus Ihrem Skript, und ersetzen Sie sie durch Verweigerungsmuster, die die Richtlinien Ihrer Organisation widerspiegeln.\n\n### Überprüfen Sie Ihre Prüfprotokolle\n\nUm neueste Einträge anzusehen:\n\n```bash copy\ntail -n 50 .github/hooks/logs/audit.jsonl\n```\n\nSo filtern Sie nur verweigerte Entscheidungen:\n\n```bash copy\njq 'select(.event==\"policyDeny\")' .github/hooks/logs/audit.jsonl\n```\n\n## 7. Sicheres Rollout über die Teams hinweg\n\nNachdem Sie Ihre Hooks in einem einzigen Repository überprüft haben, führen Sie sie schrittweise aus, um Unterbrechungen von Entwicklungsworkflows zu vermeiden.\n\n### Auswählen einer Rolloutstrategie\n\nZu den gängigen Rolloutansätzen gehören:\n\n* **Protokollierungsorientiertes Rollout (empfohlen)**: Beginnen Sie mit der Protokollierung von Prompts und der Nutzung von Tools, ohne die Ausführung zu unterbrechen. Überprüfen Sie Protokolle für einen bestimmten Zeitraum, und führen Sie dann Verweigerungsregeln ein, sobald Sie allgemeine Verwendungsmuster verstehen.\n* **Team-nach-Team-Rollout**: Stellen Sie Hooks an ein Team oder Repository nacheinander bereit, sammeln Sie Feedback, und erweitern Sie dann auf weitere Teams.\n* **Risikobasiertes Rollout**: Beginnen Sie mit Repositorys, die sensible Systeme oder Produktionsinfrastruktur behandeln, und erweitern Sie dann auf Repositorys mit geringerem Risiko.\n\n### Kommunizieren von Erwartungen\n\nBevor Sie Verweigerungsregeln erzwingen, sollten Sie sicherstellen, dass Entwickler Folgendes verstehen:\n\n* Diese Hooks sind im Repository aktiv\n* Welche Arten von Befehlen blockiert werden können\n* Vorgehensweise, wenn ein Befehl verweigert wird\n\nKlare Kommunikation reduziert Verwirrung und Supportanfragen.\n\n### Richtlinien wartbar halten\n\nWährend sich die Nutzung weiterentwickelt:\n\n* Speichern Sie Hook-Konfigurationen und Skripte in der Versionskontrolle.\n* Überprüfen Sie Überwachungsprotokolle regelmäßig, um neue Risikomuster zu erkennen.\n* Aktualisieren Sie Ablehnungsregeln inkrementell, anstatt breite Übereinstimmungen hinzuzufügen.\n* Dokumentieren Sie, warum jede Verweigerungsregel vorhanden ist, insbesondere für Einschränkungen mit hohem Einfluss.\n\n### Ausnahmen sorgfältig behandeln\n\nEinige Teams (z. B. Infrastruktur- oder Plattformteams) erfordern möglicherweise umfassendere Berechtigungen. So behandeln Sie dies sicher:\n\n* Verwalten Sie separate Hook-Konfigurationen für verschiedene Repositorys.\n* Halten Sie Ausnahmen eng und gut dokumentiert.\n* Vermeiden Sie ad-hoc lokale Umgehungen, die die Auditierbarkeit untergraben.\n\n## Weiterführende Lektüre\n\nZur Problembehandlung bei Hooks siehe [Anpassen von Agentworkflows mit Hooks](/de/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks#troubleshooting)."}