microsoft-security-agent-toolkit

# Copilot / AI agent instructions for `microsoft-security-agent-toolkit`

This file is automatically loaded as context by GitHub Copilot Chat in VS Code (and respected by most other VS Code AI agents) when working in this repo.

## Read this first

**Always read `HANDOFF.md` at the repo root before making any change.** It contains the design decisions, conventions, and open work prioritization that you will not be able to infer from the code alone.

## What this repo is

The action layer for AI agents working on Microsoft Security. Pairs with [`microsoft-security-skills`](https://github.com/vinayaklatthe/microsoft-security-skills) (skills give the agent knowledge; this toolkit lets it act on live tenant data).

Status: preview. Scaffold complete; MCP server implementations pending.

## Hard rules

- **Never log or commit a tenant secret.** `.env` is gitignored. Do not add it back. Do not paste real `CLIENT_SECRET` / tokens into commits, tests, or docs.
- **Every write tool** (anything that mutates tenant state) must take an explicit `confirm: true` parameter, must be marked `(write)` in the server README's tool table, and must use the separate write-app registration documented in `docs/permissions-required.md`.
- **Skills do not bundle this toolkit.** They only declare `tools_required` in front-matter. The host routes the declaration to whichever provider is registered. Do not change this contract without updating both repos.
- **No offensive tooling.** This is defensive-and-governance only. Generic red-team content belongs elsewhere.
- **No live tenant calls in tests, demos, or samples.** Use synthetic data.

## Conventions

- Conventional-commit-ish messages (`scaffold:`, `feat(sentinel-mcp):`, `docs:`, `kql:`). Always include `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>` when AI-assisted.
- Branch off `main`, open a PR — do not merge directly.
- One server / one snippet pack / one demo per PR.
- KQL files in `kql-snippets/` must have the header documented in `kql-snippets/README.md` (Title / MITRE / Data source / Use case / Tuning / Author / License).
- MCP server READMEs must follow the contract documented in `HANDOFF.md` (Tool ID table → Configuration → Alternatives → Cross-links).

## Tool surface (the contract you are building toward)

The full skill ↔ tool matrix is in `INTEGRATIONS.md`. Stable tool IDs:

- `sentinel.run_kql`, `sentinel.list_incidents`, `sentinel.get_incident`, `sentinel.update_incident` (write)
- `defender_xdr.list_alerts`, `defender_xdr.get_incident`, `defender_xdr.run_advanced_hunting`, `defender_xdr.update_incident` (write), `defender_xdr.isolate_device` (write)
- `graph.signins`, `graph.risky_users`, `graph.directory_audit`, `graph.revoke_sessions` (write), `graph.disable_user` (write)
- `purview_audit.search`, `purview_audit.export`

Do not rename these without updating `INTEGRATIONS.md` in **both** this repo and `microsoft-security-skills`.

## Companion repo

- `microsoft-security-skills` v0.2.0, 88 skills.
- Validators: `validation/check-structure.mjs` (offline), `validation/check-links.mjs` (network).
- Quirk: the section header `## Approach` must match literally; use `### Subsection` underneath, never `## Approach (X)`.

## When stuck

Pick the topmost unchecked item from the "Open work" section in `HANDOFF.md`. Phase 1 (`sentinel-mcp` end-to-end) is currently the highest-ROI starting point.