overreach 0.1.0__tar.gz

overreach-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raj Penchala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

overreach-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: overreach
+Version: 0.1.0
+Summary: Audit Microsoft Entra ID for over-permissioned human identities — deterministic, explainable, read-only.
+Author: Raj Penchala
+License: MIT
+Project-URL: Homepage, https://github.com/rpmsft9/overreach
+Project-URL: Repository, https://github.com/rpmsft9/overreach
+Project-URL: Issues, https://github.com/rpmsft9/overreach/issues
+Project-URL: Changelog, https://github.com/rpmsft9/overreach/blob/main/CHANGELOG.md
+Keywords: entra,azure-ad,least-privilege,iam,pim,identity-governance,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# overreach
+
+**Audit Microsoft Entra ID for over-permissioned human identities — deterministic, explainable, read-only.**
+
+`overreach` finds humans who hold more privilege than they need, right-sizes them with
+evidence, and flags the ones whose over-privilege flows into **AI agents**. It is the
+human-identity companion to [nhi-scan](https://github.com/rpmsft9/nhi-scan) (non-human &
+agent identities): nhi-scan owns the machines, `overreach` owns the people, and they
+join at the OBO bridge (OP6).
+
+No LLM in the verdict path. Every finding records its evidence and a confidence level.
+
+## Install
+
+```bash
+pip install overreach
+```
+
+Then run `overreach ...` (or `python -m overreach.cli ...` from a checkout).
+
+## Quickstart (30 seconds, no tenant needed)
+
+```bash
+overreach scan --input fixtures/sample-tenant.json
+```
+
+That runs against a synthetic directory, so you can see the output offline. JSON too:
+
+```bash
+python -m overreach.cli scan --input fixtures/sample-tenant.json --format json
+```
+
+Just want the flat "every role -> everyone assigned to it" report (the one Azure makes you
+assemble yourself), with eligible/active and via-group resolved? Markdown, JSON, or CSV:
+
+```bash
+python -m overreach.cli roles-report --input fixtures/sample-tenant.json
+python -m overreach.cli roles-report --input fixtures/sample-tenant.json --format csv > roles.csv
+```
+
+Against a real tenant (read-only; see **Safety**):
+
+```bash
+az login
+python -m overreach.cli inventory --out inv.json
+python -m overreach.cli scan --input inv.json
+```
+
+### Fold in Defender CSPM (usage-based CIEM signals)
+
+Microsoft retired Entra Permissions Management (ex-CloudKnox); its CIEM analysis now
+surfaces as **Defender CSPM** recommendations for **stale/unused and over-permissioned
+identities** on Azure (and AWS/GCP) *resource* permissions — the usage-based signal
+`overreach`'s native checks only approximate. If you have Defender CSPM, pull those and
+merge them in (tagged `_Defender CSPM_` so they stay distinct from directory-role findings):
+
+```bash
+python -m overreach.cli dcspm --out dcspm.json                     # read-only Resource Graph pull
+python -m overreach.cli scan --input inv.json --dcspm dcspm.json   # directory roles + resource-plane CIEM
+```
+
+Offline, the same merge runs against the fixtures:
+
+```bash
+python -m overreach.cli scan --input fixtures/sample-tenant.json --dcspm fixtures/sample-dcspm.json
+```
+
+Scope split: `overreach`'s native OP1–OP6 cover **Entra directory roles**; DCSPM covers
+**resource / RBAC** permissions. Together they span both planes.
+
+## The methodology (why this is more than a checkbox)
+
+"Over-privileged" means *holds more than they need* — and **"need" has no ground truth**.
+There is no authoritative record of what each person's job requires. So `overreach` does
+not pretend to a verdict. It **triangulates over-privilege from signals**, each with a
+stated confidence, and presents **candidates for review with evidence**. The tool narrows
+the haystack and shows its work; a human access review confirms "needed or not".
+
+The backbone is deterministic signals that need **no model of need**:
+
+| ID | Check | Signal | Confidence |
+|----|-------|--------|-----------|
+| **OP1** | Standing privileged role | A privileged role held as a permanent **active** assignment that should be **PIM-eligible** (on-demand). Over-privileged *in time*. | high |
+| **OP2** | Global Admin sprawl | More Global Administrators than the recommended minimum (~5). | high |
+| **OP3** | Dormant privileged account | Holds privilege but hasn't signed in (unused privilege = not needed now). The MVP proxy for usage-based right-sizing. | high |
+| **OP4** | Privileged without MFA | **Amplifier** — raises the *danger* of over-privilege, not the privilege itself. | high |
+| **OP5** | Hidden admin via nesting | Privilege inherited indirectly through a group, easy to miss in a native role view. | high |
+| **OP6** | Privilege → agent bridge | A privileged human who owns/sponsors an **OBO-capable** app or agent: the agent inherits the user's entitlements, so human over-privilege becomes agent blast radius. *The differentiator.* | high |
+
+Design principles:
+- **Lean on signals that don't require knowing "need"** (standing, nesting, dormancy, sprawl).
+- **Label amplifiers honestly** (OP4) so findings aren't overstated.
+- **Never claim a verdict you can't evidence.**
+
+## How this relates to Defender CSPM
+
+A fair question: if Defender CSPM already flags over-permissioned identities, why
+`overreach`? Because DCSPM is **one input**, and `overreach` is the layer around it.
+
+- **Different plane.** DCSPM's CIEM analyzes **resource / RBAC** permissions (Azure, AWS,
+  GCP). It does **not** assess **Entra directory roles** — Global Administrator, Privileged
+  Role Administrator, and the rest — which is where the most dangerous, tenant-takeover
+  privilege lives. `overreach`'s native OP1–OP6 target exactly that plane DCSPM leaves blind.
+- **Checks DCSPM doesn't run** on those roles: standing-vs-PIM-eligible (OP1), Global Admin
+  sprawl (OP2), dormant privileged accounts (OP3), privileged-without-MFA (OP4), and hidden
+  admin via nested groups (OP5).
+- **The agent bridge (OP6)** — connecting a human's privilege to the agents that inherit it
+  via OBO / ownership — is something no CIEM product models.
+- **Deterministic, explainable, and no license.** DCSPM is a paid plan and a black-box
+  verdict. `overreach` runs against any tenant with read-only Graph scopes, records the
+  evidence and confidence for every finding, and works where DCSPM isn't licensed.
+- **It unifies the picture** — directory-role findings (native) + resource-plane findings
+  (DCSPM, tagged by source) + non-human identities (via nhi-scan) in one risk model.
+
+In short: `overreach` **surrounds** DCSPM — it works without it, covers what it misses, and
+folds it in as the usage-based signal when you have it.
+
+## Roadmap
+
+- **Usage-based right-sizing** — the strongest signal of all: compare *granted* vs.
+  *actually-used* permissions. Needs per-action telemetry. OP3 (dormancy) is the MVP proxy.
+- **Pull Defender CSPM (DCSPM) CIEM signals.** Microsoft retired Entra Permissions
+  Management (ex-CloudKnox) as a standalone product; its CIEM analysis now surfaces as
+  **Microsoft Defender CSPM recommendations** that flag **stale/unused and over-permissioned
+  identities** across Azure (and AWS/GCP) resource permissions. `overreach` can ingest these
+  — via Azure Resource Graph over `Microsoft.Security/assessments`, or the Defender for Cloud
+  assessments API — and fold them in, upgrading the usage-based signal from a proxy to the
+  real thing. Scope split worth stating: DCSPM covers **resource / RBAC** permissions, while
+  `overreach`'s native checks cover **Entra directory roles** — the two are complementary, and
+  together they cover both planes.
+- ~~Group-nesting resolution in the collector~~ **done** — a role assigned to a group is
+  expanded into its transitive user members (tagged `via="group:<name>"`), so OP5 and
+  roles-report's via-group populate from a live tenant, not just a supplied inventory.
+- ~~owned_apps / owned_agents in the collector~~ **done** — the collector attaches each
+  user's owned app registrations (flagged `obo_capable` when the app requests delegated
+  permissions) and their Agent 365 registrations, so OP6 (the agent bridge) fires from a
+  live tenant. Agent 365 is preview, so that part is best-effort and skipped where absent.
+- **Peer baselining** — flag users with far more entitlement than functional peers.
+- **Unified report** merging `overreach` (human) and `nhi-scan` (non-human) output.
+
+## Safety
+
+- **Read-only.** `overreach` never writes to your directory.
+- **Authorized tenants only.** Run it against your own tenant, or one you have explicit
+  written permission to audit. Never point it at someone else's directory.
+- **Least-privilege scopes.** The collector needs only `Directory.Read.All`,
+  `RoleManagement.Read.Directory`, and `AuditLog.Read.All`, via your own `az login`.
+
+## Status
+
+Alpha (v0.1.0). The offline `scan` path and all six checks are implemented and tested;
+the Graph collector is a best-effort MVP (see `collect_graph.py` TODOs).

