← All docs· Edit on GitHub ↗

Установка нового sensor'а на Ubuntu/Debian

Версия после Phase Onboarding (2026-05-24). Аудитория: сетевой инженер, Linux-админ заказчика. Описывает как поднять рабочий sensor за <5 минут от первого SSH до зелёного «online» в дашборде.

Windows / macOS пока не поддерживаются. Только Ubuntu 20.04+ и Debian 11+

на x86_64. ARM64 — теоретически работает, ноу не тестировался.

---

TL;DR — самый быстрый путь

# На admin-машине (с доступом к дашборду):
# 1. Открой Sensors → Enroll new sensor → Generate token
# 2. Скопируй one-liner

# На целевой машине (фреш Ubuntu/Debian, нужен sudo):
curl -fsSL https://CONTROLLER/install-sensor.sh \
  | sudo bash -s -- --controller https://CONTROLLER --token TOKEN

# ✅ Готово. Через <30 секунд — sensor зелёный в дашборде.

Что произойдёт под капотом

Установщик проверит что вы на Ubuntu/Debian + root.
Поставит curl + libcap2-bin (если их нет).
Скачает бинарь arpg-sensor с контроллера в /usr/local/bin/.
Вызовет arpg-sensor enroll, который:

соберёт fingerprint хоста (hostname, FQDN, kernel, список интерфейсов);
POST'нет на https://CONTROLLER/api/sensors/enroll с токеном + fingerprint'ом;
получит обратно sensor_id, agent_secret, выбранный iface, NATS-адрес, baseline-URL;
запишет конфиг в /etc/arpg/sensor.toml (0600 root, содержит секрет);
скачает baseline → /var/lib/arpg/baseline.tsv;
сделает setcap cap_net_raw,cap_net_admin+eip на бинарь;
установит и запустит systemd-юнит arpg-sensor.service;
подождёт 30s, проверит что первый heartbeat дошёл до контроллера;

Дашборд через 10 секунд покажет sensor зелёным.

Каждый heartbeat подписывается HMAC-SHA256 ключом agent_secret. Поддельные heartbeat'ы контроллер отклоняет и пишет в audit.

Подробный сценарий — от консоли до триажа

Шаг 1: Admin генерирует токен (1 минута)

В дашборде:

Левое меню → Sensors
Сверху страницы — карточка Enroll new sensor → кнопка Generate token
Опционально заполняешь:

Sensor ID — например sensor-managed-3 (пусто = автогенерация)
Site / VLAN — default lab / 10
Note — "managed-3, server room rack 4"
TTL — default 60 минут

Нажимаешь Generate
Появляется баннер с тремя строками:

Сам токен RR-T7K9-B2NF-3PQE (кнопка Copy)
One-liner (для curl | bash) (кнопка Copy)
Manual (если бинарь уже стоит) (кнопка Copy)

Шаг 2: Инженер на целевой VM

# Через SSH
sudo bash
curl -fsSL https://sec.company.local/install-sensor.sh \
  | bash -s -- --controller https://sec.company.local --token RR-T7K9-B2NF-3PQE

Что увидишь:

[install] target: ubuntu 24.04
[install] downloading sensor binary from https://arpguardian.meirlan.ru/downloads/arpg-sensor-linux-x64 ...
[install] binary installed at /usr/local/bin/arpg-sensor (18345213 bytes)
[install] running enroll...
[enroll] host: managed-3 (3 ifaces detected)
[enroll] calling https://sec.company.local/api/sensors/enroll ...
[enroll] assigned sensor_id=sensor-managed-3, site=lab, vlan=10, iface=ens33
[enroll] writing config → /etc/arpg/sensor.toml
[enroll] downloading baseline → /var/lib/arpg/baseline.tsv
[enroll] setcap cap_net_raw,cap_net_admin+eip /usr/local/bin/arpg-sensor
[enroll] waiting for first heartbeat ...

✅ Enrolled as sensor-managed-3
   Site:  lab / VLAN 10
   Iface: ens33
   Controller: https://sec.company.local
   Status: systemctl status arpg-sensor

Шаг 3: Проверка в дашборде

Через 10 секунд:

Sensors → новая строка sensor-managed-3 с зелёным кружком
Колонка host=managed-3 · ens33, v0.1.0, up 30s, frames_total начинает расти
Кликни на строку → detail modal с recent_detections (пока пусто)

Шаг 4: Если что-то пошло не так

# Health-чек на хосте — 6 проверок зелёный/красный:
sudo arpg-sensor doctor

# Что показывает systemd:
sudo systemctl status arpg-sensor

# Последние 50 строк лога:
sudo journalctl -u arpg-sensor -n 50

