# 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
```