overreach-0.1.0/README.md

@@ -0,0 +1,152 @@
+# overreach
+
+**Audit Microsoft Entra ID for over-permissioned human identities — deterministic, explainable, read-only.**
+
+`overreach` finds humans who hold more privilege than they need, right-sizes them with
+evidence, and flags the ones whose over-privilege flows into **AI agents**. It is the
+human-identity companion to [nhi-scan](https://github.com/rpmsft9/nhi-scan) (non-human &
+agent identities): nhi-scan owns the machines, `overreach` owns the people, and they
+join at the OBO bridge (OP6).
+
+No LLM in the verdict path. Every finding records its evidence and a confidence level.
+
+## Install
+
+```bash
+pip install overreach
+```
+
+Then run `overreach ...` (or `python -m overreach.cli ...` from a checkout).
+
+## Quickstart (30 seconds, no tenant needed)
+
+```bash
+overreach scan --input fixtures/sample-tenant.json
+```
+
+That runs against a synthetic directory, so you can see the output offline. JSON too:
+
+```bash
+python -m overreach.cli scan --input fixtures/sample-tenant.json --format json
+```
+
+Just want the flat "every role -> everyone assigned to it" report (the one Azure makes you
+assemble yourself), with eligible/active and via-group resolved? Markdown, JSON, or CSV:
+
+```bash
+python -m overreach.cli roles-report --input fixtures/sample-tenant.json
+python -m overreach.cli roles-report --input fixtures/sample-tenant.json --format csv > roles.csv
+```
+
+Against a real tenant (read-only; see **Safety**):
+
+```bash
+az login
+python -m overreach.cli inventory --out inv.json
+python -m overreach.cli scan --input inv.json
+```
+
+### Fold in Defender CSPM (usage-based CIEM signals)
+
+Microsoft retired Entra Permissions Management (ex-CloudKnox); its CIEM analysis now
+surfaces as **Defender CSPM** recommendations for **stale/unused and over-permissioned
+identities** on Azure (and AWS/GCP) *resource* permissions — the usage-based signal
+`overreach`'s native checks only approximate. If you have Defender CSPM, pull those and
+merge them in (tagged `_Defender CSPM_` so they stay distinct from directory-role findings):
+
+```bash
+python -m overreach.cli dcspm --out dcspm.json                     # read-only Resource Graph pull
+python -m overreach.cli scan --input inv.json --dcspm dcspm.json   # directory roles + resource-plane CIEM
+```
+
+Offline, the same merge runs against the fixtures:
+
+```bash
+python -m overreach.cli scan --input fixtures/sample-tenant.json --dcspm fixtures/sample-dcspm.json
+```
+
+Scope split: `overreach`'s native OP1–OP6 cover **Entra directory roles**; DCSPM covers
+**resource / RBAC** permissions. Together they span both planes.
+
+## The methodology (why this is more than a checkbox)
+
+"Over-privileged" means *holds more than they need* — and **"need" has no ground truth**.
+There is no authoritative record of what each person's job requires. So `overreach` does
+not pretend to a verdict. It **triangulates over-privilege from signals**, each with a
+stated confidence, and presents **candidates for review with evidence**. The tool narrows
+the haystack and shows its work; a human access review confirms "needed or not".
+
+The backbone is deterministic signals that need **no model of need**:
+
+| ID | Check | Signal | Confidence |
+|----|-------|--------|-----------|
+| **OP1** | Standing privileged role | A privileged role held as a permanent **active** assignment that should be **PIM-eligible** (on-demand). Over-privileged *in time*. | high |
+| **OP2** | Global Admin sprawl | More Global Administrators than the recommended minimum (~5). | high |
+| **OP3** | Dormant privileged account | Holds privilege but hasn't signed in (unused privilege = not needed now). The MVP proxy for usage-based right-sizing. | high |
+| **OP4** | Privileged without MFA | **Amplifier** — raises the *danger* of over-privilege, not the privilege itself. | high |
+| **OP5** | Hidden admin via nesting | Privilege inherited indirectly through a group, easy to miss in a native role view. | high |
+| **OP6** | Privilege → agent bridge | A privileged human who owns/sponsors an **OBO-capable** app or agent: the agent inherits the user's entitlements, so human over-privilege becomes agent blast radius. *The differentiator.* | high |
+
+Design principles:
+- **Lean on signals that don't require knowing "need"** (standing, nesting, dormancy, sprawl).
+- **Label amplifiers honestly** (OP4) so findings aren't overstated.
+- **Never claim a verdict you can't evidence.**
+
+## How this relates to Defender CSPM
+
+A fair question: if Defender CSPM already flags over-permissioned identities, why
+`overreach`? Because DCSPM is **one input**, and `overreach` is the layer around it.
+
+- **Different plane.** DCSPM's CIEM analyzes **resource / RBAC** permissions (Azure, AWS,
+  GCP). It does **not** assess **Entra directory roles** — Global Administrator, Privileged
+  Role Administrator, and the rest — which is where the most dangerous, tenant-takeover
+  privilege lives. `overreach`'s native OP1–OP6 target exactly that plane DCSPM leaves blind.
+- **Checks DCSPM doesn't run** on those roles: standing-vs-PIM-eligible (OP1), Global Admin
+  sprawl (OP2), dormant privileged accounts (OP3), privileged-without-MFA (OP4), and hidden
+  admin via nested groups (OP5).
+- **The agent bridge (OP6)** — connecting a human's privilege to the agents that inherit it
+  via OBO / ownership — is something no CIEM product models.
+- **Deterministic, explainable, and no license.** DCSPM is a paid plan and a black-box
+  verdict. `overreach` runs against any tenant with read-only Graph scopes, records the
+  evidence and confidence for every finding, and works where DCSPM isn't licensed.
+- **It unifies the picture** — directory-role findings (native) + resource-plane findings
+  (DCSPM, tagged by source) + non-human identities (via nhi-scan) in one risk model.
+
+In short: `overreach` **surrounds** DCSPM — it works without it, covers what it misses, and
+folds it in as the usage-based signal when you have it.
+
+## Roadmap
+
+- **Usage-based right-sizing** — the strongest signal of all: compare *granted* vs.
+  *actually-used* permissions. Needs per-action telemetry. OP3 (dormancy) is the MVP proxy.
+- **Pull Defender CSPM (DCSPM) CIEM signals.** Microsoft retired Entra Permissions
+  Management (ex-CloudKnox) as a standalone product; its CIEM analysis now surfaces as
+  **Microsoft Defender CSPM recommendations** that flag **stale/unused and over-permissioned
+  identities** across Azure (and AWS/GCP) resource permissions. `overreach` can ingest these
+  — via Azure Resource Graph over `Microsoft.Security/assessments`, or the Defender for Cloud
+  assessments API — and fold them in, upgrading the usage-based signal from a proxy to the
+  real thing. Scope split worth stating: DCSPM covers **resource / RBAC** permissions, while
+  `overreach`'s native checks cover **Entra directory roles** — the two are complementary, and
+  together they cover both planes.
+- ~~Group-nesting resolution in the collector~~ **done** — a role assigned to a group is
+  expanded into its transitive user members (tagged `via="group:<name>"`), so OP5 and
+  roles-report's via-group populate from a live tenant, not just a supplied inventory.
+- ~~owned_apps / owned_agents in the collector~~ **done** — the collector attaches each
+  user's owned app registrations (flagged `obo_capable` when the app requests delegated
+  permissions) and their Agent 365 registrations, so OP6 (the agent bridge) fires from a
+  live tenant. Agent 365 is preview, so that part is best-effort and skipped where absent.
+- **Peer baselining** — flag users with far more entitlement than functional peers.
+- **Unified report** merging `overreach` (human) and `nhi-scan` (non-human) output.
+
+## Safety
+
+- **Read-only.** `overreach` never writes to your directory.
+- **Authorized tenants only.** Run it against your own tenant, or one you have explicit
+  written permission to audit. Never point it at someone else's directory.
+- **Least-privilege scopes.** The collector needs only `Directory.Read.All`,
+  `RoleManagement.Read.Directory`, and `AuditLog.Read.All`, via your own `az login`.
+
+## Status
+
+Alpha (v0.1.0). The offline `scan` path and all six checks are implemented and tested;
+the Graph collector is a best-effort MVP (see `collect_graph.py` TODOs).

