Active Directory

Scope

Active Directory remains central to many operational environments. This public guide keeps the day-to-day operating guidance while leaving private integration mechanics out.

Automatic Forest Detection

When a Windows Domain Controller is managed by Cadres, the forest is automatically detected and registered:

1. The agent sends host-info including domain_role (4=Backup DC, 5=Primary DC)
2. The backend creates an ADForest record with the DC as the probe host
3. Default policies are bootstrapped (stale account detection, event monitoring, replication checking)
4. Initial scans are triggered (inventory, replication, group analysis, stale audit)

No manual action required — just install the Cadres agent on at least one domain controller.

The the relevant workflow route now fails closed when ad.view is missing; operators without that permission see an explicit access-denied state instead of a partially bootstrapped shell.

Listing Forests

Filters: - is_active — filter by active/inactive status (optional) - skip / limit — pagination (default 0/100, max 500)

Manual Forest Registration

If auto-detection doesn’t apply (e.g., RSAT tools on a member server instead of a DC):

Quota: Forest creation is subject to account-level quotas. If the account has reached its forest limit, the request returns 422.

The probe host must: - Belong to the same organization (enforced — 422 if not) - Be running Windows (enforced — 422 if not, with current OS type in error message) - Be domain-joined to the target forest (enforced if host has reported host_info at least once — 422 if not domain-joined; new hosts that haven’t checked in yet are allowed to avoid blocking initial setup) - Have RSAT (Remote Server Administration Tools) installed - Have an active Cadres agent

These eligibility checks are enforced by validate_probe_eligibility() on all three probe assignment paths: forest create, forest update, and probe add.

Viewing Inventory

Returns the most recent completed inventory scan with summary counts (users, computers, groups, GPOs, OUs, DCs, sites, subnets, service accounts) and detailed breakdowns.

Requires a configured probe host (422 if missing).

Stale Account Detection and Remediation

Viewing Stale Audit Results

If stale audit result loading fails in the UI, the tab now shows an inline error banner with a Retry action instead of falling back to an ambiguous empty state. The same retry behavior applies to stale remediation config loading.

Trigger On-Demand Stale Scan

Setting Up Remediation

Create a remediation config:

Actions: - notify_only — Generate alerts without making changes (safest) - disable — Disable stale accounts in AD - move_to_ou — Move stale accounts to a quarantine OU (requires target_ou DN)

Triggering Remediation

Requires ad.execute permission. Dispatches an agent job to the probe host.

Dual-user safety controls:

1. Manual trigger: For destructive actions (disable, move_to_ou), the system verifies that the user triggering remediation is NOT the same user who created the config. This prevents a single operator from unilaterally disabling or moving AD accounts without peer review. If the creator tries to trigger their own config, the request is rejected with 403.

ADGLP Compliance

Understanding ADGLP Analysis

ADGLP (Account-Global-Domain Local-Permission) is the Microsoft best practice for group nesting in Active Directory. Cadres analyzes group hierarchy and detects violations:

• Direct user in local group: A domain user placed directly in a privileged local group
• Global group in local group: A global group placed directly in a local group instead of going through a Domain Local group
• Universal group in local group: A universal group bypassing proper Domain Local nesting

Running a Group Analysis

Filter options: scope=all|dc|member_server

Executing ADGLP Remediation

Requires ad.execute permission. No auto-retry on failure (write operation).

Event Monitoring

Watched Groups

Add DNs to watched_groups to receive high-priority alerts when those groups are modified. Changes to watched groups generate: - “high” severity alert for additions - “critical” severity alert for member removals

Viewing Events

Returns per-type counts and total for the specified period.

Investigating Account Lockouts

Use the lockout investigation panel in the Events tab to aggregate 4740 lockouts by account instead of reading raw events one by one.

The response is paged and includes total lockouts, latest lockout time, distinct source DCs, and source-host hints when present.

If the lockout panel fails to load, the tab shows an inline error banner with a Retry action.

GPO Drift Detection

The GPO tab is designed as an automation monitoring surface. Under normal operation, baselines are created automatically when GPOs are discovered, and drift scans run on schedule. Manual controls are available in the “Break Glass” section at the bottom of the tab.

GPO Tab Overview

The GPO tab has five sections:

1. Status Overview – Summary cards showing total baselines, new (needs review), production, open drift events, and unauthorized drift count.
2. Password Policy Compliance – Summary cards plus a per-GPO table showing extracted password and lockout settings, baseline status, linked OUs, and failed benchmark checks.
3. Drift Events – Enhanced table with severity badges (high = “Unauthorized”), change record correlation (e.g., “CHG-123 (high confidence)”), severity/status filters, and page navigation controls.
4. Break Glass Controls – Collapsible section with manual “Capture Baseline” and “Scan for Drift” buttons.

GPO Baseline Lifecycle

Baselines progress through three states: - new – Auto-created when GPOs are discovered. Shown with a warning badge. Needs operator review. - production – Promoted by an operator. Shown with a success badge. Used for scheduled drift comparison. - demoted – Removed from active monitoring. Shown with a ghost badge.

Promote a baseline: Click the “Promote” button on a new baseline row (requires ad.manage). Calls:

Demote or delete a baseline: Click the delete action on a baseline row. Production baselines are demoted; new baselines are deleted outright. The UI opens an explicit confirmation dialog before sending:

Password Policy Compliance

The GPO tab also renders a password policy report derived from stored GPO baselines.

The report evaluates extracted policy values against the windows_cis_level1_core benchmark and shows total policies reviewed, compliant vs needs-review counts, and per-GPO minimum length, complexity, lockout threshold, lockout duration, and failed checks.

