# ADscan (PyPI Launcher)

This PyPI package provides the `adscan` command as a lightweight **Python launcher**.

The launcher is responsible for:
- pulling the ADscan Docker image (`adscan install`)
- running the ADscan CLI inside Docker (`adscan start`, `adscan ci`, and passthrough commands)

The full ADscan CLI implementation lives inside the Docker image.

## Requirements

- Linux host (x86_64)
- Docker Engine + Docker Compose plugin installed
- Permission to run Docker (root or user in the `docker` group)

## Quick Start

```bash
pip install adscan
adscan install
adscan start
```

## Local development with `uv`

If you cloned this repository and want to run the launcher locally:

```bash
uv sync --extra dev
uv run adscan --help
uv run adscan version
```

Run lint/tests/build with `uv`:

```bash
uv run ruff check adscan_core adscan_launcher adscan_internal
uv run pytest -m unit
uv run python -m build
```

## Install from TestPyPI (Kali)

Use this when validating a TestPyPI release on Kali:

```bash
python -m pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  adscan --break-system-packages
```

Install a specific TestPyPI version:

```bash
python -m pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  adscan==5.0.0.devYYYYMMDDHHMMSS --break-system-packages
```

## Configuration

Override the Docker image used by the launcher:

```bash
export ADSCAN_DOCKER_IMAGE="adscan/adscan-lite:latest"
```

Use the dev channel image:

```bash
export ADSCAN_DOCKER_CHANNEL=dev
```

## User Documentation

User-facing installation, troubleshooting, and Docker/BloodHound operational guidance
is maintained in the ADscan docs site:

- https://www.adscanpro.com/docs/getting-started/installation
- https://www.adscanpro.com/docs/guides/troubleshooting
