Installation

NetVuln Tool supports macOS (development) and Linux/Debian (deployment, including Raspberry Pi). All scan logic is pure Bash with no compiled binaries, and a Python orchestrator (netvuln) drives the same pipeline with typed data models. There are two supported install paths:

• install.sh (this page, deployment path): sets up netvuln-tool for use on a scanning host or agent. It runs a preflight dependency check, installs the netvuln CLI, provisions a license key, scaffolds a per-engagement config, optionally installs the systemd daemon, and verifies portal connectivity.
• setup.sh (developer path): sets up a development checkout (git hooks, lint dependencies, editable pip install). Use this when you intend to modify the tool, not just run it.

If you want a container instead of a host install, jump to the Docker guide. For always-on edge scanners, see Raspberry Pi deployment.

Platform Support

	macOS	Linux (Debian/Ubuntu/Raspberry Pi OS)
Scanning	Yes	Yes
systemd daemon	No (systemd is Linux-only; install.sh prints a notice)	Yes
Recommended role	Development	Deployment / agents

Requirements

Dependency	Required	macOS	Linux (Debian/Ubuntu/Raspberry Pi)
Bash 4+	Yes	brew install bash	Pre-installed (verify: bash --version)
nmap	Yes	brew install nmap	sudo apt-get install -y nmap
jq	Recommended	brew install jq	sudo apt-get install -y jq
python3 3.9+	Recommended	brew install python	Pre-installed on most distros
dig	Optional	Pre-installed	sudo apt-get install -y dnsutils
whois	Optional	Pre-installed	sudo apt-get install -y whois
openssl	Optional	Pre-installed	Pre-installed
curl	Optional	Pre-installed	sudo apt-get install -y curl
smbclient	Optional	brew install samba	sudo apt-get install -y smbclient
snmpwalk	Optional	brew install net-snmp	sudo apt-get install -y snmp
iw / nmcli	Optional (WiFi, Linux only)	n/a	sudo apt-get install -y iw network-manager
wkhtmltopdf	Optional (PDF export)	brew install --cask wkhtmltopdf	sudo apt-get install -y wkhtmltopdf
mail / sendmail	Optional (email alerts)	via provider	sudo apt-get install -y mailutils

Missing optional tools are gracefully skipped with a warning.

Dependencies by purpose

Tool	Status	Purpose
nmap	Required	Core scanning engine (host discovery, port/service detection, vuln scripts)
jq	Recommended	JSON processing, required for HTML reports
python3	Recommended	The netvuln orchestrator CLI (recon/scan/upload/push/diff/status/daemon)
dig / host / nslookup	Optional	DNS enumeration
whois	Optional	WHOIS / OSINT lookups
openssl	Optional	SSL/TLS analysis
curl	Optional	HTTP header checks, CVE CVSS lookups, session upload, license validation
smbclient	Optional	SMB share enumeration
snmpwalk / snmpget	Optional	SNMP enumeration
nc / ncat	Optional	SSH banner grabbing
wkhtmltopdf	Optional	PDF export for executive summaries
mail / sendmail	Optional	Email alerts and scan reminders

Deployment install: install.sh

install.sh (repo root) prepares a host to run scans, either interactively (an analyst laptop) or as an unattended agent. It is idempotent and safe to re-run.

What it does

1. Preflight: detects the platform (macOS or Linux) and runs the dependency check. On Linux it can auto-install missing packages via apt-get; on macOS it prints brew install hints.
2. Python CLI: runs pip install -e . so the netvuln console script lands on your PATH (skip with --no-python).
3. License key: installs the provided key to ~/.netvuln/license.key (mode 600). See License Provisioning for key formats and tiers.
4. Config scaffold: creates a per-engagement config at ~/netvuln-tool/configs/<name>.conf from templates/report_config.conf.example, filling in the API URL, client ID, and targets you passed.
5. Systemd daemon (Linux only): installs and enables the netvuln-daemon service, but leaves scanning off until a config sets DAEMON_ENABLED=true with TARGETS. On macOS it prints a notice that systemd is Linux-only (use launchd or run the daemon in the foreground). Skip with --no-daemon.
6. Portal verification: checks /api/health reachability and sends an authenticated heartbeat to confirm the license key and API URL are valid.
7. Summary: prints a pi_validate.sh --json readiness summary and the next steps.

