What-if and plan¶

Two commands answer two questions on a snapshot, never on AD:

• ad-doctor whatif: if these rights, memberships or links were gone, which tier-0 paths close, which are rerouted, how does exposure change, and which findings would clear or appear?
• ad-doctor plan: what is the cheapest set of removals that closes every path ad-doctor sees, is it a proven minimum, and in which order should it go?

Neither command opens a connection to a directory. The snapshot is changed in memory to recheck the findings and is never written back. Every fix line runs with -WhatIf or is commented out.

ad-doctor plan snap.json                         # the plan, as text
ad-doctor plan snap.json -f toml -o plan.toml    # the plan file, kept in the repository
ad-doctor plan snap.json -f markdown -o plan.md  # one section per step, for tickets
ad-doctor plan snap.json -f ps1 -o plan.ps1      # the fix lines, all -WhatIf

ad-doctor whatif snap.json --remove adminsdholder:helpdesk --account alice
ad-doctor whatif new.json --plan plan.toml --check   # after the changes, in CI

A plan on the lab¶

Plan on the adlab.test snapshot of 2026-11-07 22:51 UTC (simulated; AD unchanged)

Goal: close the paths of enabled users outside tier 0.

Tier-0 paths:
                                before       after
  exposed users               25 of 26       1 of 26
                                   96%          3%
  principals with a path            12           4
  routes (changes needed)           15           0

Steps (heuristic order; each closes in the snapshot what it says):
   1. remove the ACEs of Domain Users on templates LabESC1, LabESC2, LabESC3  ->  exposed 8, ...
        c:2abd2340d93c  remove the ACEs of Domain Users on template LabESC1  (cost 1)
        ...
   8. take 6 rights away from helpdesk  ->  exposed 1, principals 4, routes 0
        c:798fc67fc112  remove the ACEs of helpdesk on AdminSDHolder  (cost 1)
          SDProp removes the copies on 20 protected objects at its next run (60 minutes)
        ...

15 changes (cost 17): proven minimum (for paths ad-doctor sees).
...
Cannot be closed by removing a right (needs a decision):
    MSOL_0a1b2c3d4e5f -[DCSync (kept: Entra Connect needs DCSync)]-> adlab.test
      -> treat MSOL_0a1b2c3d4e5f as tier 0 ([assume] tier0), or move what makes the route

The one user left exposed reaches tier 0 only through the Entra sync account, whose DCSync is kept on purpose. The plan says so instead of proposing to break sync.

Naming a change¶

Every form turns into change IDs before anything runs, and the output prints what each one became.

