sec-sre-ag — SRE Agent Custom Skills

This repository provides custom skills and runtime scripts that turn Azure SRE Agent into a security operations assistant. It integrates with Microsoft Sentinel, Microsoft Defender XDR, Microsoft Entra ID, Microsoft Graph, Azure Monitor, and selected threat-intelligence services. Supported use cases include daily threat posture scans, incident listing, investigation, statistics, and commenting; forensic investigation of users, endpoints, and indicators of compromise; identity posture assessment; KQL query authoring and validation; MITRE ATT&CK coverage analysis; Sentinel ingestion optimization; and MCP usage monitoring. Skills accept natural-language requests, collect evidence through approved agent tools, run repository scripts through Code Access, and produce structured findings, charts, and HTML reports. Top-level skill directories hold Python runtime code and data, while .builder holds deployable Skill Builder instructions and supporting documents. The setup assets create or update the skills and configure the identities, permissions, connectors, and data sources required for customer-owned Azure SRE Agent deployments.

Performs comprehensive security investigations on Windows, macOS, and Linux devices registered in Microsoft Entra ID and onboarded to Microsoft Defender for Endpoint. Collects device context, process execution history, network connections, registry persistence, file activity, vulnerability assessment, and risk scoring.

Audits organization-wide identity security posture using Microsoft Graph API and Log Analytics. Covers user inventory, directory roles, PIM assignments, Identity Protection risk signals, MFA registration, deleted accounts, stale account detection, password posture, and department-level breakdowns. Produces an HTML report with a composite posture score.

Posts content as a comment on a Microsoft Sentinel incident. Accepts plain text, Markdown, or HTML. Plain text is posted as-is; Markdown is converted to HTML optimized for the narrow Activities panel; HTML is adapted for single-column display. All input content is preserved in full — no summarization or truncation — unless the user explicitly requests it.

Deep-dives into individual security incidents from Microsoft Defender XDR / Microsoft Sentinel. Retrieves incident metadata, associated alerts, affected assets, and evidence, then orchestrates sub-investigations for involved users, devices, and IoCs. Includes cache management for reusable investigation data across sessions.

Lists recent security incidents from the Sentinel SecurityIncident table aligned with the Defender XDR portal view. Filters by last modification time, excludes phantom incidents (auto-closed with no alerts), and projects ID, title, severity, status, owner, and alert count.

Generates comprehensive incident statistics and SOC metrics from Microsoft Sentinel: severity distribution, MTTA/MTTR analysis, affected users and devices, assignee breakdown, MITRE tactics correlation, true-positive rate, and operational trends. Produces tabular data plus graphical charts.

Investigates Indicators of Compromise — IP addresses, domains, URLs, and file hashes. Correlates IoCs with threat intelligence, identifies associated CVEs, enumerates affected organizational assets, and provides third-party enrichment via ipinfo.io, vpnapi.io, AbuseIPDB, and Shodan.

Generates validated, production-ready KQL queries for Microsoft Sentinel, Defender XDR Advanced Hunting, and Azure Data Explorer. Combines schema validation, official Microsoft Learn documentation, and community examples with platform-specific adaptation and known table-pitfall mitigation.

Monitors and audits Model Context Protocol (MCP) server usage across Sentinel and Defender XDR. Tracks Graph MCP, Data Lake MCP, Triage MCP, and Azure MCP activity with user attribution, endpoint access patterns, sensitive API detection, cross-MCP footprint analysis, and usage scoring.

Generates a comprehensive MITRE ATT&CK coverage analysis. Maps analytic rules and custom detections to tactics and techniques, identifies gaps against the full Enterprise matrix, correlates operational alerts and incidents, and scores coverage across five dimensions. Includes SOC Optimization threat-scenario alignment and untagged-rule remediation recommendations.

Analyzes Sentinel workspace data ingestion: table-level volume breakdown, tier classification (Analytics / Basic / Data Lake), deep dives into high-volume tables, ingestion anomaly detection with 24-hour and week-over-week trending, analytic rule health monitoring, tier migration candidates, and license benefit analysis for Defender for Servers P2 and Microsoft 365 E5.

Performs a rapid, broad-spectrum security scan across seven domains — incidents, identity, nonhuman identities, endpoint, email, admin/cloud, and exposure — in roughly 15 minutes. Presents findings as a prioritized dashboard with drill-down recommendations to specialized investigation skills. Ideal as a daily SOC starting point.

