Policy and rules reference

Applies to client 2.0.x and later. For tenant admins and auditors.

You manage the policy in the portal (Policy and Settings); the Policy guide explains every field with examples and starter policies. This page is the reference behind it: what the device writes, how it evaluates a request, and how local settings and Group Policy interact with the portal.

Where the policy lives on the device

The service reads its policy from the registry, 64-bit view:

Key	Who writes it
HKLM\SOFTWARE\Circle Of Bytes\AdminExplorer	The installer, the service (from the portal policy) and administrators
HKLM\SOFTWARE\Policies\Circle Of Bytes\AdminExplorer	Group Policy or your own tooling. A value here always wins.

• The Applications (approved list) and Rules subkeys are replaced as a whole when the Policies key has them; they are never merged.
• On an enrolled device every policy pull (every 15 minutes, or at once with Sync now) is checked as a whole first. If any part is invalid the whole policy is refused (event 2016) and the previous one stays.
• Settings, rules and denied paths are reloaded right after a policy is applied. Changes to the approved list reach the pre-approved (automatic) flow at the next service restart, which the device schedules when it is idle, at the latest at 03:00 local time; Sync now applies them at once.
• A malformed value never widens the policy: it is ignored and logged as event 2007, and the setting falls back to its safe default (see below).
• With registry tamper protection on (TamperProtection = 1 in the base key), the kernel driver refuses every write under HKLM\SOFTWARE\Circle Of Bytes by any process other than the AdminExplorer service. The Policies key is not affected.

Settings

Registry value	Portal setting	Type	Default	Notes
ApprovalMode	Approval mode	REG_SZ	Auto	Auto or Manual. Manual needs Enterprise; on Standard the device behaves as Auto and logs 2007. Any other value is treated as Manual (fail safe).
ReasonRequired	Users must type a reason	REG_DWORD	1	0 makes reasons optional (not for “any application” matches).
ReasonMinLength	Minimum reason length	REG_DWORD	2	1 to 1024. Outside the range: 2 with 2007.
ApprovalTtlMinutes	Pending request lifetime	REG_DWORD	60	1 to 1440. The file stays locked against changes while the request is pending.
PowerShellExecutionPolicy	PowerShell execution policy	REG_SZ	Bypass	Bypass, RemoteSigned or AllSigned. Anything else becomes AllSigned.
DeniedPaths	Denied paths	REG_MULTI_SZ	empty	Your own patterns; the built-ins always apply.
AllowAnyApplicationOnDemand	Allow any application on demand	REG_DWORD	0	Enterprise only; ignored on Standard.
EntraGroupTargeting	Entra group targeting	REG_DWORD	0	Enterprise only, needs Directory Sync.
EntraGroupStaleHours	(device only)	REG_DWORD	24	1 to 72: how long the last known group membership is used while the portal does not answer.
Tray\HideExit	Hide Exit in the tray menu	REG_SZ	"1"	"0" shows Exit in the tray menu.
SoftwareInventory\Enabled, IncludeSystemComponents, IncludeUpdates	Installed software tracking	REG_DWORD	1, 0, 0	Both tiers.
License	(from the portal or the installer)	REG_SZ	none	The signed license. Missing, invalid or expired beyond the 14-day grace period: every elevation is refused (Unlicensed).

Reason length is counted in characters after trimming; a run of whitespace counts once and invisible characters (control, zero-width and format characters) do not count.

The sandbox settings live in the Sandbox subkey and the local administrator protection settings in the LocalAdmin subkey; see Run in sandbox and Local administrator removal and protection for their meaning. In both, a value in the Policies key wins per value.

Decision order for an on-demand request

Deny always wins. The service checks, in this order:

1. Path checks (below). A failure is a denial with the specific reason code.
2. Kind: only .exe, .ps1 and .msi; a shortcut (.lnk) is resolved as the user first. Otherwise UnknownKind.
3. Denied paths: the built-ins on the system drive (C:\Users\*\Downloads\*, C:\Users\*\AppData\Local\Temp\*, C:\Windows\Temp\*) and your own patterns. A match is DeniedPath.
4. License: no valid license is Unlicensed.
5. Approved list: exact, case-insensitive path match against enabled entries. When the entry has a SHA-256 it must match the file (HashMismatch).
6. Rules (Enterprise): sorted by name, the first match decides.
7. Any application on demand (Enterprise, when on): the request is matched as any, with the safety rules below.
8. No match: NoRule.
9. Reason gate, then the approval gate: Auto starts the program, Manual creates a pending request.

The SHA-256 is read from the same open file handle that was checked, and only when it is needed (a hash on the entry or rule, a hash rule, or for the audit record after a positive decision). A file that cannot be read completely is HashFailed.

Arguments

Kind	Allowed
.exe	Passed as typed, at most 2048 characters, no control characters.
.msi	Only display and restart switches, with / or -: qn, qb, qb!, qr, qf, quiet, passive, norestart, promptrestart, forcerestart. Never a property, transform, patch, log or administrative switch (anything with =, quotes, /l*, /a, /j, /x, /p, /t, /g, /f, /update).
.ps1	Script parameters, passed after -File. Never -Command, -EncodedCommand, -File or -ExecutionPolicy (also as part of a longer word) and no line breaks.

Refused arguments are BadArguments.

Rules (Enterprise)

Type	Matches	Where
Path	An absolute pattern with * and ?	System drive only. A pattern with no folder below the drive root, such as C:\*, is kept and logged as 2010.
Publisher	The common name (CN) of the leaf signer certificate, case-insensitive	Any local fixed drive
Hash	The SHA-256 of one file	Any local fixed drive