overreach-0.1.0/overreach/__init__.py

@@ -0,0 +1,8 @@
+"""overreach - audit Microsoft Entra ID for over-permissioned human identities.
+
+Deterministic and explainable: every finding records the evidence and its
+confidence, and nothing uses an LLM in the verdict path. Read-only by design.
+Companion to nhi-scan (non-human / agent identities); see OP6 for the bridge.
+"""
+
+__version__ = "0.1.0"

overreach-0.1.0/overreach/cli.py

@@ -0,0 +1,92 @@
+"""overreach command-line interface.
+
+    overreach scan --input fixtures/sample-tenant.json        # offline, no tenant needed
+    overreach scan --input inv.json --format json
+    overreach inventory --out inv.json                         # read-only gather from Graph (needs az login)
+"""
+
+import argparse
+import sys
+
+from . import engine, report
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="overreach",
+        description="Audit Microsoft Entra ID for over-permissioned human identities (read-only).",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("scan", help="Scan an inventory JSON and report over-privilege findings.")
+    s.add_argument("--input", required=True, help="Path to an inventory JSON (see fixtures/).")
+    s.add_argument("--dcspm", help="Optional normalized Defender CSPM JSON to merge in "
+                                   "(see fixtures/sample-dcspm.json).")
+    s.add_argument("--format", choices=["md", "json"], default="md")
+    s.add_argument("--ga-max", type=int, default=5, help="Max Global Admins before OP2 fires (default 5).")
+
+    g = sub.add_parser("inventory", help="Gather a read-only inventory from Microsoft Graph.")
+    g.add_argument("--out", required=True, help="Where to write the inventory JSON.")
+
+    d = sub.add_parser("dcspm", help="Gather Defender CSPM CIEM recommendations (read-only, needs az login).")
+    d.add_argument("--out", required=True, help="Where to write the normalized DCSPM JSON.")
+
+    r = sub.add_parser("roles-report",
+                       help="List every role and everyone assigned to it (eligible/active and via-group resolved).")
+    r.add_argument("--input", required=True, help="Path to an inventory JSON (see fixtures/).")
+    r.add_argument("--format", choices=["md", "json", "csv"], default="md")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "scan":
+        tenant, identities = engine.load_inventory(args.input)
+        findings = engine.scan(identities, {"ga_max": args.ga_max})
+        if args.dcspm:
+            from . import collect_dcspm
+            findings.extend(collect_dcspm.load_findings(args.dcspm))
+        out = report.to_markdown(tenant, findings) if args.format == "md" else report.to_json(tenant, findings)
+        print(out)
+        return 0
+
+    if args.cmd == "inventory":
+        from . import collect_graph
+        try:
+            data = collect_graph.gather()
+        except collect_graph.GraphError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+        with open(args.out, "w", encoding="utf-8") as f:
+            f.write(data)
+        print(f"wrote {args.out}")
+        return 0
+
+    if args.cmd == "dcspm":
+        from . import collect_dcspm
+        try:
+            data = collect_dcspm.gather()
+        except collect_dcspm.DcspmError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+        with open(args.out, "w", encoding="utf-8") as f:
+            f.write(data)
+        print(f"wrote {args.out}")
+        return 0
+
+    if args.cmd == "roles-report":
+        from . import rolesreport
+        tenant, identities = engine.load_inventory(args.input)
+        rows = rolesreport.build(identities)
+        if args.format == "md":
+            out = rolesreport.to_markdown(tenant, rows)
+        elif args.format == "json":
+            out = rolesreport.to_json(tenant, rows)
+        else:
+            out = rolesreport.to_csv(tenant, rows)
+        print(out)
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

