title: Безопасность description: Встроенные механизмы безопасности starlette-admin: защита от CSRF, безопасность загрузки файлов и контроль доступа.

Безопасность

starlette-admin включает встроенные меры защиты от рисков, связанных с эксплуатацией панели администрирования. Защита от межсайтовой подделки запросов (CSRF) и ограничения на размер экспортируемых и импортируемых данных активируются сразу после создания экземпляра класса Admin.

Эти настройки по умолчанию защищают интерфейс от распространённых атак, но не заменяют стандартную защиту инфраструктуры развёртывания. Ответственность за безопасность транспортного уровня (HTTPS/TLS), сетевой контроль доступа, аутентификацию пользователей (см. Аутентификацию), обновление зависимостей и аудит безопасности остаётся на вас. На этой странице описаны автоматические защиты, параметры, которые вы настраиваете сами, а также параметр secret_key, который обязательно нужно задать в рабочем окружении.

Что включено по умолчанию

from sqlalchemy import create_engine
from starlette.applications import Starlette
from starlette_admin.contrib.sqla import Admin

engine = create_engine("sqlite:///admin.sqlite")
app = Starlette()
admin = Admin(engine, title="My Admin")
admin.mount_to(app)

Даже без каких-либо параметров безопасности экземпляр панели защищает от нескольких распространённых уязвимостей:

• Защита от CSRF: активна для каждой формы и каждого jQuery AJAX-запроса, включая действия со строками и диалоги подтверждения.
• Flash-сообщения: передаются в подписанной cookie, поэтому SessionMiddleware не требуется.
• Санитизация имён файлов: применяется к каждому файлу, загружаемому через storage backend.
• Проверка содержимого изображений: загрузки в ImageField проверяются на уровне байтов с помощью Pillow, если он установлен.
• Ограничения экспорта: не более 100 000 строк за один запрос — это предотвращает исчерпание ресурсов и отказ в обслуживании.
• Ограничения импорта: не более 10 МБ за один запрос — это ограничивает риск переполнения памяти.

Ещё одна защита доступна, но отключена по умолчанию: экранирование, которое предотвращает инъекцию формул в CSV- и табличные экспорты (XLSX, XLS, ODS). Подробнее см. Инъекция формул.

В разделах ниже описаны эти защиты и способы настройки пороговых значений, которые находятся под вашим контролем.

Секретный ключ

admin = Admin(engine, title="My Admin", secret_key="a-long-random-string")

secret_key — это криптографическая основа для подписания двух cookie: CSRF-токена и cookie flash-сообщений. Обе используют библиотеку itsdangerous, поэтому клиент может прочитать содержимое cookie, но не может подделать или изменить его без ключа.

Защита от CSRF

CSRFMiddleware использует схему подписанного double-submit cookie для предотвращения межсайтовой подделки запросов. Он устанавливает cookie starlette_admin_csrftoken для безопасных HTTP-методов (GET, HEAD, OPTIONS и TRACE). Для изменяющих запросов он сверяет эту cookie либо с заголовком X-CSRFToken, либо со скрытым полем формы csrftoken.

Каждый встроенный шаблон панели (create, edit и login) выводит скрытое поле автоматически:

{{ csrf_input(request) }}

Поставляемый JavaScript также добавляет заголовок к каждому jQuery AJAX-запросу, поэтому действия со строками и другие асинхронные взаимодействия защищены без дополнительного кода. Вызывайте csrf_input(request) самостоятельно только при создании форм вне стандартных шаблонов. См. Custom Views.

Загрузка файлов

Каждая загрузка, проходящая через storage backend, проходит санитизацию функцией secure_filename. Компоненты пути, используемые для обхода каталогов, удаляются, а символы вне диапазона [A-Za-z0-9_.-] заменяются подчёркиваниями (_). Отключить это поведение невозможно.

Ограничения по типу содержимого и размеру задаются для каждого поля с помощью параметров accept и max_size:

from starlette_admin.fields import FileField


class DocumentView:
    invoice = FileField(accept=".pdf,.docx", max_size=5 * 1024 * 1024)  # лимит 5 МБ

Без них FileField принимает файлы любого типа и размера. Исключение составляет ImageField: по умолчанию он использует значение accept="image/*", а при установленном Pillow добавляет валидатор, который открывает загрузку через PIL.Image, чтобы убедиться, что байты действительно декодируются как изображение, вместо доверия метаданным, переданным браузером.

