🏗 Фаза 1-4: Архитектура, ядро, проверки, API, генератор отчетов

- scanner/engine.py — Playwright-движок сканирования - scanner/models.py — Pydantic модели - scanner/checks/ — 5 проверок (cookie, privacy, forms, server, external) - api/server.py — FastAPI REST API - reports/generator.py — PDF через WeasyPrint + Jinja2 - main.py — CLI + сервер Проверки: ✅ cookie_banner — поиск cookie-баннера ✅ privacy_link — проверка ссылки на политику ✅ form_checkbox — проверка чекбоксов согласия ✅ server_location — геолокация сервера (RФ или нет) ✅ external_scripts — внешние скрипты аналитики
2026-06-09 21:10:21 +05:00
commit de18090304
@@ -0,0 +1,133 @@
+# 152-ФЗ Scanner — Compliance Audit Tool
+
+Автоматизированный веб-сканер для аудита сайтов на соответствие 152-ФЗ (О персональных данных).
+Генерирует PDF-отчеты с рекомендациями для коммерческой продажи услуг по доработке.
+
+## 🏗 Архитектура
+
+```
+152-fz-scanner/
+├── main.py                  # Точка входа (CLI / FastAPI)
+├── scanner/                 # Ядро сканирования
+│   ├── engine.py            # Playwright-движок (управление браузером)
+│   ├── checks/              # Модули проверок
+│   │   ├── base.py          # Базовый класс для всех проверок
+│   │   ├── cookie_banner.py # Проверка баннера cookie
+│   │   ├── privacy_link.py  # Проверка ссылки на политику
+│   │   ├── privacy_page.py  # Проверка содержимого страницы политики
+│   │   ├── form_checkbox.py # Проверка чекбокса согласия в формах
+│   │   ├── server_location.py # Проверка геолокации IP (через API)
+│   │   └── external_scripts.py # Проверка внешних скриптов (Google, FB, etc.)
+│   └── models.py            # Pydantic модели (ScanResult, CheckResult, SiteReport)
+├── api/                     # REST API (FastAPI)
+│   ├── server.py            # Основной файл сервера
+│   ├── routes.py            # Эндпоинты
+│   └── schemas.py           # Pydantic схемы для JSON
+├── reports/                 # Генерация отчетов
+│   ├── generator.py         # Логика генерации PDF
+│   ├── templates/           # HTML-шаблоны отчетов
+│   │   └── report.html.j2
+│   └── static/              # Статика (CSS, логотипы)
+│       └── styles.css
+├── data/                    # Входные/выходные данные
+│   ├── input/               # CSV с URL сайтов для сканирования
+│   └── output/              # JSON-результаты и PDF-отчеты
+│       ├── results.json
+│       └── reports/
+│           └── audit_*.pdf
+├── requirements.txt         # Зависимости
+├── .gitignore
+└── README.md
+```
+
+## 🛠 Стек технологий
+
+| Компонент | Технология | Назначение |
+|-----------|-----------|-----------|
+| Движок браузера | `playwright` | Рендеринг JS, эмуляция пользователя, анти-бот (stealth) |
+| HTTP-клиент | `curl_cffi` | Быстрые проверки (HTTPS, redirect, IP-геолокация) |
+| Web-фреймворк | `fastapi` + `uvicorn` | REST API для запуска сканирования и получения отчетов |
+| ORM/Модели | `pydantic` | Валидация данных, JSON-схемы |
+| PDF-генерация | `weasyprint` | Конвертация HTML-шаблона в PDF-отчет |
+| Шаблоны | `jinja2` | HTML-генерация отчета |
+| CSV/Парсинг | `pandas` | Чтение входных CSV (список сайтов) |
+
+## 📋 План разработки
+
+### Фаза 1: Ядро (День 1-2)
+- [ ] Настройка окружения (venv, requirements.txt)
+- [ ] Написание базовой модели `ScanResult` (Pydantic)
+- [ ] Реализация `scanner/engine.py` (Playwright + stealth)
+- [ ] Реализация первой проверки: `cookie_banner.py`
+- [ ] CLI-утилита: `python main.py --url https://example.com --check cookie`
+- [ ] Тест: сканирование 10 сайтов, вывод CSV
+
+### Фаза 2: Расширение проверок (День 3-4)
+- [ ] `privacy_link.py` — поиск ссылки в footer/header
+- [ ] `privacy_page.py` — парсинг содержимого страницы политики
+- [ ] `form_checkbox.py` — проверка всех форм на чекбоксы согласия
+- [ ] `server_location.py` — проверка IP через MaxMind DB или API
+- [ ] `external_scripts.py` — поиск Google Analytics, FB Pixel и т.д.
+- [ ] Интеграция: сканирование сайта по всем 5 проверкам
+- [ ] Генерация JSON-результата
+
+### Фаза 3: Генератор отчетов (День 5)
+- [ ] HTML-шаблон отчета (Jinja2 + CSS)
+- [ ] `reports/generator.py` — конвертация JSON в PDF (WeasyPrint)
+- [ ] Настройка стилей (брендинг, цвета, таблица рисков)
+- [ ] Тест: генерация PDF-отчета для одного сайта
+- [ ] Тест: генерация 10 PDF-отчетов в batch-режиме
+
+### Фаза 4: API Сервер (День 6)
+- [ ] `main.py` — FastAPI сервер (uvicorn)
+- [ ] Эндпоинт `POST /api/scan` — запуск сканирования
+- [ ] Эндпоинт `GET /api/report/{scan_id}` — скачивание PDF
+- [ ] Эндпоинт `GET /api/results` — список всех сканирований
+- [ ] Эндпоинт `POST /api/scan/csv` — загрузка CSV с URL + авто-сканирование
+- [ ] Документация (Swagger UI доступен по умолчанию)
+
+### Фаза 5: Интеграция и доработка (День 7)
+- [ ] Проверка работы в headless-режиме на сервере
+- [ ] Настройка логирования
+- [ ] Добавление rate-limiting и timeout (чтобы не висели сайты)
+- [ ] Тестирование на реальном списке 50-100 сайтов Уфы
+- [ ] Документация в репозитории
+
+## 🔑 Ключевые решения
+
+1. **Playwright вместо requests**: Необходим для рендеринга JS (cookie-баннеры появляются динамически).
+2. **Stealth-режим**: Обязательно для обхода простых анти-бот-защит (Cloudflare, Akamai).
+3. **Отдельные модули проверок**: Каждая проверка — отдельный класс, наследующий `BaseCheck`. Легко добавлять новые.
+4. **Async-first**: Playwright работает асинхронно, что ускоряет пакетное сканирование в 5-10 раз.
+5. **PDF через HTML/CSS**: Проще стилизовать, чем генерировать PDF программно (weasyprint).
+
+## 📦 Зависимости
+
+```
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+playwright>=1.40.0
+curl_cffi>=0.6.0
+pydantic>=2.5.0
+weasyprint>=60.0
+jinja2>=3.1.2
+pandas>=2.1.0
+maxminddb>=2.3.0
+```
+
+## 🚀 Быстрый старт
+
+```bash
+# Установка
+pip install -r requirements.txt
+playwright install chromium
+
+# Запуск API-сервера
+uvicorn main:app --host 0.0.0.0 --port 8000
+
+# Тестирование (CLI)
+python main.py --url https://example.com
+
+# Сканирование CSV
+python main.py --csv data/input/sites.csv
+```