Metadata-Version: 2.4
Name: file-security
Version: 0.3.2
Summary: Проверка загружаемых файлов до постоянного хранилища: политика, разбор содержимого и ClamAV.
Author: Leonid Kushkin
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/lennyk1279/file_security
Project-URL: Repository, https://gitlab.com/lennyk1279/file_security
Project-URL: Changelog, https://gitlab.com/lennyk1279/file_security/-/blob/main/CHANGELOG.md
Project-URL: Issues, https://gitlab.com/lennyk1279/file_security/-/issues
Keywords: clamav,malware,upload,security,office,pdf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.13.5
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: olefile<1,>=0.47
Provides-Extra: dev
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: hypothesis>=6.130; extra == "dev"
Requires-Dist: mypy<2,>=1.15.0; extra == "dev"
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-asyncio<2,>=1.0.0; extra == "dev"
Requires-Dist: types-olefile>=0.47; extra == "dev"
Provides-Extra: yara
Requires-Dist: yara-python<5,>=4.5.4; extra == "yara"
Dynamic: license-file

# file_security

`file_security` проверяет загружаемые файлы до постоянного хранилища.

Приложение передаёт загруженный файл библиотеке до публикации в постоянное хранилище. Библиотека записывает его во временный карантин и выполняет проверки. По умолчанию приложение публикует только результаты со статусом `clean`. Результат `stale` можно опубликовать отдельно, если включён `allow_stale_database=True` и приложение явно вызывает `save_to()` или `asave_to()`. `is_clean` при этом ложен. Решение принимает приложение.

```text
загрузка в приложении
        │
        ▼
временный карантин
        │
        ▼
проверки формата, структуры и содержимого
        │
        ├─ корневой файл не прошёл цепочку до ClamAV
        │             ──► библиотека пытается удалить копию, демон для этого файла не вызывается
        ▼
ClamAV
        │
        ├─ clean ──► приложение вызывает save_to() или asave_to()
        │             метод публикует файл и удаляет копию из карантина
        ├─ stale ──► копия остаётся. Публикация — явный save_to() или asave_to(),
        │             если включён allow_stale_database=True. is_clean при этом ложно
        └─ infected, error, timeout
                      ► файл не публикуют, библиотека пытается удалить копию
```

Схема показывает путь исходного файла: на ней он назван корневым. Ветка до ClamAV — любой результат не `clean` по этому файлу: отказ политики, разбор формата или совпадение YARA. Демон для этого файла тогда не вызывается. Элемент архива и часть письма, которые уже прочитаны целиком, проверяются отдельно, внутри разбора контейнера: совпадение YARA на таком элементе демон этого элемента не отменяет.

Если проверка самого файла завершилась отказом, библиотека не передаёт этот файл в ClamAV. Элемент архива или часть письма, которые удалось прочитать целиком, при разборе этого архива или письма всё равно передаются в ClamAV и, если он включён, в YARA. Если включена YARA, она выполняется сразу перед ClamAV: срабатывание правила на самом файле отменяет проверку этого файла в ClamAV, срабатывание на элементе архива проверку этого элемента в ClamAV не отменяет. Статус `infected` не значит, что каждый обязательный сканер успел закончиться: если сканер не ответил, запись об этом остаётся в `diagnostics` с именем сканера и путём внутри файла.

Если файл прошёл проверки, библиотека возвращает результат со статусом `clean` и оставляет его копию в карантине. Приложение выбирает путь в постоянном хранилище и вызывает `result.save_to(destination)` или, в асинхронном коде, `await result.asave_to(destination)`. Метод публикует файл и после успешной записи сам удаляет копию из карантина.

При статусах `infected`, `rejected`, `error` и `timeout` библиотека пытается удалить копию до возврата результата. Приложение получает статус и машинный код и файл не публикует. Если удаление копии результата с одним из этих статусов не удалось, исходный статус не меняется и не становится `clean` или `stale`, в `cleanup_error_code` записывается `quarantine_discard_failed`, а копия остаётся до уборщика. При статусе `stale` копия остаётся в карантине и может быть опубликована явным вызовом `save_to()` или `asave_to()`, если включён `allow_stale_database=True`. Решение о публикации такого файла принимает приложение. `is_clean` при этом ложен. У возвращённого `clean` и у `stale` кода `cleanup_error_code` нет: их копию библиотека при возврате из `scan` не удаляет.