import filetype
from starlette.datastructures import UploadFile
from starlette.requests import Request
from starlette_admin.fields import BaseField

ALLOWED_DOCUMENT_MIME_TYPES = {
    "application/pdf",
    "application/msword",
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
}

def validate_document_type(
    request: Request, field: BaseField, upload: UploadFile, form_values: dict
) -> None:
    upload.file.seek(0)
    try:
        header = upload.file.read(2048)
        kind = filetype.guess(header)
        detected = kind.mime if kind else "application/octet-stream"
    finally:
        upload.file.seek(0)

    if detected not in ALLOWED_DOCUMENT_MIME_TYPES:
        raise ValueError(
            f"Invalid file type '{detected}'. Only PDF, DOC, and DOCX are allowed."
        )

Ограничения экспорта

from starlette_admin.export import ExportConfig

admin = Admin(engine, title="My Admin", export_config=ExportConfig(max_rows=50_000))

О том, как формируется ZIP-архив, см. в разделе Export & Import.

Инъекция формул

Табличные редакторы интерпретируют значение ячейки, начинающееся с символа =, +, - или @, как формулу. Если недоверенный пользователь сохранит в экспортируемое поле payload вида =HYPERLINK(...), табличное приложение выполнит его при открытии файла администратором. Эта атака известна как CSV injection, или инъекция формул.

Поскольку экспортируемые значения записываются в точности так, как они хранятся в базе данных, экранирование формул по умолчанию отключено. CSV-экспортёр и экспортёры Tablib (xlsx, xls и ods) принимают параметр escape_formulas. Когда он включён, к любой строке, начинающейся с триггерного символа, добавляется одинарная кавычка в начале ('), что заставляет приложение отображать значение как обычный текст.

Чтобы включить экранирование, замените строковый формат на явный экземпляр экспортёра:

from starlette_admin.contrib.sqla import ModelView
from starlette_admin.export import CsvExporter, TablibExporter


class ProductView(ModelView):
    exporters = [
        CsvExporter(escape_formulas=True),
        TablibExporter("xlsx", escape_formulas=True),
        "json",
    ]

Ограничения импорта

from starlette_admin.importers import ImportConfig

admin = Admin(
    engine,
    title="My Admin",
    import_config=ImportConfig(
        max_upload_size=5 * 1024 * 1024,
        max_rows=50_000,
    ),
)

Импорт полностью отклоняет ZIP-архивы, что исключает риск атак «ZIP-бомбой» на этот endpoint. Поля FileField и ImageField также исключены из массового импорта, так как для них по умолчанию задано exclude_from_import=True: файлы прикрепляются по одному через формы create или edit.

Чего эта страница не охватывает

Встроенные защиты закрывают риски внутри кодовой базы панели. Они не обеспечивают безопасность вашей архитектуры в целом. Следующие организационные меры выходят за рамки starlette-admin и остаются на вашей стороне:

• Безопасность транспорта: обслуживайте панель по HTTPS. Cookie CSRF и flash-сообщений подписываются, но не шифруются, поэтому любой, кто перехватит трафик plain HTTP, сможет их прочитать.
• Аутентификация и авторизация: экземпляр Admin общедоступен, пока вы не подключите AuthProvider. Без него открыты все endpoint'ы и маршруты. См. Аутентификацию.
• Сетевая доступность: если панели не требуется публичный доступ, разместите её за firewall, VPN или IP allowlist.
• Актуальность зависимостей: следите за бюллетенями безопасности и своевременно обновляйте starlette-admin, Starlette, драйвер вашей ORM и остальные зависимости.
• Действия после аутентификации: защита от CSRF и проверка загрузок не ограничивают возможности вошедшего пользователя. Гранулярный контроль доступа целиком определяется проверками прав, которые вы пишете в is_accessible, can_create, can_edit и can_delete. См. Аутентификацию.

Рассматривайте эту страницу как руководство по настройке пакета, а не как чек-лист по защите всего рабочего окружения.

Что дальше

• Export & Import: диалог экспорта, жизненный цикл предпросмотра импорта и структура ZIP-архива.
• File Storage: шаблоны настройки storage backend'ов для FileField и ImageField.
• Authentication: как secret_key управляет сессиями входа и проверками CSRF после подключения auth-провайдера.