> ## 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).

## Coverage

| Surface     | Monitor | Block | Redact |
| ----------- | :-----: | :---: | :----: |
| LLM input   |    ✅    |   ❌   |    ❌   |
| LLM output  |    ➖    |   ➖   |    ➖   |
| Tool call   |    ✅    |   ✅   |    ❌   |
| Tool result |    ✅    |   ⚠️  |    ❌   |

**Ask** — honoured on tool calls, through Copilot's approval prompt. In Copilot
cloud there is no user present, so `ask` becomes deny.

**Use it when** your developers use Copilot CLI or Agent mode and you want its
tool calls governed. **Not when** you need to stop a prompt: Copilot discards
command-hook output at `userPromptSubmitted`, so prompts are **audit-only** and
enforcement happens at the tool events.

**Limits.** Inline code completions expose no hooks and are out of scope. No
redaction, no coverage of the model's response, and tool declarations are not
evaluated. On tool results the collector flags untrusted content rather than
removing it.

Full comparison: [Coverage](/trustguard/integrations/coverage).

## Console setup

1. Create a **GitHub Copilot** collector (Catalog → IDE & 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)