Performs comprehensive security investigations on Entra ID user accounts. Collects identity context, sign-in activity analysis, email and Office 365 activity, audit trail events, UEBA behavioral anomalies, and IP enrichment via third-party APIs. Provides risk assessment, incident correlation, and forensic timeline reconstruction.

Complete these prerequisites before starting Setup. One person does not need to hold every role: a GitHub administrator, Entra administrator, Azure platform administrator, and Microsoft 365 service owner can perform their respective steps. Use time-bound elevation and the narrowest practical scope.

• A GitHub account that can create a repository in the target organization, grant the required repository access, and clone the repository to the local computer. Install Git and confirm that outbound HTTPS to github.com is allowed.
• The latest stable Python release available for .builder/deploy/deploy_skills.py and local script validation. The latest tests were performed with Python 3.14.7. The deployer uses the standard library; PyYAML is optional.
• Azure CLI installed on the workstation used to run the Python deployment tool and authenticated to the Entra tenant that owns the target subscription. Use az login, or az login --tenant <TARGET_TENANT_ID> when the target tenant differs from the operator's default tenant.
• A modern browser that permits OAuth pop-ups from sre.azure.com. Node.js/npm is needed only when running an npx-based MCP server locally; the configured kql-search-mcp connector itself invokes npx in its connector runtime.