# Конфиг (с secret — никому не показывай!):
sudo cat /etc/arpg/sensor.toml

# Статус:
sudo arpg-sensor status

Команды sensor'а

Команда	Что делает
`arpg-sensor enroll --controller URL --token T`	Регистрирует на контроллере, ставит systemd, запускает
`arpg-sensor doctor`	6 проверок: config, caps, iface up, iface promisc, NATS, controller, baseline freshness
`arpg-sensor status`	Показывает config + systemd status
`arpg-sensor unenroll`	Graceful: контроллеру сказать revoke, остановить systemd, удалить config
`arpg-sensor live --config /etc/arpg/sensor.toml`	Запуск capture в foreground (то что делает systemd)

Альтернативный путь — без install.sh

Если у тебя уже есть arpg-sensor бинарь на хосте (например, через scp):

sudo arpg-sensor enroll --controller https://CONTROLLER --token TOKEN

Если бинарь не в PATH:

sudo install -m 0755 ./arpg-sensor /usr/local/bin/
sudo /usr/local/bin/arpg-sensor enroll --controller … --token …

Self-signed TLS / лабораторная установка

Лабораторный controller использует self-signed cert (Caddy tls internal). Sensor проверит цепочку и упадёт. Workaround:

sudo arpg-sensor enroll --controller https://CONTROLLER --token TOKEN \
  --insecure-skip-tls-verify   # или -k

В production используй настоящий cert (LetsEncrypt через Caddy: поменяй tls internal на tls admin@you.com в infra/caddy/Caddyfile).

Установка БЕЗ systemd (контейнер / другой init)

sudo arpg-sensor enroll --controller URL --token TOKEN --skip-systemd
# затем запускай вручную:
sudo arpg-sensor live --config /etc/arpg/sensor.toml

Возможные проблемы и решения

Симптом	Решение
`curl … exit 22: HTTP 401: token already consumed`	Токен одноразовый. Сгенерируй новый.
`curl … exit 22: HTTP 401: token expired`	Токен живёт 1 час по умолчанию. Сгенерируй новый.
`setcap … Operation not permitted`	Запусти `enroll` под `sudo`.
`iface promisc … ❌ not promisc` в doctor	`sudo ip link set ens33 promisc on` (или ребут — systemd unit делает это в ExecStartPre)
`controller reachable ❌`	Проверь firewall (443/tcp out). Curl-test: `curl -k https://CONTROLLER/`
`NATS reachable ❌`	NATS на :4222/tcp. Если контроллер за NAT/firewall — нужен ALLOW для NATS-порта (не только 443)
`baseline freshness ⚠️ N days old`	`sudo arpg-sensor refresh-baseline` (или ручкой: `curl … /api/baseline.tsv`)
Sensor видно `degraded` через 30s после старта	Heartbeats не доходят. `journalctl -u arpg-sensor` → ищи "NATS connect failed"
Sensor в `revoked` после restart	Admin отозвал в дашборде. Сгенерируй новый токен + re-enroll
Multi-NIC хост, sensor взял не тот iface	Поправь `iface = X` в `/etc/arpg/sensor.toml`, `sudo systemctl restart arpg-sensor`

Bulk-rollout на 10+ хостов

Вариант 1 — Ansible (рекомендуется для >5 хостов):

# inventory.ini:
[sensors]
managed-1 ansible_host=10.0.0.11 desired_id=sensor-1
managed-2 ansible_host=10.0.0.12 desired_id=sensor-2
...

# playbook (per host: generate token, install, enroll):
- hosts: sensors
  become: yes
  tasks:
    - name: Get one-time token
      delegate_to: localhost
      uri:
        url: https://controller/api/sensors/enroll-token
        method: POST
        headers: { Authorization: "Bearer {{ admin_token }}" }
        body_format: json
        body: { desired_sensor_id: "{{ desired_id }}", note: "{{ inventory_hostname }}" }
      register: tok

    - name: Install via one-liner
      shell: >
        curl -fsSL https://controller/install-sensor.sh
        | sudo bash -s --
        --controller https://controller
        --token {{ tok.json.token }}

Вариант 2 — массовая копипаста: открой 10 SSH-окон, в каждом вставь свой one-liner. Каждый из них independent, можно паралельно.

Безопасность — что под капотом

Enrollment token — одноразовый, 1h TTL по умолчанию (admin может задать), audit-logged
Agent secret — 32 байта (64 hex), HMAC-SHA256 ключ. Хранится в /etc/arpg/sensor.toml 0600 root.

Никогда не передаётся через NATS — только при enroll (HTTPS).

