> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Copilot

> Ask or deny tool calls and flag poisoned tool results in Copilot CLI and VS Code Agent mode with TrustGuard lifecycle hooks.

Copilot's agent surfaces — **Copilot CLI** and **VS Code Agent mode** — run
shell commands and call MCP tools on the developer machine. The
[TrustGuard Copilot plugin](https://github.com/NeuralTrust/trustguard-copilot-plugin)
puts your org's policy check at each of those moments:

| Moment                                 | What you can stop                                                                                                                                                                                           | Enforcement                                                                                                                 |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Prompt, before submit                  | Visibility into jailbreaks ([Prompt Guard](/trustguard/detectors/content-security#prompt-guard--prompt_guard)) and secrets or PII pasted into the agent ([DLP](/trustguard/detectors/data-loss-prevention)) | **Audit only** — Copilot discards command-hook output at this event, so findings are recorded but the prompt is not blocked |
| Tool call, before it runs (shell, MCP) | Dangerous or out-of-policy commands; risky MCP tool calls                                                                                                                                                   | **Deny** or **Ask** (Copilot approval prompt)                                                                               |
| Tool result, after it runs             | [Indirect prompt injection](/trustguard/detectors/agent-mcp-security) in MCP / tool output                                                                                                                  | **Flag** — the result is marked as untrusted context for the model; `postToolUse` cannot undo the call                      |

Every decision lands in **Activity** with
`source.application = copilot-plugin`, so you also get an audit trail; start in
**Report** policy mode to observe before enforcing.

Coverage limits: **inline completions (ghost text) expose no hooks** and are
out of scope. Copilot **cloud** coding-agent jobs load only hooks committed
under `.github/hooks/*.json` — see [Cloud coding agent](#cloud-coding-agent).

## Console setup

1. Create a **GitHub Copilot** collector (Catalog → AI assistants & coding agents).
2. Mint a `tgk_…` API key on the **Auth** tab (shown once — store it).
3. Assign a default [policy](/trustguard/concepts/policies) on the **Policies** tab.

## Local / pilot

Copilot CLI has a plugin marketplace flow:

```bash theme={null}
copilot plugin marketplace add NeuralTrust/trustguard-copilot-plugin
copilot plugin install trustguard@neuraltrust
```

Then write the API key config:

```json theme={null}
// ~/.trustguard/copilot.json  (chmod 600)
{
  "data_url": "https://<your-trustguard-host>",
  "api_key": "tgk_…",
  "fail_mode": "open"
}
```

Environment variables (`TRUSTGUARD_DATA_URL`, `TRUSTGUARD_API_KEY`,
`TRUSTGUARD_FAIL_MODE`, `TRUSTGUARD_TIMEOUT_MS`, `TRUSTGUARD_TRANSFORM_ACTION`,
`TRUSTGUARD_CONSUMER_ID`) override the user file.

If a personal install is incomplete, the marketplace bootstrap emits `{}` and
exits 0 on purpose — Copilot's `preToolUse` command hooks fail **closed** on
non-zero exits, and a half-installed plugin must not brick Copilot.

## Enterprise

IT deploys **policy hooks**, which Copilot CLI loads machine-wide **before**
user, repository, and plugin hooks — developers cannot disable them
(`disableAllHooks` does not apply). Kandji scripts live under
[`mdm/kandji/`](https://github.com/NeuralTrust/trustguard-copilot-plugin/tree/main/mdm/kandji);
they install four pieces:

| Piece                    | Path (macOS)                                                     |
| ------------------------ | ---------------------------------------------------------------- |
| Collector binary         | `/Library/Application Support/TrustGuard/bin/trustguard-copilot` |
| Managed config (`tgk_…`) | `/Library/Application Support/TrustGuard/copilot.json`           |
| Wrapper                  | `/usr/local/bin/trustguard-policy-hook`                          |
| Policy hook file         | `/etc/github-copilot/policy.d/10-trustguard.json`                |

| OS      | Collector                                             | Managed config                          | Policy hooks dir                          |
| ------- | ----------------------------------------------------- | --------------------------------------- | ----------------------------------------- |
| macOS   | `…/TrustGuard/bin/trustguard-copilot`                 | `…/TrustGuard/copilot.json`             | `/etc/github-copilot/policy.d/`           |
| Linux   | `/opt/trustguard/bin/` or `/usr/local/bin/`           | `/etc/trustguard/copilot.json`          | `/etc/github-copilot/policy.d/`           |
| Windows | `%ProgramData%\TrustGuard\bin\trustguard-copilot.exe` | `%ProgramData%\TrustGuard\copilot.json` | `C:\ProgramData\GitHub\Copilot\policy.d\` |

The policy hook file calls the **wrapper**, not the collector directly, so one
file works across platforms (`TRUSTGUARD_COPILOT_BIN` overrides the lookup).
The wrapper distinguishes two failures on purpose: collector **not installed**
→ allow (a machine mid-provisioning is not bricked); collector **installed but
failing** → `preToolUse` is denied and `postToolUse` output marked untrusted.
Normal data-plane errors follow the configured `fail_mode`.

**VS Code Agent mode:** install the plugin from the organization marketplace.
Agent hooks are currently a VS Code **preview** feature — ensure enterprise
policy permits hooks and controls marketplace sources.

### Cloud coding agent

Cloud jobs receive no local plugins, user hooks, MDM files, or policy hooks. To
cover them:

1. Commit a Copilot hook file under `.github/hooks/`.
2. Make the collector binary available in the job image (or use an HTTP hook
   endpoint that accepts Copilot's event payload).
3. Add the TrustGuard host to the cloud-agent firewall allowlist.
4. Provide credentials through the approved GitHub environment mechanism.

In cloud, **ask is treated as deny** (no user present) and `userPromptSubmitted`
remains audit-only.

## Verify

1. Run Copilot CLI and send a test prompt, then trigger a shell tool call.
2. Confirm the events in TrustGuard **Activity**
   (`source.application = copilot-plugin`).

Smoke-test the binary (optional):

```bash theme={null}
echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"},"session_id":"pilot"}' \
  | trustguard-copilot hook
```

## What is evaluated

| Copilot event                    | TrustGuard protocol | Direction | Notes                                                  |
| -------------------------------- | ------------------- | --------- | ------------------------------------------------------ |
| `userPromptSubmitted`            | `llm`               | input     | Audit-only — Copilot discards command-hook output      |
| `preToolUse` (shell)             | `all`               | input     | `allow`, `ask`, or `deny`                              |
| `preToolUse` (MCP / other tools) | `mcp` tools/call    | input     | Same verdicts                                          |
| `postToolUse`                    | `mcp` result        | output    | Blocked / sensitive output marked as untrusted context |

## Attributes

* `attributes.source.application = "copilot-plugin"`
* `attributes.copilot.*` — the full hook stdin JSON is preserved
* `consumer_id` sent only when configured explicitly
  (`TRUSTGUARD_CONSUMER_ID` / `consumer_id` in `copilot.json`)

## Related

* [Plugin README](https://github.com/NeuralTrust/trustguard-copilot-plugin)
* [Enterprise deployment guide](https://github.com/NeuralTrust/trustguard-copilot-plugin/blob/main/docs/enterprise.md)
* [Policies — Gates](/trustguard/concepts/policies#gates)
* [Evaluate API](/trustguard/api/evaluate)