Getting Started

The team runs inside GitHub Copilot CLI — and natively on Claude Code, OpenAI Codex CLI, and Cursor (see AI Model Runtimes). Clone the repo, open it in your AI runtime, then drive the engagement either through the Pentest Manager agent or the slash-command shortcuts. Every run is read-only by default — enforced by the same guard core on every runtime — and writes all of its output into a single timestamped session folder.

git clone https://github.com/Contoso-State/red-team-agent-orchestration.git
cd red-team-agent-orchestration

Prerequisites¶

Install these once, then verify your machine is ready:

Minimum Azure RBAC on the target scope is Reader + Security Reader; Log Analytics Reader, Directory Reader, and Key Vault Reader improve coverage. Keep it read-only — assign your identity read roles only.

For a hardened least-privilege setup across both Azure RBAC and Entra ID, see Permissions & Least Privilege.

Run the environment doctor to confirm everything in one shot (it’s read-only and tells you how to fix anything missing):

node tools/preflight/check-environment.mjs

1. Define engagement scope¶

Run the guided setup — it lists the subscriptions you can access, asks which single subscription to assess, and writes engagement.yaml for you:

/setup

Single-subscription contract: one engagement run targets exactly one subscription. To assess additional subscriptions, run a separate engagement.

Prefer to do it by hand? Copy the template instead:

cp engagement.example.yaml engagement.yaml
# Edit engagement.yaml with target subscription, tenant, and permissions

2. Start the Pentest Manager¶

/agent redteam-orchestrator

This launches the Orchestrator (Pentest Manager), which dispatches the domain sub-agents for you. The slash commands below are shortcuts that drive the same team.

3. Run reconnaissance¶

/recon

The orchestrator will:

• Open a fresh per-run session folder engagements/<session>/ (where <session> = <engagement-id>-<timestamp>) that holds all output for this run and is gitignored.

• Validate your Azure permissions (preflight).

• Enumerate all resources in scope.

• Build a resource inventory.

• Identify which domain agents to dispatch.

4. Run the full assessment¶

/assess

Dispatches all domain agents against the inventory. Each agent produces structured findings in engagements/<session>/findings/raw/. Agents read cached resource config from the engagement datastore instead of re-querying Azure, so large estates stay fast.

5. Analyze attack paths¶

/attack-paths

Correlates findings across domains to identify multi-step compromise chains.

6. Generate the report¶

/report

Normalizes findings, deduplicates, reconciles severity, and generates the executive summary, technical report, normalized findings.json, and an interactive HTML report. It also folds the run into the datastore’s history and emits a delta.json of what changed since last time. See Reporting for the full deliverable set and a live sample.

7. Build the presentation deck¶

/deck

Renders a PowerPoint-convertible slide deck. Convert it to .pptx with Marp or Pandoc:

npx @marp-team/marp-cli engagements/<session>/reports/assessment-deck.md -o assessment-deck.pptx
# or
pandoc engagements/<session>/reports/assessment-deck.md -o assessment-deck.pptx --slide-level=2

/report also emits this deck automatically.

Slash commands¶

Next: see the Agent Team that powers these commands, or review Safety & Authorization before running against a real environment.