Skip to content
xdr-cli
BUILT FOR AI AGENTS / OPEN SOURCE

Defender XDR
for your coding agent.

xdr-cli is built for an AI agent to drive. Give your coding agent access to Defender incidents and advanced hunting, with investigation playbooks and output designed for its context window.

Put the coding-agent subscription you already have to work on incident triage.

Start investigating Set up your agent
INSTALL WITH PIPXPython 3.11+
pipx install "git+https://github.com/NerfBlasters/m365-xdr-cli.git"
analyst@workstation: ~xdr
# List recent high-severity incidents$ xdr incidents list --since 7d \
  --severity high
# Read the alerts and their evidence$ xdr incidents show 42 --expand alerts
# Run the guided investigation$ xdr investigate 42
Incident context Entities & evidence Relevant hunts Suggested next steps
Review the evidence before taking action.
Illustrative workflow · replace 42 with your incident ID
Defender permissions apply Local JSONL evidence Works with AI assistantsMIT licensed
EXAMPLE PROMPT

Read AGENTS.md, then investigate incident 42. Summarize the evidence and flag anything that needs my review.

Use an incident ID from your tenant.
AGENT-DRIVEN INVESTIGATIONS

Your coding agent can investigate incidents

Point your agent at AGENTS.md and ask it to investigate an incident. The instructions cover how to gather evidence, choose hunts, and report what it found. You review its conclusions and decide on response actions.

xdr-cli saves large results locally and returns a compact receipt. An agent can inspect the evidence a few rows at a time, using the same xdr commands you can run yourself.

Set up your assistant
INCIDENTS & HUNTING

The commands you'll use most

Start with the incident's alerts and evidence. Run a library query or your own KQL when you need more detail.

01 / TRIAGE

Read the incident and its alerts

View alert evidence, including affected accounts and devices. The guided investigation extracts those entities and suggests queries to investigate them further.

Read the investigation guide
02 / HUNT

Run a saved hunt or write KQL

The query library covers common investigations and accepts parameters for the accounts, devices, or time range you're working with. You can also run KQL directly.

Browse the query library
03 / RESULTS

Use the results in your own tools

Large results are saved as local JSONL files. A receipt tells you where to find them, so you can inspect the data with jq, grep, Python, or xdr results.

Read about result files
TERMINAL DEMO

Watch an investigation

Try the walkthrough
xdr investigate <incident-id>

Watch a guided investigation from the terminal.

Demo tenant; tenant and object identifiers replaced for publication.Read the text walkthrough
GUIDES & REFERENCE

RTFM

Read the fu....n.. manual

All documentation
01

Installation and setup

Install xdr-cli and connect it to your Defender tenant.

02

Query library

Find a hunting query and check which parameters it needs.

03

Investigation playbooks

Look up an alert title for investigation steps and common false positives.

04

AI assistants

Set up an agent to use xdr-cli and read its results.