admin / Synapse-Sonar

# Synapse Sonar collectors

Two ways to feed flow data into Synapse Sonar. Both push to the same endpoint
(`POST /api/ingest/flow-logs`) and authenticate with the **Sensor ingest key**
from the UI: **Integrations → NetscanXi → Sensor ingest key → Generate**.

| | Host agent (Linux) | Host agent (Windows) | Passive sensor |
|---|---|---|---|
| Where it runs | Each Debian/Ubuntu host | Each Windows host | Host on a SPAN/mirror port |
| Sees | That host's own connections | That host's own connections | All mirrored traffic to/from many devices |
| Built with | Python 3 (stdlib) | PowerShell 5.1 (built-in) | Python 3 (stdlib) |
| Privilege | Unprivileged | SYSTEM (scheduled task) | `CAP_NET_RAW` |
| Use when | You can install software | You can install software | The device **can't** take an agent (appliances, IoT, printers, OT) |
| Byte volumes | Not reported (0) | Not reported (0) | Measured from packets |

The Linux agent and sensor are pure Python 3 standard library; the Windows
agent uses only built-in PowerShell cmdlets. No third-party packages anywhere.

---

## Host agent (Debian / Ubuntu)

> Ubuntu is Debian-based, so the **same agent and installer work on both** —
> identical systemd + apt + Python 3. No separate build per distro.

```bash
cd public/agents/host-agent
sudo ./install.sh
sudo nano /etc/sonar-agent/sonar-agent.env   # set SONAR_URL + SONAR_INGEST_KEY
sudo systemctl enable --now sonar-agent
journalctl -u sonar-agent -f
```

It reads established connections via `ss` every `SONAR_INTERVAL` seconds and
reports them with this host's hostname, so the host appears as a named node.

---

## Host agent (Windows)

The Windows counterpart to the Linux agent. Reads established TCP connections via
`Get-NetTCPConnection` and pushes them; runs as a SYSTEM scheduled task that
starts at boot. Built-in PowerShell only — nothing to install from the gallery.

From an **elevated** PowerShell:

```powershell
cd public\agents\windows-agent
powershell -ExecutionPolicy Bypass -File .\install.ps1
notepad $env:ProgramData\SonarAgent\config.json   # set SonarUrl + IngestKey
Restart-ScheduledTask -TaskName SynapseSonarAgent
```

- Config: `%ProgramData%\SonarAgent\config.json`
- Logs: `%ProgramData%\SonarAgent\sonar-agent.log`
- Remove: `Unregister-ScheduledTask -TaskName SynapseSonarAgent -Confirm:$false`

> Windows has no built-in packet sniffer, so this is a host agent (own
> connections), not a passive sniffer. To passively monitor agentless Windows
> appliances, mirror their traffic to the Linux **passive sensor** below.

---

## Passive sensor (agentless)

For devices that cannot run an agent. Put a Linux box on a switch **SPAN/mirror
port** (or inline tap / gateway) so it can observe the traffic to and from those
devices, then:

```bash
cd public/agents/sensor
sudo ./install.sh
sudo nano /etc/sonar-sensor/sonar-sensor.env  # set SONAR_URL, SONAR_INGEST_KEY, SONAR_IFACE
sudo systemctl enable --now sonar-sensor
journalctl -u sonar-sensor -f
```

It sniffs IPv4 TCP/UDP, aggregates flows over `SONAR_FLUSH` seconds (with byte
counts), and excludes its own traffic to Sonar to avoid a feedback loop.

### Run the sensor in Docker (alternative)

```bash
docker run -d --name sonar-sensor \
  --network host --cap-add NET_RAW --cap-add NET_ADMIN \
  -e SONAR_URL=https://sonar.corp.internal:3000 \
  -e SONAR_INGEST_KEY=nsx_sensor_xxxx \
  -e SONAR_IFACE=eth1 \
  -v "$PWD/sonar-sensor.py:/app/sonar-sensor.py:ro" \
  python:3.12-alpine python /app/sonar-sensor.py
```
`--network host` is required so the container can see the mirrored interface.

---

## Notes & limits (honest)

- **Direction heuristic:** both collectors treat the lower port number of a
  connection as the "service" port. This is correct for the vast majority of
  flows but can misattribute unusual peer-to-peer ports.
- **IPv4 only** in the sensor today (IPv6 / VLAN-tagged frames are skipped).
- The sensor only sees what the mirror port forwards — size the SPAN session and
  the sensor NIC for the mirrored volume, or flows will be dropped upstream.
- The ingest key currently lives under the NetscanXi card (it doubles as the
  flow-collector key). Keep that integration enabled for ingestion to work.