Библиотека не выбирает постоянное хранилище и не пишет тексты для пользователя. Каталог проверок — в разделе [«Что проверяется по умолчанию»](#что-проверяется-по-умолчанию).

`file_security` не гарантирует абсолютную безопасность файла и не заменяет полноценную систему защиты. Для пользователя корректно использовать формулировку:

> Файл прошёл доступные проверки.

В этом документе карантин — временный каталог библиотеки. Постоянное хранилище выбирает приложение. Публикация — успешное копирование файла из карантина в постоянное хранилище методами `save_to()` и `asave_to()`. Копия в карантине — временный файл до этой операции. Запись в карантин публикацией не считается.

`secure_ingest` этим методом не пользуется. У него нет `save_to`: вызывающий сам копирует байты из дескриптора и затем вызывает `discard()`. Ниже описан короткий вызов. Контракт `secure_ingest` — в [ADVANCED.md](ADVANCED.md), и одно другим не заменяется.

## Содержание

- [Быстрый старт](#быстрый-старт)
- [Установка](#установка)
  - [Python-пакет](#python-пакет)
  - [ClamAV на Debian](#clamav-на-debian)
  - [Подготовка каталогов](#подготовка-каталогов)
  - [Проверка установки](#проверка-установки)
- [Интеграция](#интеграция)
  - [FastAPI](#fastapi)
  - [Django](#django)
- [Результат проверки](#результат-проверки)
  - [Статусы](#статусы)
  - [Как обработать результат](#как-обработать-результат)
  - [FileCheckResult](#filecheckresult)
  - [Коды результатов](#коды-результатов)
- [Сохранение чистого файла](#сохранение-чистого-файла)
  - [Жизненный цикл временных файлов](#жизненный-цикл-временных-файлов)
- [Жизненный цикл и конкурентное использование](#жизненный-цикл-и-конкурентное-использование)
- [Что проверяется по умолчанию](#что-проверяется-по-умолчанию)
- [Настройка](#настройка)
  - [Пределы размера и срока](#пределы-размера-и-срока)
  - [Часовой пояс даты базы](#часовой-пояс-даты-базы)
  - [Разрешённые типы](#разрешённые-типы)
  - [Правило расширений](#правило-расширений)
  - [Синонимы типов](#синонимы-типов)
- [Перед включением на сервере](#перед-включением-на-сервере)
- [Ограничения](#ограничения)
- [Разработка пакета](#разработка-пакета)
- [Расширенный API](#расширенный-api)

Обычное внедрение — это [быстрый старт](#быстрый-старт), [установка](#установка), [интеграция](#интеграция), [статусы](#статусы) и список [перед включением на сервере](#перед-включением-на-сервере). Коды, аргументы конструктора, сбои `save_to()`, уборщик и конкурентные вызовы — справочник. Его открывают, когда появился конкретный случай.

## Быстрый старт

Для скрипта хватает одного `with`: он открывает объект и закрывает его в конце. Сервер держит один `FileSecurity` на процесс; так устроены примеры [FastAPI](#fastapi) и [Django](#django). На каждый файл — одна проверка. По умолчанию публикуют только при `result.is_clean`. Если приложение включило `allow_stale_database=True`, результат со статусом `stale` публикуют отдельным решением через `save_to()` или `asave_to()`. `is_clean` при этом ложен.

```python
from pathlib import Path

from file_security import FileSecurity

quarantine = Path("/var/lib/file-security/quarantine")
destination = Path("/srv/uploads/document.pdf")

with FileSecurity(quarantine_dir=quarantine) as security:
    with open("document.pdf", "rb") as source:
        result = security.scan_sync(
            source,
            filename="document.pdf",
            content_type="application/pdf",
        )
    if result.is_clean:
        result.save_to(destination)
```

В `async def` те же шаги выглядят как `async with`, `await security.scan(...)` и `await result.asave_to(...)`. Пример выше — обычный путь.

- По умолчанию публикуют только при `result.is_clean`. Результат со статусом `stale` публикуют только если приложение само включило `allow_stale_database=True` и отдельно решило вызвать `save_to()` или `asave_to()`. `is_clean` при этом ложен.
- Путь назначения задаёт приложение. Имя загруженного файла в этот путь не подставляют.
- `save_to()` после успешной публикации сам удаляет копию из карантина.
- Результат нужно опубликовать или явно закрыть через `discard()` до закрытия `FileSecurity`. Выход из `with` вызывает `close()`. После `close()` несохранённая копия уже удалена, и вызов `save_to()` завершается исключением `UsageError`.
- Если вызов `save_to()` завершился исключением внутри `with`, выход из блока всё равно закроет объект и удалит ещё не опубликованную копию. Повторить публикацию можно, только пока объект открыт. В примерах FastAPI и Django исключение в обработчике объект не закрывает: копия остаётся до `save_to()`, `discard()` или `close()` процесса.

Установка пакета:

```bash
python -m pip install file-security
```

Нужны Python 3.13.5 или новее, Linux или другая POSIX-система и локальный демон ClamAV. Каталоги, сокет и `doctor` — в разделе [«Установка»](#установка). Настройка пути к сокету, ограничений и режима `temporary=True` описана в разделе [«Настройка»](#настройка).

Статусы — в [результате проверки](#результат-проверки). Если `save_to()` не смог опубликовать файл — в [сохранении чистого файла](#сохранение-чистого-файла).

## Установка

### Python-пакет

Нужен Python 3.13.5 или новее.

Поддерживаются Linux/POSIX-системы. Windows не поддерживается: библиотека использует модуль `fcntl` и рассчитана на Unix-сокет ClamAV.

Имя пакета в индексе — `file-security`, импорт в коде — `file_security`. Установка из индекса:

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install file-security
```

Приложению достаточно `from file_security import FileSecurity`. Установка из клона, тесты и внутренние модули — в разделе [«Разработка пакета»](#разработка-пакета).

### ClamAV на Debian

Отдельный Python-клиент ClamAV не нужен. Демон ставится отдельно, сокет только локальный, TCP к `clamd` нет.

```bash
sudo apt update
sudo apt install clamav clamav-daemon
sudo systemctl enable --now clamav-daemon
```

Сокет обычно лежит здесь:

```bash
ls -l /run/clamav/clamd.ctl
```

Процесс приложения не запускают от root ради доступа к сокету. Пользователя приложения пускают к сокету через группу. Сокет, в который может писать любой пользователь системы (бит записи для остальных, например `0666` или `0777`), библиотека считает ошибкой настройки и не стартует. Если путь — символическая ссылка, права проверяются у сокета, на который она указывает. Путь, который ведёт не на сокет, тоже ошибка старта.

### Подготовка каталогов

Каталог карантина создаёт администратор, не библиотека. Для сервера это отдельный каталог вне корня сайта, режим `0700`, владелец — пользователь процесса:

```bash
sudo install -d -m 0700 -o api /var/lib/file-security/quarantine
sudo install -d -m 0750 -o api -g api /srv/uploads
```

Каталог постоянного хранения библиотека не создаёт и права на него не выставляет. Его готовит администратор. В примерах ниже это `/srv/uploads`.

### Проверка установки

Проверить, какая копия импортируется:

```bash
python -c "import file_security; print(file_security.__file__)"
```

Проверка окружения той же учётной записью, под которой работает процесс:

```bash
python -m file_security doctor \
  --quarantine /var/lib/file-security/quarantine \
  --socket /run/clamav/clamd.ctl
```

`doctor` не проверяет пользовательские файлы. Он смотрит каталог (режим, владелец, создание и удаление пробного файла со случайным именем), права сокета, ответ `PING`, список команд, дату базы и короткий `INSTREAM`. Демон опрашивается только если путь существует, это сокет и он не открыт на запись всем пользователям. Запуск от root даёт одну критическую запись. Предупреждение о старой базе называет порог `warning_after` (по умолчанию 3 суток). Код выхода: `0` — критических ошибок нет, `2` — есть критическая ошибка, `1` — передан `--strict` и есть предупреждение.

Тот же процесс перед включением на сервере сверяют со списком [«Перед включением на сервере»](#перед-включением-на-сервере).

## Интеграция

Отдельного адаптера под Django или FastAPI в пакете нет. Хранилище приложения, поле модели и идентификатор записи остаются у приложения.

В обоих примерах один `FileSecurity` живёт столько же, сколько процесс, который принимает загрузки: у FastAPI его открывают в lifespan, у Django — `start()` и `close()` вокруг цикла сервера. В примерах публикуют только при `result.is_clean`: это обычный путь. Результат `stale` эти примеры не публикуют. После успеха копию из карантина удаляет `save_to()` или `asave_to()`. При `infected`, `rejected`, `error` и `timeout` проверка пытается удалить копию. Если удалить не удалось, копия остаётся до уборщика. При `stale` копия остаётся, пока её не опубликуют, не закроют через `discard()` или не остановится `FileSecurity`. Список разрешённых типов, максимальный размер файла и параметр `reject_macros` настраиваются одинаково для разных веб-фреймворков. Они описаны в [настройке](#настройка).

### FastAPI

Объект создают в lifespan, не внутри запроса. Чтение загрузки — асинхронное: синхронный `file.file` в обработчике блокирует цикл.

```python
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from pathlib import Path

from fastapi import FastAPI, File, Request, UploadFile
from fastapi.responses import JSONResponse
from file_security import FileSecurity, ScanStatus

quarantine = Path("/var/lib/file-security/quarantine")


@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.file_security = FileSecurity(quarantine_dir=quarantine)
    await app.state.file_security.astart()
    yield
    await app.state.file_security.aclose()


app = FastAPI(lifespan=lifespan)


@app.post("/attachments")
async def upload(request: Request, file: UploadFile = File(...)):
    security = request.app.state.file_security

    async def chunks() -> AsyncIterator[bytes]:
        while True:
            block = await file.read(1024 * 1024)
            if not block:
                break
            yield block

    result = None
    try:
        result = await security.scan(
            chunks(),
            filename=file.filename or "upload.bin",
            content_type=file.content_type,
        )
    finally:
        await file.close()
    if result is None:
        raise RuntimeError("проверка не вернула результат")
    if result.is_clean:
        destination = Path("/srv/uploads") / f"{result.sha256}.bin"
        await result.asave_to(destination)
        return {"ok": True, "sha256": result.sha256}
    if result.status is ScanStatus.INFECTED:
        return JSONResponse(
            status_code=422,
            content={
                "ok": False,
                "code": result.error_code,
                "message": "Файл заблокирован антивирусной проверкой",
            },
        )
    status_code = 503 if result.status in {ScanStatus.ERROR, ScanStatus.TIMEOUT} else 422
    return JSONResponse(
        status_code=status_code,
        content={"ok": False, "code": result.error_code},
    )
```

Фраза в ветке `infected` — текст приложения. Имя сигнатуры в ответ клиенту не кладут. `UploadFile` в примере закрывается после проверки. Если объектом владеет сам FastAPI и закроет его сам, повторное `close()` должно быть безопасным для этой версии FastAPI; при сомнении закрытие оставляют владельцу объекта.

Объект лежит в `app.state`, а не в переменной модуля. Так он принадлежит одному приложению, и в тесте его можно подменить. Конструктор по-прежнему ничего не открывает: создать его можно и при импорте, открытие остаётся в lifespan.

Код HTTP выбирает приложение. Библиотека его не назначает. Недоступный демон, таймаут и занятый слот — сбой проверки. Отказ политики и найденная угроза — отказ файла. В примере выше первые дают 503, вторые — 422.

Имя из запроса в путь не подставляют: в нём могут быть `..` и разделители каталогов. В примере имя на диске — контрольная сумма. Каталог `/srv/uploads` к этому моменту уже существует: библиотека его не создаёт. `asave_to` не читает и не пишет файл в цикле событий, копирование идёт в отдельном потоке. Если метод поднял `QuarantineCleanupError`, байты уже лежат по пути назначения: клиенту не отвечают так, будто публикации не было. Остальные исключения публикации файл ещё не записывают; объект в lifespan при этом не закрывается.

### Django

Тот же объект на процесс. `scan_sync` принимает уже открытый файл загрузки.

```python
from pathlib import Path

from django.http import JsonResponse
from file_security import FileSecurity, ScanStatus

quarantine = Path("/var/lib/file-security/quarantine")
security = FileSecurity(quarantine_dir=quarantine)
```

`serve()` ниже — схема жизненного цикла, а не готовая функция для проекта Django. Место вызова `start()` и `close()` зависит от сервера и способа запуска процесса.

```python
def serve(run_server) -> None:
    """Старт и остановка того процесса, который принимает загрузки.

    run_server — цикл сервера приложения, не функция библиотеки.
    """
    security.start()
    try:
        run_server()
    finally:
        security.close()


def upload_view(request):
    uploaded = request.FILES["file"]
    result = security.scan_sync(
        uploaded.file,
        filename=uploaded.name,
        content_type=getattr(uploaded, "content_type", None),
    )
    if not result.is_clean:
        status = 503 if result.status in {ScanStatus.ERROR, ScanStatus.TIMEOUT} else 422
        return JsonResponse({"ok": False, "code": result.error_code}, status=status)
    destination = Path("/srv/uploads") / f"{result.sha256}.bin"
    result.save_to(destination)
    return JsonResponse({"ok": True, "sha256": result.sha256})
```

`QuarantineCleanupError` из `save_to()` значит, что файл уже лежит по пути назначения. Другое исключение публикации его ещё не записало, и объект при этом не закрывается. `start()` вызывают в жизненном цикле процесса, который принимает загрузки, и там же вызывают `close()`. `serve()` в примере — схема этого цикла, а не готовый хук Gunicorn, Uvicorn, Daphne или другой системы запуска. Куда повесить старт и остановку, решает сервер и способ выкладки. `upload_view` в этом примере упрощён: угроза, отказ политики и сбой проверки сведены к коду ответа. Разделение этих веток показано в примере FastAPI. `AppConfig.ready()` для этого плохой общий пример: его запускают команды управления, миграции, процесс автоперезагрузки и каждый рабочий процесс, иногда больше одного раза. Через `ready()` можно стартовать только если приложение само ограничивает список команд и ему не мешает повторный вызов. Временный путь Django в сканер не передают: `scan_sync` сам пишет поток в карантин библиотеки.

## Результат проверки

`scan` и `scan_sync` возвращают `FileCheckResult`. Отказ по результатам проверки, обнаруженная угроза, таймаут и ошибка проверки представлены в полях результата. Исключения предназначены для ошибок вызова и использования API.

### Статусы


| Статус     | Когда                                          | Что делать                                                                                          |
| ---------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `clean`    | проверки пройдены                              | публиковать через `save_to()` или `asave_to()`                                                      |
| `stale`    | ClamAV не обнаружил угрозу, но база сигнатур старше заданного срока | публиковать можно; `is_clean` при этом ложно                                 |
| `infected` | демон нашёл угрозу                             | не публиковать                                                                                      |
| `rejected` | политика или разбор содержимого отклонили файл | не публиковать                                                                                      |
| `error`    | проверку не удалось закончить                  | не публиковать; это не доказательство заражения                                                    |
| `timeout`  | вышел общий срок проверки                      | не публиковать; это не доказательство заражения                                                    |


### Можно ли публиковать


| Статус     | Публикация                                                                                          |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `clean`    | да, через `save_to()` или `asave_to()`                                                              |
| `stale`    | только при `allow_stale_database=True` и только явным `save_to()` или `asave_to()`                  |
| `infected` | нет                                                                                                 |
| `rejected` | нет                                                                                                 |
| `error`    | нет                                                                                                 |
| `timeout`  | нет                                                                                                 |


`is_clean` истинно только при `clean`. Угроза не считается отказом политики: у неё свой статус `infected`. Статус `stale` бывает только при `allow_stale_database=True`: ClamAV не обнаружил угрозу, но база сигнатур старше `max_signature_age`, копия в карантине остаётся и `save_to()` её принимает. При статусах `infected`, `rejected`, `error` и `timeout` библиотека пытается удалить копию до возврата результата. При `stale` копия остаётся до `save_to()`, `discard()` или `close()`. Если удаление копии результата со статусом `infected`, `rejected`, `error` или `timeout` не удалось, исходный статус не меняется и не становится `clean` или `stale`, в `cleanup_error_code` записывается `quarantine_discard_failed`, а копия остаётся до уборщика. У возвращённого `clean` и у `stale` этого кода нет.

### Как обработать результат

```python
if result.is_clean:
    result.save_to(destination)
elif result.status is ScanStatus.INFECTED:
    log_security_event(result)
elif result.status is ScanStatus.REJECTED:
    return validation_error(result.error_code)
else:
    return temporary_service_error(result.error_code)
```

`log_security_event`, `validation_error` и `temporary_service_error` — функции приложения. Библиотека их не предоставляет. В журнал администратора можно передать `signature_name`. В текст для обычного пользователя его не кладут.

Поле `signature_name` заполняется только при статусе `infected`. Его место — журнал администратора. Путь карантина в результате не появляется.

Исключение бывает, когда сломан сам вызов: нет каталога, неверные аргументы, подмена временного файла, сохранение после `discard()` или `close()`, путь назначения уже занят, второй одновременный `save_to`. Отмена задачи не записывается как чистый результат: после уборки она снова выходит как `CancelledError`. Сбой публикации, занятый путь и ручной `discard()` — в [сохранении чистого файла](#сохранение-чистого-файла).

### FileCheckResult

```python
result.status
result.error_code
result.scanner_name
result.signature_name
result.executed_scanners
result.sha256
result.size_bytes
result.is_clean
result.cleanup_error_code
```

Сам тип:

```python
@dataclass(frozen=True)
class FileCheckResult:
    status: ScanStatus
    error_code: str | None
    scanner_name: str | None
    signature_name: str | None
    executed_scanners: tuple[str, ...]
    filename: str | None
    declared_mime: str | None
    detected_mime: str | None
    sha256: str | None
    size_bytes: int
    cleanup_error_code: str | None
    staged_file: StagedFile | None
    operation_id: str
    verdict: ScanResult
    findings: tuple[Finding, ...] = ()
    diagnostics: tuple[ScanDiagnostic, ...] = ()

    @property
    def is_clean(self) -> bool: ...
```

Поля после создания не меняются. `save_to`, `asave_to`, `discard` и `adiscard` меняют временный файл, не эти поля. `findings` — обнаруженные признаки содержимого: активное содержимое, макросы, имя антивирусной сигнатуры, совпадение с правилом YARA, опасный путь внутри архива. `diagnostics` — сведения о сбое, таймауте, отказе или устаревшей базе. Допустимые статусы такой записи: `error`, `timeout`, `rejected` и `stale`. Запись с итоговым `error_code` тоже входит в этот список, если статус один из этих четырёх. Статусов `clean` и `infected` у диагностики нет. Ни находки, ни диагностика сами по себе не меняют `is_clean` и не меняют решение `save_to()`. Пустой кортеж означает, что таких записей нет. `staged_file` есть только при `clean` и при `stale`. `sha256` пустой, если проверка отказала до подсчёта суммы: слишком большой файл, оборванный поток, отказ до записи. `filename`, `declared_mime` и `detected_mime` повторяют то, что было известно приёму, и тоже могут быть пустыми. Поле `signature_name` заполняется только при статусе `infected`. `scanner_name` пустой у чистого итога.


| Условие                                           | `staged_file`   | `sha256`                                                |
| ------------------------------------------------- | --------------- | ------------------------------------------------------- |
| `clean`                                           | всегда заполнен | всегда заполнен                                         |
| `infected`                                        | `None`          | обычно заполнен, если поток успели дописать и посчитать |
| `rejected` до записи потока                       | `None`          | может быть `None`                                       |
| `error` при обрыве потока                         | `None`          | может быть `None`                                       |
| `timeout` после того, как приём потока закончился | `None`          | заполнен                                                |


При `clean`, который вернул `scan`, одновременно `error_code is None`, `cleanup_error_code is None` и `staged_file is not None`: копия должна остаться для `save_to()`. При `stale` код равен `stale_signature_database`, `staged_file` тоже заполнен, а `cleanup_error_code` пуст. Поле `cleanup_error_code` заполняется, только если не удалось удалить копию результата, который публиковать уже нельзя. Если `staged_file is None`, сохранять файл нельзя. Неудача удаления копии уже после успешной публикации — это исключение `QuarantineCleanupError`, а не это поле.

`signature_name` предназначено для журнала администратора. Приложение формирует сообщение для пользователя на основе полей `status` и `error_code`. Имя сигнатуры в этот текст не входит.

`ScanResult` — вердикт расширенного вызова. У него нет файла и нет `save_to`. Повторять его вторым типом с теми же полями незачем: `FileCheckResult` несёт те же статус и код и, при `clean` или `stale`, временный файл.

`ScanResult.is_clean` истинно при статусе `clean`. `FileCheckResult.is_clean` истинно при статусе `clean`, пустом `error_code` и копии в карантине. Для `stale` оба признака ложны.

`save_to()` разрешён для двух результатов, и только пока копия ещё на месте:

- статус `clean` и `error_code` равен `None`;
- статус `stale` и `error_code` равен `stale_signature_database`.

В обоих случаях нужен `staged_file`. Экземпляр `FileSecurity` должен быть открыт. Результат ещё не опубликован, не закрыт через `close()` и не отброшен через `discard()`.

Находки и диагностика в `is_clean` не входят. Макрос при `reject_macros=False` оставляет `is_clean` истинным, и `save_to()` при этом разрешён.

### Коды результатов


| Код                         | Статус                    | Смысл для приложения                                                                                                                                                                                                                                                      |
| --------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `empty_file`                | `rejected`                | в файле нет байтов                                                                                                                                                                                                                                                        |
| `too_large`                 | `rejected`                | размер файла превышает `max_file_bytes`                                                                                                                                                                                                                                   |
| `invalid_filename`          | `rejected`                | пустое имя, путь, управляющий символ, имя длиннее 255                                                                                                                                                                                                                     |
| `dangerous_content`         | `rejected`                | опасное расширение по [правилу расширений](#правило-расширений) или заголовок ELF/PE                                                                                                                                                                                      |
| `mime_mismatch`             | `rejected`                | тип не совпал с началом файла или нет обязательной подписи                                                                                                                                                                                                                |
| `encrypted_zip`             | `rejected`                | ZIP с битом шифрования                                                                                                                                                                                                                                                    |
| `archive_limit`             | `rejected`                | разбор архива ZIP, GZIP или TAR превысил установленные ограничения: больше 10 000 элементов, один объект больше 16 МиБ, сумма прочитанных байт больше 64 МиБ или глубина больше пяти. Считается и размер из оглавления, и то, что уже прочитано                         |
| `archive_path`              | `rejected`                | имя элемента архива после удаления управляющих знаков пустое, абсолютное, с буквой диска или содержит `..`. Ссылка, устройство и канал не открываются                                                                                                                    |
| `archive_invalid`           | `rejected`                | ZIP, GZIP или TAR повреждены, либо тип элемента TAR библиотека не разбирает                                                                                                                                                                                               |
| `office_invalid`            | `rejected`                | содержимое не того вида Office, который заявлен, или пакет повреждён                                                                                                                                                                                                      |
| `external_target`           | `rejected`                | документ сам загружает что-то снаружи, ссылка ведёт на файл или сетевой ресурс, или путь внутри пакета выходит за его корень                                                                                                                                              |
| `encrypted_document`        | `rejected`                | документ или PDF зашифрован                                                                                                                                                                                                                                               |
| `active_content`            | `rejected`                | в PDF есть активное действие; в HTML или SVG есть script, обработчик события или схема `javascript:` в ссылке, которую можно исполнить; в документе Office есть ActiveX — только при `reject_macros=True`. Обычная ссылка и внешняя картинка не этот код |
| `macros_present`            | `rejected`                | только при `reject_macros=True`: в документе есть макрос, лист макросов или скрипт ODF. По умолчанию такой документ не отклоняется                                                                                                                                        |
| `nested_object`             | `rejected`                | только при `reject_embedded_objects=True`: в документе есть распознанный вставленный документ Office. По умолчанию такой объект не отклоняется и проверяется дальше                                                                                                       |
| `unverifiable_embedded_object` | `rejected`             | внутри документа вставлен произвольный или неизвестный файл: поток `Ole10Native`, поток `Package` не с документом Office, неизвестный OLE, обычный ZIP или другой файл                                                                                                    |
| `pdf_attachment`            | `rejected`                | к PDF приложен другой файл (`/EmbeddedFile`, `/EmbeddedFiles`). Пока без различения формата                                                                                                                                                                               |
| `metadata_oversize`         | `rejected`                | служебные блоки картинки больше установленного ограничения                                                                                                                                                                                                                |
| `content_limit`             | `rejected`                | файл слишком большой или слишком сложный, чтобы разобрать его в пределах установленных ограничений: PDF или картинка больше предела разбора, сжатые объекты PDF больше ограничения распаковки или сжаты способом, распаковку которого библиотека не поддерживает, служебный файл связей Office больше предела, у письма больше 1024 частей, больше 256 заголовков одной части, больше 1 МиБ заголовков, имя заголовка длиннее 256 символов или значение длиннее 8 КиБ |
| `content_invalid`           | `rejected`                | формат узнан, но безопасно не разбирается: сломанный SVG, DOCTYPE в SVG, кодировка HTML или SVG вне поддерживаемого списка, HTML без кодировки с байтами, которые не являются годным UTF-8, у письма потеряна граница MIME, сломана base64 или кодировка части вне списка, у MSG имя похоже на вложение, но хранилища Outlook нет. Это не неизвестный файл и не `clean` |
| `yara_match`                | `rejected`                | сработало правило YARA. Это не `infected`: заражение по-прежнему только ответ ClamAV |
| `malware_detected`          | `infected`                | демон нашёл сигнатуру, имя в `signature_name` и в находке `malware_signature`                                                                                                                                                                                                                             |
| `scanner_unavailable`       | `error`                   | демон не ответил                                                                                                                                                                                                                                                          |
| `scanner_busy`              | `error`                   | до истечения установленного срока не удалось получить свободный слот для проверки в демоне или в сканере содержимого                                                                                                                                                       |
| `scanner_limit`             | `error`                   | демон отверг поток по своему пределу длины                                                                                                                                                                                                                                |
| `scanner_unexpected_reply`  | `error`                   | библиотека не смогла распознать ответ демона                                                                                                                                                                                                                              |
| `scanner_timeout`           | `timeout`                 | вышел общий срок                                                                                                                                                                                                                                                          |
| `yara_timeout`              | `timeout`                 | включённая YARA не уложилась в свой срок. Это не «совпадений нет» |
| `yara_failed`               | `error`                   | YARA сломалась во время проверки. Это не «совпадений нет» |
| `scanner_shutting_down`     | `error`                   | приём уже начался, когда объект останавливался. Новый вызов `FileSecurity.scan` этот код не возвращает: до `start()` и после `close()` это `UsageError`. Код остаётся у расширенного приёма                                                                               |
| `stale_signature_database`  | `error` или `stale`       | база старше `max_signature_age`. Что делать дальше, задаёт `allow_stale_database`, см. [свежесть базы](#свежесть-базы)                                                                                                                                                     |
| `scanner_failed`            | `error`                   | сканер закончился исключением                                                                                                                                                                                                                                             |
| `scanner_invalid_result`    | `error`                   | дата базы без пояса, из будущего или ответ демона неверен                                                                                                                                                                                                                 |
| `required_scanner_missing`  | `error`                   | обязательный сканер так и не начал работу                                                                                                                                                                                                                                 |
| `no_scanner_ran`            | `error`                   | ни один сканер не начал работу                                                                                                                                                                                                                                            |
| `input_stream_failed`       | `error`                   | поток оборвался                                                                                                                                                                                                                                                           |
| `quarantine_full`           | `error`                   | каталог не вмещает ещё один приём                                                                                                                                                                                                                                         |
| `quarantine_discard_failed` | поле `cleanup_error_code` | проверку закончили, а временный файл удалить не удалось                                                                                                                                                                                                                   |


`mime_mismatch` не означает, что демон нашёл угрозу. До демона в этом случае дело не доходит.

`content_limit` — отказ файла, а не сбой проверки: тот же файл при повторе получит тот же ответ. Библиотека не пропускает файл, который не смогла разобрать до конца, и не отдаёт его демону как будто разбор прошёл.

Коды — строковое перечисление `ErrorCode` (`StrEnum`). Значение сравнивается и с членом перечисления, и с обычной строкой: `result.error_code == ErrorCode.MIME_MISMATCH` и `result.error_code == "mime_mismatch"` дают одно и то же.

`required_scanner_missing`, `no_scanner_ran` и `scanner_invalid_result` короткий вызов тоже может вернуть, пока объект запущен. Новые вызовы после `close()` вместо них получают `UsageError`. `scanner_shutting_down` в `required_scanner_missing` не превращается.

Различие трёх кодов:

- обязательного сканера нет в цепочке или он не начал работу, хотя остальные дошли до конца, — `required_scanner_missing`;
- цепочка пустая или все сканеры только пропустили файл — `no_scanner_ran`;
- сканер был вызван и вернул негодный ответ: дата базы без пояса, дата из будущего, библиотека не смогла распознать ответ демона, вердикт сканера не проходит проверку — `scanner_invalid_result`.

Публичный код при этом остаётся одним. В журнал сбоев пишется более узкая причина: `invalid_signature_date`, `future_signature_date`, `malformed_daemon_reply` или `invalid_scanner_verdict`. Эти четыре строки не являются кодами результата `scan`.


| Код                        | `FileSecurity.scan`     | Расширенный приём          |
| -------------------------- | ----------------------- | -------------------------- |
| `required_scanner_missing` | да, пока объект запущен | да                         |
| `no_scanner_ran`           | да, пока объект запущен | да                         |
| `scanner_invalid_result`   | да, пока объект запущен | да                         |
| `scanner_failed`           | да                      | да                         |
| `scanner_shutting_down`    | нет для нового вызова   | да, если приём уже начался |


Библиотека пытается удалить копию результата, который публиковать уже нельзя, до возврата из `scan`. Если это не удалось, исходные `status` и `error_code` остаются. Рядом появляется `cleanup_error_code` = `quarantine_discard_failed`, а копия остаётся до уборщика. Неудачное удаление не делает файл чистым и не отменяет уже случившийся отказ.

## Сохранение чистого файла

- `clean` — файл можно публиковать. `save_to()` и `asave_to()` копируют его в постоянное хранилище и после успешной публикации сами удаляют копию из карантина.
- `stale` — ClamAV не обнаружил угрозу, но база сигнатур старше срока. Публиковать можно тем же `save_to()`, но `is_clean` ложно: приложение само решает, брать ли такой файл.
- Любой другой статус — файл не публикуют. Библиотека пытается удалить копию до возврата из `scan`. Если удалить не удалось, исходный статус не меняется и не становится `clean` или `stale`: рядом `cleanup_error_code` = `quarantine_discard_failed`, копия остаётся до уборщика.
- Исключение из `save_to()` — сбой публикации, а не новый статус проверки. Ниже разобрано, осталась ли копия в карантине и опубликован ли уже путь назначения.

### save_to и asave_to

Для обычного приложения достаточно пути:

```python
saved_path = result.save_to(Path("/srv/uploads/document.pdf"))
saved_path = await result.asave_to(Path("/srv/uploads/document.pdf"))
```

Оба метода при успехе возвращают нормализованный `Path` назначения, тот же файл, который только что опубликован. `None` они не возвращают.

```python
def save_to(self, destination: Path, *, overwrite: bool = False) -> Path: ...

async def asave_to(self, destination: Path, *, overwrite: bool = False) -> Path: ...
```

Аргумент `destination` — только `Path`, не `str`. `overwrite` только по имени. Объект файла, клиент объектного хранилища и хранилище Django сюда не передают. Если место назначения не локальный путь, приложение читает байты из `result.staged_file.open_for_copy()` и после копирования само вызывает `result.discard()`. `save_to()` тогда не вызывают, поэтому копию из карантина удаляет `discard()`. Это по-прежнему `FileCheckResult` короткого вызова. `secure_ingest` возвращает `IngestResult` и метода `save_to` не имеет: там копирование из дескриптора и `discard()` — единственный способ забрать чистый файл, см. [ADVANCED.md](ADVANCED.md).

### Путь назначения и overwrite

Путь назначения — путь к новому обычному файлу.

- Родительский каталог уже существует. Библиотека каталоги назначения не создаёт. Нет каталога или нет прав на запись — `UsageError`, файл в карантине остаётся.
- Конечный компонент не является каталогом и не является символической ссылкой. Ссылка в предках пути допустима, ссылка на месте самого файла — нет. Проверка «путь не внутри карантина» считается по разрешённому реальному пути, не по текстовому префиксу. Иначе ссылка вида «каталог загрузок указывает внутрь карантина» обошла бы запрет. Родитель открывается как каталог, и временный файл создаётся относительно этого открытого каталога, а не повторным склеиванием строки пути.
- Разрешённый путь не лежит внутри каталога карантина. Иначе `UsageError`.
- Режим создаваемого файла — `0600`. Права постоянного дерева задаёт администратор, не библиотека.

Пока `overwrite` не передан, занятый путь не перезаписывается. Если по нему уже есть файл, вызов завершается исключением `DestinationExistsError` и ничего не пишет. Существующий файл не изменяется. Копия остаётся в карантине, вызов можно повторить с другим путём.

```python
try:
    result.save_to(destination)
except DestinationExistsError:
    result.save_to(other_path)
```

Копия остаётся в карантине. Если публиковать её больше не нужно, вместо второго `save_to()` вызывают `discard()`.

`overwrite=True` — явная замена обычного файла. Её нет в поведении по умолчанию. Старый файл заменяется атомарно, только когда новая копия уже записана и сверена. Ошибка копирования старый файл не меняет. Резервную копию библиотека не делает. Права старого файла не сохраняются: новый файл создаётся с режимом `0600`. Другие жёсткие ссылки на прежний inode, если они были, продолжают указывать на старое содержимое: заменяется только запись каталога по этому пути. Это не то же самое, что переписать файл по месту: содержимое inode, на который указывают другие жёсткие ссылки, не меняется. Каталог и символическая ссылка на месте конечного компонента не заменяются ни при каком значении `overwrite`.

Шаги записи:

1. Метод разрешён для результата со статусом `clean` и пустым `error_code`, а также для результата со статусом `stale` и кодом `stale_signature_database`. У результата должен быть `staged_file`, а экземпляр `FileSecurity` должен быть открыт. Ранее опубликованный, закрытый или уже отброшенный результат этот вызов не принимает.
2. Проверяет путь по правилам выше.
3. Создаёт временный файл со случайным именем и префиксом `.file-security-save-` в том же каталоге, что и путь назначения.
4. Копирует байты, затем сверяет размер и SHA-256.
5. Публикует копию на путь назначения атомарным переименованием, которое не затирает уже существующий файл. Если другой процесс создал файл по этому пути после проверки, но до публикации, временный файл удаляется и вызов завершается исключением `DestinationExistsError`. При `overwrite=True` переименование заменяет уже существующий обычный файл и только его.
6. После успешного переименования удаляет файл из карантина. Если удалить его не удалось, уже опубликованный путь не откатывается. Метод не возвращает обычный успех и сам сохранение не повторяет. Вызов завершается исключением `QuarantineCleanupError` (наследник `FileSecurityError`) с кодом `quarantine_discard_failed` и с путём назначения, который уже записан. Оставшийся файл карантина удалит уборщик после времени жизни. Повторный `save_to` по тому же пути без `overwrite=True` получит `DestinationExistsError`, потому что файл назначения уже есть.

### Ошибки сохранения

По исключению видно, опубликован ли файл.


| Что произошло | Файл опубликован | Что делать |
| --- | --- | --- |
| метод вернул `Path` | да | карантин уже удалён |
| `QuarantineCleanupError` | да | не откатывать путь из `exception.destination`; повторный `save_to()` нельзя; `discard()` повторяет попытку удалить файл из карантина |
| `DestinationExistsError` | нет | другой путь тем же результатом или `discard()` |
| другая ошибка до публикации, включая `DestinationCleanupError` | нет | повторить `save_to()` или `discard()`; оставшийся временный файл `.file-security-save-*` должен удалить администратор каталога |


Состояние после `QuarantineCleanupError`, одним списком:

```python
class QuarantineCleanupError(FileSecurityError):
    destination: Path
    published: bool = True
    code: str = "quarantine_discard_failed"
```

- `published` истинно: файл назначения уже существует и считается опубликованным;
- библиотека этот файл не откатывает;
- повторный `save_to` и `asave_to` этого результата запрещены, в том числе с `overwrite=True`: публикация уже была, повтор не заменяет неудачное удаление карантина;
- `result.discard()` разрешён и ещё раз пытается удалить файл карантина;
- повторный `discard()` безопасен;
- если `discard()` снова не удалил файл, вызов снова завершается тем же исключением;
- `close()` для такого результата один раз повторяет удаление файла карантина и путь назначения не откатывает; если и эта попытка не удалась, файл остаётся внешнему уборщику после времени жизни;
- после `close()` повторный `discard()` уже ничего не делает;
- уборщик после времени жизни остаётся запасным путём;
- `staged_file` остаётся привязан к результату, чтобы `discard()` мог повторить удаление. Для нового `save_to` результат уже использован.

Любое исключение на шагах 3–5 удаляет временный файл назначения. Путь назначения при этом не считается опубликованным, копия остаётся в карантине. Если удалить временный файл не удалось, вызов завершается исключением `DestinationCleanupError` с кодом `destination_cleanup_failed`. Исходная ошибка копирования к ней привязана. Временный файл с префиксом `.file-security-save-` может остаться в каталоге назначения. Команда уборки карантина эти файлы не трогает: она ходит только по каталогу карантина. Узнать такой файл можно по префиксу. Пока идёт сохранение, файл с этим префиксом живой, и чужой обход каталога не должен удалять его только из-за имени. После аварии процесса библиотека каталоги приложения не сканирует: оставшийся временный файл должен удалить администратор этого каталога. Если процесс убит во время копирования, временный файл назначения может остаться: библиотека уже не работает и убрать его не может. Копия в карантине тогда дожидается уборщика, как и при любом аварийном завершении.

После ошибки на шагах 3–5 приложение может повторить `save_to` по другому пути или по тому же, если он так и не был занят, либо вызвать `discard()`. Если не сделать ни того ни другого, файл карантина удалит уборщик после времени жизни.

```python
try:
    saved_path = result.save_to(destination)
except QuarantineCleanupError:
    raise
except (OSError, FileSecurityError):
    result.discard()
    raise
```

`QuarantineCleanupError` в этот пример не входит: путь назначения уже опубликован, и `discard()` здесь только повторяет попытку удалить файл из карантина, если предыдущая попытка удаления не прошла. Откатывать опубликованный файл этот вызов не будет. Пример отказывается от файла. Чтобы опубликовать его в другой путь, `discard()` в обработчике не вызывают.

### Отмена асинхронного сохранения

`asave_to()` выполняет копирование в отдельном потоке. Отмена не прерывает уже начавшееся копирование: библиотека дожидается завершения потока. Если публикация уже состоялась, она не откатывается. Таблица исходов и порядок вместе с `close()` — в [ADVANCED.md](ADVANCED.md#отмена-публикации).

### discard

Пока объект действителен, `save_to` можно вызвать ещё раз. Действителен он до первого успешного сохранения, до явного `discard()` / `adiscard()` или до `close()` объекта `FileSecurity`. После любого из этих трёх событий повторное сохранение завершается исключением `UsageError`, в том числе с `overwrite=True`. Один чистый результат нельзя опубликовать несколько раз. Повторный `discard()` после них ничего не делает.

Явный отказ от чистого файла:

```python
result.discard()
await result.adiscard()
```

Повторный `discard()` безопасен. Это же относится к `discard()` после успешного `save_to` и к `discard()` после `close()`: файл уже отпущен, вызов ничего не делает. Вызов `discard()` во время `save_to` или `asave_to` завершается исключением `UsageError`.


| Вызов                                             | Результат             |
| ------------------------------------------------- | --------------------- |
| первый `discard()`                                | файл карантина удалён |
| повторный `discard()` до `close()`                | ничего не делает      |
| `discard()` после успешного `save_to()`           | ничего не делает      |
| `discard()` после `close()`                       | ничего не делает      |
| `discard()` во время `save_to()` или `asave_to()` | `UsageError`          |
| `save_to()` после `close()`                       | `UsageError`          |


`result.staged_file` на том же `FileCheckResult` нужен, когда публикация идёт не через локальный `Path`: `open_for_copy()` и затем ручной `discard()`. После `save_to` или `discard()` этот доступ закрыт. Пока идёт `open_for_copy()`, удалить файл нельзя. Путь карантина по-прежнему не является публичным полем: читать байты нужно из выданного дескриптора.

### Одновременные вызовы

Защита здесь двух уровней:

- `save_to`, `asave_to`, `discard`, `adiscard` и `close` держат блокировку результата. Два сохранения одного результата одновременно не поддерживаются, в том числе `save_to` в одном потоке и `asave_to` в другом: второй вызов получает `UsageError`. `discard()` во время сохранения — тоже `UsageError`. `close()` ждёт конца сохранения.
- Ручной `staged_file.open_for_copy()` блокировку результата не берёт. Он переводит сам временный файл в состояние копирования. Пока дескриптор открыт, вызовы `discard()`, `save_to()` и второго `open_for_copy()` завершаются исключением `UsageError`, а `close()` ждёт выхода из менеджера и только потом удаляет файл.

`open_for_copy()` — синхронный контекстный менеджер расширенного доступа. Приложение обязано выйти из него и при успехе, и при исключении, и при отмене окружающей задачи. Библиотека сама брошенный дескриптор не закрывает, и `close()` будет ждать его бесконечно. После выхода из менеджера файл карантина снова можно сохранить или удалить через `discard()` или `close()`.

Если `discard()` не смог удалить файл, вызов завершается исключением `QuarantineDiscardError` с кодом `quarantine_discard_failed`. Временный файл при этом уже закрыт, повторный `discard()` снова пробует удалить его по пути. Если и это не удалось, файл заберёт уборщик после времени жизни.

### Жизненный цикл временных файлов


| Ситуация                                           | Кто удаляет                                                                                |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `infected`, `rejected`, `error`, `timeout`         | библиотека пытается удалить копию до возврата из `scan`; если не удалось, остаётся `cleanup_error_code` |
| `stale`                                            | копия остаётся до `save_to()`, `discard()` или `close()`                                   |
| `save_to` прошёл                                   | `save_to`, сразу после переименования копии на путь назначения                             |
| `save_to` опубликовал путь, а карантин не удалился | вызов завершается исключением `QuarantineCleanupError`, путь назначения остаётся, карантин ждёт уборщика |
| приложение передумало сохранять                    | `discard()`                                                                                |
| процесс останавливается через `close()`            | `close()` удаляет несохранённые копии, которые не закрыли через `discard()`                |
| `close()` не смог удалить файл                     | файл остаётся до уборщика                                                                  |
| процесс убит и `close()` не вызывался              | уборщик, после времени жизни                                                               |


Уборщик отличает живой файл от забытого по блокировке. Пока процесс держит файл, уборщик его не трогает. После гибели процесса блокировка снимается системой. Команда уборки удаляет обычные файлы с префиксом `.file-security-` старше времени жизни. По умолчанию это час, и файлы моложе пяти секунд не трогаются. Символические ссылки уборщик не удаляет и по ним не ходит.

На выход из интерпретатора уборка не повешена. Для сервера уборщик запускают отдельно, тем же пользователем:

```bash
python -m file_security cleanup \
  --quarantine /var/lib/file-security/quarantine \
  --ttl 3600
```

## Жизненный цикл и конкурентное использование

```text
конструктор     только аргументы
start           каталог, сокет, демон, цепочка
каждый файл     scan_sync из обычной функции, scan из async def
close           дождаться окончания активных операций, удалить из карантина копии, которые приложение не сохранило и не удалило через discard(), и остановить сканеры
```

### start и astart

Три равноправных способа открыть и закрыть объект. Обычная функция вызывает `scan_sync`. Функция `async def` вызывает `await security.scan(...)`. Для обычной функции:

```python
with FileSecurity(quarantine_dir=quarantine) as security:
    result = security.scan_sync(...)
```

Для функции `async def`:

```python
async with FileSecurity(quarantine_dir=quarantine) as security:
    result = await security.scan(...)
```

Когда объект создаёт само приложение и контекст неудобен:

```python
security = FileSecurity(quarantine_dir=quarantine)
security.start()          # или await security.astart()
# ...
security.close()          # или await security.aclose()
```

Повторный `start()` после успешного старта ничего не делает и возвращает `None`. `astart()` тоже возвращает `None`. Вызов `start()` после `close()` завершается исключением `UsageError`.

### close и aclose

`close()` и `aclose()` не возвращают отчёт и не отдают управление, пока внутренний разбор ещё дочитывает сеанс. Состояния `draining` у короткого вызова нет: оно остаётся у цепочки в [ADVANCED.md](ADVANCED.md). Оба метода ждут активные сохранения и рабочие сеансы сканеров, затем удаляют несохранённые копии из карантина и возвращают `None`. После этого возврата уборщик карантина запускать можно. `close()` блокирует, пока сканеры останавливаются. Если в этот момент идёт `save_to` или `asave_to`, `close()` ждёт конца этого сохранения и не удаляет файл, который сейчас копируют. После завершения текущих операций `close()` удаляет из карантина копии, которые приложение не сохранило и не удалило вызовом `discard()`. В async-процессе его вызывают так:

```python
await security.aclose()
```

`aclose()` выполняет блокирующее ожидание в отдельном потоке. Закрывать `FileSecurity` после каждого файла не нужно. Отдельные сканеры снаружи не закрывают: ими владеет объект `FileSecurity`.

`FileCheckResult` принадлежит тому экземпляру `FileSecurity`, который его создал. После `close()` этого экземпляра вызовы `save_to()` и `asave_to()` завершаются исключением `UsageError`. `discard()` и `adiscard()` после `close()` ничего не делают: файл уже отпущен при остановке, при успешном сохранении или при предыдущем `discard()`.

### Ошибки запуска

Вызов `start()` и вход в контекст завершаются исключением `ConfigurationError`. Файл при этом не считается чистым.


| Состояние                                                                              | Что происходит                                                      |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Каталог не передан и `temporary` выключен                                              | ошибка в конструкторе                                               |
| Каталога нет, он является ссылкой или в него нельзя записать файл                      | ошибка старта                                                       |
| Сокет не передан и ни одного стандартного пути нет                                     | ошибка старта, в тексте перечислены пути и команда установки демона |
| Сокет передан, но его нет или это не сокет                                             | ошибка старта                                                       |
| Демон не ответил на `PING`                                                             | ошибка старта                                                       |
| Демон не объявил `INSTREAM`                                                            | ошибка старта                                                       |
| В сокет может писать любой пользователь или процесс запущен от root                    | ошибка старта                                                       |
| `clamav_stream_max_length` меньше `max_file_bytes`                                     | ошибка старта                                                       |
| База старше `max_signature_age`, пока `allow_stale_database` выключен                  | ошибка старта                                                       |
| Дата базы без пояса или из будущего                                                    | ошибка старта                                                       |
| `enable_yara=True`, модуль `yara` не установлен                                        | ошибка старта                                                       |
| `enable_yara=True` без файла правил, с пустым каталогом, с правилом, которое не компилируется, или с `include` вне каталога | ошибка старта, файл не считается чистым          |


Если сокет не задан, библиотека берёт первый существующий путь из списка:

- `/run/clamav/clamd.ctl`
- `/run/clamav/clamd.sock`
- `/var/run/clamav/clamd.ctl`
- `/var/run/clamav/clamd.sock`

Выбранный путь после старта лежит в `security.socket_path`. Каталог `/tmp` библиотека не просматривает ни при старте, ни в `doctor`: туда может положить сокет любой пользователь. Найденный стандартный путь проходит ту же проверку прав, что и переданный явно.

Демон, который замолчал уже после успешного старта, не роняет процесс. Такой файл возвращается как `error` / `scanner_unavailable`. База, которая устарела уже во время работы, даёт `error` / `stale_signature_database`, пока `allow_stale_database` выключен. Оба случая — результат проверки, не исключение.

Вызовы `scan()` и `scan_sync()` до `start()` и после `close()` тоже завершаются исключением `UsageError`. Новый вызов короткого входа не возвращает `scanner_shutting_down`. Этот код остаётся у приёма, который уже шёл, когда остановка началась. Он описан в [ADVANCED.md](ADVANCED.md).

### Параллельное использование

Переходы жизненного цикла сериализованы внутренней блокировкой. Два одновременных `start()` не запускают сканеры дважды. Два одновременных `close()` не останавливают их дважды. `start()` одновременно с `close()` не запускает новый набор сканеров поверх останавливаемого. Вызов `scan()` в момент перехода к остановке завершается исключением `UsageError` и не получает `scanner_shutting_down`.

Один `FileSecurity` можно вызывать одновременно из нескольких потоков и асинхронных задач. Сколько приёмов пишут поток сразу, ограничивает `max_active_uploads`. Отдельный экземпляр на поток не нужен.

### Рабочие процессы

Каждый рабочий процесс создаёт свой `FileSecurity` уже после запуска процесса. Экземпляр, созданный до `fork`, в дочернем процессе не используют. Это относится к prefork-серверам, очередям задач и перезапуску процесса разработки.

## Что проверяется по умолчанию

Именованных профилей в этой версии нет. Сканер в этом документе — отдельная проверка со своим именем: разбор формата, правила YARA или демон ClamAV. Вызов без дополнительных флагов всегда делает одно и то же, по порядку:

1. Политика файла: пустой файл, размер, имя, опасное расширение, заголовок ELF или PE, зашифрованный ZIP, заявленный тип.
2. `svg` — SVG как XML. Скрипт, обработчик события и схема `javascript:` дают `active_content`. Обычная ссылка и картинка по `http` или `https` не отказ. Любой DOCTYPE и сломанный XML — `content_invalid`.
3. `html` — HTML, не как XML. Те же признаки активного содержимого. Синтаксическая ошибка сама по себе не отказ. Кодировка вне списка и негожий UTF-8 без другой кодировки из списка — `content_invalid`.
4. `eml` — письмо с блоком заголовков и пустой строкой после них. Части читаются в памяти. HTML-тело дополнительно проверяется сканером `html`. Обычный текст проверяют ClamAV и, если он включён, YARA; в сканеры PDF и HTML этот текст не попадает. Вложения классифицируются по сигнатуре байтов: PDF попадает в сканер `pdf`, ZIP внутри письма открывается с теми же ограничениями. Потерянная граница, битая base64 и кодировка вне списка — `content_invalid`. Имя `.eml` без такого блока письмо не подтверждает.
5. `msg` — письмо Outlook в контейнере OLE. Вложение — хранилище `__attach_version1.0_#…` с данными `0x3701`. HTML-тело `0x1013` дополнительно проверяется сканером `html`. Тело RTF в этот сканер не идёт: целиком прочитанные байты проверяют ClamAV и, если он включён, YARA. Вложенное письмо с методом вложения 5 разбирается на той же глубине. Поток с похожим именем, но без этой структуры, — `content_invalid`. Документ старого Office этим шагом не считается письмом.
6. `archive` — читает в памяти элементы обычного ZIP, поток GZIP и TAR. Целиком прочитанный элемент проходит те же проверки содержимого, а затем ClamAV и, если он включён, YARA, ещё во время разбора архива. Пакет Office и ODF в список файлов не превращается. 7z не разбирается. Если результат разбора архива уже не `clean`, проверка всего исходного файла в ClamAV в конце не выполняется: элементы, которые успели прочитаться целиком, демон уже видел.
7. `office` — вид документа по содержимому (пакет Office, ODF или старый OLE) против заявленного, связи с внешним миром и пути внутри пакета.
8. `pdf` — шифрование и активные действия, в том числе внутри сжатых потоков объектов.
9. `image_metadata` — служебные блоки JPEG, PNG, GIF и WEBP.
10. `macros` — ищет макросы в документе Office, листы макросов, ActiveX и скрипты ODF. По умолчанию находку пишет в журнал (`event=file_security_macros_found`) и файл не отклоняет. С `reject_macros=True` отклоняет (`macros_present` / `active_content`). Зашифрованная книга старого Excel и повреждённый документ отклоняются при любом значении флага.
11. `nested_objects` — разбирает объекты, вставленные в документ Office, и вложения PDF. Распознанный документ Office (пакет OOXML или ODF, старый Office в OLE, подчинённый документ ODF) по умолчанию не отклоняет: пишет находку в журнал (`event=file_security_embedded_object`) и проверяет его дальше теми же правилами, что и основной файл. Ограничения одни на всё дерево вложений: исходный файл имеет глубину 0, извлечённый объект глубины от 1 до 5 проходит, объект глубины 6 отклоняется и слот не занимает. Один объект не больше 16 МиБ, на дерево — 64 МиБ и 10 000 объектов, общий срок. Упаковщик (`Ole10Native`, `Package` не с документом Office), неизвестный объект и вложение PDF отклоняются всегда (`unverifiable_embedded_object`, `pdf_attachment`). С `reject_embedded_objects=True` отклоняется и распознанный документ Office (`nested_object`). `reject_macros=True` распространяется и на макросы с ActiveX во вложенных документах. Объекты внутри потока `PowerPoint Document` у `.ppt` этим разбором не извлекаются.
12. `clamav` — обязательный. Если предыдущий шаг уже отклонил файл, демон для всего файла не вызывается.

Сканеры содержимого выбирают файл и по заявленному типу, и по тому, что найдено в начале файла. Документ с макросами, заявленный как `application/zip`, всё равно проверяется как документ Office. Подробности каждого шага — в [ADVANCED.md](ADVANCED.md).

По умолчанию содержимое писем и извлечённые элементы архивов проверяются ClamAV. Если включён YARA, его правила применяются дополнительно. Проверка `yara` в список выше не входит, потому что `enable_yara` по умолчанию выключен и импорт пакета модуль `yara` не загружает. Когда флаг включён и задан `yara_rules`, проверка `yara` выполняется сразу перед `clamav` и для входного файла, и для целиком прочитанного элемента. Совпадение правила — `rejected` / `yara_match` и находка `yara_rule` с именем правила. Это не `infected`. Таймаут YARA — статус `timeout` и код `yara_timeout`. Другой сбой проверки — `error` / `yara_failed`. Оба случая не означают, что совпадений не было. Нет совпадения только с этими правилами — файл идёт дальше, к ClamAV. На самом файле совпадение, срок и сбой до демона не доходят. У элемента архива или части письма демон для этого элемента или этой части вызывается всё равно.

Очистка документа и песочница в набор не входят. Нет модуля, нет каталога или файла правил, каталог пуст, правило не компилируется или `include` выходит из каталога правил — ошибка старта, а не тихий пропуск и не `clean`.

Свой порядок и свой набор сканеров собираются расширенным вызовом, см. [ADVANCED.md](ADVANCED.md).

Список разрешённых типов по умолчанию не задан. Это не пустой список: пустой список отклоняет всё, а незаданный список после остальных правил политики отдаёт файл сканерам. Обычный текст при этом доходит до ClamAV.

## Настройка

Конструктор только проверяет аргументы. Каталог, сокет и демон он не трогает. Это делает вход в `with` / `async with`, либо явные `start()` и `astart()`.

### Аргументы FileSecurity

```python
class FileSecurity:
    def __init__(
        self,
        *,
        quarantine_dir: Path | None = None,
        temporary: bool = False,
        socket_path: str | Path | None = None,
        max_file_bytes: int = 25 * 1024 * 1024,
        scan_timeout: float = 60.0,
        allowed_types: Collection[str] | None = None,
        denied_types: Collection[str] | None = None,
        max_signature_age: timedelta | None = timedelta(days=7),
        allow_stale_database: bool = False,
        max_active_uploads: int = 8,
        quarantine_max_files: int = 1000,
        quarantine_max_total_bytes: int = 2 * 1024 * 1024 * 1024,
        enable_yara: bool = False,
        yara_rules: Path | str | None = None,
        reject_macros: bool = False,
        reject_embedded_objects: bool = False,
        forbidden_prefixes: tuple[Path, ...] = (),
        max_concurrent_scans: int = 4,
        clamav_stream_max_length: int | None = None,
        version_cache_seconds: float = 60.0,
    ) -> None:
        """Аргументы. Каталог и демон здесь не открываются."""
```

`reject_macros` — политика приложения: отклонять ли документы Office с макросами и ActiveX. По умолчанию `False`, документ с макросом проверяется дальше как обычный. Запрет включают явно; он действует и на макросы с ActiveX во вложенных распознанных документах Office:

```python
security = FileSecurity(
    quarantine_dir=quarantine,
    reject_macros=True,
)
```

`enable_yara` по умолчанию выключен. Вместе с `yara_rules` он подключает правила вызывающего: один файл или каталог `.yar` и `.yara`. Флаг без пути, как и путь без флага, правила не включает. Путь без флага просто не используется. Extra `yara` ставит `yara-python` 4.5.4 или новее, но меньше 5. Базовая установка эту зависимость не тянет.

```python
security = FileSecurity(
    quarantine_dir=quarantine,
    enable_yara=True,
    yara_rules=Path("/etc/file-security/yara"),
)
```

`reject_embedded_objects` — строгий режим для вставленных объектов. По умолчанию `False`: распознанный документ Office (таблица Excel, диаграмма, подчинённый ODF) не отклоняется за сам факт вставки. Упаковщик, неизвестный объект и вложение PDF отклоняются при любом значении. Полный запрет любых вставленных объектов:

```python
security = FileSecurity(
    quarantine_dir=quarantine,
    reject_embedded_objects=True,
)
```

Последние четыре аргумента обычному приложению не нужны:

- `forbidden_prefixes` — каталоги, внутри которых карантин лежать не должен, например корень постоянного хранилища. Совпадение — ошибка старта.
- `max_concurrent_scans` — сколько файлов одновременно идут в демон. У каждого сканера содержимого свой предел — два файла сразу. До истечения установленного срока не удалось получить свободный слот для проверки в демоне или в сканере содержимого — `error` / `scanner_busy`.
- `clamav_stream_max_length` — сколько байтов библиотека готова отправить демону, см. [пределы](#пределы-размера-и-срока).
- `version_cache_seconds` — сколько секунд помнить удачный ответ `VERSION` с датой базы. Если запрос завершился ошибкой, результат не запоминается: при проверке следующего файла библиотека снова запросит версию демона.

### Сокет ClamAV

Если стандартный сокет не подходит или нужны другие пределы, переопределяют только эти аргументы. Остальные остаются как в сигнатуре выше.

```python
security = FileSecurity(
    quarantine_dir=quarantine,
    socket_path="/custom/run/clamd.sock",
    max_file_bytes=100 * 1024 * 1024,
    scan_timeout=120,
)
```

### Пределы размера и срока

Размеры задают числом байтов. `max_file_bytes` по умолчанию — 25 МиБ.

`clamav_stream_max_length` по умолчанию равен `max_file_bytes`. Значение меньше `max_file_bytes` — ошибка старта. Предел самого демона (`StreamMaxLength` в `clamd.conf`) библиотека не меняет и не читает: его выставляет администратор не меньше `max_file_bytes`. Если предел демона меньше, демон отвергает длинный поток, и файл получает `error` / `scanner_limit`.

`scan_timeout` (60 секунд) — срок проверки уже записанного файла всеми сканерами. Он начинается после того, как файл записан в карантин, и приём потока в эти 60 секунд не входит. Приём потока ограничен отдельно и по умолчанию тоже 60 секундами. Этот срок аргументом конструктора не задаётся. Отсчёт приёма начинается, когда библиотека читает вход. Если поток не пришёл за этот срок, файл получает `error` / `input_stream_failed`, а временный файл удаляется. В `scan` срок приёма прерывает ожидание следующего куска. В `scan_sync` он проверяется между кусками: блокирующий `read()` источника библиотека прервать не может. Поэтому срок чтения синхронного входа задаёт сам источник, например таймаут сокета запроса у сервера приложения.

Тот же общий срок проверяется между сканерами и между элементами архива. Разбор, который уже вошёл в синхронный вызов, этот срок не обрывает: дерево EML, HTML, SVG, поток OLE и чтение архива дочитываются до своего собственного предела или до конца вызова. Проверка YARA прерывается по параметру `timeout` библиотеки YARA. ClamAV прерывается по сроку сокета.

### Квоты

`max_active_uploads` ограничивает, сколько входных потоков пишутся в карантин одновременно. Когда поток уже записан и посчитана сумма, этот слот освобождается: дальнейшая проверка файла его не держит. `quarantine_max_total_bytes` резервирует место из расчёта `max_file_bytes` на приём, поэтому реально занятые байты могут быть меньше резерва. `quarantine_full` — временная ошибка инфраструктуры. Загрузку можно повторить, когда другие приёмы закончатся или уборщик освободит каталог.

### Свежесть базы

Два аргумента задают возраст базы. Базу обновляет `freshclam` или внешний конвейер, не библиотека. Как считается дата, описано в разделе [часовой пояс даты базы](#часовой-пояс-даты-базы).

`max_signature_age` — с какого возраста база считается слишком старой. По умолчанию 7 суток. Сравнение строгое: ровно этот срок ещё проходит. Срок можно уменьшить или увеличить, например `timedelta(days=2)` или `timedelta(days=14)`. `None` отключает проверку возраста: процесс стартует и со старой базой, файлы могут получить `clean`. Это ослабление: демон со старыми сигнатурами может не увидеть уже известную угрозу. Предупреждение `doctor` о базе старше трёх суток при `None` остаётся предупреждением и само по себе старт не останавливает.

`allow_stale_database` по умолчанию `False`. База старше `max_signature_age` не даёт вызвать `start()`. Если она устарела уже после старта, файл получает `error` / `stale_signature_database`, в демон не отправляется и в хранилище не попадает.

`allow_stale_database=True` разрешает старт со старой базой. Файл уходит в ClamAV. Сигнатура найдена — статус `infected`, публиковать нельзя. ClamAV не обнаружил угрозу — статус `stale`, код `stale_signature_database`. `is_clean` ложно. Копия остаётся в карантине. `save_to()` принимает такой результат, пока копия на месте и сохранение ещё не выполнялось: публиковать такой файл или нет, решает приложение. Дата, которую не удалось разобрать, и дата из будущего по-прежнему останавливают старт. Недоступный демон статусом `stale` не прикрывается.

### Часовой пояс даты базы

Демон сообщает дату базы в ответе `VERSION` без часового пояса, в местном времени своего хоста. Сокет только локальный, поэтому демон и процесс работают на одном хосте. Библиотека читает эту дату в местном поясе своего процесса и переводит в UTC. Пояс процесса совпадает с поясом демона, пока у процесса не задана другая переменная `TZ`. Если пояса разошлись, возраст базы считается со сдвигом на эту разницу. Дата позже текущего времени больше чем на 5 минут считается ошибкой часов: старт не проходит, а во время работы файл получает `error` / `scanner_invalid_result`. В расширенном вызове пояс хоста демона можно передать явно: `ClamAVScanner(..., signature_date_timezone=ZoneInfo("Europe/Moscow"))`.

### temporary=True

Для локального эксперимента, не для сервера:

```python
with FileSecurity(temporary=True) as security:
    ...
```

`temporary=True` создаёт отдельный каталог с режимом `0700` и удаляет его при `close()`. Одновременно передать `quarantine_dir` и `temporary=True` нельзя. Без обоих аргументов вызов конструктора завершается исключением `ConfigurationError`.

Этот режим только для тестов и локального эксперимента. На сервере его не включают: каталог может оказаться во временной файловой системе, временем его жизни управляет процесс, после аварии каталог может остаться, а системная очистка временных файлов может стереть его вместе с ещё не сохранёнными байтами.

### Разрешённые типы

`allowed_types=None` — список не задан. Переданный пустой набор отклоняет любой тип. `scan` и `scan_sync` принимают свой `allowed_types`: он заменяет список конструктора только для этого файла.

Остальные переключатели политики в коротком вызове включены: опасные расширения (`exe`, `dll`, `bat`, `cmd`, `ps1`, `js`, `sh` и соседние из того же списка), заголовки ELF и PE, зашифрованный ZIP. Имя проверяется и как пришло, и после нормализации NFKC.

#### Правило расширений

Список опасных расширений — `file_security.DANGEROUS_EXTENSIONS`. Свой список передают в расширенном вызове через `FilePolicy(denied_extensions=...)`, например `DANGEROUS_EXTENSIONS | {"docm"}`. Имя сравнивается после нормализации NFKC и без учёта регистра. Смотрятся только два последних расширения:

- опасное последнее расширение — отказ `dangerous_content`: `report.exe`, `report.pdf.EXE`, `file.tar.gz.exe`;
- опасное предпоследнее расширение — отказ, только если оно замаскировано пробелом или другим пробельным символом внутри него или внутри последнего расширения: `doc.exe .pdf`, `doc.exe. pdf`;
- опасное слово дальше от конца имени отказа не даёт: `invoice.example.com.pdf`, `setup.exe.notes.txt` проходят.

Пробел или точка в самом конце имени, путь, `..`, управляющие и невидимые символы (в том числе знаки смены направления письма) дают `invalid_filename`, до правила расширений дело не доходит. Имя загруженного файла не используется при формировании пути сохранения, поэтому правило защищает человека, который потом скачает файл, а не сервер.

#### Синонимы типов

Браузеры и старые системы присылают для некоторых форматов не канонический тип. Библиотека приводит эти синонимы к канону и в заявленном типе, и в списках `allowed_types` и `denied_types`:


| Синоним                                             | Канон              |
| --------------------------------------------------- | ------------------ |
| `application/x-zip-compressed`, `application/x-zip` | `application/zip`  |
| `image/jpg`, `image/pjpeg`                          | `image/jpeg`       |
| `image/x-png`                                       | `image/png`        |
| `application/x-pdf`                                 | `application/pdf`  |
| `application/x-gzip`                                | `application/gzip` |
| `model/x.stl-ascii`, `model/x.stl-binary`, `application/sla` | `model/stl` |


`application/x-zip-compressed` по умолчанию шлют Chrome и Edge под Windows. Разрешив `application/zip`, приложение разрешает и его. Запрет синонима запрещает и канон. В `FileCheckResult.declared_mime` остаётся строка, которую прислал клиент. Таблица — `file_security.MIME_SYNONYMS`.

#### Строгий список типов

```python
security = FileSecurity(
    quarantine_dir=quarantine,
    allowed_types={
        "application/pdf",
        "image/png",
        "image/jpeg",
        "text/plain",
    },
    denied_types={"application/x-msdownload"},
)
```

Запрещающий список сильнее разрешающего. PDF, PNG, JPEG, GIF, WEBP, ZIP, GZIP и Office без своей подписи в начале файла получают `mime_mismatch`, даже если заявленный тип разрешён. Для текста, CSV, Markdown, RTF, HTML, XHTML, SVG, письма `message/rfc822`, `application/x-7z-compressed` и `model/stl` отсутствие известной подписи само по себе не является несовпадением: при разрешённом заявленном типе файл идёт дальше. 7z и RTF эта версия по началу файла не подтверждает. ASCII STL с началом `solid` распознаётся как `model/stl`; бинарный STL короткой подписи не имеет. Библиотека не проверяет корректность STL, число треугольников, размер, нормали, топологию или соответствие бинарного файла формату STL. Поддержка `model/stl` означает только разрешённый маршрут MIME-политики и передачу файла в ClamAV. Полноценную проверку выполняет приложение или специализированный 3D-валидатор. HTML, SVG и EML подтверждает уже их сканер, а не подпись в начале файла. Заявленный `application/vnd.ms-outlook` совместим с подписью OLE.

Если список задан, а заявленного типа нет, результат тоже `mime_mismatch`.

`content_type=None` и пустая строка — это отсутствующий заявленный тип. При заданном `allowed_types` такой файл получает `mime_mismatch`. При `allowed_types=None` он проходит остальные правила политики и может дойти до цепочки. Строка с параметрами вроде `application/pdf; charset=binary` берётся как `application/pdf`. Непустая строка, которая не разбирается как `type/subtype`, даёт `mime_mismatch`.

## Перед включением на сервере

- процесс не от root;
- каталог карантина вне корня сайта, режим `0700`, владелец — пользователь процесса;
- у процесса есть доступ к сокету через группу, и остальные пользователи писать в сокет не могут;
- `StreamMaxLength` в `clamd.conf` не меньше `max_file_bytes`;
- `doctor` запускают от этого же пользователя;
- базу обновляет `freshclam`; порог старости — `max_signature_age`, а `allow_stale_database` выбирает блокировку или статус `stale` (см. [можно ли публиковать](#можно-ли-публиковать));
- уборщик карантина стоит отдельным расписанием;
- `close()` вызывается при остановке процесса;
- путь назначения не собирается из имени загруженного файла, родительский каталог уже есть и не лежит внутри карантина;
- чистый файл либо сохранён через `save_to`, либо закрыт через `discard()`;
- строка EICAR даёт `infected` / `malware_detected`: `staged_file` отсутствует, файл карантина удалён до возврата результата;
- `text/plain` из разрешённого списка доходит до демона;
- текст с заявленным типом PDF отклоняется как `mime_mismatch` до демона.

EICAR — безопасная тестовая строка. В постоянное хранилище её не кладут. Проверяют два раза: без списка типов, чтобы увидеть сам демон, и со списком, где `text/plain` разрешён, чтобы увидеть, что текст не отсекается политикой раньше демона.

## Ограничения

- не распаковывает 7z и не отличает шифрованный 7z;
- не пишет распакованное на диск и не обходит вложенность без предела: элементы ZIP, GZIP и TAR, части письма и вставленные объекты Office читаются в памяти не глубже пяти ступеней от исходного файла. Сумма этих байт не больше 64 МиБ. Это не объём памяти процесса;
- не читает EML порциями. Разборщик стандартной библиотеки строит дерево в конце, и память сверх сырого письма пределом 64 МиБ не ограничена. Base64, который по оценке не влезает в это ограничение, не декодируется. Quoted-printable библиотека собирает раньше, чем ограничение может остановить сборку, и пустой результат без сообщения о дефекте отказом не считается. Тело RTF в MSG на активное содержимое не проверяется;
- не извлекает объекты `.ppt`: в старом PowerPoint они лежат внутри сжатого потока `PowerPoint Document` и не отклоняются;
- отклоняет формулы старого редактора формул (`Equation.3`) как неизвестный объект OLE;
- не отдаёт сканерам элемент архива, который не удалось прочитать целиком. Один слишком большой элемент ZIP не отменяет проверку остальных. Обрыв чтения TAR останавливает этот TAR, но не родительский ZIP;
- не разбирает страницы PDF: ищет ограниченный набор имён в словарях и раскрывает только потоки объектов, сжатые одним `FlateDecode` без предсказателя; другие способы сжатия потоков объектов дают `content_limit`, а не пропуск;
- у ODF проверяет только список файлов пакета и связи в манифесте, а не ссылки внутри `content.xml`;
- не заменяет песочницу разбором Office;
- не считает отсутствие совпадения YARA доказательством безопасности. Правила задаёт вызывающий, ищутся только они. Срок проверки — целое число секунд самой библиотеки, не меньше одной. `include` не выходит из каталога правил: абсолютный путь, `..` и символическая ссылка наружу — ошибка старта;
- не очищает документ и не делает поведенческий разбор;
- не обещает, что статус `infected` значит «файл проверили все обязательные сканеры». Сканер, который не закончился, остаётся в `diagnostics` с именем сканера и путём внутри файла. Общий срок не обрывает разбор, который уже вошёл в синхронный вызов;
- не обещает найти всякую угрозу;
- не обещает совпадение HTML и SVG с браузером. Не разбираются адрес по правилам WHATWG, обратная косая черта в схеме, UTF-7 и атрибут, который браузер чинит сам. Обычная ссылка `http`, `https` или `mailto` и внешняя картинка не отказ: проверка файла не запрещает их загрузку при открытии;
- у CSS ловит только `url(javascript:…)` в атрибуте `style` и в элементе `style`. Другое выражение CSS не отказ и не называется проверенным.

## Разработка пакета

Установка из клона репозитория (корневой каталог с `pyproject.toml`):

```bash
cd <каталог репозитория file_security>
python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
```

Для разработки и прогона тестов:

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
```

Правила YARA проверяются только с дополнительным extra. Без него тесты, которым нужна библиотека, пропускаются, а `import file_security` модуль `yara` не загружает:

```bash
python -m pip install -e ".[dev,yara]"
```

Вместе с пакетом ставится `olefile` (лицензия BSD): без него нельзя прочитать старый документ Office. Это обязательная зависимость, не дополнительная. Сканеры импортируют `olefile` при импорте самого пакета, поэтому без него уже вызов `import file_security` завершается исключением `ImportError`. До `start()` дело не доходит, и процесс не остаётся наполовину запущенным. `yara-python` (лицензия Apache-2.0) к этому импорту не относится: он нужен только при `enable_yara=True`.

Всё, что нужно приложению, импортируется из корня пакета: `from file_security import FileSecurity, ErrorCode, ScannerChain, ...`. Список имён — `file_security.__all__`. Внутренние модули (`file_security.scanners.*`, `file_security.intake` и другие) могут меняться без предупреждения.

## Расширенный API

Короткий вызов из этого файла публикует чистый файл через `save_to()` или `asave_to()`, и метод сам удаляет копию из карантина. `secure_ingest` этих методов не имеет. Чистый файл там забирают из `staged_file.open_for_copy()` и затем вызывают `discard()`. Подробности сканеров, пределы вложенности и отмена задачи — в [ADVANCED.md](ADVANCED.md). Что библиотека защищает и чего нет, как сообщить об уязвимости — в [SECURITY.md](SECURITY.md). Изменения — в [CHANGELOG.md](CHANGELOG.md).
