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. |
| Хранить файлы, дней | 90 | 0 — не удалять. От 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 принимает тот же формат):
{
"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 можно выключить. Адрес для агентов оставьте пустым.
Связанные страницы
- Установка агентов — сеть от агента до своего S3
- Устранение неполадок —
storage_unavailable, ошибки загрузки