Разделы документации

S3-хранилище

Куда агенты кладут отчёты, SBOM и логи шагов — настройка S3 (MinIO, Ceph RGW, AWS), права ключа, адрес для агентов, лимиты и срок хранения.

Пайплайны на агентах хранят результаты в S3-совместимом хранилище: JSON-отчёты сканеров, SBOM, полные логи шагов и дополнительные файлы. Настраивать его не обязательно: без своего S3 запуски пишут во встроенное хранилище.

Ключи доступа к S3 есть только у Archepelag. На каждый файл агент получает отдельное разрешение на загрузку, действующее до 15 минут. В нём учтены размер файла, его тип и, если агент его передал, sha256, а записать агент может только в каталог своей попытки. Скачивание из UI тоже идёт через Archepelag, а не по прямой ссылке на S3.

Встроенное хранилищеСвоё S3
Где лежат файлыS3 комплекта сервера (по умолчанию SeaweedFS), отдельный бакетВаш MinIO, Ceph RGW или AWS S3
Как загружает агентЧерез Archepelag, по тому же адресу, что и APIНапрямую в S3 по подписанной ссылке (presigned PUT)
Доступ агента к S3Не нуженНужен к адресу для агентов
Срок хранения и лимитыПеременные сервера, лимиты постоянныеВ карточке хранилища

Встроенное хранилище

Работает, пока в Настройки → Интеграции → S3-хранилище нет включённого своего хранилища. Карточка раздела тогда показывает «Используется встроенное хранилище».

  • Где. То же S3, что у файлов портала (FILES_S3_* сервера, по умолчанию SeaweedFS из комплекта), но свой бакет: SCAN_RESULTS_S3_BUCKET, по умолчанию archepelag-scans. Archepelag создаёт бакет сам. Если ваше S3 запрещает создание бакетов, создайте его заранее.
  • Ключи — scan-results/runs/…, как в разделе Что где лежит.
  • Срок хранения — SCAN_RESULTS_RETENTION_DAYS, по умолчанию 90 дней, 0 — не удалять.
  • Лимиты постоянные: 512 МБ на файл, 2048 МБ на попытку задания.
  • Загрузка. Агент отправляет файл на Archepelag (/agent-api/v1/jobs/…/artifacts/upload) со своим токеном задания. Archepelag проверяет разрешение, пишет файл в S3 и сверяет размер и sha256. Не совпало — файл удаляется, агент получает ошибку. Открывать S3 комплекта агентам не нужно.

Если FILES_S3_* на сервере не заданы и своего хранилища нет, запуск не создаётся: storage_unavailable.

Своё S3 подключайте, если нужны другой бакет, срок хранения или лимиты, или если не хотите, чтобы большие файлы шли через сервер Archepelag. Включённое своё хранилище сразу заменяет встроенное для новых запусков. Файлы прежних запусков остаются во встроенном и скачиваются как раньше.

Своё S3

Настройка

Настройки → Интеграции → S3-хранилище → Добавить хранилище (только администратор).

ПолеПо умолчаниюОписание
НазваниеS3Имя подключения в UI.
Хранилище включенодаВыключенное хранилище не используется для новых запусков. Если выключены все, новые запуски пишут во встроенное хранилище.
По умолчаниюда для первогоНовые запуски на агентах пишут в хранилище по умолчанию. Первое созданное хранилище становится им автоматически.
Адрес S3 API—По нему ходит Archepelag (core-service и core-worker). Например, http://minio:9000 или https://s3.eu-central-1.amazonaws.com.
Адрес для агентовпустоАдрес, по которому S3 доступен агентам: на него подписываются ссылки загрузки. Пусто — тот же, что адрес S3 API.
Бакет—3–63 символа: латиница, цифры, ., -, _. Бакет должен уже существовать.
Регионus-east-1Для MinIO и Ceph обычно не важен.
Префикс ключейscan-resultsКаталог внутри бакета.
Path-style адресадаhttp://host/bucket/key. Нужно для MinIO и Ceph RGW. Для AWS можно выключить.
Access Key ID, Secret Access Key—Ключ с правами из раздела ниже. Secret хранится зашифрованным и в ответах API не возвращается. Пустое поле при сохранении оставляет прежний ключ.
TLS: проверка сертификата, CAпроверятьДля HTTPS с сертификатом внутреннего CA загрузите CA (PEM). Этот CA передаётся и агентам вместе с заданием. Если CA задан, и Archepelag, и агенты доверяют только ему, без системных CA: он должен подходить и к адресу S3 API, и к адресу для агентов (в PEM можно положить несколько сертификатов). Без CA — системные CA.
Хранить файлы, дней900 — не удалять. От 0 до 3650.
Файл, МБ512Предел одного файла (отчёт, лог, SBOM), до 5120.
Задание, МБ2048Предел всех файлов одной попытки задания, до 102400.