This report is baseline-derived and does not yet include fine-grained password policy (PSO) objects.

If the report fails to load, the card shows an inline error banner with a Retry action.

a Creating a GPO Baseline (Manual)

From the UI: Open the “Break Glass Controls” section and click “Capture Baseline”. This dispatches an agent job to the probe host:

From the agent (callback): The agent posts collected GPO data directly:

Scanning for Drift

From the UI: Open the “Break Glass Controls” section and click “Scan for Drift”. This dispatches an agent job:

From the agent (callback): The agent posts collected GPO state for comparison:

Managing Drift Events

If the baseline list, password policy report, or drift list fails to load, the GPO tab now renders an inline error banner with a Retry action so operators can recover without leaving the tab.

Backup and Restore

Creating a Backup

Backup types: - dns_zone — DNS zone backup (requires zone_name)

Requires ad.execute permission. The backup is created on the probe host, then uploaded to the Cadres backend where it is encrypted at rest.

Scheduled Backups

Configure via the dedicated backup policy endpoint:

Backup scheduling is the only AD scheduling that uses cron expressions. The backup policy loop runs every 5 minutes and dispatches backups when scheduled.

Downloading a Backup

Downloads the decrypted backup file. Requires ad.restore permission (listing/metadata requires only ad.view). The backend verifies the SHA-256 hash before serving the content.

Restoring from Backup

Restore operations require dual approval — two different users (other than the requester) must approve before the restore can proceed.

Step 1: Request restore

Creates an ADRestoreApproval record in pending status. The approval expires after 24 hours — if not approved in time, the request auto-expires.

Step 2: Approvers vote

Two users with ad.restore permission must approve (the requester cannot vote on their own request):

Separation of duties: ad.restore grants both requesting and voting on restores, plus downloading decrypted backups. ad.manage grants forest/probe/policy configuration but does not permit restore approval voting.

Step 3: Automatic dispatch

Once the required number of approvals is reached, the restore job is automatically dispatched to the probe host.

Step 4: Post-restore validation

After the restore completes, a validation job verifies: - AD authentication services are functional - Replication is working - Critical AD services are running

Backup Retention

Replication Health Monitoring

Viewing Replication Status

Shows: - Convergence time (seconds) - Partner health (total, healthy, failed)

Trigger On-Demand Check

Replication Alerts

When failed partners are detected, Cadres fires a “high” severity alert: ad_replication.replication_failure. The alert includes the number of failed vs. total partners.

AD Dashboard

Provides an aggregated view across all forests: - Total forests, domains, users, computers, groups, DCs - Per-forest summaries with domain counts and latest scan data - Exception counts in the exceptions field for the “Needs Attention” dashboard section: - unauthorized_drift_count — GPO drift without approved change records - failed_scan_count — forests with failed scans - pending_approvals_count — restore approvals awaiting votes - stale_threshold_exceeded_count — forests with stale accounts - backup_failure_count — forests with failed backups - probes_down_count — forests where all probes are failing

Permissions Reference

Permission	Operations
ad.view	List/view forests, inventory, stale results, replication, groups, events, backup metadata, restore approval status, dashboard
ad.manage	Create/update/delete forests, probes, policies, configs; trigger scans; scan-all; manage GPO baselines; acknowledge/resolve GPO drift
ad.execute	Trigger ADGLP remediation, stale remediation, create backups
ad.restore	Download decrypted backups, initiate restore requests, vote on restore approvals

UI Guide

The Active Directory page (Cadres > Active Directory) has 9 tabs:

For account admins, the page-level organization selector now loads accessible organizations in paged batches, so later tenants still appear even when the account has more orgs than fit on the first API page.

1. Dashboard — overview stats and “Needs Attention” exception cockpit. Exception cards show counts for unauthorized GPO drift, failed scans, pending restore approvals, stale account alerts, backup failures, and probe outages. Each card has a “View” button that navigates directly to the relevant tab. When all counts are zero, shows an “All Clear” indicator.
2. Forests — manage forests, edit intervals (scan/replication/group analysis), trigger scans. Click the probe badge to expand inline probe management (add/remove/toggle probes). Use the lightning bolt icon for scan-all.
3. Inventory — latest AD inventory snapshot. Click “History” to browse past scans.
4. Stale Accounts — stale account policies, paged audit history/detail, plus inline retryable errors when stale-result or remediation-config loads fail
5. Replication — replication topology diagram and partner health. Click “History” for past checks.
6. Groups — ADGLP compliance analysis
7. Events — security event monitoring configuration, event log, and lockout investigation workflow
8. GPO — Automation monitoring surface with status overview, baseline lifecycle management (new/production/demoted with promote action plus explicit demote/delete confirmation), password-policy compliance reporting, server-paginated baseline/drift tables with page controls and total counts, drift events with severity and change record correlation, inline retryable load errors, and collapsible Break Glass manual controls
9. Backups — create/download/restore backups, configure backup policy (schedule + retention), manage restore approvals (vote to approve/reject)

Permissions: - ad.view — read-only access to all tabs - ad.manage — CRUD forests, probes, policies, scan triggers, GPO baseline management, acknowledge/resolve GPO drift, delete backups - ad.execute — trigger ADGLP remediation, trigger stale remediation, create new backups - ad.restore — download backups, initiate restore requests, vote on restore approvals

Cross-References

• Network discovery: See network-discovery.md for discovery setup and probe management
• SNMP device management: See snmp.md for credential management, device registration, and polling