mirivlad
/
domovoy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
domovoy/Техническое задание - Домов...

26 KiB
Raw Permalink Blame History

Краткое описание

Нужно разработать self-hosted web-приложение "Домовой" для инвентаризации домашней и малой серверной инфраструктуры.

Главная идея: приложение не требует вручную заносить всю инфраструктуру с нуля. Оно умеет сканировать заданные локальные сетевые диапазоны, находить устройства, предлагать создать карточки устройств, затем после добавления доступа к устройству запускать read-only deep scan по SSH и предлагать создать карточки сервисов, контейнеров, портов, доменов, cron-задач и backup-подсказок.

Приложение должно быть безопасным, локальным и read-only в части сканирования. Оно не должно ничего менять на удалённых хостах.

Основной стек

Backend:

  • PHP 8.3+
  • Slim Framework 4
  • PDO
  • MariaDB/MySQL

Frontend:

  • Bootstrap 5.3
  • Vanilla JavaScript (только для тривиальных действий)
  • htmx для частичных обновлений без перезагрузки страницы
  • server-side rendered templates

htmx использовать для:

  • обновления таблицы scan jobs;
  • принятия/игнорирования найденного host;
  • запуска сканирования;
  • подгрузки деталей без полной перезагрузки;
  • создания устройства из discovered_host.

Alpine.js — только если htmx не покрывает кейс. Никакого "чистый JS потом допишем" — весь JS должен быть заявлен заранее и обоснован.

Deploy:

  • Docker Compose

Composer-зависимости:

  • slim/slim:"4.*"
  • slim/psr7
  • php-di/php-di
  • monolog/monolog
  • vlucas/phpdotenv
  • ramsey/uuid
  • symfony/process
  • phpseclib/phpseclib:"~3.0"
  • defuse/php-encryption

composer require robmorgan/phinx

Dev-зависимости: composer require --dev phpunit/phpunit

Не использовать тяжёлый frontend framework. Не использовать ORM в первой версии. Не использовать произвольное выполнение shell-команд от пользователя.

Миграции выполняются через Phinx: php vendor/bin/phinx migrate php vendor/bin/phinx rollback php vendor/bin/phinx create MigrationName

Каждая миграция — отдельный класс с методами up() и down(). Файл phinx.php — точка входа для конфигурации Phinx.

Архитектура выполнения задач

HTTP-запросы НЕ должны выполнять сканирование напрямую. Правильная архитектура:

  1. Web UI создаёт запись в scan_jobs (status=pending).
  2. Отдельный CLI worker (bin/run-scan-worker.php) забирает pending-задачи и выполняет их.
  3. Web UI показывает статус задачи через polling (htmx).

Это означает:

  • PHP не висит внутри HTTP-запроса во время сканирования.
  • Время выполнения HTTP-запроса — миллисекунды.
  • Worker можно запускать вручную или через cron/supervisor.
  • Worker должен обрабатывать сигналы (SIGTERM) для graceful shutdown.

Важные ограничения безопасности

  1. Сканировать только явно добавленные пользователем диапазоны.
  2. По умолчанию считать допустимыми только private/local сети:
    • 10.0.0.0/8
    • 172.16.0.0/12
    • 192.168.0.0/16
    • fd00::/8
    • link-local
  3. Не делать brute force.
  4. Не делать exploit/probe.
  5. Не пытаться подбирать пароли.
  6. Deep scan запускать только после явного добавления доступа пользователем.
  7. Все команды deep scan должны быть read-only.
  8. Секреты хранить только в зашифрованном виде.
  9. Секреты не выводить в UI и логи.
  10. Любой найденный объект сначала попадает в "Найденное", а не автоматически в основной инвентарь.
  11. Все действия сканера логировать.
  12. Запрещено делать универсальный shell executor, принимающий произвольную команду из UI.

Главный пользовательский сценарий

  1. Пользователь устанавливает приложение через Docker Compose.
  2. Заходит в web UI.
  3. Создаёт первый локальный аккаунт.
  4. Добавляет сетевой диапазон, например 192.168.1.0/24.
  5. Запускает скан сети.
  6. Видит список найденных хостов.
  7. Для нужных хостов нажимает "Создать устройство".
  8. Открывает карточку устройства.
  9. Добавляет SSH-доступ.
  10. Нажимает "Тест подключения".
  11. Если тест успешен, нажимает "Глубокий скан".
  12. Приложение собирает read-only информацию с хоста.
  13. Приложение показывает найденные порты, Docker-контейнеры, systemd-сервисы, cron-задачи, nginx-vhost-ы.
  14. Пользователь подтверждает найденные сервисы.
  15. Приложение создаёт карточки сервисов и связи между устройством, сервисами, портами, доменами и backup-подсказками.

