Metadata-Version: 2.4
Name: adpentest
Version: 3.0.2
Summary: Active Directory penetration testing framework with automatic Domain Controller detection
Author-email: Netanel Cyber <nsh531@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/netanelcyber/AdPentestAI-Python
Project-URL: Repository, https://github.com/netanelcyber/AdPentestAI-Python.git
Project-URL: Issues, https://github.com/netanelcyber/AdPentestAI-Python/issues
Project-URL: Documentation, https://github.com/netanelcyber/AdPentestAI-Python#readme
Keywords: active-directory,penetration-testing,ad-enumeration,kerberos,smb,ldap,security,offensive-security,red-team
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: dnspython<3,>=2.4
Requires-Dist: ldap3<3,>=2.9
Requires-Dist: jinja2>=3.0
Requires-Dist: SQLAlchemy<3,>=2.0
Provides-Extra: kerberos
Requires-Dist: impacket<1,>=0.12; extra == "kerberos"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# AdPentestAI-Python

## WinRM profile — version 3.0.2

Run anonymous WinRM discovery on one authorized target, with JSON, SQLite,
table and HTML output:

```powershell
python -m adpentest --winrm-check --target ITGO_NETANEL-DC.netanel-pt.local --mode active --scope-confirmed --winrm-diagnostics --winrm-domain netanel-pt.local --table --db-path winrm.db --html-report winrm.html
```

The default is dry-run when `--mode active` is omitted. Discovery works without
credentials on Windows/Linux. Opt-in authenticated checks use native Windows
PowerShell with an existing identity or an explicit authorized test account.
WORKGROUP/no-ticket, DNS/DC discovery, authentication, endpoint permission and
remote token observations are reported separately. No CVE or privilege escalation
is confirmed merely because a port is open or an administrative token is present.

See [the WinRM guide](docs/WINRM_PENTESTING.md) for all options, secure credential
handling, permission/RunAs auditing, platform limits and SQL report examples.

