This guide walks you through your first scan with ADscan in less than 5 minutes.

Authorization Required

Only use ADscan on systems you have written authorization to test. Unauthorized access to computer systems is illegal.

Labs vs real environments

This quickstart is designed to get you productive fast. Lab timings are benchmarks; validate against a real internal engagement baseline (time-to-first-credential, time saved, reporting). Running 2+ AD engagements/year? PRO beta access is free.

Prerequisites

Make sure you have:

ADscan installed (Installation guide)
Docker installed and running (docker info)
The ADscan image pulled (adscan install)
Network access to the target domain

ADscan does not need to be run under sudo. It prompts for elevation only for the few operations that genuinely require it.

Step 1: Start ADscan

Launch the interactive CLI:

adscan start

If ADscan detects missing dependencies, it will run a quick preflight check and may offer to repair common issues automatically. If you see warnings about missing components, run:

adscan check

You'll see the ADscan prompt:

(ADscan) >

Enable Verbose Mode (Optional)

For more detailed output during your first scan:

adscan start -v
# or
adscan start --verbose

Step 2: Create or Select a Workspace

Workspaces keep your scan data organized. How ADscan behaves on startup depends on whether workspaces already exist.

Case A: First run (no workspaces)

On the first run, after adscan start ADscan will prompt you for a workspace name:

Workspace creation (first run)

  ⚠ No workspaces detected.
  Enter name for a new workspace: : my_first_scan
  ✓ Workspace 'my_first_scan' created
  ℹ  Loading workspace data from: ~/.adscan/workspaces/my_first_scan
  ℹ  Variables loaded from ~/.adscan/workspaces/my_first_scan/variables.json
  ✓ Workspace data successfully processed for ~/.adscan/workspaces/my_first_scan
  ✓ Workspace 'my_first_scan' selected automatically as it's the only one.
  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) >

Case B: A single workspace already exists

If there is already exactly one workspace, ADscan loads it automatically:

Automatic workspace selection (single workspace)

  ℹ  Loading workspace data from: ~/.adscan/workspaces/client_2025
  ℹ  Variables loaded from ~/.adscan/workspaces/client_2025/variables.json
  ✓ Workspace data successfully processed for ~/.adscan/workspaces/client_2025
  ✓ Workspace 'client_2025' selected automatically as it's the only one.
  (ADscan:client_2025 ~/.adscan/workspaces/client_2025) >

Case C: Multiple workspaces exist

If you have several workspaces, ADscan shows a menu so you can select or create one:

Workspace selection menu

  ? Select a workspace: (Use arrow keys)
  Forest
  Test
  > [ + Create new workspace ]

To create a new workspace from the menu:

Create new workspace from menu

  ? Select a workspace: [ + Create new workspace ]
  Enter name for a new workspace: : my_first_scan
  ✓ Workspace 'my_first_scan' created
  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) >

You can also create additional workspaces at any time from the CLI:

Create workspace manually

  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) > workspace create my_first_scan

Workspace isolation

Each workspace keeps its credentials, enumeration data and attack graph separate. Use one per engagement.

Step 3: Configure Network Interface

Set your network interface (e.g., eth0, tun0 for VPN):

Configure interface

  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) > set iface tun0

Step 4: Choose Automation Level

ADscan offers two modes:

Semi-automatic (auto=False) - Prompts for each action (recommended for production)
Automatic (auto=True) - Faster, minimal prompts (good for labs/CTFs)

For your first scan, use semi-automatic mode:

Set automation mode

  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) > set auto False

Production Environments

Always use auto=False (semi-automatic mode) in production environments. With auto=True, ADscan automates safe steps but still asks for confirmation before noisy or high-impact operations. For real client environments, auto=False gives you maximum control and keeps every important action explicitly confirmed.

Step 5: Run Your First Scan

Option A: Unauthenticated Scan

Start with an unauthenticated scan to discover targets:

Unauthenticated scan

  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) > set hosts 10.10.10.0/24
  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) > start_unauth

ADscan will:

Discover Active Directory domain controllers
Enumerate users and computers
Perform anonymous LDAP queries
Extract useful information without credentials

If you later want to continue only the Kerberos username-enumeration step, rerun:

kerberos_enum_users <domain>

In audit workspaces, ADscan can build a more focused username list by combining a known corporate username format with statistically-likely corp username lists, manually supplied employee names, and optional LinkedIn employee discovery. If the username format is unknown, ADscan also ships a built-in general common username wordlist as a lower-friction fallback.

If you already know the domain and a DC IP, you can skip host-range discovery and go straight to enumeration:

Unauthenticated scan (domain known)

  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) > start_unauth example.local 10.10.10.1

