# easysiem-openwrt-agent (OpenWRT package)

Ships OpenWRT's system log (via `logread`, BusyBox syslogd's ring buffer
-- the one log source every OpenWRT router has; firewall drop/accept
lines show up in this same stream if firewall logging is enabled) and,
on devices with enough flash/RAM to run it, Suricata IDS/IPS alerts, to
an EasySIEM `ingest-api` server over HTTPS.

**Built and documented without access to a real OpenWRT device.** The
Suricata half reuses code already verified end-to-end elsewhere in this
project. The `logread` line parser is built from BusyBox syslogd's
documented default format and has real unit tests against hand-built
sample lines, but those weren't captured from a real device -- the full
raw line always ships as `LogreadRaw` regardless, so nothing is lost even
if the structured fields need adjusting. See the main repo's
`agents/openwrt/main.go` for the full caveat.

**Architecture strings are a real unknown too.** OpenWRT's `opkg`
architecture identifiers are per-target/subtarget (e.g. `aarch64_generic`,
`aarch64_cortex-a53`, `mipsel_24kc`, `arm_cortex-a7`, ...), not a simple
CPU-family string -- the three packages built here
(`easysiem-openwrt-agent_1.0.0_aarch64_generic.ipk`,
`..._mipsel_24kc.ipk`, `..._arm_cortex-a7.ipk`) use common generic
identifiers, but **check `opkg print-architecture` on your actual router
first** -- if none of these match, use the raw binary directly instead
(see "If the .ipk doesn't match your device" below) or rebuild with a
matching `arch:` in `nfpm.yaml`.

## Installing (if your device's arch matches one of the three built here)

```sh
scp easysiem-openwrt-agent_1.0.0_aarch64_generic.ipk root@router:/tmp/
ssh root@router
opkg install /tmp/easysiem-openwrt-agent_1.0.0_aarch64_generic.ipk
```

## If the .ipk doesn't match your device

The agent is a single static binary (`CGO_ENABLED=0`, no libc dependency
either way, so musl vs. glibc doesn't matter) -- copy it over directly and
skip opkg entirely:

```sh
scp bin/openwrt-agent-arm64 root@router:/usr/bin/easysiem-openwrt-agent   # pick the matching GOARCH build
scp agents/openwrt/agent.json.example root@router:/etc/easysiem/agent.json.example
scp packaging/ipk-openwrt/easysiem-openwrt-agent.init root@router:/etc/init.d/easysiem-openwrt-agent
ssh root@router chmod 755 /usr/bin/easysiem-openwrt-agent /etc/init.d/easysiem-openwrt-agent
```

(No `arm64`/`mipsle`/`arm` build matches your router's actual CPU either?
Cross-compile your own: `GOOS=linux GOARCH=<yours> CGO_ENABLED=0 go build
-ldflags="-s -w" -o openwrt-agent ./agents/openwrt` from the main repo --
see Go's own `go tool dist list` for every GOARCH it supports.)

## Configuring

```sh
cp /etc/easysiem/agent.json.example /etc/easysiem/agent.json
```

Edit `agent.json`:

- `server_url` -- `https://<easysiem-server-host>:8443`
- `api_key` -- generate one on the server with `genkey` (`easysiem-genkey
  -agent-id openwrt-01 -os openwrt -restart` on a Linux EasySIEM server,
  `bin\genkey.exe -agent-id openwrt-01 -os openwrt -restart` on Windows)
- `agent_id` -- whatever you want, no format restrictions
- `ca_cert_path` -- copy the server's `server.crt` to this device first
  (e.g. `/etc/easysiem/server.crt`), then point this at it -- or set
  `insecure_skip_verify: true` instead for a quick lab test
- `logread_skip_fw_accept` -- **defaults to `true`** (omit it entirely to
  get this): of the subset of `logread` lines that look like fw4/nftables
  firewall log lines, only ships `DROP`/`REJECT` ones, not `ACCEPT`.
  Mirrors `agents/opnsense`'s `filterlog_skip_pass` -- same "allowed
  traffic is usually noise, denied traffic is usually what a SIEM wants"
  reasoning, but **unverified against real device volume** the way
  OPNsense's equivalent was (confirmed there: 92% "pass"); there's no
  real OpenWRT box to measure against, and OpenWRT firewall configs often
  don't even enable ACCEPT-rule logging by default in the first place.
  Doesn't touch the rest of `logread`'s much noisier general syslog
  stream (DHCP, wifi, cron, ...) -- only the firewall-heuristic subset.
  Set `"logread_skip_fw_accept": false` explicitly for full ACCEPT+DROP
  firewall visibility.
- `suricata_eve_path` -- only relevant if you've installed Suricata via
  `opkg` yourself; leave blank otherwise

## Running

```sh
/etc/init.d/easysiem-openwrt-agent enable
/etc/init.d/easysiem-openwrt-agent start
```

Check it's alive:

```sh
logread | grep openwrt-agent
```

## Uninstalling

```sh
/etc/init.d/easysiem-openwrt-agent stop
opkg remove easysiem-openwrt-agent
```

(Or, if installed manually rather than via opkg: stop the init script,
`rm /usr/bin/easysiem-openwrt-agent /etc/init.d/easysiem-openwrt-agent`.)

## Notes

- Runs as root (procd's default) -- `logread` and Suricata's `eve.json`
  (if configured) both need it.
- Flash-constrained devices: the static binary is ~6.5-7.9 MB depending
  on architecture (stripped, `-ldflags="-s -w"`) -- fine for most current
  routers (128 MB+ flash is common), worth checking `df -h /` first on
  anything older/smaller.
- Full project docs, server-side setup, and the Windows/Linux/OPNsense
  agents: <https://easysiem.com>.