[![GitHub stars](https://img.shields.io/github/stars/netanelcyber/AdPentestAI-Python?style=flat)](https://github.com/netanelcyber/AdPentestAI-Python/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/netanelcyber/AdPentestAI-Python)](https://github.com/netanelcyber/AdPentestAI-Python/issues)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/adpentest)](https://pypi.org/project/adpentest/)

**Active Directory penetration testing framework** with automatic Domain Controller detection, multi-threaded tool execution, WAF bypass engine, CVE scanning, and SQLite scan history.

> **For authorized penetration testing only.** Always get explicit written permission before testing any systems.

---

## Table of Contents

- [WinRM profile — version 3.0.2](#winrm-profile--version-302)
- [Quick Start](#quick-start)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Kerberos security and remediation](docs/KERBEROS_SECURITY.md)
- [CVE Scanners](#cve-scanners)
- [WAF Detection & Bypass](#waf-detection--bypass)
- [Scan History Database](#scan-history-database)
- [DC Detection Strategies](#dc-detection-strategies)
- [Tool Registry](#tool-registry)
- [Email Protocol Enumeration](#email-protocol-enumeration)
- [DNS Configuration](#dns-configuration)
- [Architecture](#architecture)
- [Contributing](#contributing)
- [License](#license)

---

## Quick Start

```bash
pip install adpentest

# Dry-run — preview what would execute, no actual tool runs
adpentest --target 10.0.0.1 --mode dry-run --scope-confirmed

# Active scan with auto DC detection
adpentest --target corp.local --mode active --scope-confirmed

# View scan history
adpentest --history

# View only current verified CVE findings
adpentest --cve-report
```

### Confirmed CVE findings

The CVE report, HTML findings, and dashboard show only confirmed findings.
An open port, service banner, signing observation, or high correlation score
does not establish a specific CVE. All built-in heuristic scanners return
`assessment: "unverified"` until target-specific proof is available. Passive
correlations are retained under `passive_cve_scan.observations`; `matches`
contains no unverified candidates. Raw tool observations remain available.

Supply inventory collected from the target with `--cve-evidence FILE.json`.
The file is an array of proofs keyed by exact CVE and target. Each proof must
include this structure, replacing placeholders with observed facts:

```json
[
  {
    "cve": "CVE-2025-33073",
    "target": "192.0.2.10",
    "method": "vendor-version-and-patch-inventory",
    "checked_at": "<UTC timestamp of the inventory>",
    "vendor": "<exact vendor in the official record>",
    "product": "<exact product in the official record>",
    "version": "<observed product/build version>",
    "platform": "<platform if the official record restricts it>",
    "patch_state": "missing",
    "prerequisites_verified": true,
    "advisory_url": "<vendor advisory listed in the official record>",
    "evidence": {
      "product_version": {"source": "inventory.json", "sha256": "<SHA-256 of inventory.json bytes>", "value": "<same observed version>"},
      "patch_inventory": {"source": "inventory.json", "sha256": "<same file digest>", "value": {"complete": true, "installed": [], "missing": ["<applicable vendor patch>"]}},
      "prerequisites": {"source": "inventory.json", "sha256": "<same file digest>", "value": ["<CVE-specific condition verified on this target>"]}
    }
  }
]
```

Each `source` names a local collector export relative to the selected manifest's
directory. An export has `collection_method: "authenticated-inventory"`, the
same `cve`, `target`, `checked_at`, `vendor`, `product`, `platform`, and
`advisory_url` as its proof, plus an `evidence` object mapping the three kinds
to their actual values. For example:

```json
{
  "collection_method": "authenticated-inventory",
  "cve": "CVE-2025-33073",
  "target": "192.0.2.10",
  "checked_at": "<UTC timestamp of collection>",
  "vendor": "<vendor>", "product": "<product>", "platform": "<platform>",
  "advisory_url": "<official advisory URL>",
  "evidence": {
    "product_version": "<observed version>",
    "patch_inventory": {"complete": true, "installed": [], "missing": ["<applicable patch>"]},
    "prerequisites": ["<verified CVE-specific condition>"]
  }
}
```

The operator must select authentic exports from a trusted authenticated
collector, including the applicable vendor patch and prerequisite checks.
The verifier checks their bytes, binding, freshness, complete patch inventory,
and consistency; a file digest by itself does not prove the truth of a capture.
Absolute paths, traversal, and paths outside that directory are rejected.
Imported JSON cannot select an evidence manifest or authorize its own files.

The verifier fetches the official [CVE List](https://github.com/CVEProject/cvelistV5)
record, requires `PUBLISHED`, checks CVE identity, advisory, product, platform,
and affected version range, recomputes SHA-256 over the fetched response bytes,
rejects unexpected redirects, and uses the record's severity. Reserved, rejected,
missing, mismatched, or unverifiable records do not qualify. Inventory and
record verification expire after 24 hours; metadata refreshes at least hourly
when used. Only exact versions and numeric `semver` ranges without status
changes are currently supported; custom/git/Maven ordering stays unverified. The inventory proof
confirms applicability and missing updates; it does not perform exploitation.
Existing historical rows are retained, and legacy `vulnerable=true` flags
without this proof are excluded from current reports.

To revalidate history or a saved report, explicitly supply the current local
manifest again. Missing local files, changed bytes, expired inventory, record
changes, and legacy confirmation schema 1 remain unverified. SQLite table
layouts and existing CLI arguments are preserved; JSON adds `result_table`
and confirmation policy schema 2. Default output remains JSON.

```bash
python -m adpentest --history --cve-evidence evidence/proofs.json
python -m adpentest --run-details RUN_ID --cve-evidence evidence/proofs.json --table
python -m adpentest --report-input prior-report.json --cve-evidence evidence/proofs.json --table --html-report report.html
```

The WebForms dashboard delegates verification to the same Python policy.
Administrators can set absolute `AdPentestPythonPath`,
`AdPentestWorkingDirectory`, and `AdPentestCveEvidencePath` in app settings.
The evidence path is also passed to new scans. Without a configured manifest
or a working verifier, no imported CVE is displayed as confirmed.

### Kerberos tickets and all-results tables

To run all eight fixed diagnostic profiles through the main module, use
`python -m adpentest --diagnostic-tools all --target dc.lab.example --domain lab.example --mode dry-run --db-path diagnostics.sqlite`.
The [main-module guide](docs/KERBEROS_SECURITY.md#run-all-diagnostic-profiles-from-the-main-module)
also documents active mode, output, and the separate local ticket/export commands.

See [Kerberos security and remediation](docs/KERBEROS_SECURITY.md) for the
privilege boundaries, configuration checks, and correction of the old
[Golden Ticket guide](GOLDEN_TICKET_CREDENTIAL_GUIDE.md). Port 88 reachability,
SPN metadata, and successful authentication do not prove privilege escalation.
Normal TGT/TGS requests authenticate the supplied account; they do not turn
a test user's ticket into an administrator ticket.

Install the optional cross-platform ticket client with
`python -m pip install -e '.[kerberos]'` from this checkout. `--obtain-tickets` requests a TGT
for the supplied account and normal TGS only for explicit `--ticket-spn`
values. Dry-run lists planned requests. Active requests require
`--scope-confirmed`, the realm/account/KDC, a private output directory, and a
password entered with a secure prompt or read from an explicitly named
environment variable. Passwords are never placed in command arguments.

```bash
python -m adpentest --obtain-tickets --ticket-domain lab.example --ticket-user researcher --ticket-kdc dc.lab.example --ticket-spn cifs/server.lab.example --table
python -m adpentest --obtain-tickets --ticket-domain lab.example --ticket-user researcher --ticket-kdc dc.lab.example --ticket-spn cifs/server.lab.example --ticket-output-dir private-tickets --mode active --scope-confirmed --table
python -m adpentest --ticket-inventory --ticket-cache FILE:private-tickets/example.ccache --table
```

Ticket inventory reads local FILE ccaches, including available and expired
tickets; other cache backends remain explicitly unsupported. Acquisition and
inventory may be combined with `--target` to include metadata in a scan's
JSON, HTML and SQLite tool results. Credential caches are saved separately
with mode 0600 in a 0700 directory on Unix; use a directory restricted to the
account by ACLs on Windows. Reports include client, service, ticket kind,
encryption type, status and expiry, without passwords, keys or ticket bytes.

`--table`, HTML and WebForms show all CVE candidates, SMB configuration
observations, tool outcomes and ticket metadata with their status. Unverified
CVEs have informational severity and do not affect CVE risk or active-CVE
counts. Successful Kerberos authentication does not establish a vulnerability.

## Features

### Core Capabilities

- **Auto DC Detection** — discovers Domain Controllers via DNS SRV records, LDAP RootDSE probes, port fingerprinting, and subnet sweep
- **Multi-threaded execution** — 16 parallel workers for tool execution, 32 workers for port/DNS/credential tasks (10-15x speedup)
- **35+ AD/SMB/Kerberos/ADCS/Email tools** — cross-platform binary tools + pure Python implementations
- **CVE candidate probes** — service/configuration observations; current CVE confirmation requires the official-record and target-inventory policy described above
- **WAF detection & bypass** — identifies WAF/CDN vendors and attempts bypass via HTTP spoofing, raw LDAP/Kerberos, TCP fragmentation
- **SQLite scan history** — persistent storage of all scan runs, tool results, and CVE findings
- **Auto-install** — missing tools installed automatically via apt/pip/git
- **Safety** — `dry-run` is the default mode; `--scope-confirmed` required for authorization

### Attack Vectors

| Category | Tools | Description |
|----------|-------|-------------|
| **Reconnaissance** | nmap, masscan, enum4linux-ng, rpcdump, bloodhound-python, ldapdomaindump | Network & AD enumeration |
| **SMB** | smbclient, smbmap, crackmapexec, impacket | Null sessions, share enum, signing detection, credential testing |
| **Kerberos** | LDAP/SPN analysis, local FILE ccache inventory, normal account TGT/TGS requests | Directory and ticket metadata; each operation has its own scope and prerequisites |
| **ADCS** | certipy (find, shadow, ESC1, ESC3, ESC9) | Certificate template analysis & exploitation |
| **Email** | SMTP/POP3/IMAP enum & auth testing | User discovery, credential testing, Exchange detection |
| **Privilege Escalation** | ACL scanner, GPO abuse, delegation chain, auto privesc | Permission analysis & escalation paths |
| **Persistence** | Golden/silver ticket, DCshadow, skeleton key, DSRM, SID history | Domain persistence techniques |
| **Coercion & Relay** | PetitPotam, PrinterBug, NTLM relay | Authentication coercion attacks |
| **CVE Scanning** | Built-in candidate probes | Unverified observations until current official records and target-specific evidence confirm applicability |

---

## Installation

### From PyPI

```bash
pip install adpentest
```

### From Source

```bash
git clone https://github.com/netanelcyber/AdPentestAI-Python.git
cd AdPentestAI-Python
pip install -e .
```

### Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| `httpx` | >= 0.27 | HTTP client for EWS/web enumeration |
| `dnspython` | >= 2.4 | DNS resolution with SRV record support |
| `ldap3` | >= 2.9 | LDAP operations (RootDSE, anonymous bind) |

Standard library modules used: `smtplib`, `poplib`, `imaplib`, `socket`, `concurrent.futures`, `subprocess`, `sqlite3`, `json`.

---

## Usage

### Basic Scans

```bash
# Dry-run (check tools, detect DCs, preview commands — no actual execution)
adpentest --target 10.0.0.1 --mode dry-run --scope-confirmed

# Active scan with auto DC detection
adpentest --target corp.local --mode active --scope-confirmed

# Custom timeout and no auto-install of missing tools
adpentest --target 192.168.1.10 --mode active --scope-confirmed --timeout 600 --no-auto-install

# Custom DNS servers
adpentest --target corp.local --mode active --scope-confirmed --dns-server 1.1.1.1,8.8.8.8

# Connect via VPN before scanning
adpentest --target 10.10.10.1 --mode active --scope-confirmed --vpn lab.ovpn
```

### Scan History & Reports

```bash
# Show all past scan runs
adpentest --history

# Show last 5 runs
adpentest --history --history-limit 5

# Show all vulnerable CVE findings across all runs
adpentest --cve-report

# Show details for a specific run
adpentest --run-details run-8824073e5124-20260904055457

# Use custom database path
adpentest --history --db-path /path/to/custom.db
```

### HTML Pentest Report Generation

Generate an executive-ready, standalone, and interactive HTML penetration test report (<100KB):

```bash
# Generate report during active scan
adpentest --target corp.local --mode active --scope-confirmed --html-report report.html

# Generate report from an existing JSON output file
python -m adpentest.report_generator scan_results.json report.html
```

- **0.0 - 10.0 Executive Risk Score** with CVSS & severity metrics gauge
- **Interactive Dark / Light mode** toggle & print-optimized layout
- **Target architecture & Domain Controller detection** breakdown
- **Categorized security findings** with remediation advice
- **Collapsible tool execution logs** with timing and duration metrics


### Lab Setup

```bash
# Interactive lab setup orchestrator
adpentest --setup-labs
```

### Output Format

All scan output is JSON:

```json
{
  "status": "completed",
  "run_id": "run-abc123-20260901120000",
  "db_path": "~/.adpentest/scan_history.db",
  "dc_detection": {
    "dc_count": 2,
    "detected_domain": "corp.local",
    "domain_controllers": [...]
  },
  "execution": {
    "result_count": 35,
    "completed": 28,
    "failed": 7
  }
}
```

See [`examples/sample-dry-run-output.json`](examples/sample-dry-run-output.json) for a complete example.

---

## CVE Scanners

The built-in candidate probes collect service, protocol, and configuration
observations when selected by a scan. The identifiers below are implementation
labels, not independently verified mappings between a probe and a vulnerability.
Use the official-record and target-inventory policy in
[Confirmed CVE findings](#confirmed-cve-findings) to establish applicability,
affected versions, severity, and missing updates. A successful probe alone
does not establish exploitation or a specific CVE.

Some probes attempt authentication; they are not all anonymous or passive.
Check the selected operation and prerequisites before an active run.

| Candidate identifier | Observation collected by the implementation |
| --- | --- |
| CVE-2026-59270 | Embedded-LDAP authentication and accessible directory data |
| CVE-2026-54121 | AD CS enrollment-service/template metadata |
| CVE-2025-54918 | LDAP authentication/signing-related observations |
| CVE-2026-33826 | RPC-related port exposure and AD directory metadata |
| CVE-2026-27912 | Kerberos/kpasswd reachability and available domain metadata |
| CVE-2026-24294 | SMB negotiation/signing and alternative-port observations |
| CVE-2026-20833 | Replies to Kerberos requests selecting encryption types |

### What Each Scanner Checks

**CVE-2026-59270** — Attempts an embedded-LDAP credential check and reports accessible entry counts. This is an authentication attempt, not an anonymous metadata query.

**CVE-2026-54121** — Queries AD CS Enrollment Services and certificate templates via LDAP. Identifies templates with `ENROLLEE_SUPPLIES_SUBJECT` flag or risky enrollment configurations.

**CVE-2025-54918** — Checks if LDAP accepts NTLM/GSS-SPNEGO authentication without enforced signing. Extracts DC functional level and domain context.

**CVE-2026-33826** — Probes RPC endpoint mapper (port 135), confirms AD DC via LDAP, checks for exposed RPC-related ports (135, 593, 445, 139).

**CVE-2026-27912** — Checks kpasswd (port 464) and Kerberos (port 88) reachability and queries available domain metadata, including `ms-DS-MachineAccountQuota`. These observations do not verify a password-reset bypass, affected patch state, or domain takeover.

**CVE-2026-24294** — Sends SMB2 Negotiate to detect protocol version and signing mode. Checks for alternative SMB ports (8445, 9445, etc.) indicating port multiplexing.

**CVE-2026-20833** — Sends Kerberos requests selecting RC4 (etype 23), AES256 (etype 18), and AES128 (etype 17). A protocol/error reply is not proof that a ticket was issued with the selected type or that a specific CVE is present; validate the actual result and current vendor requirements.

Additional registered candidate probes include `cve_2025_33073`,
`cve_2025_29810`, `cve_2025_58726`, `cve_2026_25177`, `cve_2025_24054`, and
`cve_2026_20929`. Their labels and observations have the same confirmation
requirements; the registry is not a list of confirmed vulnerabilities.

---

## WAF Detection & Bypass

When scanning targets behind WAF/CDN services, the framework automatically:

1. **Detects WAF vendor** — checks HTTP headers and body content for signatures of 17+ WAF vendors (Incapsula/Imperva, Cloudflare, Akamai, AWS WAF, Azure Front Door, Sucuri, etc.)
2. **Attempts bypass** via 5 technique layers:
   - **HTTP bypass** — header spoofing (X-Forwarded-For, X-Real-IP, CF-Connecting-IP), User-Agent rotation, path obfuscation, verb tampering
   - **Raw LDAP** — BER-encoded LDAPv3 anonymous bind directly to port 389
   - **Raw Kerberos** — AS-REQ with TCP framing to port 88
   - **TCP fragmentation** — 1 byte per TCP segment with TCP_NODELAY
   - **Email/HTTP** — OWA, EWS NTLM handshake, Autodiscover, ActiveSync, MAPI probing

The legacy engine can label raw LDAP/Kerberos responses as a WAF bypass and
adjust its DC-detection confidence. Interpret those responses as separate
service/protocol observations: direct LDAP or Kerberos reachability does not
establish a bypass of an HTTP WAF or an authentication boundary.

---

## Scan History Database

All scan data is automatically stored in SQLite at `~/.adpentest/scan_history.db`.

### Database Schema

**`scan_runs`** — One row per scan execution:
- `run_id`, `target`, `mode`, `started_at`, `finished_at`, `status`
- `dc_count`, `live_hosts`, `tools_executed`, `tools_succeeded`, `tools_failed`
- `cves_checked`, `cves_vulnerable`

**`tool_results`** — One row per tool execution:
- `tool`, `host`, `is_dc`, `fqdn`, `status`, `duration_sec`, `output`, `error`

**`cve_findings`** — One row per CVE check:
- `cve_id`, `target`, `cvss`, `severity`, `vulnerable`, `impact`, `details_json`

### Querying Directly

```bash
# Open the database
sqlite3 ~/.adpentest/scan_history.db

# Historical rows carrying a stored flag; this query does not revalidate evidence
SELECT cve_id, target, cvss, severity, impact FROM cve_findings WHERE vulnerable=1 ORDER BY cvss DESC;

# Scan history summary
SELECT run_id, target, mode, status, tools_executed, cves_vulnerable, started_at FROM scan_runs ORDER BY started_at DESC;

# Tool success rate
SELECT tool, COUNT(*) as runs, SUM(CASE WHEN status='completed' THEN 1 ELSE 0 END) as ok FROM tool_results GROUP BY tool ORDER BY runs DESC;
```

For current confirmed findings, use `--cve-report --cve-evidence FILE.json`.
SQL over historical flags cannot replace fresh record and local-artifact checks.

---

## DC Detection Strategies

The framework uses a multi-strategy pipeline to discover Domain Controllers:

| Strategy | Method | Confidence |
|----------|--------|------------|
| DNS SRV | Queries `_ldap._tcp.dc._msdcs.<domain>` | High (0.9) |
| LDAP RootDSE | Anonymous bind to extract domain/forest info | High (0.9) |
| Port fingerprint | Checks Kerberos (88), LDAP (389/636), GC (3268/3269) | Medium (0.7) |
| Subnet sweep | Kerberos port 88 scan on /24 → /23 → /22 | Medium (0.6) |

The legacy engine may adjust its heuristic confidence to 0.7 (`waf-bypassed`)
or 0.1 (`waf-blocked`). These labels describe its probe outcome; they do not
confirm an HTTP WAF bypass, Kerberos privilege escalation, or a CVE.

---

## Tool Registry

### Available Tools (35+)

**Binary tools:** nmap, masscan, enum4linux-ng, rpcdump, smbclient, bloodhound-python, certipy, ldapdomaindump, kerbrute, crackmapexec, smbmap, impacket (secretsdump, psexec)

**Windows-native:** powershell_ldap_enum, powershell_smb_enum, powershell_ad_recon

**Kerberos:** GetUserSPNs, AS_REP_roast, kerberoast

**ADCS:** certipy_shadow, certipy_esc1, certipy_esc3, certipy_esc9

**Email:** smtp_enum, smtp_auth_test, pop3_auth_test, imap_auth_test, email_server_discovery

**Exploitation:** ntlm_null_session, auto_privesc, golden_ticket, silver_ticket, delegation_abuse, trust_enumeration, trust_abuse, petitpotam, printerbug, ntlm_relay, acl_scanner, acl_exploit, gpo_abuse, delegation_chain, sid_history, dsrm_backdoor, dcshadow, golden_gmsa, skeleton_key

**CVE scanners:** cve_2026_59270, cve_2026_54121, cve_2025_54918, cve_2026_33826, cve_2026_27912, cve_2026_24294, cve_2026_20833

---

### SMB protocol version testing

The built-in `smb_version_test` tool negotiates SMB 2.0.2, 2.1, 3.0, 3.0.2,
and 3.1.1 on TCP 445 and independently checks SMBv1. It uses the current Python
interpreter and is included in the careful active tool set. Dry-run only
previews its command; active execution sends negotiation requests without
authenticating or accessing shares.

The API is also available independently of the full scan workflow:

```python
from adpentest.core import test_smb_versions

result = test_smb_versions("192.0.2.10", timeout=5.0)
```

Existing result keys are retained. Support and security fields use `true` for
an observed positive, `false` for an explicit negative, and `null` when the
probe is inconclusive. Each entry in `dialect_results` retains its negotiation
error and status code. `max_dialect` is the highest successfully observed
dialect; partial failures return `completed-with-errors`. Signing and encryption
fields describe that dialect. Encryption capability does not establish share
encryption enforcement, and SMBv1 support does not confirm a specific CVE.

Wire formats follow Microsoft's [SMB2 NEGOTIATE request](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/e14db7ff-763a-4263-8b10-0c3944f52fc5)
and [response](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/63abf97c-0d09-47e2-88d6-6bfa552949a5)
specifications, including SMB 3.1.1 preauthentication and encryption contexts.

## Email Protocol Enumeration

Pure Python email enumeration using standard library (no external dependencies):

- **SMTP VRFY** — discover valid usernames via VRFY command
- **SMTP RCPT TO** — validate recipients via RCPT TO
- **Credential testing** — automatic fallback chain: SMTP → POP3 → IMAP
- **Exchange detection** — OWA, EWS NTLM handshake (extracts domain/DC/forest from NTLM challenge), Autodiscover, ActiveSync, MAPI
- **Parallel testing** — 32 concurrent workers for credential testing

Ports scanned: 25, 465, 587 (SMTP), 110, 995 (POP3), 143, 993 (IMAP).

---

## DNS Configuration

### Priority Order

1. **CLI arguments** (`--dns-server`, `--dns-timeout`) — highest priority
2. **Environment variables** (`DNS_SERVERS`, `DNS_TIMEOUT`)
3. **System default DNS** — auto-detected
4. **Public DNS fallback** — Google (8.8.8.8, 8.8.4.4), Cloudflare (1.1.1.1, 1.0.0.1)

```bash
# CLI
adpentest --target corp.local --mode active --scope-confirmed --dns-server 192.168.1.1,8.8.8.8 --dns-timeout 5.0

# Environment
export DNS_SERVERS=192.168.1.1,1.1.1.1
export DNS_TIMEOUT=5.0
adpentest --target corp.local --mode active --scope-confirmed
```

---

## Architecture

### Single-File Design

All framework logic is in `adpentest/core.py`. This monolithic approach provides clear dependency flow, centralized tool registry, unified error handling, and easy deployment.

### Execution Pipeline

```
Input: --target 10.0.0.1 --mode active --scope-confirmed
  │
  ├── Scope validation (dry-run vs active)
  ├── Tool discovery (scan $PATH)
  ├── SQLite run initialization
  │
  ├── DC Detection (multi-strategy)
  │   ├── DNS SRV queries
  │   ├── LDAP RootDSE probe
  │   ├── Port fingerprint (+ WAF detect/bypass)
  │   └── Subnet sweep (/24 → /23 → /22)
  │
  ├── Domain discovery + FQDN resolution
  ├── Email server discovery (MX + port scan)
  │
  ├── Parallel Tool Execution (ThreadPoolExecutor, 16 workers)
  │   ├── AD tools against DCs (prioritized)
  │   ├── CVE scanners against all targets
  │   └── Results → SQLite (tool_results + cve_findings)
  │
  └── Output: JSON + SQLite database
```

### Threading Model

| Pool | Workers | Purpose |
|------|---------|---------|
| Tool execution | 16 | AD diagnostic tools in parallel |
| Port scanning | 32 | Concurrent TCP port checks |
| DNS resolution | 32 | Concurrent DNS queries |
| Credential testing | 32 | SMTP/POP3/IMAP auth testing |

---

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines.

Check the [open issues](https://github.com/netanelcyber/AdPentestAI-Python/issues) for tasks labeled `good-first-issue` or `help-wanted`.

### Adding a New CVE Scanner

1. Add scanner function `scan_cve_YYYY_NNNNN(target, timeout)` returning a dict with `cve`, `cvss`, `severity`, `vulnerable`, `impact`, `remediation`
2. Add tool name `cve_YYYY_NNNNN_short_name` to `AD_TOOLS` set
3. Add to `PIP_PACKAGES` (empty list for pure Python)
4. Add to `EXECUTABLES` (python3/python/python.exe)
5. Add `build_ad_command` handler

### Adding a New Tool

1. Add tool name to `AD_TOOLS` set
2. Add package mapping to `PIP_PACKAGES`/`APT_PACKAGES`/`WINGET_PACKAGES`
3. Add executable names to `EXECUTABLES` dict
4. Implement command building in `build_ad_command()`

---

## License

[MIT](LICENSE)

---

**Disclaimer:** This tool is designed for authorized penetration testing and security research only. Users are responsible for obtaining proper authorization before testing any systems. The authors assume no liability for misuse.
