Installation and First Run

Host environment

• OS: Linux or macOS recommended; Windows via WSL2 + Docker Desktop.
• Python 3.9 or higher, Git, Docker Engine or Docker Desktop.
• RAM: 8 GB minimum; 16 GB if LLM agent + proxy + several containers.
• Network: Internet access for pip install and initial Docker images.
• Local ports: 80 (DVWA), 8080/9090 (WebGoat/WebWolf), 21/80/2222/3306 (Metasploitable) --- verify no other service occupies them.

Step-by-step installation

Clone and prepare the venv

git clone https://github.com/SIA-IOTechnology/Kittysploit-framework
cd Kittysploit-framework
python3 -m venv venv
source venv/bin/activate    # Windows: venv
pip install -r install/requirements.txt

First launch

python kittyconsole.py

Accept the usage charter. Then in the console:

banner
status
doctor
sync now
lab list

• sync now indexes modules for search.
• lab list displays JSON scenarios under labs/.
• doctor produces a health report (Python, dependencies, Docker, assets).

The doctor command in detail

doctor centralizes pre-campaign checks. Typical categories:

doctor
agent doctor

agent doctor completes the diagnosis for Ollama, agent policies, and LLM dependencies.

Interpreting the report

• FAIL: blocking --- fix before isolated test environments (often Docker or dependency).
• WARN: degraded functionality (Tor absent, optional asset).
• OK: prerequisite satisfied.

Docker management: environments

The isolated test environment command starts usage scenarios; environments manages all KittySploit containers (including those launched via use docker_environments/...).

Subcommands

environments
environments list
environments info kittysploit_dvwa
environments stop kittysploit_dvwa
environments restart kittysploit_dvwa
environments stop all
environments help

Docker troubleshooting

Common symptoms

1. Cannot connect to Docker in environments or lab start.
2. lab score fails on TCP objective (closed port).
3. Port already in use (80, 8080, 2222).
4. Container exited immediately after start.

Linux checklist

# Daemon actif ?
sudo systemctl status docker
sudo usermod -aG docker $USER   # puis deconnexion/reconnexion
docker ps
docker pull hello-world && docker run --rm hello-world

In KittySploit:

doctor
lab reset dvwa-basics
lab start dvwa-basics
environments info kittysploit_dvwa
lab score dvwa-basics --skip-start

Port conflict

sudo ss -tlnp | grep ':80 '
sudo ss -tlnp | grep ':8080 '

Stop the conflicting service (local Apache, another DVWA) or modify mapping in the docker_environments/* module personal isolated test environment only --- document the alternate port in your workspace.

WSL2 / macOS

• WSL2: Docker Desktop must be ``Running''; integrate WSL in Docker settings.
• macOS: allocate enough RAM to Docker Desktop (Preferences → Resources).
• Remote VM: isolated test environments listen on the machine hosting Docker; use the VM IP, not your laptop, if the console runs remotely.

After persistent failure

environments stop all
docker system prune -f    # attention : supprime conteneurs arretes non utilises
lab start dvwa-basics

Orchestration: isolated test environment command

lab list
lab show dvwa-basics
lab walkthrough dvwa-basics
lab start dvwa-basics
lab score dvwa-basics
lab run dvwa-basics
lab reset dvwa-basics
lab state dvwa-basics

isolated test environment run is equivalent to start then score. --skip-start on run or score assumes the environment is already running.

Isolated test environment 1: dvwa-basics (detail)