Архитектура каталогов

Создать структуру:

domovoy/ app/ Controllers/ Services/ Discovery/ HostScan/ Inventory/ Security/ Jobs/ Analysis/ Repositories/ Middleware/ public/ index.php assets/ css/ js/ templates/ layout.php auth/ dashboard/ discovery/ devices/ credentials/ services/ documents/ migrations/ storage/ logs/ scans/ reports/ bin/ console run-scan-worker.php docker/ docker-compose.yml composer.json .env.example README.md

База данных

Нужны миграции для таблиц:

users

  • id
  • username
  • password_hash
  • created_at
  • updated_at

network_ranges

  • id
  • name
  • cidr
  • enabled
  • created_at
  • updated_at

scan_jobs

  • id
  • type
  • status
  • started_at
  • finished_at
  • error_message
  • created_by
  • created_at

type:

  • network_discovery
  • host_deep_scan
  • docker_scan
  • nginx_scan
  • cron_scan

status:

  • pending
  • running
  • done
  • failed
  • cancelled

discovered_hosts

  • id
  • scan_job_id
  • ip_address
  • mac_address
  • hostname
  • vendor
  • detected_os
  • open_ports_json
  • protocols_json
  • fingerprint_json
  • confidence
  • status
  • matched_device_id
  • first_seen
  • last_seen
  • created_at
  • updated_at

status:

  • new
  • accepted
  • merged
  • ignored
  • ignored_always

devices

  • id
  • name
  • type
  • description
  • primary_ip
  • mac_address
  • hostname
  • vendor
  • os_name
  • os_version
  • location
  • importance
  • status
  • created_at
  • updated_at

type:

  • server
  • router
  • nas
  • desktop
  • laptop
  • phone
  • printer
  • iot
  • vm
  • container_host
  • unknown

credentials

  • id
  • device_id
  • type
  • name
  • username
  • port
  • auth_method
  • encrypted_secret
  • encrypted_private_key
  • public_key_fingerprint
  • last_test_status
  • last_test_at
  • created_at
  • updated_at

type:

  • ssh
  • snmp
  • http_api
  • routeros
  • manual

MVP реализует только ssh.

host_scans

  • id
  • device_id
  • credential_id
  • scan_job_id
  • status
  • raw_json_path
  • summary_json
  • started_at
  • finished_at
  • error_message
  • created_at

detected_services

  • id
  • host_scan_id
  • device_id
  • kind
  • name
  • source
  • port
  • protocol
  • raw_json
  • suggested_service_id
  • status
  • created_at
  • updated_at

kind:

  • open_port
  • systemd_unit
  • docker_container
  • nginx_vhost
  • cron_job
  • backup_hint
  • database_hint

status:

  • new
  • accepted
  • merged
  • ignored

services

  • id
  • name
  • type
  • description
  • device_id
  • status
  • importance
  • url
  • main_port
  • created_at
  • updated_at

type:

  • web_app
  • database
  • reverse_proxy
  • backup
  • monitoring
  • storage
  • git
  • media
  • system
  • unknown

service_endpoints

  • id
  • service_id
  • protocol
  • host
  • port
  • url
  • is_public
  • created_at
  • updated_at

domains

  • id
  • domain
  • target_service_id
  • target_device_id
  • source
  • notes
  • created_at
  • updated_at

relations

  • id
  • from_type
  • from_id
  • to_type
  • to_id
  • relation_type
  • created_at

relation_type:

  • runs_on
  • depends_on
  • proxied_by
  • uses_database
  • uses_volume
  • backed_up_by
  • exposes
  • resolves_to

documents

  • id
  • entity_type
  • entity_id
  • title
  • body_markdown
  • created_at
  • updated_at

audit_log

  • id
  • user_id
  • action
  • entity_type
  • entity_id
  • details_json
  • created_at

Web UI

Общий layout

Сделать Bootstrap layout:

Левое меню:

  • Dashboard
  • Сканирование сети
  • Устройства
  • Сервисы
  • Документы
  • Настройки

Верхняя панель:

  • название "Домовой"
  • текущий пользователь
  • logout

Dashboard

Показывать:

  • количество устройств
  • количество сервисов
  • количество новых находок
  • количество предупреждений
  • последний сетевой скан
  • последние найденные хосты
  • последние deep scan результаты

Сканирование сети

Страница должна позволять:

  1. Добавить network range.
  2. Включить/выключить range.
  3. Запустить scan.
  4. Посмотреть список scan jobs.
  5. Посмотреть результаты discovered_hosts.