После смены адреса, адреса для агентов или настроек TLS, а также после отключения проверки сертификата Secret Access Key нужно ввести заново: сохранённый ключ не уходит на новый адрес без подтверждения.

Пока хранилищем пользуются задания в очереди или в работе, удалить его нельзя.

Проверка подключения

Проверить подключение выполняет HeadBucket, затем записывает, читает и удаляет пробный объект в <префикс>/_probe/. Так проверяются все права, которые нужны Archepelag, включая удаление для очистки по сроку хранения. Результат последней проверки виден в карточке и в общем обзоре состояния интеграций.

Проверка идёт со стороны Archepelag. Доступность адреса для агентов с машин агентов она не проверяет.

Адрес для агентов

Archepelag и агенты часто видят S3 по разным адресам. Типичный случай — MinIO в той же docker-сети, что и Archepelag: Archepelag обращается к http://minio:9000, а агенты на других машинах — к https://s3.corp.example. Тогда:

  • Адрес S3 API — http://minio:9000;
  • Адрес для агентов — https://s3.corp.example.

Подпись ссылки включает имя хоста, поэтому адрес для агентов должен быть именно тем, по которому агент придёт в S3. Прокси или балансировщик перед S3 не должен менять заголовок Host.

Права ключа доступа

Archepelag нужно читать, записывать, перечислять и удалять объекты под префиксом. Пример политики (AWS IAM; MinIO принимает тот же формат):

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::archepelag-scans"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::archepelag-scans/scan-results/*"
    }
  ]
}
  • s3:ListBucket нужен для проверки бакета и для удаления каталогов запусков по сроку хранения.
  • s3:DeleteObject нужен для очистки по сроку хранения и для проверки подключения.
  • Агентам ключи не нужны: загрузки идут по подписанным ссылкам.

CORS настраивать не нужно: браузер с S3 напрямую не работает.

Что где лежит

Код
<префикс>/runs/<запуск>/jobs/<задание>/attempt-<N>/
  out/…               отчёты и SBOM из $ARCHEPELAG_OUTPUT
  logs/NN-<шаг>.log   полный лог шага
  logs/job.log        лог задания (клон, служебные сообщения)
  files/…             файлы из artifacts шаблона

Ключи строятся только из идентификаторов, имена репозиториев в них не попадают. Каждая попытка задания пишет в свой каталог.

На странице запуска, на вкладке Файлы выбранного репозитория, видны все файлы попытки: вид (отчёт, SBOM, лог, файл), формат, шаг и размер. Их можно скачать, а SBOM — кнопкой Скачать SBOM в заголовке. Файлы и находки видят только те, кому виден репозиторий.

Лимиты

ЧтоПредел
Один файлФайл, МБ (по умолчанию 512) и не больше 5 ГБ; во встроенном хранилище — 512 МБ
Все файлы попыткиЗадание, МБ (по умолчанию 2048), не больше 1000 файлов; во встроенном хранилище — 2048 МБ
Разбор отчёта в находки64 МБ. Больший отчёт сохраняется, но не разбирается

Файлы, которые не удалось загрузить, перечислены на вкладке Файлы с причиной.

Срок хранения

Раз в сутки (в 03:17 UTC) core-worker удаляет каталоги runs/<запуск>/ запусков, завершённых раньше, чем Хранить файлы, дней назад (во встроенном хранилище — SCAN_RESULTS_RETENTION_DAYS). Находки остаются в базе. На странице запуска появляется пометка «Файлы удалены по сроку хранения».

Примеры

MinIO рядом с Archepelag. Бакет создайте заранее (mc mb), ключ — отдельный пользователь MinIO с политикой выше. Адрес S3 API — http://minio:9000, адрес для агентов — внешний адрес MinIO, path-style включён.

Ceph RGW. Адрес — https://rgw.corp.example, path-style включён, CA вашего центра сертификации загрузите в карточку.

AWS S3. Адрес — https://s3.<регион>.amazonaws.com, регион — регион бакета, path-style можно выключить. Адрес для агентов оставьте пустым.

Связанные страницы