Skip to content

Operations

Jump to bottom
Andrii Sheiko edited this page Nov 3, 2026 · 13 revisions

Operations

Ця сторінка описує типовий продакшн-розкат PyCVE: регулярна збірка правил на одній машині, статичний хостинг і періодичні запуски агента на хостах. Перше знайомство краще починати з Getting Started.

Вимоги до середовища

Компонент Python Ще потрібно
pycve-server 3.11+ мережевий доступ до фідів (Data Sources)
pycve-agent 3.8+, або не потрібен зовсім при використанні зібраного бінарника HTTP-доступ до статики; на Ubuntu/Debian — dpkg ≥ 1.16.2, на RPM-платформах — rpm

Вимога до dpkg стосується і Python-варіанта, і бінарника: уся package- і Debian kernel-логіка агента спирається на поля ${source:Package}, ${source:Version} і ${db:Status-Abbrev} з dpkg-query, які є з dpkg 1.16.2 (dpkg-query(1)). Усі релізи, для яких будуються рулсети (focal і новіші, bullseye і новіші), мають значно новіший dpkg; старіший є лише на Ubuntu 12.04 і Debian 6. На такому dpkg результат неповний: CVE source-пакетів пропускаються, а видалені без purge пакети рахуються встановленими.

У прикладах нижче репозиторії розгорнуті в /opt/pycve-server і /opt/pycve-agent, а правила збираються в /srv/www/pycve/rules. Обгортки run-rule-builder.sh / run-local-agent.sh не потребують попередньо активованого venv.

Збірка правил

Ubuntu:

/opt/pycve-server/run-rule-builder.sh \
  --canonical-cves \
  --releases focal,jammy,noble \
  --output-dir /srv/www/pycve/rules \
  --write-priority

Debian:

/opt/pycve-server/run-rule-builder.sh \
  --debian-cves \
  --releases bookworm,bullseye,trixie \
  --output-dir /srv/www/pycve/rules

AlmaLinux 10:

/opt/pycve-server/run-rule-builder.sh \
  --almalinux-oval \
  --releases 10 \
  --output-dir /srv/www/pycve/rules

Для змішаного парку команди запускаються по черзі в той самий --output-dir. AlmaLinux використовує ім'я almalinux10.json, тому числові major releases різних RPM-вендорів не конфліктуватимуть.

Перший повний обхід Canonical feed довгий; якщо він перерветься, просто перезапустіть команду — builder продовжить із checkpoint (Architecture). Частковий результат (наприклад, обмежений --max-pages) ніколи не публікуйте як продакшн-правила.

Оновлення пріоритетів

cve-priority.json варто оновлювати частіше, ніж правила: статус KEV чи EPSS-оцінка можуть змінитися за години, тоді як нові version-правила з'являються повільніше. Режим --priority-only робить це дешево — без походу в source-фіди, читаючи вже зібрані рулсети з --output-dir:

/opt/pycve-server/run-rule-builder.sh \
  --output-dir /srv/www/pycve/rules \
  --priority-only

Під час інциденту сюди ж додається файл ручних пріоритетів (Priority):

/opt/pycve-server/run-rule-builder.sh \
  --output-dir /srv/www/pycve/rules \
  --priority-only \
  --manual-priority-file /srv/www/pycve/manual-priority.json

Статичний хостинг

Єдина вимога до хостингу — віддавати каталог правил по HTTP(S):

https://host/rules/<release>.json     # focal.json, jammy.json, bookworm.json, ...
https://host/rules/almalinux10.json  # RPM platform + major release
https://host/rules/cve-priority.json  # опційно

Підійде nginx, S3+CDN чи будь-який інший статичний сервер — PyCVE не нав'язує спосіб публікації. Builder пише файли безпосередньо у served-каталог, тож після завершення збірки сервер одразу віддає свіжі дані; окремого кроку deploy немає.

Мінімальний приклад для nginx:

server {
    listen 443 ssl;
    server_name host;

    # ssl_certificate     /etc/nginx/ssl/host.crt;
    # ssl_certificate_key /etc/nginx/ssl/host.key;

    location /rules/ {
        alias /srv/www/pycve/rules/;
        default_type application/json;

        # Свіжістю рулсетів керує сам агент через поле ttl у файлі,
        # тому проміжні кеші (проксі, CDN) не повинні тримати копії:
        # інакше після оновлення файлів агенти можуть отримувати
        # протухлі правила довше, ніж очікується.
        add_header Cache-Control "no-cache";
    }
}

Двох речей тут достатньо, щоб не отримати тонких проблем: default_type application/json — щоб файли віддавались із коректним типом незалежно від mime-конфігурації, і Cache-Control "no-cache" — щоб проміжний кеш щоразу ревалідовував файл у origin (nginx відповість дешевим 304, якщо файл не змінився), а не роздавав стару копію за власною евристикою.