Таблица discovered_hosts:

  • IP
  • Hostname
  • MAC
  • Vendor
  • Open ports
  • Confidence
  • Status
  • Actions

Actions:

  • Создать устройство
  • Объединить с устройством
  • Игнорировать
  • Детали

Устройства

Страницы:

  • список устройств
  • создание устройства вручную
  • редактирование устройства
  • карточка устройства

Карточка устройства должна показывать:

  • основные поля
  • IP/MAC/hostname/vendor
  • тип
  • важность
  • заметки
  • доступы
  • найденные сервисы
  • подтверждённые сервисы
  • история сканов
  • документы

Доступы

На карточке устройства добавить блок SSH-доступов.

Для SSH-доступа:

  • name
  • username
  • port
  • auth_method password/private_key
  • password/private_key

Кнопки:

  • Тест
  • Сохранить

Тест должен проверять подключение через phpseclib.

Секреты хранить в зашифрованном виде.

Deep scan

На карточке устройства добавить кнопку:

"Глубокий скан"

После запуска:

  • создать scan_job
  • выполнить read-only SSH команды
  • сохранить raw JSON в storage/scans/
  • summary сохранить в host_scans.summary_json
  • создать detected_services

Network discovery implementation

Сделать сервисы:

  • NetworkScanner
  • PingScanner
  • TcpPortScanner
  • ArpTableReader
  • HostFingerprintService

Первый MVP network scan:

  1. Получить список IP из CIDR.
  2. Для каждого IP:
    • ping check
    • TCP connect scan по базовым портам
    • reverse DNS lookup
  3. После sweep прочитать ARP table:
    • ip neigh
    • arp -a как fallback
  4. Обогатить найденные хосты MAC-адресами.
  5. Если MAC известен — попытаться определить vendor через локальную OUI-базу или оставить пустым.
  6. Сохранить discovered_hosts.

Базовые TCP-порты:

  • 22
  • 23
  • 53
  • 80
  • 443
  • 445
  • 548
  • 631
  • 3306
  • 5432
  • 6379
  • 8000
  • 8080
  • 8443
  • 9000
  • 9090
  • 9100

Не делать агрессивное сканирование. Добавить timeout. Добавить limit параллельности.

SSH deep scan implementation

Сделать сервисы:

  • SshClientFactory
  • LinuxHostScanner
  • DockerScanner
  • NginxScanner
  • CronScanner
  • SystemdScanner
  • BackupHintScanner
  • CommandWhitelist
  • SecretMasker

Все команды должны быть в CommandWhitelist.

Запрещено принимать произвольную команду из UI.

Формат команд в CommandWhitelist — массивы аргументов, НЕ строки:

'linux.docker_ps' => ['docker', 'ps', '--format', '{{json .}}'] 'linux.hostnamectl' => ['hostnamectl'] 'linux.ip_addr' => ['ip', '-j', 'addr']

ЗАПРЕЩЕНО использовать строковые шаблоны: // НЕПРАВИЛЬНО: 'linux.docker_ps' => "docker ps --format '{{json .}}'"

Массивы аргументов безопаснее — не ломаются при передаче через Symfony Process, не конфликтуют с Twig-шаблонами, не требуют экранирования кавычек и фигурных скобок.

Разрешённые read-only команды (формат: ключ => массив аргументов):

'linux.hostname' => ['hostname'] 'linux.hostnamectl' => ['hostnamectl'] 'linux.uname' => ['uname', '-a'] 'linux.os_release' => ['cat', '/etc/os-release'] 'linux.ip_addr' => ['ip', '-j', 'addr'] 'linux.ip_route' => ['ip', 'route'] 'linux.ss_tulpen' => ['ss', '-tulpen'] 'linux.df' => ['df', '-h'] 'linux.lsblk' => ['lsblk', '-J'] 'linux.mount' => ['mount'] 'linux.systemctl_units' => ['systemctl', 'list-units', '--type=service', '--all', '--no-pager'] 'linux.systemctl_timers' => ['systemctl', 'list-timers', '--all', '--no-pager'] 'linux.crontab_user' => ['crontab', '-l'] 'linux.crontab_system' => ['cat', '/etc/crontab'] 'linux.crontab_d' => ['ls', '-la', '/etc/cron.d', '/etc/cron.daily', '/etc/cron.hourly', '/etc/cron.weekly', '/etc/cron.monthly'] 'linux.docker_ps' => ['docker', 'ps', '--format', '{{json .}}'] 'linux.docker_networks' => ['docker', 'network', 'ls', '--format', '{{json .}}'] 'linux.docker_volumes' => ['docker', 'volume', 'ls', '--format', '{{json .}}'] 'linux.docker_compose_ls' => ['docker', 'compose', 'ls', '--format', 'json']