• A rule can be limited to kinds (exe, ps1, msi; none = all three) and can carry an extra SHA-256 that must also match.
• Publisher verification checks the embedded signature or, for catalog-signed Windows files, the catalog. The device never downloads revocation lists while it decides; when revocation cannot be determined from the local cache the signature is accepted and the audit record says “revocation unknown”. A revoked certificate is refused.
• Keep publisher rules narrow: a rule for an operating system vendor effectively grants administrator rights on request.
• Use path rules only for folders standard users cannot write to.

Any application on demand (Enterprise)

When Allow any application on demand is on, a request that matches no approved entry and no rule is matched as any. The service enforces:

• Never a file the user controls: when the user can write to the file or its folder, or owns either, the request is UserWritableDir (also when the check cannot be completed).
• A reason of at least 10 characters (or the minimum length, when higher) is always required.
• System drive only; never child elevation; the SHA-256 is always recorded.
• With approval mode Auto, the person at the keyboard must confirm on a secure desktop prompt. Cancel or timeout is ConsentCancelled; a second prompt in the same session is ConsentBusy. When no prompt is possible (locked session, a session that is not the active console or an active remote session) the request goes to an approver instead, never to an automatic start.
• After confirmation the whole decision is made again against the current policy and license.

Allowing any application is equivalent to administrator rights on request, with a reason and a full audit trail. Add shells and administration tools to your denied paths if they must stay out of reach. Details: Any application on demand.

Entra group targeting (Enterprise)

Approved entries, rules and Run in sandbox can carry up to 20 Entra group object ids (AssignedGroups). The service enforces:

• Fail closed: a group-scoped entry applies to a user only when targeting is on and the service knows the user is a member of one of its groups.
• Group-scoped entries work only on demand (right-click and the tray menu), never as pre-approved automatic starts, because the pre-approved list is per machine.
• Membership comes from the portal per user, is cached for at most 15 minutes, and the last known answer is used for up to EntraGroupStaleHours (default 24) when the portal does not answer.
• A pending request whose match came from a group is checked again at approval (GroupChanged).

Details: Entra group targeting.

Path checks

Before any policy is evaluated the file must pass these checks, done as the requesting user:

Check	Reason code when it fails
A plain absolute local path: no network path, no device or NT prefixes, no alternate data streams, no .. components, no trailing space or dot, no reserved device names, no 8.3 short names	Unc, DevicePrefix, NtPrefix, ForwardSlash, StreamColon, DotDotComponent, TrailingSpaceOrDot, ReservedName, ShortName
A local fixed drive (not a network drive, a removable drive or a SUBST drive)	RemoteDrive, RemovableDrive, SubstDrive
The user can open the file	OpenFailed
No symbolic link, junction or mount point in the file or any parent folder	ReparsePoint, ParentReparsePoint
A regular file whose final path equals the requested path	NotRegularFile, FinalPathMismatch
At most 1 GiB	TooLarge

The file is then held open for reading only: it cannot be changed, renamed or deleted until the program has started (for .ps1 and .msi until the host process ends, and for a pending request until it is final).

Whether the user can write to the file’s folder is recorded in the audit record as “user-writable folder” for approved entries and rules.

Pending requests (Manual approval)

• At most 20 open requests per user and 200 per device (TooManyRequests).
• A request expires after the pending request lifetime (event 2008).
• On approval the service checks that the file is unchanged and that the user is still signed in to the same session (TargetChanged, SessionGone).
• Pending requests live in the service’s memory: a service restart drops them.
• Manual approval needs an enrolled device (ApprovalBackendUnavailable otherwise).

Approved list menu placement

Registry value (per approved entry)	Portal field	Default	Notes
ShowInMenu	Show in the AdminExplorer menu	shown	0 hides the entry from the tray menu; it still works.
MenuCategory	Menu category	top level	One-level submenu, 1 to 40 characters: letters, digits, space and - _ . &. An invalid value shows the entry at the top level.

Portal-managed and local entries

On an enrolled device the service writes the portal policy to the base key, never to the Policies key.

• The portal owns only the Applications and Rules subkeys whose value Source is portal. Each pull writes the portal’s entries and deletes portal entries that are no longer in the policy.
• Every other subkey is local and never changed or deleted: entries made by hand, by the installer’s bundled settings or migrated from an older AdminExplorer. A portal entry with the same name as a local one is skipped (event 1016 “skipped (local)”).
• To hand a local entry over to the portal, delete it on the device.
• For a local override of a setting, use the Policies key.

Example: local settings and rules

The same settings and rules can be written by hand or by your own tooling, for example on a device that is not enrolled:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Circle Of Bytes\AdminExplorer]
"ApprovalMode"="Auto"
"ReasonRequired"=dword:00000001
"ReasonMinLength"=dword:00000005

[HKEY_LOCAL_MACHINE\SOFTWARE\Circle Of Bytes\AdminExplorer\Rules\10-Contoso installers]
"Type"="Publisher"
"Publisher"="Contoso Software Ltd"
"Kinds"=hex(7):6d,00,73,00,69,00,00,00,00,00

[HKEY_LOCAL_MACHINE\SOFTWARE\Circle Of Bytes\AdminExplorer\Rules\20-Tools]
"Type"="Path"
"Pattern"="C:\\Program Files\\Contoso Tools\\*"

Kinds above is the REG_MULTI_SZ value msi. Rules need an Enterprise license. With tamper protection on, use the Policies key (or the portal) instead of the base key.