A web-based tool for scanning subnets, running commands over SSH and analysing the results, with multi-threaded scanning, encrypted credential storage, scheduled scans and server profiling.
- User Authentication: login-protected interface with admin and non-admin roles
- Subnet Scanning: scan IPv4 and IPv6 addresses, CIDR subnets and ranges in parallel
- SSH Connection: password or private-key authentication (with or without a key passphrase), sudo with or without a password, on a configurable port
- Command Execution: run custom commands or predefined templates, with a best-effort command filter
- Server Profiling: collect basic or detailed information about remote servers
- Result Analysis: view and filter scan results with charts and statistics
- Export: CSV (protected against spreadsheet formula injection), JSON or PDF
- Scheduled Scans: recurring scans run by a background scheduler
- Encrypted Credential Storage: SSH passwords, keys, key passphrases and sudo passwords are encrypted with Fernet
- Multiple Credential Sets: saved credential sets are tried in priority order
- Customizable Theme: dark and light mode
Pick one of the two ways below. Both give you the web app with a SQLite database stored in instance/.
Requires Docker with the Compose plugin.
git clone https://github.com/mbelsis/SubnetWhisperer.git
cd SubnetWhisperer
cp .env.example .env # optional settings; the defaults work
./docker-start.sh # or: make run (builds the image on first run)Open http://localhost:5000. On macOS, port 5000 is used by the AirPlay Receiver: add HOST_PORT=5050 to .env and open http://localhost:5050 instead.
Get the first admin password (user admin):
cat instance/initial_admin_password
# or: docker compose logs web | grep "initial admin"Requires Python 3.11 or newer (python3 --version; on macOS install it with brew install python@3.12).
git clone https://github.com/mbelsis/SubnetWhisperer.git
cd SubnetWhisperer
./setup.sh # or: PYTHON=python3.12 ./setup.sh
source .venv/bin/activate
set -a; . ./.env; set +a # load your settings
python main.py # macOS: PORT=5050 python main.pyOpen http://127.0.0.1:5000 (or the port you chose). The first admin password is printed by setup.sh and saved in instance/initial_admin_password.
- Log in as
adminwith that password. You are asked to choose a new password (at least 8 characters); theinitial_admin_passwordfile is deleted automatically afterwards. - Follow the Usage Guide: add credentials, create a template, run a scan.
- Python 3.11 or newer
- SQLite (default) or PostgreSQL
- Basic understanding of SSH and network operations
SubnetWhisperer/
├── app.py # Flask application and routes
├── main.py # Development entry point (python3 main.py)
├── models.py # Database models (User, ScanSession, ScheduledScan, ...)
├── forms.py # Flask-WTF form definitions
├── encryption_utils.py # Fernet key management and credential encryption
├── security_utils.py # Command filter and sensitive-data masking
├── ssh_utils.py # SSH connections, host-key policy, scan workers
├── subnet_utils.py # IPv4/IPv6 subnet, range and CSV parsing
├── scheduler.py # Background scheduler for recurring scans
├── run_migrations.py # Creates/updates the schema explicitly (non-zero exit on failure)
├── migrations/ # Schema sync (adds missing tables and columns)
├── static/
│ ├── css/ # Custom styling and dark/light theme
│ └── js/ # Page scripts (common helpers, scan, results, theme)
├── templates/ # Jinja2 HTML templates
├── tests/ # Unit smoke tests and Docker SSH integration tests
│ ├── test_app.py
│ ├── test_docker_integration.py
│ ├── run_docker_integration.py
│ ├── docker-compose.integration.yml
│ ├── docker/ # SSH target images and test-only keys
│ └── README.md
├── instance/ # Runtime data, created on first start, NOT in git
│ ├── subnet_whisperer.db # SQLite database (default)
│ ├── .encryption_key # Fernet key (if ENCRYPTION_KEY is not set): back it up
│ ├── .secret_key # Session secret (if SESSION_SECRET is not set)
│ ├── known_hosts # SSH host keys recorded by the TOFU policy
│ └── initial_admin_password # First admin password (only if ADMIN_PASSWORD was unset)
├── logs/ # Application logs
├── Dockerfile # Multi-stage image, runs gunicorn
├── docker-compose.yml # SQLite and PostgreSQL deployments
├── docker-start.sh # Compose wrapper (SQLite or postgres)
├── .dockerignore
├── Makefile # Docker shortcuts (run `make` for help)
├── setup.sh # Local installation script
├── .env.example # Documented configuration variables
├── pyproject.toml # Project metadata and dependencies
├── uv.lock # Pinned dependency versions
├── TESTING.md # Testing guide
└── .replit, replit.nix # Replit configuration
- Python 3.11 or newer, with pip
- Windows only: Microsoft Visual C++ 14.0 or newer may be needed for some dependencies
./setup.sh # uses python3
PYTHON=python3.12 ./setup.sh # or choose the interpreterThe script:
- checks for Python 3.11+ and stops with a clear error on older versions
- uses the active virtualenv, or creates and uses
.venv/(system and Homebrew Pythons refuse globalpip install) - installs the dependencies (exact versions from
uv.lockifuvis installed, otherwise the ranges inpyproject.toml) - creates
instance/andlogs/ - creates
.envfrom.env.exampleif it doesn't exist and appends aSESSION_SECRETif one is missing. An existing.envis never overwritten, and existing values are never changed - creates or updates the database schema (
run_migrations.py), creates the first admin account, and stops with an error if anything fails
It is safe to run again, for example after pulling a new version.
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# with uv (exact versions from uv.lock):
uv export --frozen --no-dev --no-emit-project --no-hashes -o requirements.txt && pip install -r requirements.txt
# or, without uv, install the dependencies listed in pyproject.toml:
pip install "email-validator>=2.2.0" "flask-wtf>=1.2.2" "flask>=3.1.0" "flask-sqlalchemy>=3.1.1" \
"gunicorn>=23.0.0" "pandas>=2.2.3" "paramiko>=3.5.1" "psycopg2-binary>=2.9.10" "wtforms>=3.2.1" \
"flask-login>=0.6.3" "matplotlib>=3.10.1" "sqlalchemy>=2.0.40" "bcrypt>=4.3.0" "cryptography>=44.0.2"
mkdir -p instance logs
python run_migrations.py # optional: the schema is also synced when the app startssource .venv/bin/activate
python main.pymain.py starts Flask's development server (the database schema is created or updated automatically when the app is imported) on FLASK_HOST (default 127.0.0.1) and PORT (default 5000), so it is only reachable from the local machine by default. Debug mode (the Werkzeug debugger) is enabled only with FLASK_DEBUG=true. Never enable it on an address other people can reach: the debugger allows remote code execution.
The app does not read .env by itself. To use it outside Docker, export it first:
set -a; . ./.env; set +a
python main.pyIf port 5000 is busy (on macOS it is used by the AirPlay Receiver), choose another: PORT=5050 python main.py.
gunicorn --bind 0.0.0.0:5000 --workers 1 --threads 4 main:appUse one worker per instance: each process starts its own scheduler (see Scheduled Scans). Put a TLS-terminating reverse proxy in front and set SESSION_COOKIE_SECURE=true.
On first start (when the database has no users) an admin account is created:
- The password is the value of
ADMIN_PASSWORD, if it is set when the database is first created. - Otherwise a random password is generated. It is logged once at WARNING level and written to
instance/initial_admin_password(mode 600):cat instance/initial_admin_password
Either way, you must change the password at first login: until you do, every page redirects to Change Password. Passwords must be at least 8 characters. Once an admin has changed the password, instance/initial_admin_password is deleted automatically.
Only a bcrypt hash of each user's password is stored, in the users table of the database. Lost the admin password? Another admin can reset it on User Management; if there is no other admin, stop the app, delete the database (instance/subnet_whisperer.db, which also deletes scans, templates, schedules and saved credentials), and start again to get a new first-run password.
cp .env.example .env # then edit .env
./docker-start.sh # SQLite
./docker-start.sh postgres # PostgreSQL (POSTGRES_PASSWORD must be set)Or with Make (run make on its own to list the targets):
make build # Build the image
make run # Run with SQLite
make run-postgres # Run with PostgreSQL (needs POSTGRES_PASSWORD)
make stop # Stop all containers
make clean # Remove this project's containers, networks and volumes (including the PostgreSQL data volume)
make prune # Host-wide 'docker system prune', asks for confirmation firstThe Makefile uses docker compose. For the legacy binary run make COMPOSE=docker-compose <target>.
Compose reads .env from the project folder and passes these variables to the app: ENCRYPTION_KEY, FLASK_SECRET_KEY (legacy, no default), SESSION_SECRET, ADMIN_PASSWORD, SESSION_COOKIE_SECURE, COMMAND_SANITIZATION, SSH_HOST_KEY_POLICY, MAX_SCAN_IPS, MAX_CONCURRENCY, START_SCHEDULER and DATABASE_URL. Empty values count as unset.
- Encryption key: if
ENCRYPTION_KEYis not set, the app createsinstance/.encryption_keyin the bind-mounted./instancefolder on first start. Back it up. - PostgreSQL: the
postgresprofile takesPOSTGRES_USER(defaultpostgres),POSTGRES_PASSWORD(required) andPOSTGRES_DB(defaultsubnet_whisperer) and buildsDATABASE_URLfrom them. The database port is not published on the host; only the app container can reach it. Use a password without URL-special characters (@ : / ? #).
The app is available at http://localhost:5000, or on the port set with HOST_PORT in .env (for example HOST_PORT=5050 on macOS, where port 5000 is used by the AirPlay Receiver). To follow the logs: docker compose logs -f web. To stop: make stop or docker compose down.
docker build -t subnet-whisperer .
docker run -p 5000:5000 \
-e ENCRYPTION_KEY="<fernet key>" \
-e DATABASE_URL="postgresql://user:password@host/dbname" \
-v "$(pwd)/instance:/app/instance" \
-v "$(pwd)/logs:/app/logs" \
subnet-whisperer- Multi-stage build on
python:3.11-slim. Compilers and-devheaders are used only in the build stage; the runtime image contains the virtualenv,openssh-clientand the app code. - Dependencies are installed at the exact versions pinned in
uv.lock. tests/(including its test-only SSH key),instance/,.envand docs are excluded by.dockerignore.- Runs as the non-root user
appuser(uid 1000) with gunicorn on0.0.0.0:5000, 1 worker and 4 threads, without--reload.
instance/(bind mount): SQLite database,.encryption_key,.secret_key,known_hosts,initial_admin_passwordlogs/(bind mount): application logs- PostgreSQL data: the named volume
postgres_data
On Linux, the container user (uid 1000) must be able to write to ./instance and ./logs. If your host user has a different uid, run sudo chown -R 1000:1000 instance logs.
All settings are environment variables. .env.example documents each one. The Settings page in the app shows the values the running instance is using (read-only).
| Variable | Default | Purpose |
|---|---|---|
ENCRYPTION_KEY |
unset | Fernet key for stored credentials (see Encryption Key) |
FLASK_SECRET_KEY / SECRET_KEY |
unset | Legacy encryption-key derivation only |
SESSION_SECRET |
instance/.secret_key |
Flask session signing secret |
ADMIN_PASSWORD |
random | First admin password (first start only) |
DATABASE_URL |
sqlite:///instance/subnet_whisperer.db |
SQLAlchemy database URL |
FLASK_DEBUG |
false |
Werkzeug debugger (main.py only) |
FLASK_HOST |
127.0.0.1 |
Bind address (main.py only) |
PORT |
5000 |
Port (main.py only) |
HOST_PORT |
5000 |
Host port published by docker compose |
SESSION_COOKIE_SECURE |
false |
Send the session cookie over HTTPS only |
COMMAND_SANITIZATION |
enabled |
Command filter mode (enabled or disabled) |
SSH_HOST_KEY_POLICY |
tofu |
tofu, reject or warn |
SSH_KNOWN_HOSTS_FILE |
instance/known_hosts |
Known-hosts file used by the app |
SSH_COMMAND_TIMEOUT |
60 |
Per-command timeout in seconds |
SSH_CONNECT_TIMEOUT |
10 |
SSH connect, banner and auth timeout in seconds |
SSH_MAX_OUTPUT_BYTES |
1048576 |
Output kept per stream per command (truncated beyond this) |
MAX_SCAN_IPS |
65536 |
Maximum IP addresses per scan |
MAX_CONCURRENCY |
100 |
Maximum concurrent connections per scan (minimum 1) |
START_SCHEDULER |
true |
Set to false to disable the background scheduler |
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB |
postgres, required, subnet_whisperer |
docker compose postgres profile |
Subnet Whisperer uses SQLAlchemy, so the same code runs on SQLite (default, a file in instance/) or PostgreSQL.
To use your own PostgreSQL server:
- Create a database and user:
sudo -u postgres psql postgres=# CREATE DATABASE subnet_whisperer; postgres=# CREATE USER myuser WITH ENCRYPTED PASSWORD 'mypassword'; postgres=# GRANT ALL PRIVILEGES ON DATABASE subnet_whisperer TO myuser; postgres=# \q
- Set
DATABASE_URL:export DATABASE_URL="postgresql://myuser:mypassword@localhost/subnet_whisperer"
- Run
./setup.sh(orpython3 run_migrations.py). The schema is also created or updated automatically when the app starts.
A typical first session: log in, (admin) save your SSH credentials as credential sets, create a command template, run a scan, look at the results, then schedule it.
- Log in with your username and password. New users must change their password at first login.
- Change Password is in the user menu (top right).
- User Management (admin only, in the user menu): create users, optionally with admin rights; reset a user's password (they must change it at next login, and their open sessions are signed out); delete users (not yourself, and not the last admin).
See Authentication and Roles for what admins and other users can do.
Every combination of login method and sudo is supported:
| SSH login | Sudo on the target | What to enter |
|---|---|---|
| Password | needs a password | username, SSH password, sudo password |
| Password | no password (NOPASSWD) |
username, SSH password (leave sudo password empty) |
| Private key | needs a password | username, private key, sudo password |
| Private key | no password (NOPASSWD) |
username, private key |
| Private key with a passphrase | either | as above, plus the key passphrase |
| any | no sudo rights | works; sudo commands fail and root-only details are skipped |
- Private keys: Ed25519, RSA, ECDSA and DSA, in OpenSSH (
-----BEGIN OPENSSH PRIVATE KEY-----) or PEM format. Paste the whole private key, including the BEGIN/END lines. If the key has a passphrase, enter it in Key Passphrase; if you forget, the scan fails with "Private key is passphrase-protected; enter the key passphrase". - Sudo password: used only when sudo actually asks for one. With
NOPASSWDsudo it is never sent. - Port: the SSH port (default 22).
- The SSH, sudo and key passphrases are never shown in results, exports or logs.
On Credentials, click Add New Credential Set and enter: username; authentication type (password or SSH key); the password, or the private key and its optional passphrase; an optional sudo password; a priority (higher is tried first); and a description.
- Secrets are encrypted in the database (see Where Credentials Are Stored). They are never shown again: when you edit a set, leave the secret fields blank to keep the stored values. If you paste a new key, also enter its passphrase (blank means the new key has none).
- A scan can use one set, or all sets: each host is then tried with every set in priority order until one logs in. This is useful when different servers use different accounts.
- A set that is used by a schedule can't be deleted until the schedule is changed.
Templates lists reusable command lists that anyone can use in a scan. Admins can create them (name, description, one command per line), edit them (pencil button, then Update Template) and delete them. Names must be unique. Commands from a template run first, followed by any custom commands entered on the scan form.
Open Scan:
- Targets: one per line or comma-separated. Single addresses (
192.168.1.10,2001:db8::5), CIDR subnets (192.168.1.0/24,2001:db8::/120) or ranges (192.168.1.1-192.168.1.10, the short form192.168.1.1-10, or2001:db8::1-2001:db8::20). Click Validate Subnets to see how many addresses will be scanned, a sample, and any invalid entries. Or use the CSV Import tab: upload a CSV with a column namedip,ip_address,subnet,addressornetwork(otherwise the first column is used); the addresses are loaded into the form for review, and invalid rows are reported. - Credentials: enter them manually (see SSH Authentication Options) or, as an admin, tick Use Saved Credential Sets and pick one set or all of them.
- Commands: pick a template and/or type custom commands, one per line. To run a command as root, start it with
sudo, for examplesudo cat /var/log/syslog. The command filter rejects dangerous commands and, by default, pipes, redirects and chaining (|,>,;,&&); rejected commands are shown as Blocked in the results and are not run. - Server information: tick Collect Server Information for the basic profile, and also Collect Detailed Server Profile for the detailed one (see below).
- Concurrency (hosts scanned at the same time, 1 to
MAX_CONCURRENCY) and Port, then Start Scan.
A progress dialog shows how many hosts are done. You can close it: the scan keeps running on the server. When it finishes, click View Results.
Each command runs with a time limit (SSH_COMMAND_TIMEOUT, default 60 seconds) and its output is capped (SSH_MAX_OUTPUT_BYTES, default 1 MB per stream). Commands are run in a non-interactive session, so commands that wait for input (editors, top, prompts) time out. A single scan can include at most MAX_SCAN_IPS addresses (default 65536).
- Basic: hostname, OS, kernel, CPU, memory, disk usage, network interfaces, uptime.
- Detailed: also DNS configuration, running services, listening network connections, network cards, default gateway, virtualization, login accounts, load average, installed packages (first 100; dpkg, rpm or apk) and firewall rules.
Firewall rules (iptables/nft) and hardware details (lshw) need root: they are read through sudo when the account has sudo rights (with or without a sudo password); otherwise those sections stay empty. Running services need systemd (or OpenRC/service). Sections whose tools are missing on a host are shown as not available.
Open Results:
- The Recent Scans table lists every scan session with its status (running, completed or failed) and success and failure counts. Click a session to see its hosts.
- Filter hosts by status or sudo access, or search. Click the eye button to open a host's details:
- Commands: each command with its exit code, output and errors. Blocked commands are marked Blocked.
- Server Info: the collected profile.
- Errors: connection or authentication errors.
- Export the session as CSV (one row per host), JSON (everything, including command output and server info) or PDF (summary charts and the first 20 hosts).
- Admins can delete finished scans.
Times are stored in UTC and shown in your browser's local time.
On Schedules, click New Schedule and fill in:
- Name and targets: same format as on the scan page.
- Credentials: username and password or key (with optional passphrase), or a saved credential set. Optionally a sudo password and the SSH port.
- Commands: a template and/or custom commands, plus the server-information options and concurrency.
- Frequency: hourly, daily, weekly, monthly (same day each month) or every N minutes (custom, minimum 5).
- Start and end dates, in UTC. The first run happens at the start date. The end date is optional, and a schedule whose end date has passed cannot be activated.
The schedule list shows each schedule's next run. Use the buttons to view, edit, deactivate/activate (pause and play icons) or delete a schedule. Each run appears as a normal scan session on Results.
The scheduler runs in the background inside the web process and checks for due schedules every 60 seconds. It starts with the app unless START_SCHEDULER=false. Each run is claimed atomically in the database, so even if several processes run a scheduler, a schedule is not run twice. The default single-worker gunicorn setup is still recommended. If the app was down when runs were due, the missed runs are skipped (not replayed) and the schedule continues at its next regular time.
Settings shows the configuration the running instance uses: command-filter mode, host-key policy, timeouts, limits, scheduler status, database type and where the encryption key comes from. It is read-only: settings are environment variables (see Configuration), and changes need a restart. The theme (light or dark) is switched with the button in the navigation bar.
| What | Where | How |
|---|---|---|
App user passwords (including admin) |
users table in the database |
bcrypt hash only |
| First admin password (generated) | instance/initial_admin_password, mode 600 |
plain text, deleted after the first password change |
| SSH passwords, private keys, key passphrases, sudo passwords (credential sets and schedules) | database | encrypted with Fernet |
| Encryption key for the above | ENCRYPTION_KEY or instance/.encryption_key |
back it up, never commit it |
| Passwords typed on the scan form | memory only, for that scan | not stored |
| SSH host keys (TOFU) | instance/known_hosts |
plain text (public keys) |
The database is instance/subnet_whisperer.db by default, or the PostgreSQL database in DATABASE_URL.
Subnet Whisperer stores SSH credentials and runs commands on remote hosts. Run it on a trusted network, behind TLS, and give admin rights only to people who should be able to use every stored credential.
- All pages require login (Flask-Login, bcrypt password hashes, minimum length 8).
- The first admin's password comes from
ADMIN_PASSWORDor is generated (see First Login). A password change is forced at first login. - Admins can: manage users; view and manage credential sets (
/credentialsand the credential API); use saved credential sets in scans; create, edit, activate and delete schedules; create, edit and delete command templates; delete scans. - Non-admins can: run scans with manually entered credentials; view results and exports; list templates and use them in scans; change their own password.
- CSRF protection covers all forms and AJAX requests. Tokens last as long as the session.
- Logout is a POST request with a CSRF token. Session cookies are
SameSite=Lax, andSecurewhenSESSION_COOKIE_SECURE=true. - The session is signed with
SESSION_SECRET, or with a secret generated once and stored ininstance/.secret_key.
SSH passwords, private keys, key passphrases and sudo passwords are encrypted with Fernet. The key is chosen in this order:
ENCRYPTION_KEY. It must be a valid Fernet key; if it isn't, the app refuses to start with a clear error. Generate one with:python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"instance/.encryption_key, if the file exists.- Legacy: a key derived (PBKDF2) from
FLASK_SECRET_KEYorSECRET_KEY. A warning is logged. Use this only to keep reading credentials from an old install. - Otherwise a new key is generated and saved to
instance/.encryption_keywith mode 600.
Keep and back up the key (the ENCRYPTION_KEY value or instance/.encryption_key). If it is lost or changes, stored credentials can't be decrypted: decryption fails with an error and the credentials must be re-entered. Never commit the key or the instance/ folder.
Server information and command output are stored unencrypted (after masking), so be careful with commands that print secrets.
Set with SSH_HOST_KEY_POLICY:
tofu(default): trust on first use. The key of a host seen for the first time is recorded inSSH_KNOWN_HOSTS_FILE(defaultinstance/known_hosts). If a known host later presents a different key, the connection is rejected. If a host's key legitimately changes, remove its line from that file.reject: only connect to hosts already listed in the system known_hosts or the app's known_hosts file.warn: legacy behavior. Any key is accepted and nothing is recorded, so there is no protection against man-in-the-middle attacks.
Passwords, private keys (including PKCS#8 and encrypted keys), tokens and similar values are masked in command output before it is stored or shown, and in the commands and messages written to the logs. The sudo password is masked wherever it appears. Masking is pattern-based, so treat it as a safety net, not a guarantee.
The command filter is a best-effort guardrail against mistakes, not a security boundary. Anyone who can run arbitrary commands over SSH with a set of credentials can do whatever those credentials allow, and a determined user can find commands the filter doesn't recognise. Control access with roles and with the permissions of the remote accounts.
Commands are tokenized like a shell (shlex) and checked before they are sent. A rejected command is simply not run; the result shows it as blocked. There is no approval workflow.
Always blocked (in every mode):
rmrecursive deletes of/,/*or~, in any flag order (-rf,-fr,-r -f,--recursive --force,--no-preserve-root)find / ... -deletemkfsand its variants (mkfs.ext4, ...)dd,shredorwipefswriting to block devices (/dev/sd*,/dev/hd*,/dev/nvme*,/dev/vd*,/dev/xvd*,/dev/mmcblk*)- fork bombs
curlorwgetpiped intoshorbashshutdown,reboot,halt,poweroff,init 0/init 6,telinit 0/telinit 6when used as commands (a word such ashalting-problemis fine)sudo -i,sudo -s,sudo su- access to
/etc/shadow(cat /etc/passwdis allowed)
These checks also apply inside shell wrappers such as bash -c "..." or sudo sh -c "...". Interpreters (python -c, perl -e, ...) are not inspected.
Also blocked when COMMAND_SANITIZATION=enabled (the default):
- shell operators and substitutions:
;,&&,||, a single&,|,>,<, backticks,$(,${and newlines - restricted commands, matched on the command name (after any
sudo), for examplesystemctl,chmod,useraddand the rest ofRESTRICTED_COMMANDSinsecurity_utils.py. Sosystemctl status nginxis rejected in enabled mode.
With COMMAND_SANITIZATION=disabled, pipes, redirects, chaining and restricted commands are allowed; only the always-blocked list applies.
Examples in enabled mode:
| Command | Result |
|---|---|
uname -a, df -h, free -m, uptime, ls -la /var/log/ |
allowed |
cat /etc/os-release, cat /etc/passwd |
allowed |
sudo apt list --installed |
allowed |
ps aux | grep nginx |
blocked (pipe) |
cd /var/log; cat syslog |
blocked (;) |
echo hi > /tmp/x |
blocked (redirect) |
echo $(id) |
blocked (command substitution) |
systemctl status nginx |
blocked (restricted command) |
rm -fr /, sudo reboot |
blocked in every mode |
To run pipelines while keeping the filter enabled, put them in a script on the target and run the script as a single command, or set COMMAND_SANITIZATION=disabled.
-
instance/is no longer tracked in git. Pulling the change that untracked it deletesinstance/.encryption_keyandinstance/subnet_whisperer.dbfrom your working copy. Back upinstance/before you pull (cp -a instance instance.backup) and restore it afterwards. Keep your existinginstance/.encryption_key: it is the key your stored credentials are encrypted with. -
The committed key is public. The
.encryption_keythat used to be in the repository is known to anyone with access to it. If your install used that file, rotate the SSH credentials you stored, then start with a new key (deleteinstance/.encryption_keyand set a freshENCRYPTION_KEY, or let the app generate a new file) and re-enter the credentials. -
docker-compose no longer sets
FLASK_SECRET_KEY. Old compose files defaulted it todefault_dev_key_please_change_in_production, and the encryption key was derived from it. That key is public too. To read the old credentials once, either:- set
ENCRYPTION_KEYto the legacy derived key:python3 -c "import base64,sys; from cryptography.hazmat.primitives import hashes; from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC; print(base64.urlsafe_b64encode(PBKDF2HMAC(algorithm=hashes.SHA256(), length=32, salt=b'subnet_whisperer_secure_salt_v2', iterations=480000).derive(sys.argv[1].encode())).decode())" 'default_dev_key_please_change_in_production'
- or set
FLASK_SECRET_KEYto the old value and moveinstance/.encryption_keyout of the way (the key file takes priority overFLASK_SECRET_KEY).
Either way, plan to rotate the credentials and move to a fresh key, or simply re-enter them.
- set
-
PostgreSQL in compose now needs
POSTGRES_PASSWORD, and port 5432 is no longer published. If your existingpostgres_datavolume was initialised withpostgres/postgres, setPOSTGRES_PASSWORD=postgres(or change the password inside the database first). -
Python 3.11 is now required.
-
Schedules are interpreted in UTC. Check the start and end times of existing schedules.
See TESTING.md and tests/README.md. Tests set START_SCHEDULER=false.
- "Address already in use" / port 5000 busy: on macOS the AirPlay Receiver uses port 5000. Use
PORT=5050 python main.py, or setHOST_PORT=5050in.envfor Docker (or turn off AirPlay Receiver in System Settings). setup.sh: "Python 3.11 or higher is required": install a newer Python (brew install python@3.12, or your distribution's package) and runPYTHON=python3.12 ./setup.sh.- Where is the admin password?
cat instance/initial_admin_password(first start only, until it is changed), or theADMIN_PASSWORDyou set. See First Login. - "Host key verification FAILED": the host's key changed since it was first recorded (TOFU). Verify the change, then remove the host's line from
instance/known_hosts. - "Private key is passphrase-protected; enter the key passphrase": fill in Key Passphrase. "wrong passphrase, or unsupported or malformed key": check the passphrase and that you pasted the complete key.
sudocommands fail: enter the sudo password (unless the account hasNOPASSWDsudo) and check that the account is allowed to use sudo on the target (sudo -l).- Firewall rules or network cards are empty: they need root; give the account sudo rights and the sudo password.
- Command shows "Blocked": the command filter rejected it; see Command Filtering.
- Command "timed out": it ran longer than
SSH_COMMAND_TIMEOUTor waited for input; raise the timeout or make the command non-interactive. - App won't start, "Invalid encryption key from ENCRYPTION_KEY": the value isn't a Fernet key. Generate one as shown in Encryption Key, or unset it to use
instance/.encryption_key. - "could not be decrypted (encryption key changed?)": restore the old key, or re-enter the credentials.
- Permission denied on
instance/in Docker (Linux): see Persistent Storage. - "Too many IP addresses": split the scan, or raise
MAX_SCAN_IPS. - Slow scans: unreachable addresses wait for
SSH_CONNECT_TIMEOUT(10 s); raise the concurrency or scan smaller ranges.
Copyright © 2025 Meletis Belsis
This project is free for any use as long as you include the original copyright statement and a link to the author's GitHub account.
USE AT YOUR OWN RISK: This application implements security best practices including credential encryption, but may still contain bugs or security vulnerabilities. By using this software, you assume all associated risks.