Каждая команда выполняется отдельно. Если отдельная команда возвращает ошибку или timeout — записать ошибку в raw JSON этого collector-а, продолжить остальные.

SSH таймауты

Все SSH-операции должны иметь жёсткие таймауты. Конфигурируются через .env:

SSH_CONNECT_TIMEOUT_SECONDS=5 SSH_AUTH_TIMEOUT_SECONDS=10 SSH_COMMAND_TIMEOUT_SECONDS=8 SSH_TOTAL_SCAN_TIMEOUT_SECONDS=60 SSH_RETRY_COUNT=0

Для MVP retry отключён — лучше быстро упасть, чем зависнуть. Каждый collector внутри deep scan должен обрабатывать timeout отдельно — ошибка одного collector-а не роняет весь scan.

Если команда недоступна или возвращает ошибку, не падать всем сканом. Записать ошибку конкретного collector-а в raw JSON.

DockerScanner

Если docker доступен:

  1. Получить список контейнеров.
  2. Для каждого контейнера получить:
    • name
    • image
    • status
    • ports
    • mounts
    • networks
    • labels
    • restart policy
    • health status
  3. Не показывать значения секретных env-переменных.
  4. По контейнерам создать detected_services kind=docker_container.

Секретные имена:

  • PASSWORD
  • PASS
  • SECRET
  • TOKEN
  • KEY
  • PRIVATE
  • CREDENTIAL

NginxScanner

Если nginx найден:

  1. Проверить наличие:
    • /etc/nginx/nginx.conf
    • /etc/nginx/sites-enabled/
    • /etc/nginx/conf.d/
  2. Прочитать только конфиги.
  3. Не читать private key files.
  4. Вытащить:
    • server_name
    • listen
    • proxy_pass
    • root
    • ssl_certificate
  5. Создать detected_services kind=nginx_vhost.
  6. Создать domain suggestions.

CronScanner и BackupHintScanner

CronScanner должен собрать:

  • crontab -l
  • /etc/crontab
  • файлы /etc/cron.d

BackupHintScanner должен искать признаки:

  • rsync
  • borg
  • restic
  • rclone
  • tar
  • zip
  • mysqldump
  • mariadb-dump
  • pg_dump
  • sqlite
  • docker exec
  • scp
  • sftp

Если найдено, создать detected_services kind=backup_hint.

Формулировка в UI: "Похоже на backup job", а не "Это точно backup".

Создание сервиса из detected_service

На странице найденных сервисов добавить действие:

"Создать сервис"

При создании:

  1. Создать services.
  2. Создать service_endpoints, если есть порт/url.
  3. Создать relation:
    • Device runs_on Service или
    • Service exposes Endpoint
  4. detected_service.status = accepted

Merge / deduplication

Для discovered_hosts сделать простую логику:

Если MAC совпадает с device.mac_address:

  • предложить merge с высокой уверенностью.

Если hostname совпадает:

  • предложить merge со средней уверенностью.

Если IP совпадает:

  • предложить merge с низкой уверенностью, потому что IP может меняться.

В MVP достаточно показывать suggestions в UI. Автоматически не объединять.

Audit log

Логировать:

  • login
  • logout
  • network scan started
  • host scan started
  • device created from discovered host
  • credential created
  • credential tested
  • service created from detected service
  • object ignored
  • object merged

Docker Compose

Сделать docker-compose.yml:

services:

  • app
  • db

app:

  • PHP 8.3
  • composer install
  • volume для проекта
  • volume storage
  • depends_on db

db:

  • mariadb
  • volume db_data
  • env из .env

Добавить .env.example:

  • APP_ENV
  • APP_SECRET
  • DB_HOST
  • DB_PORT
  • DB_DATABASE
  • DB_USERNAME
  • DB_PASSWORD
  • ENCRYPTION_KEY

README

README должен содержать:

  1. Что такое Домовой.
  2. Предупреждение: сканировать только свои сети.
  3. Установка.
  4. Запуск docker-compose.
  5. Создание первого пользователя.
  6. Добавление network range.
  7. Первый scan.
  8. Создание устройства из найденного хоста.
  9. Добавление SSH-доступа.
  10. Запуск deep scan.
  11. Где смотреть логи.
  12. Как запустить миграции.

CI/CD и smoke tests