• An active Azure subscription with sufficient credit or billing capacity for Azure SRE Agent, its supporting Application Insights and Log Analytics resources, and the customer's Sentinel ingestion and retention. SRE Agent is usage-billed in Azure Agent Units (AAUs): always-on charges continue while an agent exists, and active-flow charges accrue while it processes work. Review Pricing and billing and set the monthly AAU allocation before production use.
• The Microsoft.App resource provider registered, a resource group for the agent, and permission to deploy in a currently supported SRE Agent region. See Minimum administrative access below for the required roles. Confirm current regions in the portal rather than relying on a static list.
• Network access from the browser and administrative workstation to sre.azure.com, *.azuresre.ai, Azure Resource Manager (including https://management.azure.com), the Azure SRE Agent data plane, Microsoft Entra ID, Microsoft Graph, Azure Monitor/Log Analytics endpoints, GitHub, and the OAuth endpoints used by Teams and Exchange Online. In particular, the workstation that runs the Python deployment tool must be able to reach the Azure management and SRE Agent endpoints.
• A running Microsoft Sentinel Log Analytics workspace containing the data that the selected skills need. Required Sentinel, Defender, Entra, Microsoft 365, and Identity Protection licenses must already be assigned. In particular, Identity Protection risk data requires Entra ID P2, endpoint investigations require Defender for Endpoint, and using the Teams and Outlook notification connectors requires appropriately licensed Teams and Exchange Online accounts.

To complete the setup procedure end to end, ensure that the following minimum privileges are available before starting:

1. Contributor plus Role Based Access Control Administrator on the target subscription or target resource group.
2. Privileged Role Administrator or Global Administrator in the target Entra tenant. This Entra role is needed only to run setup/assign-permissions.sh, which assigns Microsoft Graph and Defender API Application permissions to the new SRE Agent UAMI.

The detailed table below is intended for a setup split into separate phases and delegated to different operators with the minimum authorization required for each activity. It separates Azure RBAC, SRE Agent roles, Entra roles, and external-service permissions; these controls are independent and are sometimes required together.

• GitHub: organization permission to create the customer repository and authorize OAuth access to it. For private repositories, the credential must have Metadata and Contents read access. GitHub MCP write workflows additionally need only the selected Contents and Pull requests write permissions. GitHub Enterprise Cloud (<tenant>.ghe.com) requires organization/repository admin access to create and install a BYO GitHub App, plus a Key Vault and an agent identity with Key Vault Secrets User on that vault.
• Exchange Online and Microsoft Teams: the managed connectors run in the security context of the user who completes each OAuth connection. Emails and Teams messages therefore show that user as the sender. Until agent-user authentication is supported, use a dedicated service account with an active mailbox and Teams license, permission to send email, and access to the target teams, channels, and chats. Obtain a channel URL when using the legacy Teams connector.
• Validation: nonproduction recipients and representative test resources, including a mailbox, Teams destination, Sentinel incident, Entra user, and Defender-onboarded device. The tester must be allowed to read those resources and perform the specific write tests described under Validation Tests.

Complete stages A through C first so the API permissions and Azure roles begin propagating before the remaining configuration. This section is the authoritative end-to-end setup procedure for this repository.

Create a repository owned by the customer from https://github.com/stefanpems/sec-sre-ag using one of these options:

1. Fork on GitHub. Select Fork in the source repository and choose the customer's user account or organization as the owner. Because the source repository is public, its owner does not need to enable any additional setting or add the customer as a collaborator. The customer must have permission to create repositories in the destination organization, and that organization's GitHub or GitHub Enterprise policies must allow forks. A fork remains linked to the upstream repository and, as part of a public fork network, may not support the private visibility required by the customer.

2. Import with GitHub Importer. Create a repository from https://github.com/stefanpems/sec-sre-ag.git. This preserves the Git history but creates an independent repository with customer-selected ownership, name, and visibility. No source-repository credentials or configuration are required because the source is public.

3. Clone and push. Create an empty private repository in the customer organization, then run:

   git clone https://github.com/stefanpems/sec-sre-ag.git
   cd sec-sre-ag
   git remote rename origin upstream
   git remote add origin https://github.com/<customer-org>/<customer-repo>.git
   git push -u origin main

   The retained upstream remote can be used to retrieve future source updates with git fetch upstream. Authentication is required only for pushing to the customer repository.

Importing or cloning and pushing into a private repository is recommended when the customer requires a clear ownership, visibility, and governance boundary. Do not deploy directly from stefanpems/sec-sre-ag: the customer copy is the configuration and change-control boundary for its agent. If the source is made private in the future, its owner must grant access and enable private forking at the repository and organization or enterprise level; import and clone operations would also require source credentials.

Grant access only to the administrators and operators who maintain the agent. Enable branch protection and pull-request review if the agent is allowed to write code. Enable secret scanning and push protection where available. Never commit PATs, connector credentials, config.json, generated reports, or investigation output. Treat any token exposed in a screenshot, chat, log, or commit as compromised: revoke it immediately, replace it, and update the connector that used it.

Creating an Azure SRE Agent requires Contributor plus Role Based Access Control Administrator on the target subscription or resource group, or Owner on that scope. Contributor alone is not sufficient. If the resource group does not exist yet, the operator also needs, at least temporarily, permission to create it at subscription scope.

If the customer does not already have an agent, create one at https://sre.azure.com:

1. Select Create agent, then choose the customer subscription and resource group.
2. Enter a customer-specific name, choose a currently supported region, and assign only the resource groups required by the security operations use cases. Start with Reader access.
3. Complete deployment and wait until the agent state is Running.
4. Record the agent's managed identity. Use a user-assigned managed identity when it must be shared across connectors, managed independently, or retained outside the agent lifecycle.

Agent provisioning also creates supporting Application Insights and Log Analytics resources. That telemetry workspace is not automatically the customer's Microsoft Sentinel workspace.

Connector setup additionally requires SRE Agent Author or Administrator on the agent.

Perform this step as soon as the agent has been created and its UAMI Object ID and Client ID are available. Run the two permission-assignment scripts promptly: Graph application permissions and Azure RBAC assignments can take up to one hour to propagate, so starting them now avoids delaying later validation.

The accounts that run the assignment scripts require:

• Privileged Role Administrator activated through PIM, or Global Administrator, in the target tenant for assign-permissions.sh.
• Role Based Access Control Administrator or Owner on the target Log Analytics workspace or a parent scope for assign-azure-roles.sh.
• Role Based Access Control Administrator or Owner on the Key Vault or a parent scope when KEYVAULT_RESOURCE_ID is passed as the third argument.

Run setup/discover-setup-ids.sh from Azure Cloud Shell (Bash) before assigning permissions. The script uses read-only Azure CLI commands to list the values required by the assignment scripts:

• UAMI Object ID (principal ID) for assign-permissions.sh
• UAMI Client ID for assign-azure-roles.sh
• Microsoft Sentinel workspace Resource ID
• Key Vault Resource ID, when IP enrichment is enabled

git clone https://github.com/<customer-org>/<customer-repo>.git
cd <customer-repo>/setup
chmod +x *.sh
./discover-setup-ids.sh [SUBSCRIPTION_ID]

If the setup files in the customer repository have not been modified, you can instead clone the source repository with git clone https://github.com/stefanpems/sec-sre-ag.git.

The subscription argument is optional. When omitted, the script reads the active Azure CLI subscription. It does not call az account set; the selected subscription is passed explicitly to every resource query. If exactly one UAMI and one Sentinel workspace are found, the output includes ready-to-run commands for both assignment scripts. Otherwise, select the intended resources from the displayed list.

Once the IDs are known, execute the generated commands immediately. Their full arguments and behavior are documented under API Permissions and Azure RBAC Roles:

./assign-permissions.sh <UAMI_OBJECT_ID> <SUBSCRIPTION_ID>
./assign-azure-roles.sh <UAMI_CLIENT_ID> <WORKSPACE_RESOURCE_ID> [KEYVAULT_RESOURCE_ID]

WORKSPACE_RESOURCE_ID is not the Log Analytics Workspace ID/customer ID GUID. It is the workspace's complete Azure Resource Manager resource ID, with this structure:

/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.OperationalInsights/workspaces/<WORKSPACE_NAME>

The scripts verify that the subscription is visible, the supplied identity is a managed identity in the target tenant, and the required assignments exist after execution. If the portal later displays Grant permissions, treat it as an interactive On-Behalf-Of fallback, not as a replacement for assigning Application permissions to the UAMI.

In the agent portal, connect the customer repository under Builder > Code Access. For github.com, prefer GitHub OAuth for interactive Code Access; it does not require a PAT. Code Access provides repository search, reads, and context; it does not create file changes or commits. If the agent must maintain customer-specific skills and scripts, add a separately governed GitHub MCP connector with only the required branch, file, commit, and pull-request tools. Protect main and require changes through reviewed pull requests. Then add the connectors below under Builder > Connectors:

1. Open Builder > Code Access, add GitHub Code Access, and authenticate.
2. For github.com, prefer OAuth and select only the customer repository.
3. Wait until the repository status is Ready, then run the Code Access test under Connector smoke tests.

Code Access supplies repository search, reads, branch selection, and context; it does not provide file edits or commits. GitHub Enterprise Cloud repositories on <tenant>.ghe.com require a customer-owned GitHub App rather than the github.com OAuth flow.

When repository writes are required, add the GitHub MCP partner connector with a separate fine-grained PAT. Enable only the current catalog equivalents for branch creation, file creation or update, commits, and pull requests. Set write tools to Ask, protect main, and require the agent to work through a branch and reviewed pull request rather than writing directly to production.

Use independent credentials with the smallest practical scope:

Use short expirations, record an owner, define rotation, and complete any required organization approval. Never place a real PAT in the repository; enter it only in the connector's protected environment-variable field. Sharing one PAT across these integrations couples rotation and can expose write access to a read-only service, so it is not the recommended design.

For Outlook, add Outlook Tools (Office 365 Outlook), sign in with the dedicated service account, select the agent UAMI, enable Send an email, and set the write operation to Ask for interactive use.

For Teams, sign in with the dedicated service account, select the UAMI, enable the five operations in the connector table, set posting operations to Ask, and leave schema and metadata reads as Allow. Lock a destination parameter only when the agent must never send outside that destination; otherwise leave it agent-defined. Preview operation labels can change, so select the current catalog equivalents when necessary.

These connections use the security context of the user who completes OAuth consent, not the UAMI. Every email or Teams message therefore identifies that user as the sender. Until agent-user authentication is supported, use a dedicated service account with its own mailbox and Teams license. Autonomous mode may execute tools configured as Ask without an interactive approval; review autonomous workflows separately.

1. Add Log Analytics Workspace under Builder > Connectors > Telemetry.
2. Enter a descriptive name, then select the customer subscription, Sentinel workspace, and agent UAMI.
3. Add the connector and confirm it queries the Sentinel workspace rather than the separate workspace created for agent telemetry.

If automatic discovery fails, enter the workspace ARM resource ID, workspace name, and Workspace ID/customer ID manually. A query-time 403 usually means the selected identity lacks Log Analytics Reader or Monitoring Reader at the required scope; the later Azure RBAC step adds the Sentinel-specific roles.

1. Add an MCP connector, choose Stdio, set MCP Server to kql-search-mcp, and set Command to npx.

2. Add -y and kql-search-mcp as two separate arguments.

3. Add the read-only PAT as GITHUB_TOKEN. Optionally set FAVORITE_REPOS to a comma-separated list such as <customer-org>/<customer-repo>,Azure/Azure-Sentinel,microsoft/Microsoft-365-Defender-Hunting-Queries.

4. Select the agent UAMI and enable only these tools:

   • get_table_schema
   • search_github_examples_fallback
   • search_kql_repositories
   • validate_kql_query
   • find_column
   • generate_kql_query
   • search_tables
   • get_query_documentation
   • list_table_categories
   • get_tables_by_category

The repository was verified with package version 1.0.5. That version requires GITHUB_TOKEN and has a known search_favorite_repos parsing issue; use search_github_examples_fallback instead. Do not select every package tool by default: Azure SRE Agent permits at most 80 tools across native and MCP connectors, and a smaller set improves tool-selection accuracy.

Add an MCP connector, choose Streamable HTTP, set MCP Server to ms-learn-mcp, use https://learn.microsoft.com/api/mcp, select No authentication, enable all three returned tools, and verify the connector is Connected.

Use .builder/deploy/deploy_skills.py both for the initial creation of the agent's custom skills and for every subsequent update. The deploy command is idempotent: it sends a PUT for each selected skill, creating it when absent and replacing the existing skill definition and supporting files when present.

Run these commands on a workstation with both the latest stable Python release and Azure CLI installed. Sign in to the target tenant with Azure CLI first, and ensure outbound traffic can reach Azure Resource Manager, including https://management.azure.com, and the Azure SRE Agent data-plane endpoint.

cd .builder/deploy
python deploy_skills.py deploy --dry-run
python deploy_skills.py deploy
python deploy_skills.py list

To update only selected skills, pass their folder names:

python deploy_skills.py deploy --skills identity-posture,incident-investigation

The deployer uploads only Skill Builder content from .builder/<skill>/. Python runtime scripts remain in the top-level skill folders and are obtained through Code Access; they must not be copied into .builder. See the deployment tool guide for target configuration, cross-tenant deployment, and delete operations.

After creating the corresponding incident-investigation and user-investigation HTTP triggers in Azure SRE Agent, optionally deploy either or both parameterized Logic App ARM templates under setup/logic-app. Do not deploy a playbook before its target HTTP trigger exists and its URL has been recorded. Deploy the templates to the same resource group as the Azure SRE Agent; each template exposes only the corresponding HTTP trigger URL and derives all other deployment values from fixed settings or that resource group.

The incident template creates a Sentinel incident-creation playbook. The user template creates an Account Entity playbook that sends the selected user's UPN to Azure SRE Agent. Each template creates its own Microsoft Sentinel connection and system-assigned workflow identity, and assigns the built-in SRE Agent Standard User role to that identity on the deployment resource group.

Use a separate target-specific parameter file containing only the trigger URL for each deployed playbook. Grant Microsoft Sentinel permission to run playbooks in the Logic App resource group separately. The template guide documents the validation, deployment, and post-deployment checks.

Preview portal labels may change; use the current equivalent when a label differs. The setup procedure was checked against:

• Create and set up Azure SRE Agent
• Connect source code
• Set up an Outlook connector
• Set up the Teams connector
• Set up a Log Analytics connector
• MCP connectors and tools
• Set up a GitHub connector
• kql-search-mcp package, verified at version 1.0.5

config.json is runtime configuration for the SRE Agent sandbox. It is not created by the Cloud Shell setup scripts or by the skill deployment tool, and it must not be committed to this repository. Do not confuse it with .builder/deploy/deploy.config.json, which only identifies the agent targeted by the deployment tool.

After connecting this repository and deploying the skills, invoke any skill in the table below. Before it runs its first script, the skill instructions require the agent to:

1. Locate the root of the agent's runtime workspace (the parent of codeRefs/ and tmp/), not the root of a local deployment clone.
2. Check for config.json and validate the required workspace fields.
3. If the file is missing or incomplete, ask only for the tenant name; derive the subscription ID, Log Analytics workspace GUID, and workspace name from the platform-injected <azure_resource_access> and <log_analytics_access> settings.
4. Discover the Log Analytics workspace resource group with the sandbox Azure CLI read tool. The agent must not invoke az in the sandbox terminal.
5. Create and then re-read config.json before continuing. If the platform settings are unavailable or discovery fails, the agent must stop and report the missing value instead of guessing it.

The following deployed skills contain this bootstrap procedure and can create and populate the shared file on their first execution:

This is instruction-driven bootstrap: the agent creates the file through its file and Azure tools. The Python scripts do not create it themselves; they only read it when needed. The first skill invoked in a new sandbox creates the shared file, and later skills reuse it. A new sandbox or conversation may have a fresh workspace, so the same existence check is performed again.

Expected runtime schema:

{
  "tenant_name": "<tenant name, for example contoso.onmicrosoft.com>",
  "sentinel_workspace_id": "<Log Analytics workspace GUID>",
  "subscription_id": "<Azure subscription ID>",
  "azure_mcp": {
    "subscription_id": "<same Azure subscription ID>",
    "resource_group": "<resource group containing the Log Analytics workspace>",
    "workspace_name": "<Log Analytics workspace name>"
  },
  "api_tokens": {}
}

api_tokens remains empty. IP-enrichment tokens are loaded from Key Vault or environment variables at runtime. config.json, output, and report directories are excluded by .gitignore.

Before completing setup sections 1 and 2, clone the repository and make all setup scripts executable in Azure Cloud Shell (Bash):

git clone https://github.com/<customer-org>/<customer-repo>.git
cd <customer-repo>/setup
chmod +x *.sh

If the setup files in the customer repository have not been modified, you can instead clone the source repository with git clone https://github.com/stefanpems/sec-sre-ag.git.

The agent's User-Assigned Managed Identity (UAMI) needs Application permissions on Microsoft Graph and WindowsDefenderATP APIs. Assign them to the identity actually used by the SRE Agent Azure CLI read tool. An identity selected for a connector is not automatically the runtime identity for every agent tool.

These permissions are Entra tenant permissions, not Azure RBAC roles. Reader, Contributor, or Owner on the subscription does not authorize Microsoft Graph /devices, /users, or other directory endpoints. The subscription argument in the setup command selects the tenant from which Azure CLI requests the Graph token; it does not grant Graph access.

All permissions above are Application type (not Delegated). All are read-only except SecurityIncident.ReadWrite.All which is read-write (required to post incident comments).

Run setup/assign-permissions.sh from Azure Cloud Shell (Bash) with an account that has Privileged Role Administrator activated through PIM or Global Administrator in the target tenant:

./assign-permissions.sh <UAMI_OBJECT_ID> <SUBSCRIPTION_ID>

Use the UAMI Object ID / principal ID, not its client ID. The script derives the target tenant from SUBSCRIPTION_ID, passes that subscription to every Graph request, and verifies that the supplied object is a managed identity in that tenant before making changes. It is idempotent and performs a final check that Microsoft Graph Device.Read.All is assigned.

For a cross-tenant setup, first sign in to the target tenant with az login --tenant <TARGET_TENANT_ID>. After the script succeeds, wait up to one hour for token caches to refresh and start a new agent session before retesting.

If the agent displays Grant permissions after a managed identity authorization failure, that is an On-Behalf-Of fallback using the interactive user. The displayed .default scopes request permissions already configured for that client; they do not assign Device.Read.All to the managed identity. Do not use that prompt as the production fix. Assign the Application permission to the UAMI and run Graph GET requests through the Azure CLI read tool.

Note: Skills that depend on Graph API (user-investigation, computer-investigation, identity-posture) include KQL-based fallback queries that work even when Graph API permissions are not yet effective.

The UAMI also needs Azure RBAC roles for Sentinel workspace access and (optionally) Key Vault secret retrieval.

Why is Sentinel Responder required? The Graph API SecurityIncident.ReadWrite.All permission is assigned to the UAMI as an Application permission, but the agent's sandbox uses a delegated user token for Graph API calls — which does not carry Application-level scopes. The ARM/Sentinel REST API uses the UAMI's own token (where RBAC roles apply), making it the reliable path for posting incident comments.

Run setup/assign-azure-roles.sh from Azure Cloud Shell (Bash) with an account that has Role Based Access Control Administrator or Owner on the target Log Analytics workspace or a parent scope. If the optional Key Vault argument is supplied, the account needs one of those roles on the Key Vault or a parent scope as well:

./assign-azure-roles.sh <UAMI_CLIENT_ID> <WORKSPACE_RESOURCE_ID> [KEYVAULT_RESOURCE_ID]

The script is idempotent (skips roles already assigned). RBAC roles typically propagate within 5–10 minutes.

The shared/enrich_ips.py script enriches IP addresses with third-party threat intelligence. If you want to use it, store API tokens as secrets in an Azure Key Vault and grant the UAMI Key Vault Secrets User role (see §2 above).

Skills affected: user-investigation, ioc-investigation.

The skills query tables that are populated by Microsoft Sentinel data connectors. Enable the relevant connectors in your Sentinel workspace:

The user-investigation and incident-investigation skills use the optional Signinlogs_Anomalies_KQL_CL table to prioritize new sign-in IP addresses, device combinations, and geographic novelty against a 90-day baseline. Without it, the skills continue with raw SigninLogs fallbacks but provide less precise anomaly prioritization.

The table is created and populated by an hourly Microsoft Sentinel Data Lake KQL job. Follow setup/signin-anomalies-kql-job.md and use the included setup/signin-anomalies-kql-job.kql. The Data Lake managed identity (msg-resources-<guid>) must have Log Analytics Contributor on the destination workspace; this identity is separate from the agent UAMI configured in sections 1 and 2.

For MCP usage monitoring and audit capabilities, enable these diagnostic settings on the Log Analytics workspace:

These are optional — all other skills work without them.

The skills have been tested extensively and several platform constraints, KQL pitfalls, and operational patterns have been documented in docs/known-issues.md. These include:

• Sandbox limitations (no PowerShell, no shell az, MI token caching up to 24h)
• KQL column-name gotchas (ThreatIntelIndicators vs deprecated ThreatIntelligenceIndicator, SecurityIncident alignment with Defender XDR portal, SentinelHealth casing)
• Operational patterns (prefetch workflow, sequential Graph API calls)

First-time setup: After connecting this repository to your agent, ask it to seed its memory with these learnings in the first conversation:

IMPORTANT — MANUAL ACTION REQUIRED: This step is NOT performed automatically by the deployment process or by the agent. You MUST manually copy, paste, and send the prompt below in the agent's first conversation.

Read the file codeRefs/sec-sre-ag/docs/known-issues.md and save its contents 
to your memory as operational knowledge. Organize it into your debugging index 
and behavior expectations as you see fit.

This is a one-time operation — the agent remembers across threads. See the guide's full instructions for details.

Run these tests after initial setup and after connector, permission, or skill changes. Replace every placeholder with a customer test resource. Use a nonproduction mailbox, Teams destination, device, user, and Sentinel incident where a test causes an external action. Confirm the tool card reports success and verify the result in the target system; a plausible chat response alone is not sufficient evidence.

For Outlook attachment validation, use the complete procedure in docs/email-html-report.md. For Teams channel, group-chat, direct-message, and self-message payload validation, use docs/teams-delivery.md.

The prompts below exercise the minimum recognizable workflow for each deployed skill. Some skills depend on licensed products or populated tables; a clear prerequisite error is acceptable only when the corresponding dependency is intentionally unavailable. Unexpected tool, permission, schema, or file errors must be resolved before production use.

Record the date, agent version, repository commit, connector status, tester, and outcome for each test. Re-run the affected rows after changing OAuth accounts, managed identities, RBAC, Graph permissions, MCP credentials, selected tools, Skill Builder content, or repository scripts.

In Azure SRE Agent, when a new conversation is started, a new thread is created. The agent's tool execution runs inside an isolated sandbox — a micro VM powered by Azure Dedicated Compute (ADC), separate from the reasoning engine. In the sandbox's workspace filesystem, under codeRefs/, the content of the GitHub or Azure DevOps repositories connected to the agent is cloned and made available for reading.

This means that when a skill needs to execute a Python script or load a companion data file (JSON, YAML), the file already exists on the sandbox filesystem at a predictable path such as codeRefs/sec-sre-ag/<skill-name>/<filename>.

Every SKILL.md in this repository instructs the agent to resolve script and data files using a mandatory three-step cascade before execution:

1. codeRefs/sec-sre-ag/<skill-name>/<filename>
   → If found: use / execute directly from this path.
     Companion files (queries.yaml, JSON reference data, etc.) are co-located here.

2. tmp/<skill-name>/<filename>
   → If found: use from this path (left over from a previous materialization
     in the same conversation).

3. Neither found → materialize from Builder:
   → read_skill_file("<skill-name>", "<filename>") — returns file content via API
   → CreateFile("tmp/<skill-name>/<filename>", <content>)
   → Repeat for ALL companion files the script depends on.

Rules enforced in every SKILL.md:

• When a file is found in codeRefs/, execute it directly from there — do not copy it to tmp/.
• When materializing from Builder (step 3), materialize all companion files the script depends on, not just the script itself.
• The read_skill_file tool returns file content via API but does not place files on the local filesystem. Running python3 <script>.py directly will fail with No such file or directory (exit code 2) unless the file has been resolved first.

codeRefs/ contains the latest version-controlled scripts with companion files co-located. Because the repository is cloned into the sandbox automatically, step 1 succeeds in the vast majority of cases, making execution fast and reliable. Steps 2 and 3 exist as fallbacks: step 2 reuses files already materialized earlier in the conversation, and step 3 fetches content from the Builder API as a last resort.

Once the agent has resolved a script to a filesystem path and invokes it with python3, the scripts themselves use two patterns to find companion files:

No script manipulates sys.path or imports modules from other skill directories. Every script is self-contained. Shared utilities (e.g., shared/enrich_ips.py) are invoked as subprocesses, not imported.

Ten runtime skills listed in Setup section 0 include a Pre-requisite: Environment Configuration section that instructs the agent to ensure config.json exists at the workspace root before running a script. The agent bootstraps the file on the first applicable skill execution in a sandbox by:

1. Checking that config.json contains all required workspace fields.
2. If missing or incomplete, extracting environment values from the agent's own platform settings (<azure_resource_access>, <log_analytics_access>), asking the user for the tenant name, and discovering the resource group through the sandbox Azure CLI read tool.
3. Writing and validating config.json at the runtime workspace root with tenant_name, sentinel_workspace_id, subscription_id, and azure_mcp fields.

Scripts that consume the file find it by walking up from their own directory (up to 6–10 levels of parent directories). Because the runtime workspace root is an ancestor of both codeRefs/sec-sre-ag/<skill>/ and tmp/<skill>/, the file is found regardless of which File Resolution cascade step resolved the script. The api_tokens object is left empty; API tokens are loaded from Key Vault or environment variables independently.

sec-sre-ag/
├── shared/                    ← Scripts shared across multiple skills
├── <skill-name>/              ← Scripts and data to materialize for each skill
└── .builder/                  ← Reference copies of SKILL.md files and LLM docs
    └── <skill-name>/             (the authoritative version is in the Builder)

The files in .builder/ are backup / reference copies. The authoritative version of all SKILL.md and LLM instruction files is the one in the agent's Builder (SRE Agent portal → Builder → Skills).

API tokens and environment parameters are NOT in the repo. See shared/.env.example for the template of required environment variables.

The applicable SRE Agent skill instructions generate config.json at the runtime workspace root from platform settings before running their first script. No manually maintained or repository-tracked runtime configuration file is needed. See Setup section 0 for timing, ownership, eligible skills, and failure behavior.

{
  "tenant_name": "<short tenant name for report filenames>",
  "sentinel_workspace_id": "<Log Analytics workspace GUID>",
  "subscription_id": "<Azure subscription ID>",
  "azure_mcp": {
    "subscription_id": "<same as above>",
    "resource_group": "<resource group containing the LA workspace>",
    "workspace_name": "<Log Analytics workspace name>"
  },
  "api_tokens": {}
}

The agent reads these values from:

• sentinel_workspace_id, subscription_id, azure_mcp.* → from <agent_settings> and <log_analytics_access> injected by the platform
• tenant_name → from agent memory or user prompt
• IP-enrichment tokens → from Azure Key Vault or environment variables at runtime; they are not persisted in config.json

Scripts also accept CLI arguments (--workspace-id, --subscription-id, etc.) which override config.json values.