152-fz-scanner/README.md

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

🚀 Быстрый старт

# Установка
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