Troubleshooting

Troubleshooting

Prerequisites and Docker

docker compose not available Medusa could not find either the Compose plugin or the legacy binary. Install Docker Compose, then re-run ./medusa.sh check. Medusa prefers docker compose (plugin) and falls back to docker-compose.

Daemon not running on the Configuration page The Docker daemon is installed but not started. Start it (systemctl start docker or Docker Desktop) and ensure your user is in the docker group, otherwise commands need sudo.

A deploy fails with a permission error You are likely not in the docker group, or the operation genuinely needs root (system-package installs, raw network capture). Run Medusa as a user in the docker group; let it escalate with sudo only when a tool requests it.

Tool-specific

Velociraptor pull fails / image not found The bundled compose references velociraptor/velociraptor, which is not published under that name on Docker Hub (there is no official image, only community forks such as wlambert/velociraptor-docker). The pull can therefore fail. Workaround: edit medusa_deployments/<env>/velociraptor/docker-compose.yml to point at a community image you trust, then ./medusa.sh restart velociraptor. Tracked as a known issue.

OpenVAS returns no scan results at first Greenbone must sync its vulnerability feed before scans produce findings. The first start can take a long time. Watch progress with ./medusa.sh logs openvas.

Wazuh fails to start, certificate errors The deployer generates indexer certificates before starting. If startup was interrupted, remove and redeploy: ./medusa.sh remove wazuh && ./medusa.sh deploy wazuh.

Port already in use Two tools may share a port (notably 8443 for Eramba/CISO Assistant and 443 for Wazuh/MISP). See Ports-Reference for the collision list and how to remap.

DFIR-IRIS / Cortex, where is the password? DFIR-IRIS prints its initial administrator password in the container logs on first start (./medusa.sh logs dfir-iris). Cortex has no default account, you create the admin on first web access.

CLI tools

<tool> already installed CLI installers call ensure_command_absent, if the binary is already on PATH they bail out rather than reinstall. Use the menu's Reinstall action to force a fresh install.

A CLI tool installed but the dashboard shows it as not installed CLI tools are tracked by a .installed marker (or by detecting the binary on PATH). If you installed the binary outside Medusa, Medusa creates the marker the next time it checks status.

General

The menu loop exits unexpectedly Medusa runs without set -e precisely to survive failed reads/greps. If it still exits, run with bash tracing to locate the failure:

bash -x ./medusa.sh 2> medusa-trace.log

Verify the install is intact

bash -n medusa.sh lib/*.sh      # syntax
./medusa.sh list                # all 35 tools listed
./medusa.sh check               # prerequisites

---

Next: FAQ · Security