Microsoft Security Agent Toolkit

The action layer for Microsoft Security AI agents.

MCP servers · KQL snippets · Logic Apps templates · end-to-end demos that pair with microsoft-security-skills.

---

Why this repo exists

The companion plugin microsoft-security-skills gives an AI agent knowledge - the workflows, decision trees, and guardrails for working with Defender, Sentinel, Entra, Purview, Intune, and Security Copilot.

Knowledge alone is not enough. To investigate a real incident or run a real hunt, the agent also needs access to live tenant data: incidents in Microsoft Defender XDR, KQL on a Sentinel workspace, Entra sign-ins via Microsoft Graph, Purview Audit logs, and so on.

This repo is that action layer. It ships:

• MCP servers for Sentinel, Defender XDR, Microsoft Graph (Entra), and Purview Audit
• KQL snippet packs mapped to MITRE ATT&CK and grouped by data plane
• Logic Apps and Copilot Studio templates referenced by skills' SOAR sections
• End-to-end demos that wire a skill, an MCP server, and sample data into a runnable scenario

microsoft-security-skills          microsoft-security-agent-toolkit
        (brain)                              (hands)
   "how to do BEC IR"           +    "run KQL, read incidents,
   "when to revoke sessions"         revoke sessions, query Audit"

Together they let an AI agent do real Microsoft SOC work end-to-end - not just answer questions about it.

Status

Preview. Stubs are in place for the four MCP servers and the demo scenarios; production-ready implementations land in subsequent releases. See issues for the roadmap.

Repo layout

microsoft-security-agent-toolkit/
├── docs/                       Deployment shapes, permissions, secrets
├── mcp-servers/                MCP servers for live tenant data
│   ├── sentinel-mcp/           KQL on Log Analytics workspace
│   ├── defender-xdr-mcp/       Incidents, alerts, advanced hunting
│   ├── graph-security-mcp/     Entra sign-ins, risky users, audit
│   └── purview-audit-mcp/      Audit search, eDiscovery
├── kql-snippets/               Runnable KQL grouped by data plane
│   ├── identity/               Sign-in patterns, MFA bypass
│   ├── endpoint/               MDE schema patterns
│   ├── email/                  MDO BEC and phishing patterns
│   └── data/                   Purview / MDA exfiltration patterns
├── playbooks/                  SOAR templates referenced by skills
│   ├── logic-apps/             Sentinel automation
│   └── copilot-studio/         Prompt-flow templates
├── samples/                    End-to-end demos
│   ├── bec-investigation-demo/
│   ├── identity-compromise-demo/
│   └── secops-modernization-demo/
├── INTEGRATIONS.md             Which skill needs which tool
├── .env.example                Required environment variables
└── README.md

Three deployment shapes

The toolkit is designed for three audiences that all consume the same skills knowledge layer:

1. Security Copilot user (lowest effort)

You already have a Microsoft Security Copilot license. You install microsoft-security-skills into your AI agent (Copilot in VS Code, Claude Code, Cursor, etc.) for knowledge, and use Security Copilot's first-party plugins for the live data layer. Nothing from this repo is required.

2. IDE-native analyst (Cursor / Claude / Copilot CLI)

You live in an IDE or CLI, not the Defender / Sentinel portal. You install:

• microsoft-security-skills (knowledge)
• One or more MCP servers from this repo (live data)

The agent pulls live data via MCP, applies the skill's workflow, and reasons about what it sees. This is where the toolkit is most differentiated.

3. Custom SOC agent (programmatic)

You are building an internal SOC agent (Copilot Studio, AutoGen, LangGraph, custom). You mount:

• The skills as the system-prompt knowledge layer
• The MCP servers and / or the underlying APIs (Defender XDR REST, Sentinel REST, Microsoft Graph, Purview) as tools

This is the enterprise pattern.

See docs/deployment-shapes.md for full setup details for each.

Quick start (deployment shape 2)

Prereqs: an AI host that supports MCP (Claude Code, Cursor, Copilot CLI, etc.), the microsoft-security-skills plugin installed, and read access to your Microsoft tenant.

# 1. Clone
git clone https://github.com/vinayaklatthe/microsoft-security-agent-toolkit.git
cd microsoft-security-agent-toolkit

# 2. Configure secrets (do not commit)
cp .env.example .env
# fill in TENANT_ID, CLIENT_ID, CLIENT_SECRET, WORKSPACE_ID, etc.

# 3. Install your chosen MCP server (example: Sentinel)
cd mcp-servers/sentinel-mcp
# follow the per-server README for run / install instructions

# 4. Register the MCP server with your AI host
# (config snippet provided per host in the per-server README)

Then in your AI agent, ask something like:

"Pull incident 12847 from Defender XDR, then hunt for related sign-in anomalies in Sentinel for the affected user over the last 7 days."

The agent matches the relevant skill (e.g. identity-compromise-investigation), routes the data calls to the MCP servers you have registered, and produces a structured investigation timeline.

Permissions and secrets

This toolkit talks to your live Microsoft tenant. Read docs/permissions-required.md and docs/secrets-management.md before running anything. Short version:

• Use a dedicated app registration with read-only Graph / Defender / Sentinel / Purview scopes for everyday hunting.
• Use a second app registration with write scopes (revoke sessions, disable users, kill mailbox rules) only when the agent is allowed to take action - and gate it behind human approval.
• Never commit .env or any tenant secrets. .gitignore covers .env by default.

Pairs with microsoft-security-skills

This repo is intentionally thin on its own. The opinionated workflow logic lives in microsoft-security-skills; this repo provides only the executable surface those skills call into. See INTEGRATIONS.md for the skill <-> tool mapping.

License

MIT. See LICENSE.