Names are a sAMAccountName, a name, a DN or a SID. Two matches are an error that lists them. No match means the change is absent in this snapshot: a status, not an error, unless --strict or --check is given. Naming an SDProp copy or an inherited copy prints rewritten: it resolves to the AdminSDHolder ACE or the container ACE it comes from, because removing only the copy would not last. Edges that are not a change (an OU's contains, GPO scope, a sync server holding its sync account, the nesting AD enforces) are refused with where to cut instead.

plan¶

The sources are the enabled users outside tier 0 and their implicit groups (Everyone, Authenticated Users, Users, the primary group): the population of the exposure figure. --goal all-paths uses every AD-PATH-001 holder instead, and --from NAME (repeatable) named principals.

The plan is a minimum cut of a flow network built on the path subgraph, so its cost is the cheapest in the model whenever the model is exact (see How it works). The output says proven minimum (for paths ad-doctor sees) only when that holds or the lower bound meets the plan; otherwise it says "plan of N changes" with the lower bound. The order of the steps is a heuristic: each step takes the change or bundle that closes the most users per cost, then principals, then routes (changes still needed). A bundle is "close this node": the cheapest part of the plan that cuts one of the 20 nodes most paths run through, which is how the three ESC templates that Domain Users enrolls in go together.

plan rechecks the findings once, on the whole plan, and stops with "model mismatch" if the AD-PATH-001 holders or the exposure of the changed snapshot differ from what the masked graph predicted.

whatif¶

whatif evaluates --remove SPEC (repeatable) and the open changes of --plan FILE. It prints each change with its status, warnings and notes; the tier-0 paths before and after (exposed users, principals with a path, routes); the principals whose paths close in the snapshot, the ones rerouted (still a path, another one, same fingerprint) and the ones still open; the sources no removal closes; the findings that would clear, appear or change, rechecked on the changed snapshot; and, per --account, the blast radius before and after. --paths-only skips the findings.

The plan file¶

plan -f toml writes it. It holds decisions, never results: what to change, what to keep and what to assume.

schema = 1

[plan]
domain = "adlab.test"
domain_sid = "S-1-5-21-..."
made_against = 2026-11-07T22:51:51Z
made_by = "ad-doctor 0.2.0 plan"
goal = "exposure"

[assume]
tier0 = ["ENTRA01$"]

[[change]]
id = "c:798fc67fc112"
kind = "adminsdholder-ace"
trustee = "S-1-5-21-...-1117"
label = "remove the ACEs of helpdesk on AdminSDHolder"
reason = "helpdesk needs password reset only"   # optional, like ticket, owner, due
due = 2026-11-30

[[keep]]
kind = "ace"
object = "dc=adlab,dc=test"
trustee = "S-1-5-21-...-1137"
reason = "Entra Connect needs DCSync"
expires = 2027-06-30                           # required, as in the accept file

[expect]
closes_all = true
max_exposed_percent = 4
max_holders = 4

The kind and its identity fields decide; id is a checksum of them, so an id that does not match means the file was edited. Strings are escaped like the viewer's accept drafts. plan writes [expect] from what the plan reaches.

Against any later snapshot each [[change]] is:

An expired [[keep]] is a candidate again, with a note.

CI¶

- run: ad-doctor collect dc01 -u 'CORP\auditor' -o snap.json
- run: ad-doctor whatif snap.json --plan plan.toml --check -f json -o whatif.json

Fix lines¶

-f ps1 uses the framing of the remediation script analyze writes: a header, #Requires, then one section per change with its lines and the findings it is expected to clear. An ACE removal reads the ACL, takes out only the explicit rules with that SID, rights mask and object type (RemoveAccessRuleSpecific) and writes it back with Set-Acl -WhatIf. It never uses dsacls /R, which removes every ACE of the trustee on the object. An AdminSDHolder change says how many protected objects hold a copy; an inherited-ACE change says how many objects below lose it. Owner changes, CA rights and Restricted Groups entries have no dry run, so their lines are comments. -f markdown adds a rollback line per change, written from the snapshot's values.

Changes¶

A change removes one snapshot fact; the control-graph edges it made go with it. paths.build(snapshot, provenance=True) records, for every edge, the change that made it, at the place where the edge is made. The graph itself is the same with and without it.

The flags of template-flag are require-approval, enrollee-supplies-subject, any-purpose-eku and request-agent-eku (an EKU only goes when another one stays, because an empty list means any purpose).

A change ID is c: and the first 12 hex digits of a SHA-256 over the kind and the identity fields, DNs in lower case and SIDs in upper case, like a finding fingerprint. It stays the same while the fact exists. A redacted snapshot gives other IDs, so a plan made from one does not resolve against the real snapshot.

Not removable: contains (ACL inheritance structure), GPO scope plumbing, hosts sync account, the edges out of a GPO with its filter changed (the right into that node is the change), the links of the two default domain policies, the nesting AD enforces (Domain Admins and Enterprise Admins in Administrators), implicit membership (Everyone, Authenticated Users, Users and primary groups are where paths start, not edges), and everything out of a tier-0 node.

Warn class (cost 10, proposed only when nothing of equal cost avoids it, with a warning): rights of Exchange Windows Permissions and Exchange Trusted Subsystem, of Key Admins, default grants Windows expects (Pre-Windows 2000 Compatible Access, Cert Publishers), taking the built-in Administrator out of a tier-0 group, and template-flag.

Kept changes are never proposed: the Entra sync account's DCSync by default (--allow warn lifts it), [[keep]] entries, --keep, accepted findings, [dcsync] allowed and the declared members of [groups] from an invariants file. Accepted AD-PATH-001 holders are not sources.

Not in this version: disabling an account (an account that is disabled keeps its rights in the model, and whoever controls it can enable it again), narrowing an ACE change to some of its rights, and adding rights.

Findings a change can clear¶

The recheck on the changed snapshot is the authority; this table is what fp: names resolve through and what "expected to clear" in the output and fix lines come from.

Settings, probes, account hygiene, policies, trusts, CA registry flags and SYSVOL secrets are never cleared by a removal; --remove fp: on them says so.

Where the snapshot and AD differ¶

• SDProp. An ACE of a trustee on a protected object (adminCount, a protected group, Administrator, krbtgt, or a principal with inheritance turned off) that equals one of the trustee's ACEs on AdminSDHolder belongs to adminsdholder-ace. SDProp would put the copy back within the hour, so the copy is never a change of its own. Removing the AdminSDHolder ACE removes the copies too, as the next SDProp run would.
• Inheritance. Snapshots from this version keep the INHERITED_ACE flag (ace_inheritance_checked in the file). An inherited copy belongs to the nearest OU or container above it with an explicit inheritable ACE of the same trustee. Older snapshots cannot tell an inherited copy from an explicit ACE, so there the copy is a change of its own and the output says so: a plan can be too large, never too small.
• One AD ACE, two lists. A container ACE that applies to the container and is inherited is one change, as in AD.
• GPO-enforced membership. A member that Restricted Groups puts into a domain group has its own member of via GPO edge, so closing it takes both the member and the gpo-entry change. The cut finds that by itself.
• Monotone. Every change only removes facts; fewer facts never add an edge.

How it works¶

Forward. Level 1 masks the graph: the edges of the changes are dropped and the rest keep their order, so the shortest paths, ties included, are those of a graph built from the changed snapshot. Changes that can move GPO scope are not masked but rebuilt: gplink, and a membership or GPO ACE that a security filter reads. Level 2 takes the changes out of the snapshot in place (one mutator per kind, each reporting what it removed) and runs every check again. The AD-PATH-001 holders and exposure of both levels must agree; a difference stops the run as a model mismatch, a bug to report.

Reverse. The flow network covers the path subgraph only: what a source reaches and what reaches tier 0. Each change is one arc with its cost, an edge made by a change runs through that arc, edges that cannot be removed and kept changes are infinite, and tier 0 is the sink. The maximum flow is the cost of the cheapest set of changes that closes every source, in this model.

• Exact when every change is one arc that joins no routes that do not exist: all of its edges share a source node, or all share a target (tier 0 counts as one). The count of changes where that fails is reported; with any, the cut is still valid but is only called minimal when a lower bound (paths whose changes are pairwise disjoint) meets it, and changes it does not need are dropped one by one.
• Cost first, then no warn class at equal cost, then fewest changes, through the capacities.
• Two cuts. The cut nearest tier 0 (default) and the one nearest the sources are each unique; when they differ, another cut of equal cost exists.
• Unclosable. A source that reaches tier 0 over infinite arcs only is listed with the route and the suggestion to treat the node as tier 0.

Measured¶

On one core of an Intel Xeon Gold 6138, Python 3.12, scripts/bench.py domains (the generator now lists nested Domain Admins members as tier 0, as a collection does), one run at a time under a 5 GB limit. Times are the whole command, loading included.

At 250,000 users loading the snapshot and building the provenance graph take most of the paths-only time; with findings, every check runs twice (before and after the changes). The bench domain has few paths for its size, so its plan is one step of all its changes.

In the viewer¶

The HTML viewer shows a plan or a what-if result on its What-if screen:

ad-doctor plan snap.json -f json -o plan.json
ad-doctor view snap.json --whatif plan.json

The JSON must come from the same snapshot file (its SHA-256 is checked) or, for a JSON report, the same domain. The screen shows what was computed on the command line; it does not run a new plan in the page.

Limits¶

The commands work on the snapshot. What happens in AD after a change differs:

• SDProp runs every 60 minutes; inheritance changes at an OU reach every object below it.
• adminCount stays on removed members (AD-ACC-006).
• Group Policy applies at the next refresh, and local groups keep members a GPO added.
• Kerberos tickets keep group memberships until they expire (10 hours by default).
• Certificates already issued stay valid until they expire or are revoked.
• Other DCs see a change after replication.
• Edges ad-doctor does not see stay: sessions, local admin outside Group Policy, delegation as a path, trusts, Deny ACEs.
• What an attacker already planted (shadow credentials, added SPNs, other persistence) is not undone. Collect again and run whatif --plan plan.toml --check.