Создать файл scripts/check.sh — локальный чек-скрипт, который запускается после каждой итерации.

Минимальный набор проверок:

#!/usr/bin/env bash set -euo pipefail

echo "=== composer validate ===" composer validate --no-check-publish

echo "=== PHP syntax check ===" find app public bin -name "*.php" -print0 | xargs -0 -n1 php -l

echo "=== docker compose config ===" docker compose config > /dev/null

echo "=== docker compose up ===" docker compose up -d --build

echo "=== phinx migrate ===" docker compose exec app php vendor/bin/phinx migrate

echo "=== HTTP health check ===" curl -sI http://localhost:8080/login | head -1

echo "=== ALL CHECKS PASSED ==="

Для следующих итераций добавлять свои проверки:

  • network scan: "docker compose exec app php bin/console scan:test"
  • device CRUD: curl к страницам devices
  • credentials: тест SSH mock-connection

Головное правило: итерация не считается завершённой, пока check.sh не прошёл успешно без ошибок.

Технические требования

  1. Код должен быть простым и читаемым.
  2. Не делать преждевременно сложную архитектуру.
  3. Контроллеры не должны содержать бизнес-логику.
  4. SQL изолировать в Repository-классах.
  5. Сканеры изолировать в Services.
  6. Все shell-команды запускать только через CommandWhitelist.
  7. Все ошибки scanner collector-ов сохранять, но не ронять весь scan.
  8. UI должен быть рабочим, пусть и простым.
  9. Bootstrap использовать без сборки frontend.
  10. Vanilla JS только для небольших интерактивных действий.
  11. Никаких React/Vue.
  12. Никаких внешних SaaS-зависимостей.

Порядок реализации

Итерация 1

Сделать каркас:

  • Slim app
  • Docker Compose
  • DB connection
  • migrations runner
  • auth
  • dashboard
  • layout

Результат должен запускаться.

Итерация 2

Сделать:

  • network_ranges CRUD
  • scan_jobs table
  • discovered_hosts table
  • NetworkScanner с ping/tcp scan
  • страницу результатов

Итерация 3

Сделать:

  • devices CRUD
  • создание device из discovered_host
  • ignore discovered_host
  • карточку устройства

Итерация 4

Сделать:

  • credentials CRUD для SSH
  • шифрование секрета
  • тест SSH-подключения через phpseclib

Итерация 5

Сделать:

  • HostScan по SSH
  • LinuxHostScanner
  • raw JSON сохранение
  • summary на карточке устройства

Итерация 6

Сделать:

  • DockerScanner
  • detected_services из контейнеров
  • страницу найденных сервисов

Итерация 7

Сделать:

  • создание service из detected_service
  • service_endpoints
  • relations

Итерация 8

Сделать:

  • NginxScanner
  • CronScanner
  • BackupHintScanner

Итерация 9

Сделать:

  • RiskAnalyzer
  • dashboard warnings
  • scan history
  • basic diff

Формат ответа после каждой итерации

После работы нужно выдать:

  1. Что сделано.
  2. Какие файлы созданы/изменены.
  3. Как запустить.
  4. Какие команды выполнить.
  5. Что проверить вручную.
  6. Известные ограничения.
  7. Что делать следующей итерацией.

Не переходить к следующей итерации без успешного запуска текущей. Обязательно запустить scripts/check.sh и показать вывод. Без успешного smoke test итерация не считается завершённой.

Правила для owl-alpha / LLM-кодера

Запрещено:

  • переписывать уже готовое без причины;
  • делать большие коммиты — только маленькие атомарные;
  • выдумывать несуществующие зависимости;
  • делать произвольный shell executor;
  • использовать строковые шаблоны для docker-команд;
  • писать "чистый JS" без обоснования — весь JS заранее заявлен.

Требуется:

  • маленькие коммиты;
  • список изменённых файлов после каждой итерации;
  • инструкции запуска;
  • self-check через scripts/check.sh;
  • показать реальный вывод smoke test, а не утверждать "готово".

Итерация 1

Сделай только Итерацию 1 проекта "Домовой".

Нужно:

  • создать каркас Slim 4 приложения;
  • настроить Docker Compose с app + MariaDB;
  • сделать .env.example;
  • сделать простой migrations runner;
  • сделать таблицу users;
  • сделать регистрацию первого пользователя через CLI или временную страницу setup;
  • сделать login/logout;
  • сделать Dashboard;
  • сделать Bootstrap layout с меню;
  • написать README с запуском.

Не реализовывать network scan, devices, credentials и deep scan в этой итерации. После выполнения выдать список файлов, команды запуска и что проверить вручную.