Каждый heartbeat подписан — поле sig. Поддельный → controller'ом отброшен, audit-row sensor.heartbeat_rejected с reason=HMAC mismatch.
Revocation — admin → Sensors → detail modal → Revoke. После revoke секрет в БД обнулён,

все будущие heartbeats отбиваются с reason=revoked.

HMAC-secret не светится в логах — даже в debug-режиме показываем только первые 16 hex.

RBAC

Действие	Минимальная роль
Видеть Sensors list / detail	viewer
Generate enrollment token	admin
Disable / Enable / Revoke sensor	admin
Удалить unused token из queue	admin
Sensor → controller (enroll, heartbeat)	требует token / HMAC, не JWT

Что НЕ работает (явный non-goal Phase Onboarding v1)

Auto-upgrade ("кнопка upgrade to v0.2.0 в дашборде") — отложено, нужен release pipeline + GPG-подпись
macOS / Windows — только Linux
`.deb` пакет — пока бинарь раздаётся как статика по /downloads/arpg-sensor-linux-x64. apt-репо позже.
mTLS / NATS NKeys — пока NATS открыт всем в сегменте. v1.5.
Auto-rotation `agent_secret` — пока вручную через unenroll + re-enroll.
Раздельный режим "только capture, без heartbeat publish" — пока всё или ничего.

Полный flow в одной диаграмме

                       Admin                           Controller                        Sensor Host
                         |                                  |                                |
   Settings → Sensors    |                                  |                                |
   → Generate token   ───┼─► POST /api/sensors/enroll-token │                                |
                         │   ├─► row in enrollment_tokens   │                                |
                         │   └─► returns token + one-liner  │                                |
   Copy one-liner        │                                  │                                |
                         │                                  │                                |
   scp / SSH paste ──────┼──────────────────────────────────┼──► sudo bash install-sensor.sh │
                         │                                  │     ├─► GET /downloads/arpg-sensor-linux-x64 │
                         │                                  │◄───┤   (public static)         │
                         │                                  │    └─► installed at /usr/local │
                         │                                  │                                │
                         │                                  │     arpg-sensor enroll          │
                         │                                  │     ├─► fingerprint host       │
                         │                                  │◄────┤ POST /api/sensors/enroll  │
                         │   ├─► validate token             │     │                          │
                         │   ├─► mint agent_secret          │     │                          │
                         │   ├─► UPSERT sensors row         │     │                          │
                         │   └─► return {sensor_id, secret}─┼────►│ write /etc/arpg/sensor.toml
                         │                                  │     │ setcap, install systemd  │
                         │                                  │     │ start service            │
                         │                                  │                                │
                         │                                  │◄────┤ heartbeat (signed)       │
                         │   verify HMAC ✓ → upsert         │     │ every 10s                │
                         │                                  │     │                          │
   Sensors page          │                                  │                                │
   → row appears 🟢 ─────┴──────────────────────────────────┘                                │
                                                                                            │
   ── If admin revokes:                                                                     │
   Sensor detail → Revoke ─► sensors.revoked=true, agent_secret=''                          │
                                  ↓                                                          │
   next heartbeat ──────────┘ → controller logs HMAC verify fail (revoked) → audit row     │

См. также

SENSOR-COVERAGE.md — обязательно к прочтению перед production-deployment: Distributed vs Centralized vs Hybrid, конкретные команды для Cisco/Aruba/Juniper SPAN, VMware/KVM/Hyper-V promisc.
Sensors PM-review
Sensor Onboarding PM-review
Sensor Coverage PM-review
SENSORS-USER-GUIDE.md — после установки: что делать дальше
AUDIT-USER-GUIDE.md — каждое enroll/revoke попадает в audit

Что произойдёт ПОСЛЕ enroll'а (Phase Sensor Coverage)

Installer запустит arpg-sensor doctor --coverage 15 и выведет verdict:

Verdict	Что это значит
✅ `FULL`	Sensor видит unicast между чужими хостами. Все detection-rule'ы активны.
⚠ `PARTIAL`	Только свои unicast + broadcasts. Cross-host replies невидимы.
⚠ `BROADCAST-ONLY`	Только broadcasts. Detection сильно ограничен — см. SENSOR-COVERAGE.md.
❌ `SILENT`	Не видим ничего. Проблема с интерфейсом / VLAN.

Если verdict не FULL — прочитай [SENSOR-COVERAGE.md](SENSOR-COVERAGE.md) до того как полагаться на детекцию. Чаще всего лекарство: либо включить vSwitch promisc (VMware/Hyper-V), либо SPAN/mirror на upstream switch, либо распределить host-agent на каждую защищаемую ноду.

Перепроверить coverage позже:

sudo arpg-sensor doctor --coverage 30 -i ens33