Install the ADscan launcher with pipx/pip and pull the Docker images (recommended). Legacy host installer is available with --legacy.

ADscan is installed as a small launcher (pipx / pip) that runs ADscan inside Docker by default.

Current version: ADscan version 9.1.1-lite

Prerequisites (Docker mode — recommended)

Linux (x86_64) with Docker support
Docker Engine (docker)
Permission to run Docker (root or in the docker group)
Internet access (pulls the ADscan container image)
Supported runtime: Docker Engine (Podman Docker API is opt-in advanced mode)

Why Docker-first?

Docker mode avoids the biggest source of installation failures: dependency drift across distributions. It also keeps tooling isolated and makes upgrades much simpler.

Platform support

Launcher runtime commands (install, check, start, ci, update, upgrade) are supported on Linux hosts only. On unsupported platforms (for example macOS/Windows), ADscan now fails fast with a clear platform message. Linux arm64/aarch64 hosts are also blocked by default in Docker mode because ADscan runtime images are currently published for amd64. WSL / WSL2 is also blocked by default. Use a native Linux host or Linux VM instead.

Step 1 — Install the ADscan launcher

Method 1: Install with pipx (Recommended)

pipx ensures ADscan runs in an isolated environment without affecting your system Python.

# Install pipx if not already installed
sudo apt update
sudo apt install -y pipx
pipx ensurepath

# Install ADscan
pipx install adscan

Method 2: Install with pip

pip install adscan

Verify Installation

ADscan is designed to run as a normal user. It will request sudo only for the specific steps that need it.

adscan --version

Step 2 — Install Docker

If you already have Docker, verify it:

docker version

Note: ADscan 9.x no longer requires docker compose. The previous BloodHound CE container stack was replaced by the native attack-path collector, so the launcher only needs the Docker Engine.

Kali Linux (recommended)

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable --now docker

Debian / Ubuntu (recommended)

Install Docker Engine from Docker's official apt repository:

# Remove distro Docker packages that can conflict with docker-ce
sudo apt remove -y docker.io docker-compose docker-doc podman-docker containerd runc || true

# Add Docker's apt repository
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

# Ubuntu hosts
if [ "$( . /etc/os-release && echo "$ID" )" = "ubuntu" ]; then
  sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
else
  # Debian hosts
  sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
fi

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin
sudo systemctl enable --now docker

Parrot (recommended)

Use distro packages for simplicity/compatibility:

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable --now docker

Convenience script (quick setup)

get.docker.com is useful for fast development bootstrap, but for long-term reproducibility use package-repository installs.

curl -fsSL https://get.docker.com/ -o get-docker.sh
sudo sh ./get-docker.sh

Allow your user to run Docker without sudo (recommended):

sudo usermod -aG docker "$USER"
# Log out/in, or run:
newgrp docker

Step 3 — Pull the ADscan image

adscan install

Slow networks / VPN pulls

If your docker pull takes a long time (large images), consider installing on a faster connection (VPNs/proxies can throttle Docker pulls).

You can also increase the pull timeout:

adscan install --pull-timeout 3600

To disable the pull timeout entirely:

adscan install --pull-timeout 0

What this does (Docker mode):

Pulls the ADscan image (adscan/adscan-lite:latest)
Verifies Docker Engine is reachable and the user has permission to run containers
Prepares the workspace directory under ~/.adscan/

That's it — no additional services, no compose stack, no BloodHound container to manage. Attack-path analysis runs inside the ADscan container using the native graph collector. If you want a BloodHound UI to explore graphs visually, you can run your own BloodHound CE instance separately and load the exported attack_graph.json.

Podman environments

ADscan is validated against Docker Engine by default. If your DOCKER_HOST points to a Podman socket, launcher commands will fail fast unless you explicitly opt in:

export ADSCAN_ALLOW_PODMAN_DOCKER_API=1

Use this only if your Podman Docker API setup is intentional and stable.

Step 4 — Start ADscan

adscan start

Run as normal user

Run ADscan launcher as your normal user (recommended):

adscan install
adscan start

Avoid running from a root shell (sudo su / su -) because it can create state under /root/.adscan and cause permission/context issues.

Do not launch ADscan from inside the runtime container

ADscan FULL runtime must be started by the official host launcher installed with pipx install adscan or pip install adscan.

Do not docker exec into the container and run adscan manually from there. The launcher prepares required runtime wiring before startup, including:

host-helper socket access
local DNS resolver context
workspace/state mounts
launcher/runtime environment markers

If you open a shell inside the container and run adscan directly, ADscan now blocks startup on purpose and tells you to exit the container and launch it again from the host.

One Docker runtime session at a time

ADscan currently supports one active Docker runtime session per ADSCAN_HOME.

Do not launch adscan start, adscan ci, adscan check, or another launcher-driven Docker command from a second terminal while an ADscan runtime is already active.

Why this is blocked:

the host-helper socket is shared
runtime run/, state/, and logs/ mounts are shared
workspace persistence paths are shared

If you try to start a second session, ADscan now stops early and shows which launcher command is already active. Return to that terminal, exit the active ADscan session cleanly, then retry.

On start, ADscan will:

Run the ADscan container with host networking
Mount persistent directories from ~/.adscan/:
- workspaces/
- logs/
- run/
- state/
- .config/ (used by local CLI integrations like Codex auth)

The launcher also injects runtime-only context that the container needs for premium workflows such as GUI host file picking, host clock sync, and AD-managed DNS forwarding. This is why the supported way to run ADscan is always:

adscan start

from the host terminal, not from an interactive shell inside the container.

Memory / OOM

ADscan validates RAM headroom before starting the runtime container in: adscan install, adscan start, adscan check, and adscan ci.

Current behavior:

< 1.0 GB available RAM: critical low-memory guard (non-interactive runs fail fast; interactive runs require explicit confirmation)
1.0 - 1.5 GB: warning only (startup may still fail with OOM)
>= 1.5 GB: no low-memory warning

To continue intentionally in constrained environments, use:

adscan install --allow-low-memory
adscan start --allow-low-memory
adscan check --allow-low-memory
adscan ci --allow-low-memory -- <ci-args>

See Troubleshooting for full diagnostics.

Legacy host-based install (not recommended)

If Docker is not allowed in your environment, you can still use the legacy installer:

adscan install --legacy
adscan check --legacy --fix
adscan start --legacy

Docker mode is the default; --legacy opts into the old apt/pip/go/rust-based provisioning.

Important: Remove legacy sudo alias (if present)

Older versions used to add a shell alias that forced running every command as sudo -E. This is no longer required and can cause permission issues (for example, a root-owned ~/.adscan directory).

If you previously used a legacy alias, remove the block from your shell config (~/.zshrc, ~/.bashrc, or ~/.bash_aliases) and repair ownership:

# Remove the legacy alias block (look for "# ADscan auto-sudo alias")
# Then fix ownership if needed:
sudo chown -R "$USER":"$USER" ~/.adscan

Next Steps

Once installation is complete, proceed to the Quick Start guide to run your first scan.

Troubleshooting

If you run into issues, see the Troubleshooting guide. For Docker-mode startup blockers, use the Host helper troubleshooting section.

🛠️ Installation