Запуск агента

/opt/pycve-agent/run-local-agent.sh --rules-base-url https://host/rules

Альтернатива для хостів без Python — самодостатній бінарник з ідентичним CLI (стандартний для Ubuntu 22.04+/Debian 12+, legacy для старіших систем, зокрема focal і bullseye):

/opt/pycve-agent/pycve-agent-linux-x86_64 --rules-base-url https://host/rules

Деталі варіантів і збірки — в Agent Reference.

Агент друкує результат у stdout — підсумковий рядок, а при кількох збігах ще й список CVE (за замовчуванням перші 5, див. --cve-limit і --show-all-cves в Agent Reference); логи йдуть у stderr. Для повної перевірки запускайте його від root: без root агент не бачить процеси зі старим кодом інших користувачів. Завершується з кодом:

Exit code Статус Значення
0 OK Жодне правило не заматчилось і немає процесів зі старим кодом.
1 ERROR Перевірку виконати не вдалося (немає рулсету і свіжого кешу тощо).
2 VULNERABLE Є збіг з priority low/medium/unknown (або priority payload недоступний), або процеси зі старим кодом.
3 VULNERABLE_HIGH Є збіг з priority high.
4 VULNERABLE_CRITICAL Є збіг з priority critical (включно з KEV і ручним override).

Exit code відображає найвищий priority серед знайдених збігів, а не kernel/package — цей поділ лишився тільки в тексті повідомлення. Деталі — в Agent Reference.

Корисні режими фільтрації (комбінуються):

# тільки kernel-збіги / тільки package-збіги
run-local-agent.sh --rules-base-url https://host/rules --kernel-only
run-local-agent.sh --rules-base-url https://host/rules --packages-only

# тільки precise-збіги з опублікованою fixed version (без advisory) — типово для алертингу
run-local-agent.sh --rules-base-url https://host/rules --fixed-only

# більше рядків у виводі (типово 5) або взагалі всі
run-local-agent.sh --rules-base-url https://host/rules --cve-limit 20
run-local-agent.sh --rules-base-url https://host/rules --show-all-cves

Повний перелік ключів, формати повідомлень і правила сортування — в Agent Reference.

Кеш агента

Останній успішно завантажений рулсет кешується (типово /tmp/local-agent-ruleset.json, для priority — сусідній файл із суфіксом .priority). Якщо статика тимчасово недоступна, агент використовує кеш, поки той свіжий у межах ttl рулсету. Протухлий кеш без явного --allow-expired-cache дає ERROR — «не зміг перевірити» свідомо не маскується під OK.

Розклад через cron

Рекомендована модель — три незалежні джоби на builder-машині та один на кожному хості:

# Ubuntu-правила — щодня
0 3 * * * /opt/pycve-server/run-rule-builder.sh --canonical-cves --releases focal,jammy,noble --output-dir /srv/www/pycve/rules >> /var/log/pycve-rule-builder.log 2>&1

# Debian-правила — щотижня (трекер змінюється повільніше)
0 4 * * 1 /opt/pycve-server/run-rule-builder.sh --debian-cves --releases bookworm,bullseye,trixie --output-dir /srv/www/pycve/rules >> /var/log/pycve-rule-builder.log 2>&1

# AlmaLinux 10 OVAL — щодня
30 4 * * * /opt/pycve-server/run-rule-builder.sh --almalinux-oval --releases 10 --output-dir /srv/www/pycve/rules >> /var/log/pycve-rule-builder.log 2>&1

# Пріоритети — щогодини (дешева операція, див. вище)
0 * * * * /opt/pycve-server/run-rule-builder.sh --output-dir /srv/www/pycve/rules --priority-only >> /var/log/pycve-priority.log 2>&1

На кожному хості:

*/15 * * * * /opt/pycve-agent/run-local-agent.sh --rules-base-url https://host/rules >> /var/log/pycve-agent.log 2>&1

Завдяки сталому формату stdout і зрозумілим exit codes агент також легко вбудовується в наявний check-runner чи систему моніторингу.

Відомі обмеження

  • Агент очікує per-release статичні JSON-файли; --rules-base-url вказує на каталог, а не на конкретний файл. RPM-платформи використовують <platform><release>.json.
  • У контейнері kernel_version-перевірка фактично стосується ядра хоста.
  • Debian kernel-перевірки порівнюють версію встановленого пакета поточного ядра (linux-image-*), а не uname -r із версією в трекері.
  • Зворотної телеметрії немає: агент нікуди не звітує, збір результатів із парку — відповідальність зовнішнього тулінгу (cron + логи, check-runner, тощо).
  • Сторонні репозиторії не покриваються (Sury, Percona тощо): OK не означає, що такі пакети безпечні. Деталі — в Data Sources.

Clone this wiki locally