Flags

Flag	Purpose
--license-key <key>	License key to install to ~/.netvuln/license.key (e.g. nvt_pro_<hex>)
--api-url <url>	Portal upload endpoint (e.g. https://bullium.com/api/upload)
--client-id <id>	Client identifier injected into the config for portal multi-tenancy
--targets <spec>	Comma-separated IPs, CIDRs, ranges, or domains for the scaffolded config
--config-name <name>	Basename for the scaffolded config (~/netvuln-tool/configs/<name>.conf)
--no-daemon	Skip installing/enabling the systemd service
--no-python	Skip the pip install -e . step (bash-only install)
--verify-only	Run the portal connectivity + readiness checks only, no install steps
--full-verify	Run the extended verification (health + authenticated heartbeat + pi_validate)
--offline	Skip all network steps (dependency auto-install, portal verification)
--non-interactive, --yes	Assume defaults and never prompt (agent/automation mode)
-h, --help	Show usage

Example: unattended agent install

bash install.sh --non-interactive \
  --license-key nvt_pro_<hex> \
  --api-url https://bullium.com/api/upload \
  --client-id acme \
  --targets 192.168.1.0/24

This installs the CLI, writes the license key, scaffolds ~/netvuln-tool/configs/acme.conf with the URL/client/targets pre-filled, installs the systemd daemon (Linux), verifies portal connectivity, and prints a readiness summary. The daemon stays idle until you set DAEMON_ENABLED=true in that config.

Enable scheduled scanning after install

install.sh installs the daemon but does not start scanning. Edit the scaffolded config, set DAEMON_ENABLED="true" with a SCAN_SCHEDULE and TARGETS, then reload the daemon. See Daemon Mode and Scheduling.

Only scan authorized networks

Provisioning targets in a config does not grant authorization. Only scan hosts and networks you are explicitly authorized to assess.

Developer install: setup.sh

Use setup.sh when you are working on netvuln-tool itself. Clone the repository and run it once:

git clone ssh://git@100.101.73.49:2222/Bullium-Consulting/netvuln-tool.git
cd netvuln-tool
bash setup.sh

setup.sh performs a five-step developer bootstrap:

1. Configures git hooks (git config core.hooksPath .githooks) so the pre-commit ShellCheck lint and pre-push test suite run automatically.
2. Checks linting dependencies (shellcheck, bats) and prints install hints for any that are missing.
3. Checks runtime dependencies (nmap, jq).
4. Installs the Python orchestrator in editable mode with dev extras (pip install -e ".[dev]"), putting the netvuln CLI on your PATH.
5. Verifies the git hooks are executable.

It does not install a license, scaffold an engagement config, or install the systemd daemon; those belong to the deployment path (install.sh).

Dependency check

At any time, verify your environment with:

bash scripts/dependency_check.sh

This detects your platform (macOS or Linux) and prints the correct install command for each missing tool: brew install on macOS, apt-get install on Linux.

Platform validation

For deployment readiness (especially on Raspberry Pi or other edge devices), use the platform validation script:

bash scripts/pi_validate.sh          # Run the deployment checks
bash scripts/pi_validate.sh --json   # JSON output (used by install.sh's summary)
bash scripts/pi_validate.sh --fix    # Attempt to install missing dependencies

It checks disk space, memory, required tools, permissions, and portal (/api/health) reachability, and can emit JSON for monitoring integration. Combine flags, for example pi_validate.sh --fix --json.

Next steps

• Quick Start: run your first scan in a few commands.
• Docker: run scans from a container with no host install.
• Raspberry Pi: stand up an always-on scanning appliance.
• Report Configuration: the per-engagement config file in depth.