ADPulse — Active Directory Security Scanner

ADPulse is an open-source Active Directory security auditing tool that connects to a domain controller via LDAP(S), runs 35 automated security checks, and produces detailed reports in console, JSON, and HTML formats.

It is designed for IT administrators, penetration testers, and security teams who need a fast, read-only assessment of AD misconfigurations and attack surface.

A PowerShell script named test_environment.ps1 is also included if you wish to set up your own vulnerable domain controller to test with.

Features

Security Checks (35 total)

Reporting

• Console — colour-coded terminal output with at-a-glance critical findings and key metrics
• JSON — machine-readable export for integration with SIEMs, ticketing systems, or custom dashboards
• HTML — self-contained dark-themed report with collapsible sections, severity badges, stat cards, scoring legend, and an ADCS template inventory

Scoring

Every finding carries a risk-score deduction. The overall score starts at 100 and is reduced per finding:

Requirements

• Python 3.8+
• Network access to a Domain Controller (port 636 for LDAPS, 389 for LDAP, 445 for SMB probes)
• A domain account with read access (no admin rights required for most checks)
• For check 25 (GPP/cpassword): SYSVOL must be accessible from the scanning host (UNC path on Windows, or Samba mount on Linux/macOS)

Python Dependencies

ldap3>=2.9
colorama>=0.4.6
dnspython>=2.4.0
pycryptodome
weasyprint

Installation

# Clone the repository
git clone https://github.com/yourorg/adpulse.git
cd adpulse

# (Recommended) Create a virtual environment
python -m venv venv
source venv/bin/activate        # Linux / macOS
venv\Scripts\activate           # Windows

# Install dependencies
pip install -r requirements.txt

Usage

Basic Scan

python ADPulse.py --domain corp.local --user jsmith --password 'P@ssw0rd!'

The DC IP is auto-resolved via DNS. All three report formats (console, JSON, HTML) are generated by default into a Reports/ folder.

Specify a Domain Controller

python ADPulse.py --domain corp.local --user jsmith --password 'P@ssw0rd!' --dc-ip 10.0.0.1

Choose Report Format

# Console only
python ADPulse.py --domain corp.local --user jsmith --password 'P@ssw0rd!' --report console

# JSON only
python ADPulse.py --domain corp.local --user jsmith --password 'P@ssw0rd!' --report json

# HTML only
python ADPulse.py --domain corp.local --user jsmith --password 'P@ssw0rd!' --report html

# All formats (default)
python ADPulse.py --domain corp.local --user jsmith --password 'P@ssw0rd!' --report all

Custom Output Directory

python ADPulse.py --domain corp.local --user jsmith --password 'P@ssw0rd!' --output-dir /tmp/scans

Reports are written to <output-dir>/Reports/.

Disable Colour Output

python ADPulse.py --domain corp.local --user jsmith --password 'P@ssw0rd!' --no-color

Full Argument Reference

Project Structure

adpulse/
├── ADPulse.py          # Entry point — argument parsing, orchestration
├── connector.py        # LDAP(S) connection, search helpers, SID resolution
├── checks.py           # All 35 security checks
├── models.py           # Finding and ScanResult data classes
├── report.py           # Console, JSON, and HTML report generation
├── __init__.py         # Package metadata
└── requirements.txt    # Python dependencies

How It Works

1. Connect — ADPulse binds to the target DC over LDAPS (port 636) with automatic fallback to LDAP (port 389). Authentication is attempted via NTLM and SIMPLE bind.
2. Scan — Each of the 35 check functions queries AD via LDAP and, for certain checks, performs supplementary operations: lightweight network probes (SMBv1, signing, null sessions) against discovered hosts, SYSVOL filesystem traversal for GPP credential detection, and raw binary DACL parsing for ACL-based checks.
3. Score — Findings are assigned a severity (CRITICAL → INFO) and a point deduction. The overall score is max(0, 100 - total_deductions).
4. Report — Results are rendered to the console and optionally exported as JSON and/or a self-contained HTML file.

All operations are read-only. ADPulse does not modify any AD objects, group memberships, GPOs, or ACLs.

Security Considerations

• ADPulse requires valid domain credentials. Store and transmit credentials securely.
• The SMB probe checks (SMBv1, signing, null sessions) send raw TCP packets to port 445 on discovered hosts. Ensure you have authorisation to perform network-level testing.
• The GPP/cpassword check (check 25) reads files from SYSVOL. No files are modified or deleted.
• HTML reports may contain sensitive information (account names, group memberships, SPN details, decrypted GPP passwords). Treat all report formats as confidential and store them securely.
• Run ADPulse from a trusted, hardened workstation on the target network.

Limitations

• Registry-only settings — NTLMv1 (LmCompatibilityLevel), WDigest (UseLogonCredential), LDAP signing (ldapServerIntegrity), and channel binding (ldapEnforceChannelBinding) cannot be read via LDAP. ADPulse flags these as manual verification items.
• GPO content — ADPulse checks GPO metadata (flags, version, SYSVOL path, links) but does not parse GPO settings files from SYSVOL (with the exception of the cpassword scan in check 25).
• SYSVOL access — Check 25 (GPP/cpassword) requires the scanning host to have filesystem access to SYSVOL. On Windows this is available via UNC path. On Linux/macOS the share must be mounted via Samba. If inaccessible, the check reports a manual verification notice.
• ADCS ESC8 — The HTTP web enrollment check requires network reachability to the CA's certsrv endpoint.
• SMB probes — Firewalls or host-based rules may block port 445, causing false negatives for SMBv1/signing/null session checks.
• Shadow credentials — msDS-KeyCredentialLink entries added by legitimate Windows Hello for Business deployments will be reported and require manual review to distinguish from attacker-planted entries.
• Size limits — LDAP queries are capped at 10,000 results per search. Very large domains may require multiple runs or increased server-side limits.

Contributing

Contributions are welcome. To add a new check:

1. Create a function in checks.py following the signature def check_name(ad: ADConnector) -> Tuple[List[Finding], Dict].
2. Add it to the checks list inside run_all_checks().
3. Add any new stat keys to _SPECIAL_STATS in report.py if they need dedicated rendering, or to _build_stat_cards() if they warrant a key-metric card.

License

This project is released under the MIT License. See LICENSE for details.

Disclaimer

ADPulse is provided as-is for authorised security assessments only. Always obtain written permission before scanning any Active Directory environment. The authors are not responsible for misuse or any damage caused by this tool.