errors.md

Отчет об уязвимостях и ошибках проекта

Этот документ содержит перечень найденных уязвимостей, ошибок, неточностей и рекомендации по их устранению для проекта extract-text.

1. Безопасность (Security)

Критичность	Файл	Описание	Рекомендация
Высокая	app/main.py	Неограниченный CORS (allow_origins=["*"]) — Разрешение запросов со всех источников (*) создает риски атак типа Cross-Site Request Forgery (CSRF).	✅ ИСПРАВЛЕНО v1.11.0: добавлена переменная ALLOWED_ORIGINS (default * для совместимости). При wildcard allow_credentials=False по требованию спецификации CORS. В prod рекомендуется указать конкретные домены через запятую.
Высокая	app/extractors.py	Отсутствие проверки SSL-сертификатов при запросах (requests без verify=True) — При извлечении данных по URL не проверяется SSL-сертификат, что может привести к атакам "человек посередине" (MITM).	✅ ИСПРАВЛЕНО v1.11.0: во все вызовы requests.get/head и session.get/head добавлен явный verify=True.
Средняя	app/extractors.py	Извлечение текста из JavaScript (playwright) — Использование playwright для рендеринга JS на стороне сервера может привести к DoS-атакам через ресурсоемкие скрипты на веб-страницах.	✅ ИСПРАВЛЕНО: Добавлены дополнительные таймауты (page.set_default_navigation_timeout), JavaScript отключен по умолчанию (ENABLE_JAVASCRIPT=false), время выполнения ограничено до 15 секунд максимум.
Средняя	Dockerfile	Запуск pip install под root — Установка зависимостей с правами суперпользователя может быть небезопасной. Вредоносный пакет может получить полный контроль над системой.	✅ ЧАСТИЧНО ИСПРАВЛЕНО: Создан непривилегированный пользователь appuser для запуска приложения. Установка зависимостей от root принята как стандартная практика Docker для упрощения совместимости с системными зависимостями (tesseract, libreoffice, playwright).
Средняя	app/config.py	Использование os.getenv с небезопасными значениями по умолчанию — Некоторые переменные окружения, например BLOCKED_IP_RANGES, имеют значения по умолчанию, которые могут быть изменены.	Используйте более строгие и безопасные значения по умолчанию для критичных параметров. Например, для BLOCKED_IP_RANGES стоит убедиться, что список полон.
Низкая	docker-compose.yml	Использование .env файла в разработке — В docker-compose.yml используется .env файл, что может привести к случайной утечке секретов, если .env попадет в репозиторий.	Добавьте .env в .gitignore и используйте env_example как шаблон.

2. Надежность и производительность (Reliability & Performance)

Критичность	Файл	Описание	Рекомендация
Высокая	app/main.py	Блокирующие операции в асинхронном коде — Функции извлечения текста (text_extractor.extract_text) являются CPU-bound и блокируют основной поток FastAPI, что снижает производительность.	✅ ИСПРАВЛЕНО: Все CPU-bound операции (extract_text, extract_from_url) выполняются через run_in_threadpool, добавлен graceful shutdown для ThreadPoolExecutor в lifespan менеджере.
Высокая	requirements.txt	Не зафиксированы версии всех зависимостей — Некоторые зависимости могут иметь неявные под-зависимости, версии которых не зафиксированы. Это может привести к нестабильной сборке.	Используйте pip-tools для компиляции requirements.in в requirements.txt, что позволит зафиксировать все дерево зависимостей.
Средняя	app/extractors.py	Отсутствие graceful shutdown для ThreadPoolExecutor — Пул потоков не закрывается корректно при завершении работы приложения, что может привести к потере данных или "зависшим" процессам.	✅ ИСПРАВЛЕНО: Добавлен graceful shutdown для ThreadPoolExecutor в lifespan менеджере FastAPI с вызовом executor.shutdown(wait=True).
Средняя	app/utils.py	Очистка временных файлов по времени — cleanup_temp_files удаляет файлы старше 1 часа, но не гарантирует удаление всех временных файлов, созданных текущим процессом, что может привести к утечке дискового пространства.	Реализуйте более надежный механизм очистки. Например, создавайте временные файлы в уникальной для каждого запроса директории и удаляйте эту директорию после завершения обработки.
Низкая	docker-compose.prod.yml	Неправильное количество workers для uvicorn — В docker-compose.prod.yml жестко задано 9 воркеров. Оптимальное количество зависит от числа ядер CPU.	✅ ИСПРАВЛЕНО: Добавлена переменная окружения CPU_CORES и реализован автоматический расчет воркеров по формуле (2 * CPU_CORES) + 1 в docker-compose.prod.yml. По умолчанию используется 4 ядра (9 воркеров).

