{"id":50278923,"url":"https://github.com/laserattack/humanguard","last_synced_at":"2026-05-27T23:01:01.735Z","repository":{"id":340987123,"uuid":"1161543002","full_name":"laserattack/HumanGuard","owner":"laserattack","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-22T16:27:50.000Z","size":417,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-22T17:29:26.748Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laserattack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-19T08:25:04.000Z","updated_at":"2026-05-22T16:27:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/laserattack/HumanGuard","commit_stats":null,"previous_names":["laserattack/humanguard"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/laserattack/HumanGuard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserattack%2FHumanGuard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserattack%2FHumanGuard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserattack%2FHumanGuard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserattack%2FHumanGuard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laserattack","download_url":"https://codeload.github.com/laserattack/HumanGuard/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserattack%2FHumanGuard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33586821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-27T23:01:00.081Z","updated_at":"2026-05-27T23:01:01.728Z","avatar_url":"https://github.com/laserattack.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HumanGuard\n\n**HumanGuard** — это SaaS-решение для защиты веб-сайтов от автоматизированных атак и ботов. Система работает как обратный прокси, анализируя поведение посетителей и HTTP-запросы для выявления аномальной активности.\n\n## Содержание\n\n- [Общее описание](#общее-описание)\n- [Функциональное назначение](#функциональное-назначение)\n- [Алгоритм настройки и запуска](#алгоритм-настройки-и-запуска)\n- [Требования к аппаратному обеспечению](#требования-к-аппаратному-обеспечению)\n- [Описание безопасности системы](#описание-безопасности-системы)\n\n## Общее описание\n\n### Назначение\n\n- Защита веб-сайтов от ботов и автоматизированных атак\n- Анализ поведенческих метрик посетителей (движения мыши, клики, скроллинг)\n- Детектирование headless-браузеров и подозрительных паттернов\n- Автоматическая блокировка или показ CAPTCHA при высоком уровне риска\n- Предоставление API для интеграции со сторонними сервисами\n\n### Архитектура системы\n\n| Модуль | Назначение |\n|--------|------------|\n| **Сбор поведенческих данных** | Сбор клиентских метрик на стороне браузера |\n| **Анализ паттернов обращений** | Анализ HTTP-запросов на серверной стороне |\n| **Детекция аномалий** | Присвоение каждой сессии оценки риска (0–100) |\n| **Реагирование** | Настраиваемые действия в зависимости от уровня риска |\n| **Логирование и мониторинг** | Запись событий, экспорт метрик в Prometheus, визуализация в Grafana |\n| **Управление настройками** | Настройка порогов срабатывания |\n| **Аутентификация** | Регистрация по email с 2FA, OAuth, управление API ключами |\n| **Файловое хранилище** | Загрузка файлов, расшаривание по токенам, поддержка MinIO S3 |\n\n### Среда исполнения\n\n| Компонент | Версии |\n|-----------|--------|\n| Go | 1.25+ |\n| React | 18+ |\n| Docker | 29+ |\n| Docker Compose | 2+ |\n| Nginx | alpine |\n| PostgreSQL | 15 |\n| MinIO | latest |\n\n## Функциональное назначение\n\n### API Эндпоинты\n\n| Метод | Путь | Назначение | Auth |\n|-------|------|------------|------|\n| POST | `/api/users` | Регистрация пользователя | Нет |\n| POST | `/api/login` | Вход с TOTP 2FA | Нет |\n| GET | `/api/auth/google/login` | OAuth авторизация Google | Нет |\n| GET | `/api/auth/github/login` | OAuth авторизация GitHub | Нет |\n| GET | `/api/auth/keycloak/login` | OAuth авторизация Keycloak | Нет |\n| POST | `/api/check` | Проверка сессии (для nginx reverse-proxy) | Нет |\n| POST | `/api/behavior/{id}` | Отправка поведенческих метрик | Нет |\n| GET | `/api/me` | Профиль текущего пользователя | JWT/API Key |\n| GET | `/api/sites` | Список сайтов пользователя | JWT/API Key |\n| POST | `/api/sites` | Создание сайта | JWT/API Key |\n| GET | `/api/sites/{id}/stats` | Статистика по сайту | JWT/API Key |\n| GET | `/api/sites/{id}/sessions` | Активные сессии сайта | JWT/API Key |\n| GET | `/api/sites/{id}/sessions/suspicious` | Подозрительные сессии | JWT/API Key |\n| PUT | `/api/sites/{id}/settings` | Обновление настроек сайта | JWT/API Key |\n| POST | `/api/sites/{id}/activate` | Активация сайта | JWT/API Key |\n| POST | `/api/sites/{id}/suspend` | Блокировка сайта | JWT/API Key |\n| POST | `/api/keys` | Создание API ключа | JWT |\n| GET | `/api/keys` | Список API ключей | JWT |\n| DELETE | `/api/keys/{id}` | Отзыв API ключа | JWT |\n| GET | `/api/files` | Список файлов пользователя | JWT/API Key |\n| POST | `/api/files/upload` | Загрузка файла | JWT/API Key |\n| GET | `/api/files/{id}` | Скачивание файла | JWT/API Key |\n| POST | `/api/files/share` | Создать публичную ссылку | JWT/API Key |\n| GET | `/api/files/share/{token}` | Скачать по публичной ссылке | Нет |\n| POST | `/api/sessions/{id}/block` | Блокировка сессии | JWT/API Key |\n| GET | `/metrics` | Метрики для Prometheus | internal |\n| GET | `/health` | Health check | Нет |\n\n### Коды ошибок\n\n| Код | Описание |\n|-----|----------|\n| 200 | Успешный запрос |\n| 201 | Ресурс создан |\n| 400 | Неверный запрос |\n| 401 | Неавторизован / неверные учётные данные |\n| 403 | Доступ запрещён |\n| 404 | Ресурс не найден |\n| 409 | Конфликт (email уже занят / домен уже используется) |\n| 413 | Файл слишком большой (превышает 5GB) |\n| 415 | Неподдерживаемый тип файла |\n| 429 | Слишком много запросов (превышен rate limit) |\n| 500 | Внутренняя ошибка сервера |\n\n### Возможности пользователя\n\n1. **Регистрация и вход**\n   - Регистрация по email с паролем (мин. 8 символов)\n   - Двухфакторная аутентификация (TOTP) — обязательна\n   - Вход через OAuth (Google, GitHub, Keycloak)\n\n2. **Управление сайтами**\n   - Создание сайта (указать domain и origin-server)\n   - Активация/блокировка сайта\n   - Настройка порогов риска и действий (allow/captcha/block)\n   - Просмотр активных и подозрительных сессий\n\n3. **Управление API ключами**\n   - Создание API ключей для автоматизации\n   - Настройка срока действия (дни)\n   - Отзыв ключей\n\n4. **Файлы**\n   - Загрузка файлов (до 5GB)\n   - Создание публичных ссылок с ограничением по времени\n   - Скачивание по прямой ссылке (без авторизации)\n\n5. **Профиль**\n   - Смена пароля\n   - Обновление аватара (через URL или загрузку изображения)\n\n## Алгоритм настройки и запуска\n\n### Структура директорий\n\n    HumanGuard/\n    ├── backend/                 # Go бэкенд\n    │   ├── cmd/server/         # Точка входа\n    │   ├── auth/               # Аутентификация\n    │   ├── handlers/           # HTTP обработчики\n    │   ├── storage/            # PostgreSQL и MinIO\n    │   ├── detector/           # Детектор аномалий\n    │   ├── reaction/           # Реакции на риск\n    │   ├── metrics/            # Prometheus метрики\n    │   ├── middleware/         # CSP, RateLimit, RequestID\n    │   ├── migrations/         # SQL миграции\n    │   └── Dockerfile\n    ├── frontend/               # React фронтенд\n    │   ├── src/\n    │   ├── nginx.conf\n    │   └── Dockerfile\n    ├── infra/                  # Инфраструктура\n    │   ├── nginx/\n    │   ├── docker-compose.yml\n    │   ├── docker-compose.release.yml\n    │   ├── .env.example\n    │   └── setup-scripts/\n    ├── docs/                   # Документация\n    ├── .github/workflows/      # CI/CD пайплайны\n    └── README.md\n\n### Быстрый старт для разработки\n\n#### 1. Запуск базы данных\n\n    docker run -d \\\n      --name humanguard-db \\\n      -e POSTGRES_DB=humanguard \\\n      -e POSTGRES_USER=postgres \\\n      -e POSTGRES_PASSWORD=123 \\\n      -p 5432:5432 \\\n      postgres:15\n\n#### 2. Применение миграций\n\n    cd backend\n    docker cp migrations/001_init_up.sql humanguard-db:/tmp/init.sql\n    docker exec -i humanguard-db psql -U postgres -d humanguard \u003c migrations/001_init_up.sql\n\n#### 3. Запуск MinIO (опционально)\n\n    docker run -d \\\n      --name minio \\\n      -p 9000:9000 \\\n      -p 9001:9001 \\\n      -e \"MINIO_ROOT_USER=minioadmin\" \\\n      -e \"MINIO_ROOT_PASSWORD=minioadmin123\" \\\n      minio/minio server /data --console-address \":9001\"\n\n#### 4. Запуск бэкенда\n\n    cd backend\n    go run cmd/server/main.go\n\nСервер доступен на `http://localhost:8080`\n\n#### 5. Запуск фронтенда\n\n    cd frontend\n    npm install\n    npm run dev\n\nФронтенд доступен на `http://localhost:5173`\n\n### Алгоритм запуска ПО для отладки с помощью docker compose\n\u003e Для отладки проекта без разворачивания nginx с TLS\n\n#### 1. Настроить .env файлы для отладки в `/frontend/.env` и в `/infra/.env`\n\n`/frontend/.env`:\n```\nVITE_API_URL=http://localhost:8080\n```\n\n#### 2. Поднять сервис в docker compose\n\n```bash\ncd infra\ndocker compose up --build --remove-orphans\n```\n\n#### 3. Проверка\n\nБэкенд доступен на `http://localhost:8080`\n\nФронтенд доступен на `http://localhost:80`\n\n\n### Руководство по настройке и запуску дистрибутива ПО\n\u003e Документ: `docs/DEPLOY`.\n\n    # Health check\n    curl http://localhost:8080/health\n\n    # Prometheus метрики\n    curl http://localhost:8080/metrics\n\n### Production установка на Ubuntu 24.04\n\n#### Требования к системе\n\n- **ОС:** Ubuntu 24.04\n- **Утилиты:** wget, tar, vi, docker, docker compose\n\n#### Шаги установки\n\n**1. Скачать релизный архив**\n\n    wget https://github.com/laserattack/HumanGuard/releases/download/{tag}/humanguard-{tag}.tar.gz\n    tar -xf humanguard-{tag}.tar.gz\n    cd humanguard-{tag}\n\n**2. Настроить переменные окружения**\n\n    vi .env\n\nПример `.env`:\n\n    POSTGRES_USER=postgres\n    POSTGRES_PASSWORD=secure_password\n    POSTGRES_DB=humanguard\n    APP_DOMAIN=example.com\n    JWT_SECRET=your-super-secret-key-32-chars-minimum\n    STORAGE_TYPE=local\n\n**3. Получить SSL сертификат Let's Encrypt**\n\n    docker compose --profile certbot-init run --rm --service-ports certbot certonly --standalone -d example.com -m admin@example.com --agree-tos --no-eff-email\n\n**4. Запустить сервис**\n\n    docker compose up -d --remove-orphans\n\nСервис доступен на `https://ваш-домен`\n\n**5. Остановить сервис**\n\n    docker compose down\n\n### Переменные окружения\n\n| Имя | Описание | Значение по умолчанию |\n|-----|----------|----------------------|\n| `POSTGRES_USER` | Пользователь БД | postgres |\n| `POSTGRES_PASSWORD` | Пароль БД | change-me |\n| `POSTGRES_DB` | Название БД | humanguard |\n| `APP_DOMAIN` | Домен приложения | example.com |\n| `JWT_SECRET` | Секрет JWT (32+ символов) | super-secret-key |\n| `STORAGE_TYPE` | Тип хранилища (local/minio) | local |\n| `MINIO_ENDPOINT` | Адрес MinIO | localhost:9000 |\n| `GOOGLE_CLIENT_ID` | OAuth Client ID Google | (пусто) |\n| `GITHUB_CLIENT_ID` | OAuth Client ID GitHub | (пусто) |\n\n### CI/CD пайплайн\n\n#### GitHub Secrets для CI\n\n| Secret | Описание |\n|--------|----------|\n| `SONAR_TOKEN` | Токен для SonarQube |\n\n#### Secrets для деплоя\n\n| Secret | Описание |\n|--------|----------|\n| `DEPLOY_HOST` | IP адрес сервера |\n| `DEPLOY_USER` | Пользователь SSH |\n| `SSH_PRIVATE_KEY` | Приватный SSH ключ |\n| `SSH_PORT` | Порт SSH |\n| `POSTGRES_USER` | Пользователь БД |\n| `POSTGRES_PASSWORD` | Пароль БД |\n| `POSTGRES_DB` | Название БД |\n| `LETSENCRYPT_EMAIL` | Email для SSL сертификата |\n\n## Требования к аппаратному обеспечению\n\n| Компонент | Минимальные | Рекомендуемые |\n|-----------|-------------|---------------|\n| CPU | 2 ядра | 4 ядра |\n| RAM | 2 GB | 4 GB |\n| Диск | 10 GB | 30 GB SSD |\n\n## Описание безопасности системы\n\n### Аутентификация и авторизация\n\n| Механизм | Реализация |\n|----------|------------|\n| **JWT токены** | HMAC-SHA256 подпись, срок жизни 24 часа, содержит user_id, role, session_id |\n| **2FA (TOTP)** | Обязательна для всех пользователей, 6-значный код, обновляется каждые 30 секунд |\n| **OAuth 2.0** | Поддержка Google, GitHub, Keycloak. Автоматическое создание пользователя |\n| **API ключи** | Формат `hg_v1_{32 байта hex}`, хешируются в БД (SHA-256) |\n| **Роли** | `user` — базовый доступ, `admin` — полный доступ |\n\n### Защита интерфейсов\n\n| Мера | Реализация |\n|------|------------|\n| **CSP** | Заголовок Content-Security-Policy с ограничением скриптов, стилей |\n| **CORS** | Ограниченный список доверенных доменов |\n| **Rate Limiting** | login: 5/мин, check: 100/мин, behavior: 300/мин. Возврат 429 |\n| **Request ID** | UUIDv7 в каждом запросе, заголовок X-Request-ID |\n| **CSRF** | Токены в формах (в разработке) |\n\n### Защита данных\n\n| Данные | Защита |\n|--------|--------|\n| **Пароли** | Хеширование bcrypt (cost 10) |\n| **API ключи** | Хеширование SHA-256, ключ отдаётся только один раз |\n| **JWT секрет** | Переменная окружения JWT_SECRET |\n| **TOTP секрет** | Хранится в БД, отдаётся только при создании (QR код) |\n| **Файлы** | Доступ через JWT или API ключ. Публичные ссылки с expiration |\n| **Соединение с БД** | SSL/TLS (опционально) |\n\n### Мониторинг безопасности\n\n| Инструмент | Назначение |\n|------------|------------|\n| **Prometheus** | Сбор метрик: количество запросов, активные сессии, риск-скоры |\n| **Grafana** | Визуализация: CPU/RAM, RPS, rate limit ошибки |\n| **Node Exporter** | Метрики сервера |\n| **Semgrep (CI)** | SAST статический анализ кода |\n| **SonarQube (CI)** | Анализ качества кода и уязвимостей |\n| **Trivy (CI)** | Сканирование Docker образов |\n\n### Журналирование\n\nКаждый HTTP запрос логируется в формате JSON:\n\n    {\n      \"request_id\": \"019e2752-21c8-7457-bcec-be1665692a65\",\n      \"method\": \"POST\",\n      \"path\": \"/api/check\",\n      \"duration\": \"1.2ms\",\n      \"auth_method\": \"api_key\",\n      \"remote_addr\": \"192.168.1.100\"\n    }\n\n### Безопасность сессий\n\n- **User Session** — для аутентифицированных пользователей. TTL 24 часа\n- **Visitor Session** — для посетителей защищаемых сайтов. TTL 30 минут\n- **Защита от подделки** — сессия привязана к site_id\n\n### Обеспечение безопасности среды эксплуатации\n\nСкрипты настройки сервера (`infra/setup-scripts/`):\n\n| Скрипт | Назначение |\n|--------|------------|\n| `startup-1_install-git-docker.sh` | Установка Git, Docker, Docker Compose |\n| `startup-2_setup-ssh-ufw.sh` | Настройка SSH, UFW, fail2ban, политика паролей |\n\n#### Требования к серверу (hardening)\n\n- Запрещён вход под root по SSH (используется пользователь `deploy`)\n- Настроена политика сложных паролей (minlen=12, цифры, спецсимволы)\n- Включена защита от перебора паролей (fail2ban)\n- Настроено подключение по SSH-ключам\n- Порт SSH перенесён на нестандартный (2222)\n- Настроен UFW (разрешены только 80, 443, SSH порт)\n- Приложение запускается в Docker от непривилегированного пользователя\n- Readonly файловая система для контейнеров\n- Nginx reverse-proxy с TLS (Let's Encrypt)\n- HSTS заголовок (`Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`)\n\n## Документация\n\n- [Техническое задание](docs/1_SRS.md)\n- [Описание системы](docs/2_SYSTEM_SPECS.md)\n- [Руководство пользователя](docs/3_USER_SPECS.md)\n- [Руководство по развёртыванию](docs/4_DEPLOY.md)\n- [Описание мер безопасности](docs/5_SECURITY.md)\n- [API документация](docs/api/README.md)\n- [OpenAPI спецификация](docs/api/swagger.yaml)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaserattack%2Fhumanguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaserattack%2Fhumanguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaserattack%2Fhumanguard/lists"}