Guide · Agent skill
How to use the Office 365 compromise log analysis agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains what the analyzing-office365-audit-logs-for-compromise skill does, how to install it for an AI agent, and how to ask the agent to check a Microsoft 365 (Office 365) tenant for signs of email account takeover. It is aimed at security analysts, incident responders and engineers who may not have used agent skills before. By the end you will know the prerequisites, the install options, the kinds of requests that trigger the skill, and the limits you should keep in mind.
Office 365 Compromise Log Analysismukul975/Anthropic-Cybersecurity-Skills · Apache-2.0 Download the skill Quick start
- 1Confirm the prerequisites. Check that you have Python 3.9 or newer, the msal and requests libraries, and an Azure AD app registration with the three required application permissions.
- 2Prepare credentials. Create a client secret or certificate for the app registration and make sure the account you use holds the Global Reader or Security Reader role.
- 3Download and unzip the skill. Download the ZIP from this page and unzip it so the skill folder sits in ~/.claude/skills/ or in your project's .claude/skills/ folder.
- 4Or upload it in the Claude apps. If you use the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
- 5Ask for a specific check. Describe the task in plain language, naming the mailboxes and time window, such as the last 7 days for specific users.
- 6Review the JSON report and timeline. Check each flagged forwarding rule, delegation change or OAuth grant against the source audit records before drawing conclusions.
What does this skill make the agent do?
The skill gives the agent a structured procedure for checking a Microsoft 365 tenant for signs that an email account has been taken over. The indicators it focuses on include new inbox rules that forward mail to outside addresses, delegated mailbox access, and suspicious third-party app consents.
It includes a Python script, scripts/agent.py, that connects to Microsoft Graph using an Azure app registration and queries audit and mailbox data. The agent is then guided to produce a JSON report and a timeline of indicators with affected mailboxes.
- Queries the Unified Audit Log for operations such as Set-Mailbox and New-InboxRule
- Enumerates inbox rules across mailboxes and flags forwarding rules
- Detects mailbox delegation changes such as Add-MailboxPermission
- Identifies OAuth consent grants to suspicious applications
- Checks audit logs for suspicious sign-in patterns
What do you need before you start?
The skill cannot run without credentials and the right roles. Check these requirements before installing anything else.
- Python 3.9 or newer, with the msal and requests Python libraries
- An Azure AD app registration with AuditLog.Read.All, MailboxSettings.Read and Mail.Read application permissions
- A client secret or certificate for the app
- Global Reader or Security Reader role
- A Microsoft 365 (Office 365) tenant you are authorised to investigate
How do you install the skill?
Download the ZIP file from this page and unzip it. The package contains SKILL.md, scripts/agent.py and references/api-reference.md.
For a personal install, unzip the folder into ~/.claude/skills/. For a project-specific install, place it in the project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill there.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with a natural request?
You do not need special syntax. Describe the task in plain language and name the tenant data you want checked. The agent should recognise a request that matches the skill's description, which covers Office 365 audit logs, forwarding rules, inbox delegation and OAuth app grants.
Good requests name the scope: the mailboxes, the time window and the kind of indicator. Vague requests such as 'is my email safe' are less likely to produce a useful, structured result.
- Check the audit logs for the last 7 days for new inbox rules and mailbox permission changes.
- Look for forwarding rules on user@domain.com and tell me whether mail is going to an external address.
- Review OAuth app consents in the tenant for anything suspicious.
- Run a full compromise check on user1@d.com and user2@d.com over the last 7 days and build a timeline.
How do you run the script directly?
The API reference lists the command-line interface for scripts/agent.py. Replace T, C and S with your tenant ID, client ID and client secret. Each subcommand covers one kind of check, and the full subcommand runs several together for a list of users.
Review the script before you run it, and only run it against tenants you are authorised to investigate.
python agent.py --tenant-id T --client-id C --client-secret S audit-logs --days 7
python agent.py --tenant-id T --client-id C --client-secret S inbox-rules --user user@domain.com
python agent.py --tenant-id T --client-id C --client-secret S forwarding --user user@domain.com
python agent.py --tenant-id T --client-id C --client-secret S oauth
python agent.py --tenant-id T --client-id C --client-secret S full --users user1@d.com user2@d.com --days 7What output should you expect?
The expected output is a JSON report listing forwarding rules, delegation changes, OAuth grants and suspicious audit events, along with risk scores. The skill also produces a timeline of compromise indicators with the affected mailboxes.
The source does not provide tested risk scoring logic, so treat the scores as a prompt for review rather than a verdict. Confirm each finding against the underlying audit records.
- JSON report: forwarding rules, delegation changes, OAuth grants, suspicious audit events, risk scores
- Timeline: compromise indicators with affected mailboxes
What safety points should you know?
This skill runs scripts and uses the network. The script connects to Microsoft Graph and reads sensitive mailbox configuration and audit data, so it should only be run by people authorised to access that data.
Keep the client secret or certificate protected, and use the least privileged access that still lets the checks run. Remember that the files give a procedure but no validation, chain-of-custody handling or tested risk scoring, so they are not a substitute for production-grade forensic collection.
- Read scripts/agent.py before running it
- Protect the client secret or certificate
- Only query tenants you are authorised to investigate
- Do not treat the risk scores as proof of compromise
What people use it for
- Triage a suspected business email compromise by checking a user's mailbox for forwarding rules to external addresses.
- Review recent Set-Mailbox and New-InboxRule audit events across a set of users after a phishing report.
- Audit OAuth application consents in a Microsoft 365 tenant for unfamiliar third-party apps.
- Build a repeatable checklist for mailbox compromise indicators that a SOC team can follow each time.
- Draft detection or threat-hunting queries by seeing which Microsoft Graph audit fields the script uses.
Frequently asked questions
How do I install the Office 365 compromise log analysis skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
What do I need to run the analyzing-office365-audit-logs-for-compromise skill?
You need Python 3.9 or newer with the msal and requests libraries, an Azure AD app registration with AuditLog.Read.All, MailboxSettings.Read and Mail.Read application permissions, a client secret or certificate, and the Global Reader or Security Reader role. Without app credentials and these roles, the skill cannot run.
Is the skill free to use?
The skill is licensed under Apache-2.0, as stated on this page. The source does not cover Microsoft 365 or Azure licensing costs, so check those separately with your tenant administrator.
What should I do if the script cannot authenticate?
Confirm the tenant ID, client ID and client secret are correct, and that the app registration has the three required application permissions. Also check that the account you use has the Global Reader or Security Reader role, since the skill depends on these credentials.
Does this skill give forensic-grade evidence?
No. The files give a procedure but no validation, chain-of-custody handling or tested risk scoring logic. Use the output as a structured starting point and confirm findings against the original audit records.
How does this compare with other ways to check Microsoft 365 for compromise?
The source does not compare this skill with other tools. It is best suited to analysts who want a repeatable, scripted checklist for mailbox compromise indicators via Microsoft Graph, and who are comfortable reviewing and running the included Python script.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a security analyst, incident responder or detection engineer who has Azure admin access and a Microsoft 365 tenant, and who wants a repeatable checklist for mailbox compromise indicators. Pick something else if you lack app credentials or the reader roles, or if you need production-grade forensic evidence collection with validated scoring and chain-of-custody handling.
Download the skill