Аудит безопасности: OOM-гейты входа, потокобезопасность, периметр #99

Merged
pjandro merged 7 commits from audit-security-memory-threading into main 2026-11-08 23:38:05 +03:00
6 changed files with 134 additions and 24 deletions
Showing only changes of commit 8a8e8a9f84 - Show all commits
+1 -1
View File
@@ -35,7 +35,7 @@
- **Коды**: 400 — `ValidationException`/`BadRequestException`/битые параметры; 401 — `ApiKeyFilter`; 404/405/415 — путь/метод/content-type; 413 — multipart; **422** — `DrawingRejectedException` (core-`DrawingFoundException`, `Kind {CHARTS, SMARTART, OLE}`); 500/503/504 — `ConversionFailedException`/`ConversionRejectedException`/`ConversionTimeoutException`. 500 отвечает фиксированный текст («Внутренняя ошибка конвертации») — сообщение ядра логируется, наружу не попадает. Полная карта — `docs/agent/repo-map.md`.
- **Текст 422** — контракт с фронтом: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты».
- **Ключ**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES` (`/actuator/`, `/swagger-ui`, `/v3/api-docs`), пути с точечными сегментами — никогда.
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503): ядро дополнительно сериализует конвертации монитором `WordPdfConverter.class` (`convert()` безопасен из нескольких потоков); головой очереди на старте стоит `warmup()`. До очереди — только дешёвый гейт размера (`WordPdfValidator.checkInput` на потоке Tomcat); полный `validate` (контейнер/страницы — распакованные проходы до 64 МБ) выполняется внутри воркера ядром, `ValidationException` из `ExecutionException` пробрасывается как 400. Лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException`; параметрами запроса не переопределяются).
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503): ядро дополнительно сериализует конвертации монитором `WordPdfConverter.class` (`convert()` безопасен из нескольких потоков); головой очереди на старте стоит `warmup()`. До очереди — только дешёвый гейт размера (`WordPdfValidator.checkInput` на потоке Tomcat); полный `validate` (контейнер/страницы — бюджет распаковки считается из лимитов входа `maxMb`/`maxPages`, крышки 64/32 МБ) выполняется внутри воркера ядром, `ValidationException` из `ExecutionException` пробрасывается как 400. Лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException`; параметрами запроса не переопределяются).
- **SPA**: вся сеть в `wordpdf-web/src/api.ts`; ключ в `localStorage` (`wordpdf.api.key`); `ApiKeyGate` — только если `probeApiKey()` подтвердил требование ключа (признак открытого сервера — **405**); base — `VITE_BASE`; DropZone `.docx,.doc`.
## Chart/SmartArt-движок (`internal/chart`, 18 классов)
+1 -1
View File
@@ -4,7 +4,7 @@
| Путь | Назначение |
|---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | Публичный API: `WordPdfConverter` (`convert(byte[],String[,ConvertOptions])`), `WordPdfValidator` (`checkInput`/`checkPageCount`/`validate` — без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`), `WordPdfSettings` (`MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=64`/`MAX_DECOMPRESSED_XML_MB=32`/`MAX_IMAGE_PIXELS=25_000_000`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_*=false`), `ConvertOptions` (record) |
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | Публичный API: `WordPdfConverter` (`convert(byte[],String[,ConvertOptions])`), `WordPdfValidator` (`checkInput`/`checkPageCount`/`validate` — без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`), `WordPdfSettings` (`MAX_INPUT_MB=5`, `MAX_PAGES=100`, крышки автобюджетов распаковки `MAX_DECOMPRESSED_MB=64`/`MAX_DECOMPRESSED_XML_MB=32` — сами бюджеты считает `WordPdfValidator.maxDecompressed*` из `maxMb`/`maxPages`, коэффициенты в `WordPdfConverter.DECOMPRESS_*`; защитные `MAX_IMAGE_PIXELS=25_000_000`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_*=false`), `ConvertOptions` (record) |
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы, self-map, `DISPLAY_NAMES`, `bundledFamily`), `GlyphFont` (глиф-движок fontbox) |
| `…/wordpdf/internal/` | 11 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–10, raw-копия неизменённых записей) + `LayoutPostRenderer` (кастомный `FORenderer`, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0). Классы `public` (иначе родительский пакет не вызвал бы), публичные члены наружу только `normalize`/`STEP`/`declare`/`DependencyGuard.check`/`LayoutPostRenderer.register`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)` |
| `…/wordpdf/internal/doc/` | Мост `.doc` → `.docx`: 18 классов (детали — `docs/agent/doc-bridge.md`) — `CfbReader`, `FibHeader`, `PieceTable`, `Grpprl`, `ChpxIndex`, `PapxIndex`, `Styles`, `Tables`, `Lists`, `Sections`, `FontTable`, `SummaryInfo`, `Headers`, `OfficeArt`, `PrcData`, `DocFile`, `DocxWriter`, `DocToDocx` (публичные `convert`/`countPages`; вложенный `DocxBody` — рендер текста и табличного автомата в XML) |
@@ -239,6 +239,24 @@ public final class WordPdfConverter {
private static final Logger LOG = Logger.getLogger(WordPdfConverter.class.getName());
// Бюджеты распаковки docx (считает WordPdfValidator.maxDecompressed* от
// лимитов входа ConvertOptions). Значения — строго литералы compile-time
// констант: javac инлайнит их в WordPdfValidator, и обращение из валидатора
// НЕ инициализирует этот класс (его static-блок выставляет sysprops docx4j —
// инвариант «WordPdfValidator не зависит от docx4j» сохраняется).
/** Бюджет суммарной распаковки: MiB на каждый МБ лимита размера входа. */
static final int DECOMPRESS_MB_PER_MAX_MB = 10;
/** Бюджет суммарной распаковки: KiB на каждую страницу лимита. */
static final int DECOMPRESS_KIB_PER_PAGE = 64;
/** Бюджет XML-частей: MiB на каждый МБ лимита (JAXB-разбор дороже байта). */
static final int DECOMPRESS_XML_MB_PER_MAX_MB = 4;
/** Бюджет XML-частей: KiB на каждую страницу лимита. */
static final int DECOMPRESS_XML_KIB_PER_PAGE = 32;
/** Пол бюджета суммарной распаковки (MiB) — чтобы мелкие лимиты не ломали легитимные документы. */
static final long MIN_DECOMPRESSED_MB = 16;
/** Пол бюджета XML-частей (MiB). */
static final long MIN_DECOMPRESSED_XML_MB = 4;
/**
* Прогрев ядра: первая конвертация после старта JVM стоит 1,3–1,7 с
* (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет
@@ -16,17 +16,21 @@ public final class WordPdfSettings {
public static final int MAX_PAGES = 100;
/**
* Потолок суммарного распакованного размера архива (МБ) — защита от zip-бомбы.
* Вход ограничен {@link #MAX_INPUT_MB}, медиа в zip не сжимается — легитимный
* документ суммарно распаковывается в единицы МБ; 64 МБ — запас на huge-таблицы.
* Жёсткая крышка автоматического бюджета суммарного распакованного размера
* архива (МБ) — защита от zip-бомбы. Бюджет считается из лимитов входа
* ({@code maxMb}/{@code maxPages}) в {@link WordPdfValidator#maxDecompressedBytes}
* (коэффициенты — {@code WordPdfConverter.DECOMPRESS_*}); эта константа не
* даёт ему вырасти при raise-е {@code wordpdf.max-mb}: легитимный документ
* суммарно распаковывается в единицы МБ, 64 МБ — запас на huge-таблицы.
*/
public static final long MAX_DECOMPRESSED_MB = 64;
/**
* Потолок суммарного распакованного размера XML-частей ({@code *.xml},
* {@code *.rels}) в МБ — отдельный гейт: байтовый бюджет архива можно
* выжатый XML уложить в десятки МБ, а JAXB-разбор такого документа стоит
* CPU/heap несоизмеримо дороже байт.
* Жёсткая крышка автоматического бюджета суммарного распакованного размера
* XML-частей ({@code *.xml}, {@code *.rels}) в МБ
* ({@link WordPdfValidator#maxDecompressedXmlBytes}) — отдельный гейт:
* байтовый бюджет архива можно выжатый XML уложить в десятки МБ, а
* JAXB-разбор такого документа стоит CPU/heap несоизмеримо дороже байт.
*/
public static final long MAX_DECOMPRESSED_XML_MB = 32;
@@ -34,10 +34,12 @@ import java.util.zip.ZipInputStream;
* <ul>
* <li>{@link WordPdfSettings#MAX_INPUT_MB} — максимальный размер входного .docx (МБ);</li>
* <li>{@link WordPdfSettings#MAX_PAGES} — максимально допустимое число страниц;</li>
* <li>{@link WordPdfSettings#MAX_DECOMPRESSED_MB} — потолок суммарного
* распакованного размера архива (МБ);</li>
* <li>{@link WordPdfSettings#MAX_DECOMPRESSED_XML_MB} — потолок распакованных
* XML-частей (МБ);</li>
* <li>{@link WordPdfSettings#MAX_DECOMPRESSED_MB} — жёсткая крышка
* автоматического бюджета суммарного распакованного размера архива
* (считается из лимитов входа, см. {@link #maxDecompressedBytes});</li>
* <li>{@link WordPdfSettings#MAX_DECOMPRESSED_XML_MB} — жёсткая крышка
* автоматического бюджета распакованных XML-частей
* (см. {@link #maxDecompressedXmlBytes});</li>
* <li>{@link WordPdfSettings#MAX_IMAGE_PIXELS} — потолок пиксельной площади
* одного растрового медиа;</li>
* <li>{@link WordPdfSettings#MAX_ZIP_ENTRIES} — потолок числа записей
@@ -300,7 +302,9 @@ public final class WordPdfValidator {
|| (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) {
throw new ValidationException("Содержимое не похоже на .docx или .doc (не zip-архив)");
}
checkDocxContainer(docxBytes);
checkDocxContainer(docxBytes,
maxDecompressedBytes(options.maxMb(), options.maxPages()),
maxDecompressedXmlBytes(options.maxMb(), options.maxPages()));
checkPageCount(docxBytes, options.maxPages());
}
@@ -310,10 +314,14 @@ public final class WordPdfValidator {
* в {@link #checkPageCount(byte[], int)}) и наличие в
* {@code [Content_Types].xml} декларации документа wordprocessingml
* (архив без неё — не .docx: обычный zip, переименованный .xlsx/.pptx).
*
* <p>Бюджеты распаковки передаются параметром (считает
* {@link #validate(byte[], ConvertOptions)} из лимитов входа через
* {@link #maxDecompressedBytes} / {@link #maxDecompressedXmlBytes}):
* заголовок центрального каталога врёт о размере, поэтому считается по ходу чтения.
*/
private static void checkDocxContainer(byte[] docxBytes) throws ValidationException {
long maxTotal = WordPdfSettings.MAX_DECOMPRESSED_MB * 1024 * 1024;
long maxXmlTotal = WordPdfSettings.MAX_DECOMPRESSED_XML_MB * 1024 * 1024;
private static void checkDocxContainer(byte[] docxBytes, long maxTotal, long maxXmlTotal)
throws ValidationException {
long total = 0;
long xmlTotal = 0;
int entries = 0;
@@ -350,13 +358,13 @@ public final class WordPdfValidator {
total += n;
if (total > maxTotal) {
throw new ValidationException("Распакованный размер архива больше "
+ WordPdfSettings.MAX_DECOMPRESSED_MB + " МБ (признак zip-бомбы)");
+ (maxTotal / 1048576) + " МБ (признак zip-бомбы)");
}
if (isXml) {
xmlTotal += n;
if (xmlTotal > maxXmlTotal) {
throw new ValidationException("Суммарный распакованный размер XML-частей больше "
+ WordPdfSettings.MAX_DECOMPRESSED_XML_MB + " МБ (признак zip-бомбы)");
+ (maxXmlTotal / 1048576) + " МБ (признак zip-бомбы)");
}
}
if (isCt) {
@@ -397,6 +405,40 @@ public final class WordPdfValidator {
}
}
/**
* Бюджет суммарной распаковки docx, байты: {@code clamp(maxMb×10MiB +
* maxPages×64KiB, 16MiB, }}{@link WordPdfSettings#MAX_DECOMPRESSED_MB}{@code )}.
* Коэффициенты — {@link WordPdfConverter#DECOMPRESS_MB_PER_MAX_MB} и
* {@link WordPdfConverter#DECOMPRESS_KIB_PER_PAGE} (запас на XML/медиа
* легитимного архива), пол — {@link WordPdfConverter#MIN_DECOMPRESSED_MB}
* (мелким лимитам входа), крышка — константа WordPdfSettings (защита JAXB
* DOM при raise-е {@code wordpdf.max-mb}). Регрессия —
* WordPdfValidatorTest#validate_smallLimitsBudgetFloor,
* #validate_budgetScalesWithInputLimits.
*/
static long maxDecompressedBytes(long maxMb, int maxPages) {
long budget = Math.multiplyExact(maxMb,
WordPdfConverter.DECOMPRESS_MB_PER_MAX_MB * 1048576L)
+ (long) maxPages * WordPdfConverter.DECOMPRESS_KIB_PER_PAGE * 1024L;
return Math.min(WordPdfSettings.MAX_DECOMPRESSED_MB * 1048576L,
Math.max(WordPdfConverter.MIN_DECOMPRESSED_MB * 1048576L, budget));
}
/**
* Бюджет распаковки XML-частей docx, байты: {@code clamp(maxMb×4MiB +
* maxPages×32KiB, 4MiB, }}{@link WordPdfSettings#MAX_DECOMPRESSED_XML_MB}{@code )}
* (XML парсится JAXB DOM — дороже байта, поэтому коэффициенты вдвое ниже
* суммарных). Инвариант: при одних лимитах строго меньше суммарного
* бюджета, поэтому гейт XML достижим.
*/
static long maxDecompressedXmlBytes(long maxMb, int maxPages) {
long budget = Math.multiplyExact(maxMb,
WordPdfConverter.DECOMPRESS_XML_MB_PER_MAX_MB * 1048576L)
+ (long) maxPages * WordPdfConverter.DECOMPRESS_XML_KIB_PER_PAGE * 1024L;
return Math.min(WordPdfSettings.MAX_DECOMPRESSED_XML_MB * 1048576L,
Math.max(WordPdfConverter.MIN_DECOMPRESSED_XML_MB * 1048576L, budget));
}
/** Поиск байтов ASCII-строки в массиве (манифест ограничен 8 МБ — наивного поиска достаточно). */
private static boolean containsAscii(byte[] data, String needle) {
byte[] pat = needle.getBytes(StandardCharsets.UTF_8);
@@ -331,8 +331,9 @@ class WordPdfValidatorTest {
}
/**
* Zip-бомба: распакованный суммарный размер больше
* {@link WordPdfSettings#MAX_DECOMPRESSED_MB} отсекается потоково — до
* Zip-бомба: распакованный суммарный размер больше бюджета распаковки
* (из лимитов входа, крышка {@link WordPdfSettings#MAX_DECOMPRESSED_MB})
* отсекается потоково — до
* {@code readAllBytes} в {@code checkPageCount} (без проверки валидатор
* прочитал бы 200+ МБ в память). Регрессия — WordPdfValidator#checkDocxContainer.
*/
@@ -351,8 +352,10 @@ class WordPdfValidatorTest {
ValidationException ex = assertThrows(ValidationException.class,
() -> WordPdfValidator.validate(zip, ConvertOptions.defaults()));
assertTrue(ex.getMessage().contains("zip-бомбы"), ex.getMessage());
assertTrue(ex.getMessage().contains(String.valueOf(WordPdfSettings.MAX_DECOMPRESSED_MB)),
"сообщение должно упоминать лимит: " + ex.getMessage());
assertTrue(ex.getMessage().contains(String.valueOf(
WordPdfValidator.maxDecompressedBytes(WordPdfSettings.MAX_INPUT_MB,
WordPdfSettings.MAX_PAGES) / 1048576)),
"сообщение должно упоминать вычисленный бюджет: " + ex.getMessage());
}
/**
@@ -399,6 +402,48 @@ class WordPdfValidatorTest {
assertTrue(ex.getMessage().contains("XML-частей"), ex.getMessage());
}
/**
* Мелким лимитам входа — пол бюджета: maxMb=1/maxPages=10 дают 11 МБ,
* поднимается до пола 16 МБ; 17 МБ распаковки отвергаются с числом «16».
* Бросок случается в цикле до проверки манифеста — архив без
* [Content_Types].xml доходит до throw'а бюджета. Регрессия —
* WordPdfValidator#maxDecompressedBytes.
*/
@Test
void validate_smallLimitsBudgetFloor() throws Exception {
ByteArrayOutputStream out = new ByteArrayOutputStream();
try (ZipOutputStream zos = new ZipOutputStream(out)) {
zos.putNextEntry(new ZipEntry("word/bomb.bin"));
zos.write(new byte[17 * 1024 * 1024]);
zos.closeEntry();
}
byte[] zip = out.toByteArray();
ValidationException ex = assertThrows(ValidationException.class,
() -> WordPdfValidator.validate(zip, options(1, 10)));
assertTrue(ex.getMessage().contains("16 МБ"),
"бюджет мелких лимитов — пол 16 МБ: " + ex.getMessage());
}
/**
* Бюджет растёт с лимитами входа: maxMb=2/maxPages=20 дают ~21 МБ — 20 МБ
* non-XML-распаковки проходят; те же байты при maxMb=1/maxPages=10 (пол
* 16 МБ) отвергаются. Крышка WordPdfSettings: maxMb=10/maxPages=100 →
* 64 МБ, 65 МБ — отказ. Регрессия — WordPdfValidator#maxDecompressedBytes.
*/
@Test
void validate_budgetScalesWithInputLimits() throws Exception {
byte[] zip = zipOf("word/bomb.bin", new byte[20 * 1024 * 1024]);
assertDoesNotThrow(() -> WordPdfValidator.validate(zip, options(2, 20)));
ValidationException floor = assertThrows(ValidationException.class,
() -> WordPdfValidator.validate(zip, options(1, 10)));
assertTrue(floor.getMessage().contains("16 МБ"), floor.getMessage());
byte[] big = zipOf("word/bomb.bin", new byte[65 * 1024 * 1024]);
ValidationException capped = assertThrows(ValidationException.class,
() -> WordPdfValidator.validate(big, options(10, 100)));
assertTrue(capped.getMessage().contains("64 МБ"),
"крышка WordPdfSettings.MAX_DECOMPRESSED_MB: " + capped.getMessage());
}
/**
* Дубликаты имён записей — отказ: OPC требует уникальных имён, а партии
* с одним именем по-разному трактуются валидатором (первая) и парсером.
@@ -591,7 +636,8 @@ class WordPdfValidatorTest {
/**
* Нераспознанный/неполный заголовок растра (подписи нет или dimensions
* не влезают) — не отклонять: площадь не объявлена, а реальный decode
* ограничен бюджетом {@code MAX_DECOMPRESSED_MB}. Регрессия —
* ограничен бюджетом распаковки из лимитов входа (крышка
* {@code MAX_DECOMPRESSED_MB}). Регрессия —
* WordPdfValidator#rasterArea (ветки «-1» каждого формата).
*/
@Test