Skip to main content
Glama
shigechika

entraadm-mcp

by shigechika
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

signin_success_stats

Detect breached accounts by aggregating successful Entra sign-ins per source IP, surfacing shared IPs and legacy-protocol logins for investigation.

Instructions

Tenant-wide successful sign-in aggregation by source IP -- the view that finds a breach.

signin_failure_stats shows who is being attacked; this shows whether anyone got in. The breach signature is one source IP signing in successfully as several different accounts, most often over a legacy protocol (clientAppUsed such as "Authenticated SMTP" or "IMAP4", which carry no MFA). shared_ips lists the IPs with successes for min_distinct_users or more distinct accounts, most-shared first (up to 50 IPs, shared_ips_capped when more qualified; account names up to 25 per IP), with the client apps and the countries seen. legacy_auth_users lists the accounts that succeeded over a legacy protocol at all, with how many IPs and countries they came from.

A campus NAT, a VDI farm or a shared proxy also puts many accounts behind one IP, so a shared IP is a lead, not a verdict: the caller excludes its own egress ranges and reads the client apps and countries before calling anything a breach. Graph cannot filter sign-ins on status/errorCode server-side, so like signin_failure_stats this walks the sign-in log for the window and aggregates client-side. The walk covers interactive sign-ins only (Graph's default listing): every legacy-protocol authentication is logged as interactive, so none is missed, but non-interactive token refreshes are not counted; capped=true means the page budget or the deadline (ENTRAADM_DEADLINE, default 45 s) ran out first and the counts are a lower bound -- narrow hours for a full count.

Read-only (AuditLog.Read.All application permission, or -- for azure-cli auth -- the Reports Reader directory role).

Args: hours: How far back to look, clamped to [1, 720] (30 days). max_pages: Page budget (default: ENTRAADM_MAX_PAGES_DEFAULT). min_distinct_users: Distinct accounts an IP needs to appear in shared_ips (default 2, clamped to >= 2).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
hoursNo
max_pagesNo
min_distinct_usersNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.1.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so: read-only, required permission (AuditLog.Read.All / Reports Reader role), client-side aggregation because Graph cannot filter on status/errorCode server-side, interactive-sign-ins-only scope with the reasoning that legacy auth is logged as interactive, and lower-bound semantics when the page budget or ENTRAADM_DEADLINE expires. This is exactly the context annotations would otherwise supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the failure/success contrast are front-loaded, and the dense middle does real work. It is longer than strictly necessary — the breach-signature narrative and the NAT/VDI caveat could be tightened — but almost every sentence carries operational information rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must explain return values directly, and it does: shared_ips (up to 50, ordering, per-IP account/client-app/country detail, shared_ips_capped) and legacy_auth_users with IP/country counts. Combined with the permission, scope, and cap caveats, an agent has everything needed to call and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate and it does for all three params: hours clamped to [1,720], max_pages defaulting to ENTRAADM_MAX_PAGES_DEFAULT (page budget), and min_distinct_users defaulting to 2 with a clamp of >=2. No parameter is left to inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource+scope (tenant-wide successful sign-in aggregation by source IP) and explicitly contrasts itself with the sibling signin_failure_stats ('shows who is being attacked; this shows whether anyone got in'). An agent can distinguish it from every sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing to signin_failure_stats, plus genuine interpretation guidance: shared IPs are 'a lead, not a verdict' because NAT/VDI/proxy produce the same signature, and it tells the caller to exclude its own egress ranges before concluding a breach. It also names the condition that invalidates results (capped=true) and the remedy (narrow hours).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools