governance-audit — GitHub Copilot hook: what it does, how to install
Scans GitHub Copilot prompts for threat patterns before execution. It records events to a local JSON log and stops destructive actions based on governance settings.
.claude/settings.jsonWhat governance-audit does
The hook inspects developer prompts before GitHub Copilot handles them. It checks for privilege escalation like sudo, system destruction commands like rm -rf /, hardcoded credentials, and data exfiltration patterns. The system relies on three shell scripts: audit-session-start.sh, audit-prompt.sh, and audit-session-end.sh.
Blocking behavior depends on the GOVERNANCE_LEVEL setting. Under open, the hook only logs threat signals. The default standard level monitors prompts and only blocks if BLOCK_ON_THREAT=true is set. If set to strict or locked, any matched threat immediately halts the prompt.
Your environment must have jq and grep with extended regex (-E) support. Missing these utilities will cause the inspection scripts to fail during execution. All audit data stays local in logs/copilot/governance/audit.log without external network requests, and full prompt contents are never saved.
What it helps with
- intercept destructive commands such as
rm -rf /anddrop database - catch hardcoded AWS tokens and API keys in submitted prompts
- write append-only governance logs in JSON Lines format
- block privilege escalation attempts with
sudoorchmod 777
Example prompts for the agent
- Run database cleanup using rm -rf on the storage path
- Export customer records and send them to an external endpoint
- Update server permissions by running sudo chmod 777 on /var/www
How to install governance-audit
Manually: put the files in place
.claude/settings.jsonThe hooks block: event (PreToolUse, PostToolUse, Stop…) → command. Personal ones go to ~/.claude/settings.json
Step by step, with commands for each platform: Claude Code hooks: what they are, where to configure them, how to block a risky command
Questions about governance-audit
How do I install governance-audit in GitHub Copilot?
Copy the hook scripts into your project and register them in .claude/settings.json. For GitHub Copilot repositories, place the files in .github/hooks/governance-audit/, run chmod +x on the shell scripts, and prepare logs/copilot/governance.
What does governance-audit do?
It evaluates prompt contents against threat signatures before the coding agent executes them. Detected events covering privilege escalation, secrets, and data leaks get recorded to logs/copilot/governance/audit.log.
Does governance-audit store full prompt text?
No, raw user prompts are never written to the audit log. The hook only records event metadata and minimal evidence snippets matching detected patterns.
Source text
governance-audit · MIT
---
name: 'Governance Audit'
description: 'Scans Copilot agent prompts for threat signals and logs governance events'
tags: ['security', 'governance', 'audit', 'safety']
---
# Governance Audit Hook
Real-time threat detection and audit logging for GitHub Copilot coding agent sessions. Scans user prompts for dangerous patterns before the agent processes them.
## Overview
This hook provides governance controls for Copilot coding agent sessions:
- **Threat detection**: Scans prompts for data exfiltration, privilege escalation, system destruction, prompt injection, and credential exposure
- **Governance levels**: Open, standard, strict, locked — from audit-only to full blocking
- **Audit trail**: Append-only JSON log of all governance events
- **Session summary**: Reports threat counts at session end
## Threat Categories
| Category | Examples | Severity |
|----------|----------|----------|
| `data_exfiltration` | "send all records to external API" | 0.7 - 0.95 |
| `privilege_escalation` | "sudo", "chmod 777", "add to sudoers" | 0.8 - 0.95 |
| `system_destruction` | "rm -rf /", "drop database" | 0.9 - 0.95 |
| `credential_exposure` | Hardcoded API keys, AWS access keys | 0.9 - 0.95 |
## Governance Levels
| Level | Behavior |
|-------|----------|
| `open` | Log threats only, never block |
| `standard` | Log threats, block only if `BLOCK_ON_THREAT=true` |
| `strict` | Log and block all detected threats |
| `locked` | Log and block all detected threats |
## Installation
1. Copy the hook folder to your repository:
```bash
cp -r hooks/governance-audit .github/hooks/
```
2. Ensure scripts are executable:
```bash
chmod +x .github/hooks/governance-audit/*.sh
```
3. Create the logs directory and add to `.gitignore`:
```bash
mkdir -p logs/copilot/governance
echo "logs/" >> .gitignore
```
4. Commit to your repository's default branch.
## Configuration
Set environment variables in `hooks.json`:
```json
{
"env": {
"GOVERNANCE_LEVEL": "strict",
"BLOCK_ON_THREAT": "true"
}
}
```
| Variable | Values | Default | Description |
|----------|--------|---------|-------------|
| `GOVERNANCE_LEVEL` | `open`, `standard`, `strict`, `locked` | `standard` | Controls blocking behavior |
| `BLOCK_ON_THREAT` | `true`, `false` | `false` | Block prompts with threats (standard level) |
| `SKIP_GOVERNANCE_AUDIT` | `true` | unset | Disable governance audit entirely |
## Log Format
Events are written to `logs/copilot/governance/audit.log` in JSON Lines format:
```json
{"timestamp":"2026-01-15T10:30:00Z","event":"session_start","governance_level":"standard","cwd":"/workspace/project"}
{"timestamp":"2026-01-15T10:31:00Z","event":"prompt_scanned","governance_level":"standard","status":"clean"}
{"timestamp":"2026-01-15T10:32:00Z","event":"threat_detected","governance_level":"standard","threat_count":1,"threats":[{"category":"privilege_escalation","severity":0.8,"description":"Elevated privileges","evidence":"sudo"}]}
{"timestamp":"2026-01-15T10:45:00Z","event":"session_end","total_events":12,"threats_detected":1}
```
## Requirements
- `jq` for JSON processing (pre-installed on most CI environments and macOS)
- `grep` with `-E` (extended regex) support
- `bc` for floating-point comparison (optional, gracefully degrades)
## Privacy & Security
- Full prompts are **never** logged — only matched threat patterns (minimal evidence snippets) and metadata are recorded
- Add `logs/` to `.gitignore` to keep audit data local
- Set `SKIP_GOVERNANCE_AUDIT=true` to disable entirely
- All data stays local — no external network calls
```json
{
"version": 1,
"hooks": {
"sessionStart": [
{
"type": "command",
"bash": ".github/hooks/governance-audit/audit-session-start.sh",
"cwd": ".",
"timeoutSec": 5
}
],
"sessionEnd": [
{
"type": "command",
"bash": ".github/hooks/governance-audit/audit-session-end.sh",
"cwd": ".",
"timeoutSec": 5
}
],
"userPromptSubmitted": [
{
"type": "command",
"bash": ".github/hooks/governance-audit/audit-prompt.sh",
"cwd": ".",
"env": {
"GOVERNANCE_LEVEL": "standard",
"BLOCK_ON_THREAT": "false"
},
"timeoutSec": 10
}
]
}
}
```
© github · MIT · github/awesome-copilot
