# AbuseTrack × UniFi

Turn your UniFi gateway into an AbuseTrack sensor. Every IDS/IPS hit (Threat
Management) and firewall drop with an external attacker IP is reported to the
community, like the fail2ban and CrowdSec integrations, but driven by your
UniFi logs over **remote syslog**.

Report-only: it never touches your firewall. It runs a tiny syslog listener
(standard-library Python, no pip installs) as a systemd service, parses the
incoming UniFi logs, maps each event to a threat type and reports the external
source IP. Internal/private IPs are skipped, and for an outbound C2 alert it
reports the external destination, not your own host.

## Requirements

- A UniFi gateway with **Threat Management (IDS/IPS)** enabled (UDM/UDM-Pro/UXG).
  Firewall drops are reported too if your drop rules log with a `-D]`/`DROP`
  prefix; IDS works regardless.
- A Linux host on the same network with `python3`, reachable from the gateway.

## Install

Create an API key at `…/account/api-keys`, then on the Linux host as **root**:

```bash
curl -fsSL https://abusetrack.io/integrations/unifi/install.sh | \
  AT_API_KEY=your_api_key AT_API_URL=https://abusetrack.io bash
```

The installer writes `/etc/abusetrack/unifi.conf`, installs the listener to
`/usr/local/bin/abusetrack-unifi-report`, runs it as the
`abusetrack-unifi` systemd service (UDP **5514** by default) and verifies your
key.

## Point UniFi at the host

UniFi Network → **Settings → System → Logging** (older: **Remote Syslog Server**):

- Server: the Linux host's IP
- Port: `5514` (UDP) — or set `LISTEN_PORT=514` at install time if your UniFi
  only allows the default port
- Enable IPS/IDS and firewall logging

Make sure inbound `udp/5514` is open on the host from the gateway.

## Options (environment variables at install time)

| Variable         | Default            | Meaning                                              |
| ---------------- | ------------------ | ---------------------------------------------------- |
| `AT_API_KEY`     | _(required)_       | Your AbuseTrack API key                              |
| `AT_API_URL`     | `https://abusetrack.io` | Base URL of the AbuseTrack instance             |
| `LISTEN_PORT`    | `5514`             | UDP port to receive UniFi syslog on                  |
| `THREAT_DEFAULT` | `Port Scan`        | Fallback threat type when no signature rule matches  |
| `COOLDOWN_HOURS` | `24`               | Don't re-report the same IP within this window       |
| `IGNORE_IPS`     | _(empty)_          | Comma-separated IPs/CIDRs to never report (your WAN) |

> Tip: set `IGNORE_IPS` to your own public/WAN IP(s) so the gateway never
> reports you by accident.

## Signature → threat-type mapping

| UniFi / Suricata signature contains          | Reported as         |
| -------------------------------------------- | ------------------- |
| `brute`, `ssh`, `rdp`, `credential`, `login` | Brute Force         |
| `scan`, `probe`, `recon`, `sweep`            | Port Scan           |
| `trojan`, `botnet`, `c2`, command and control| Command & Control   |
| `malware`, `exploit`, `cve`, `sqli`, web app | Malware             |
| `ddos`, `flood`                              | DDoS                |
| firewall drops / anything else               | `THREAT_DEFAULT`    |

## Try it without sending anything

Parse a set of built-in sample lines:

```bash
python3 /usr/local/bin/abusetrack-unifi-report --selftest
```

Run the live listener in dry-run mode (prints, sends nothing):

```bash
systemctl stop abusetrack-unifi
AT_DRY_RUN=1 python3 /usr/local/bin/abusetrack-unifi-report
```

## Verify / troubleshoot

```bash
journalctl -u abusetrack-unifi -f      # live reporter output
systemctl status abusetrack-unifi      # service state
# confirm UniFi packets arrive:
tcpdump -ni any udp port 5514
```

## Uninstall

```bash
systemctl disable --now abusetrack-unifi
rm /etc/systemd/system/abusetrack-unifi.service /usr/local/bin/abusetrack-unifi-report
```