3. Конфигурация и сборка (Configuration & Build)

Критичность	Файл	Описание	Рекомендация
Высокая	Dockerfile	Установка playwright браузеров от root — Запуск playwright install-deps chromium от root, а playwright install chromium от appuser может вызвать проблемы с правами доступа.	✅ ИСПРАВЛЕНО: Упрощена архитектура установки - все зависимости Python и Playwright устанавливаются от root (стандартная практика Docker), приложение запускается от непривилегированного пользователя appuser для безопасности.
Средняя	Makefile	Команда make test устанавливает зависимости локально — Это нарушает принцип изоляции. Тесты должны выполняться в контролируемом окружении, чтобы избежать расхождений.	Измените make test так, чтобы тесты всегда запускались внутри Docker-контейнера. Это обеспечит консистентность окружения.
Средняя	Dockerfile	Большой размер итогового образа Docker — Установка libreoffice, tesseract-ocr-* и других зависимостей в одном слое увеличивает размер образа.	Используйте многоступенчатые сборки (multi-stage builds). На первом этапе компилируйте зависимости, а на втором — копируйте только необходимые артефакты в чистый образ.
Низкая	run_tests.sh	Использование jq без проверки установки — Скрипт может завершиться с ошибкой, если jq не установлен.	Добавьте проверку наличия jq и выводите понятное сообщение, если утилита отсутствует.
Средняя	Makefile	Отсутствующая цель stop — В prod-up вызывается несуществующая цель stop, что приводит к ошибке развертывания.	✅ ИСПРАВЛЕНО: Добавлена цель stop как алиас для down, обновлены PHONY директивы и справка.

4. Качество кода и поддержка (Code Quality & Maintainability)

Критичность	Файл	Описание	Рекомендация
Средняя	app/extractors.py	"Магические" числа и строки — В коде встречаются жестко заданные значения, например, таймауты, пути или ключи. Это усложняет конфигурацию и поддержку.	Вынесите все "магические" значения в app/config.py как именованные константы.
Низкая	app/main.py	Дублирование логики обработки ошибок — Код обработки ошибок в эндпоинтах /v1/extract/file и /v1/extract/base64 практически идентичен.	Создайте общую функцию-декоратор или зависимость (Depends) для обработки исключений и формирования стандартного ответа об ошибке.
Низкая	app/utils.py	Слишком сложная функция validate_file_type — Функция содержит большой словарь MIME-типов и сложную логику, что затрудняет ее чтение и расширение.	Рефакторите функцию: вынесите словарь extension_to_mime в app/config.py. Разбейте логику на более мелкие, хорошо документированные функции.
Низкая	Makefile	Отсутствие цели для очистки кэша — __pycache__, .pytest_cache и другие кэши не всегда удаляются, что может приводить к неожиданному поведению.	Добавьте в make clean команду для рекурсивного удаления всех __pycache__ и других кэш-директорий.
Низкая	requirements.txt	Тестовые зависимости в requirements.txt — pytest и другие тестовые пакеты находятся в общем файле зависимостей.	Разделите зависимости на requirements.txt (для продакшена) и requirements-test.txt (для разработки и тестирования).

Общие рекомендации

1. Документация: Расширьте README.md, добавив более подробное описание всех эндпоинтов, переменных окружения и команд Makefile.
2. CI/CD: Настройте CI/CD пайплайн (например, с помощью GitHub Actions), который будет автоматически запускать линтеры и тесты при каждом коммите.
3. Мониторинг: Интегрируйте систему мониторинга (например, Prometheus + Grafana) для отслеживания состояния приложения в продакшене: RPS, время ответа, использование CPU/памяти.

---

Отчет сгенерирован автоматически. Требуется ручная проверка и приоритизация задач.