Option B: Authenticated Scan

If you have credentials, start with an authenticated scan:

Authenticated scan

  (ADscan:my_first_scan ~/.adscan/workspaces/my_first_scan) > start_auth

ADscan will:

Verify the credential
Enumerate domain users, groups, and computers
Build the attack graph with the native LDAP collector
Detect escalation opportunities and store them as attack steps
Compute attack paths from your owned users to high-value targets
Offer guided execution for supported paths, with confirmations

You can also run start_auth <domain> <dc_ip> <username> <password|hash> to skip the guided prompts.

Correct flow for `creds save`

Use start_auth first to initialize the domain context (DNS/DC checks + credential validation). Then, if you obtain additional credentials later (for example from external tooling), add them with: creds save <domain> <username> <password|hash>.

Step 6: Review Attack Paths

Once start_auth finishes (or whenever you add new verified credentials), review what ADscan has discovered:

# Show paths from all owned users in this domain
attack_paths <domain> owned

# Show the underlying steps ADscan detected
attack_steps <domain>

In semi‑automatic mode (auto=False), treat this as your main decision point: inspect the chain and execute only what matches the rules of engagement.

Step 7: Follow Interactive Prompts

ADscan will guide you through the enumeration and exploitation process:

Green prompts: Safe enumeration actions
Yellow warnings: Potentially noisy operations
Red confirmations: Disruptive actions (always require explicit confirmation)

Example interactive flow (captured while walking through the HTB Forest guide):

Do you want to enumerate privileges for user svc-alfresco? [y/n] (y): y
Do you want to enumerate host 10.129.95.210 via WinRM as user svc-alfresco? [y/n]: y
Do you want to exploit the GenericAll/GenericWrite privilege on Exchange Windows Permissions? [y/n] (y):

Step 8: View results

Everything the scan produced is in the workspace:

ls ~/.adscan/workspaces/my_first_scan/

~/.adscan/workspaces/my_first_scan/
├── variables.json                       session state: domains, credentials, config
├── technical_report.json                the structured finding set reports render from
├── environment_changes.json             ledger of directory changes, and their rollback state
├── adscan_exposure_report_<stamp>.html  the exposure report (audit workspaces)
├── adscan_exposure_report_<stamp>.pdf
├── enabled_computers.txt                host rollups across every domain
├── logs/adscan.debug.log                always DEBUG on disk
├── smb/ ldap/ kerberos/ dns/ …          per-service ips.txt of the hosts that answered
├── flags/                               user.txt and root.txt, on a CTF workspace
└── domains/<domain>/
    ├── attack_graph.json                the graph, BloodHound-compatible
    ├── attack_paths_snapshot.json       computed paths and their status
    ├── inventory/                       users, computers, groups, acls, gpos, trusts, …
    ├── cracking/                        hashes, and whatever cracked
    └── kerberos/tickets/                ccaches, one per principal

The workspace page annotates the full layout.

The report writes itself on an audit workspace

If the workspace type is audit, ADscan renders a client-ready exposure report when the scan ends — HTML and PDF, no command needed. On a ctf workspace it does not; it offers you the verb instead, and you type it if you want it:

generate_report      # the exposure report for this workspace
writeup              # the evidence spine for a lab writeup

Both are documented under the exposure report.

Example: Complete CTF Scan

Here's a complete example for a CTF box:

# Start ADscan
adscan start

Complete CTF scan (interactive)

  (ADscan:forest ~/.adscan/workspaces/forest) > workspace create htb_forest
  (ADscan:forest ~/.adscan/workspaces/forest) > set iface tun0
  (ADscan:forest ~/.adscan/workspaces/forest) > set auto True
  (ADscan:forest ~/.adscan/workspaces/forest) > set hosts 10.10.10.161
  (ADscan:forest ~/.adscan/workspaces/forest) > start_unauth

ADscan will automatically:

Discover domain (htb.local)
Discover attack steps and compute attack paths to high‑value targets
Attempt quick credential wins where applicable (with safe defaults)
Prompt before noisy or disruptive actions (even in auto=True)
Continue mapping additional paths as access improves

For the HTB Forest machine, this process takes ~3 minutes in automatic mode.

Next steps

Workspace management
Scanning commands
Attack paths
Credential management
adscan ci — the same scan, unattended
A lab walkthrough end to end: HTB Forest

Getting Help

Within the ADscan shell, you can always get help:

# List all commands
(ADscan:workspace) > help

# Get help for specific command
(ADscan:workspace) > help start_auth

Community Support

Need help? Join our community:

Discord: discord.com/invite/fXBR3P8H74
GitHub Issues: github.com/ADscanPro/adscan/issues

Quick Start