Agent Installation Guide
System Requirements
| OS | Version | Architecture | Python |
|---|---|---|---|
| Ubuntu | 20.04+ | x64, ARM64 | 3.8+ |
| Debian | 11+ | x64, ARM64 | 3.8+ |
| CentOS/RHEL | 8+ | x64 | 3.8+ |
| Windows | 10/11, Server 2019+ | x64 | 3.8+ |
| macOS | 12+ | x64, ARM64 | 3.8+ |
Minimum resources: 1 CPU core, 256 MB RAM, 100 MB disk space.
Linux Installation
Automatic (recommended)
curl -fsSL https://install.netsenx.com | sudo bash -s -- --key YOUR_LICENSE_KEY
This will:
- Install the NetSenX agent via pip
- Create a systemd service (
netsenx-agent.service) - Start monitoring automatically
- Survive reboots
Manual
pip install netsenx-agent
export NETSENX_LICENSE_KEY="your_key"
export NETSENX_BACKEND_URL="https://api.netsenx.com"
export NETSENX_AGENT_ID="$(hostname)-$(uuidgen | head -c 8)"
python -m agent.run
Verify installation
systemctl status netsenx-agent
# Should show: active (running)
journalctl -u netsenx-agent -n 20
# Should show: "Agent registered", "config_pull: success", "stats: flows_analyzed=..."
Windows Installation
PowerShell (recommended)
Run PowerShell as Administrator:
iex "& { $(irm https://install.netsenx.com/win) } -Key YOUR_LICENSE_KEY"
This creates a Windows Scheduled Task that runs at startup.
MSI Installer
Download the MSI from Dashboard -> Agents -> Deploy Agent -> Download MSI. Double-click to install. Enter your license key when prompted.
Verify
Get-ScheduledTask -TaskName "NetSenX Agent"
# Should show: Ready or Running
macOS Installation
curl -fsSL https://install.netsenx.com | bash -s -- --key YOUR_LICENSE_KEY
This creates a launchd service (com.netsenx.agent.plist).
Network Requirements
The agent needs outbound HTTPS access to:
| Destination | Port | Purpose |
|---|---|---|
api.netsenx.com | 443 | API communication, alert upload |
feodotracker.abuse.ch | 443 | Threat intel feeds (optional) |
releases.netsenx.com | 443 | Auto-updates (optional) |
No inbound ports need to be opened. The agent only makes outbound connections.
Firewall / Proxy
If behind a corporate proxy:
export HTTPS_PROXY="http://proxy.company.com:8080"
export NETSENX_LICENSE_KEY="your_key"
python -m agent.run
Auto-Updates
The agent checks for updates every 24 hours. When a new version is available, it downloads and installs automatically, then restarts the service.
To disable auto-updates:
export NETSENX_AUTO_UPDATE=false
Configuration
All configuration is via environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
NETSENX_LICENSE_KEY | Yes | — | Your license key |
NETSENX_BACKEND_URL | Yes | — | Backend API URL |
NETSENX_AGENT_ID | Yes | — | Unique agent identifier |
NETSENX_INTERFACE | No | auto | Network interface to monitor |
NETSENX_BPF_FILTER | No | ip and not (src net 127.0.0.0/8) | Custom BPF filter |
NETSENX_LOG_LEVEL | No | INFO | Logging verbosity |
NETSENX_AUTO_UPDATE | No | true | Enable auto-updates |
Uninstallation
Linux:
sudo systemctl stop netsenx-agent
sudo systemctl disable netsenx-agent
sudo rm /etc/systemd/system/netsenx-agent.service
pip uninstall netsenx-agent
Windows:
Unregister-ScheduledTask -TaskName "NetSenX Agent" -Confirm:$false
pip uninstall netsenx-agent
macOS:
launchctl unload ~/Library/LaunchAgents/com.netsenx.agent.plist
rm ~/Library/LaunchAgents/com.netsenx.agent.plist
pip uninstall netsenx-agent