Enhance README with key fields and review guidance

Added detailed explanations of key fields and rights that warrant closer review in the README.

Author: rolling-code

README.md

@@ -589,29 +589,42 @@ Audits Active Directory ACEs that apply to a user through direct and nested secu
 .\Get-AdPrincipalPermissions.ps1 -Username "XXX\mcontestabile" -Domain "DC=YYYYYY,DC=net"
 ```
 
-Key fields include:
-
-ObjectDN: Distinguished name of the AD object whose security descriptor contains the ACE.
-ObjectClass: Type of AD object, such as a user, group, organizational unit, computer, or Group Policy container.
-Principal: Target user or group to which the ACE applies.
-PrincipalType: Whether the matching principal is the user or an AD security group.
-Rights: Active Directory rights recorded in the ACE.
-AccessControlType: Indicates whether the ACE allows or denies the listed rights.
-IsInherited: Indicates whether the ACE is explicit on the object or inherited from a parent.
-ObjectType: Attribute, object class, property set, or extended right scoped by the ACE.
-RiskSeverity / RiskReason: Triage guidance generated by the script. These fields assist review but do not replace validation of the affected object and scoped right.
-Rights that warrant closer review
+## Understanding the output
+
+Each output row represents one matching Access Control Entry associated with the target user or one of the user's direct or nested security groups.
+
+### Key fields
+
+- **ObjectDN:** Distinguished name of the AD object whose security descriptor contains the ACE.
+- **ObjectClass:** Type of AD object, such as a user, group, organizational unit, computer, or Group Policy container.
+- **Principal:** Target user or group to which the ACE applies.
+- **PrincipalType:** Whether the matching principal is the user or an AD security group.
+- **Rights:** Active Directory rights recorded in the ACE.
+- **AccessControlType:** Indicates whether the ACE allows or denies the listed rights.
+- **IsInherited:** Indicates whether the ACE is explicit on the object or inherited from a parent.
+- **ObjectType:** Attribute, object class, property set, or extended right scoped by the ACE.
+- **RiskSeverity / RiskReason:** Triage guidance generated by the script. These fields assist review but do not replace validation of the affected object and scoped right.
+
+## Rights that warrant closer review
 
 Prioritize ACEs containing:
 
-GenericAll: Full control over the affected AD object.
-GenericWrite: Broad ability to modify writable properties.
-WriteDacl: Ability to change the object’s permissions and potentially grant additional access.
-WriteOwner: Ability to assume ownership and potentially alter permissions.
-WriteProperty: Ability to modify one or more attributes. Impact depends on the attribute or property set shown in ObjectType.
-ExtendedRight: A scoped control right whose impact depends on ObjectType. Some extended rights are sensitive, while others, such as Apply Group Policy, are expected and low risk.
-CreateChild / DeleteChild: Ability to create or remove specific child-object types beneath a container or OU.
-Delete / DeleteTree: Ability to delete an object or an object subtree.
+- **GenericAll:** Full control over the affected AD object.
+- **GenericWrite:** Broad ability to modify writable properties.
+- **WriteDacl:** Ability to change the object's permissions and potentially grant additional access.
+- **WriteOwner:** Ability to assume ownership and potentially alter permissions.
+- **WriteProperty:** Ability to modify one or more attributes. Impact depends on the attribute or property set shown in `ObjectType`.
+- **ExtendedRight:** A scoped control right whose impact depends on `ObjectType`. Some extended rights are sensitive, while others, such as **Apply Group Policy**, are expected and low risk.
+- **CreateChild / DeleteChild:** Ability to create or remove specific child-object types beneath a container or OU.
+- **Delete / DeleteTree:** Ability to delete an object or an object subtree.
+
+Always evaluate:
+
+1. The affected object in `ObjectDN`
+2. Whether the ACE is explicit or inherited
+3. The granting principal
+4. The scoped attribute, class, or extended right in `ObjectType`
+5. Whether the permission is required for the principal's documented function
 
 ---
 ### `delegated_rights.ps1`