overreach-0.1.0/overreach/collect_dcspm.py

@@ -0,0 +1,161 @@
+"""Defender CSPM (DCSPM) CIEM collector + mapping.
+
+Microsoft retired Entra Permissions Management (ex-CloudKnox) as a standalone
+product. Its CIEM analysis now surfaces as **Microsoft Defender CSPM
+recommendations** that flag stale/unused and over-permissioned identities across
+Azure (and AWS/GCP) *resource* permissions. That analysis is usage-based — it is
+the gold-standard signal overreach's native checks only approximate (OP3 dormancy).
+
+This module:
+  1. `gather()`  — read-only pull of those recommendations from Azure Resource
+     Graph (securityresources / Microsoft.Security assessments), normalized to a
+     small JSON shape. Needs Defender CSPM enabled and an ARM token (az login).
+  2. `load_findings(path)` — read a normalized DCSPM JSON (from gather() or the
+     fixture) and map each recommendation to an overreach Finding, tagged
+     source="defender-cspm" so the report keeps it distinct from directory-role
+     findings.
+
+Scope note: DCSPM covers resource / RBAC permissions; overreach's native checks
+cover Entra directory roles. They are complementary — merge both for the full
+picture across the directory plane and the resource plane.
+"""
+
+import json
+import subprocess
+import urllib.error
+import urllib.request
+
+from .models import Finding
+
+ARM = "https://management.azure.com"
+
+# The Defender CSPM CIEM recommendations we care about. Match on lowercased display name.
+_ARG_QUERY = """
+securityresources
+| where type == "microsoft.security/assessments"
+| extend displayName = tostring(properties.displayName),
+         status = tostring(properties.status.code),
+         severity = tostring(properties.metadata.severity),
+         resourceId = tostring(properties.resourceDetails.Id)
+| where status == "Unhealthy"
+| where displayName has_any ("permission","permissions","identity","identities",
+                             "unused","stale","inactive","overprovisioned",
+                             "over-provisioned","super")
+| project displayName, status, severity, resourceId,
+          additionalData = tostring(properties.additionalData)
+"""
+
+_SEV_MAP = {"critical": "critical", "high": "high", "medium": "medium", "low": "low"}
+
+
+class DcspmError(RuntimeError):
+    pass
+
+
+# --- gather (live, read-only) ------------------------------------------------
+
+def _arm_token():
+    try:
+        out = subprocess.run(
+            ["az", "account", "get-access-token", "--resource", ARM,
+             "--query", "accessToken", "-o", "tsv"],
+            capture_output=True, text=True, check=True,
+        )
+        token = out.stdout.strip()
+        if not token:
+            raise DcspmError("empty ARM token from 'az account get-access-token'")
+        return token
+    except FileNotFoundError:
+        raise DcspmError("Azure CLI ('az') not found. Install it and run 'az login' first.")
+    except subprocess.CalledProcessError as e:
+        raise DcspmError(f"'az account get-access-token' failed: {e.stderr.strip()}")
+
+
+def gather():
+    """Return normalized DCSPM CIEM recommendations as a JSON string."""
+    token = _arm_token()
+    url = f"{ARM}/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01"
+    assessments = []
+    skip_token = None
+    while True:
+        options = {"resultFormat": "objectArray"}
+        if skip_token:
+            options["$skipToken"] = skip_token
+        body = json.dumps({"query": _ARG_QUERY, "options": options}).encode("utf-8")
+        req = urllib.request.Request(
+            url, data=body, method="POST",
+            headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req) as resp:
+                payload = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            raise DcspmError(f"Resource Graph query failed: HTTP {e.code}: "
+                             f"{e.read().decode('utf-8', 'ignore')[:300]}")
+        for row in payload.get("data", []):
+            assessments.append(_normalize_row(row))
+        skip_token = payload.get("$skipToken")
+        if not skip_token:
+            break
+    return json.dumps({"source": "defender-cspm", "assessments": assessments}, indent=2)
+
+
+def _normalize_row(row):
+    """Map a raw Resource Graph assessment row to the normalized shape."""
+    # The specific over-permissioned principal often lives in additionalData / sub-assessments;
+    # we surface the resource and display name, and best-effort an identity if present. TODO: expand.
+    return {
+        "display_name": row.get("displayName", ""),
+        "status": row.get("status", "Unhealthy"),
+        "severity": (row.get("severity") or "Medium"),
+        "identity": None,
+        "identity_type": None,
+        "resource_id": row.get("resourceId", ""),
+        "remediation": "",
+    }
+
+
+# --- map normalized recommendations to findings (used offline + live) --------
+
+def _classify(display_name):
+    d = (display_name or "").lower()
+    if "super" in d:
+        return "DCSPM-SUPER", "Super identity (excessive resource permissions)"
+    if "unused" in d:
+        return "DCSPM-UNUSED", "Unused identity (resource permissions)"
+    if "stale" in d or "inactive" in d:
+        return "DCSPM-STALE", "Stale / inactive identity"
+    if "overprovisioned" in d or "over-provisioned" in d or "necessary permissions" in d:
+        return "DCSPM-OVERPROV", "Over-provisioned identity (resource permissions)"
+    return "DCSPM", "Defender CSPM identity recommendation"
+
+
+def _to_finding(rec):
+    rule, title = _classify(rec.get("display_name", ""))
+    sev = _SEV_MAP.get(str(rec.get("severity", "medium")).lower(), "medium")
+    who = rec.get("identity") or rec.get("resource_id") or "(resource)"
+    where = rec.get("resource_id", "")
+    scope = f" on {where}" if where and rec.get("identity") else ""
+    return Finding(
+        rule=rule, title=title,
+        identity_id=rec.get("identity") or rec.get("resource_id") or "(resource)",
+        identity_upn=who,
+        severity=sev, confidence="high", amplifier=False,
+        evidence=f"Defender CSPM (usage-based): '{rec.get('display_name', '')}'{scope}.",
+        remediation=rec.get("remediation")
+                    or "Right-size the resource role assignments to the permissions actually used "
+                       "(per the Defender CSPM recommendation).",
+        source="defender-cspm",
+    )
+
+
+def findings_from_normalized(data):
+    """Map a normalized DCSPM dict (as produced by gather()) to a list of Findings."""
+    return [_to_finding(rec) for rec in data.get("assessments", [])]
+
+
+def load_findings(path):
+    """Read a normalized DCSPM JSON file and return a list of Findings."""
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    return findings_from_normalized(data)