🐳 RAUDI: Регулярно и автоматически обновляемые Docker-образы

RAUDI (Regularly and Automatically Updated Docker Images) автоматически генерирует и поддерживает актуальную серию Docker-образов через GitHub Actions для инструментов, которые не предоставляются разработчиками.

Содержание

• Что такое RAUDI
• Форк
• Настройка
• Тестирование
• Локальное использование
• Доступные инструменты
• Структура инструмента
• Вспомогательные функции
• Примеры
• Как произносить
• Вклад
• Авторы
• Лицензия

Что такое RAUDI

RAUDI — это то, что спасёт вас от необходимости вручную создавать и поддерживать множество Docker-образов. Каждый раз, когда обновляется программное обеспечение, вам нужно обновлять Docker-образ, если вы хотите использовать последние возможности; зависимости перестают работать.

Это грязно и отнимает много времени.

Больше не беспокойтесь, мы всё сделаем за вас.

Вы можете либо форкнуть этот репозиторий и использовать GitHub Workflow самостоятельно, либо использовать его локально (и управлять его выполнением так, как вам удобно).

Форк

Если вы хотите форкнуть этот репозиторий, вам также необходимо настроить некоторые секреты, чтобы иметь возможность отправлять образы в свой личный аккаунт Docker Hub. Два секрета GitHub обязательно должны быть установлены:

• DOCKER_USER: Ваше имя пользователя Docker Hub;
• DOCKER_API_TOKEN: Ваш пароль или API-токен Docker Hub.

После установки этих секретов вам нужно изменить переменную organization, заданную в файле tools/main.py, так как она настроена на отправку в Docker Hub для SecSI.

Вот и всё: перейдите в Action, включите его для вашего форкнутого репозитория, подождите до полуночи, и Workflow сделает всю тяжёлую работу!

Настройка

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

• Python 3.x
• Docker (с BuildX)

Вот документация по работе с BuildX: https://docs.docker.com/buildx/working-with-buildx/

Этап настройки довольно прост, вам нужно выполнить следующие команды:

git clone https://github.com/cybersecsi/RAUDI
cd RAUDI
pip install -r requirements.txt

Вы готовы к работе!

Тестирование

Для запуска тестов необходимо установить pytest командой pip install pytest (его нет в requirements.txt, так как он нужен только для тестирования), после чего вы можете выполнить:

pytest -s

или

python -m pytest -s

для запуска тестов.

Локальное использование

RAUDI может собирать и отправлять все инструменты, помещённые в каталог tools. При запуске доступны различные опции. Перед локальным использованием вы должны создать файл .env (можно просто скопировать файл .env.sample) и добавить свой GitHub Personal Access Token, чтобы избежать ограничения скорости. Для неавторизованных пользователей GitHub разрешает до 60 запросов в час, а для авторизованных — до 15 000 запросов в час. По этой причине мы рекомендуем добавить его! Вы также можете создать персональный токен доступа без каких-либо областей, так как мы только читаем некоторую информацию для каждого репозитория GitHub.

Режимы выполнения

Обычное выполнение

В этом режиме RAUDI пытается собрать все инструменты, если это необходимо. Команда для запуска:

python3 ./raudi.py --all

Одиночная сборка

В этом режиме RAUDI пытается собрать только указанный инструмент. Команда в этом случае:

python3 ./raudi.py --single <имя_инструмента>

имя_инструмента ДОЛЖНО быть именем каталога внутри папки tools.

Тестирование инструмента

Поскольку в структуру конфигурации инструмента был добавлен параметр tests, это может быть полезно для проверки того, возвращают ли вставленные команды код состояния 0. Команда для тестирования конкретного инструмента:

python3 ./raudi.py --test <имя_инструмента>

имя_инструмента ДОЛЖНО быть именем каталога внутри папки tools.

Показать инструменты

Если вы хотите узнать доступные инструменты, выполните эту команду:

python3 ./raudi.py --list

Заготовка инструмента

Если вы хотите быстро добавить папку нового инструмента, используя один из доступных шаблонов, выполните эту команду:

python3 ./raudi.py --bootstrap <имя_нового_инструмента>

Опции

Доступные инструменты

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

Структура инструмента

Каждый инструмент в каталоге tools содержит как минимум два файла:

• config.py
• Dockerfile.
• README.md (необязательный README для Docker Hub)

Если вы хотите добавить новый инструмент, просто создайте папку для этого инструмента внутри каталога tools. В эту папку нужно поместить Dockerfile с определёнными build args для настройки и автоматизации сборки. После создания Dockerfile вы должны создать config.py в той же директории с функцией get_config(organization, common_args). Будьте внимательны: функция ДОЛЖНА называться именно так и ДОЛЖНА иметь эти два параметра (даже если вы их не используете). Возвращаемое значение — это конфигурация для этого конкретного инструмента, имеющая следующую структуру:

config =  {
    'name': organization+'/<имя_образа>',
    'version': '', # Должна быть вспомогательная функция
    'buildargs': {
    },
    'tests': []
  }

Четыре ключа:

• name: имя Docker-образа (например, secsi/<имя_инструмента>);
• version: номер версии Docker-образа. Для этого вы можете использовать вспомогательную функцию, которая может получить номер последней доступной версии (посмотрите на tools/ffuf в качестве примера);
• buildargs: словарь для указания частей Docker-образов, которые подлежат обновлению (опять же: посмотрите на tools/ffuf в качестве примера);
• tests: массив тестов (обычно просто один простой тест, например '--help').

После этого всё готово! Только будьте внимательны: имя инструмента ДОЛЖНО БЫТЬ ТАКИМ ЖЕ, как и директория, в которую вы поместили его Dockerfile.

Существует СОГЛАШЕНИЕ ПО ИМЕНОВАНИЮ для версий: используйте только ТОЧКИ и ЦИФРЫ; поэтому, пожалуйста, удалите все начальные символы 'v' из версии в соответствующем config.py (рабочий пример смотрите в tools/dirsearch/config.py).

Вспомогательные функции

Для получения последних версий и информации об инструментах и базовых образах был реализован набор вспомогательных функций. Если вы хотите добавить новый инструмент, вам следует использовать эти вспомогательные функции, чтобы получить Docker-образ, который автоматически обновляется RAUDI.

get_latest_pip_version

Эта вспомогательная функция используется для получения последней версии pip-пакета. Всё, что нужно — это имя пакета, и она возвращает номер версии. Пример:

VERSION = helper.get_latest_pip_version(package_name)

get_latest_npm_registry_version

Эта вспомогательная функция используется для получения последней версии npm-пакета. Всё, что нужно — это имя пакета, и она возвращает номер версии. Пример:

VERSION = helper.get_latest_npm_registry_version(package_name)

get_latest_github_release

Эта вспомогательная функция используется для получения информации о репозитории GitHub, который использует Releases и имеет несколько видов ассетов (например, исполняемые файлы для разных ОС). Эта функция принимает репозиторий (в формате user/repo) и целевую строку, чтобы определить правильный ассет для загрузки. Она возвращает словарь с двумя ключами (url и version). Пример:

VERSION = helper.get_latest_github_release("user/repo", "linux_amd64")

get_latest_github_release_no_browser_download

Эта вспомогательная функция используется для получения информации о репозитории GitHub, который использует Releases, но имеет только исходный код (то есть есть zipball и tarball). Эта функция принимает репозиторий (в формате user/repo) и возвращает словарь с двумя ключами (url и version). Пример:

VERSION = helper.get_latest_github_release_no_browser_download("user/repo")

get_latest_github_tag_no_browser_download

Эта вспомогательная функция используется для получения информации о репозитории GitHub, который использует Tags, но имеет только исходный код (то есть есть zipball и tarball). Эта функция принимает репозиторий (в формате user/repo) и возвращает словарь с двумя ключами (url и version). Пример:

VERSION = helper.get_latest_github_tag_no_browser_download("user/repo")

get_latest_github_commit

Эта вспомогательная функция используется для получения информации о репозитории GitHub, который не использует Tags или Releases. В этом случае цель — получить последний коммит. Эта функция принимает репозиторий (в формате user/repo) и возвращает строку, представляющую дату последнего коммита в формате YYYYMMDD.

VERSION = helper.get_latest_github_commit("user/repo")

Примеры

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

Общий пример

docker run -it --rm secsi/<инструмент> <команда>

Конкретный пример

docker run -it --rm -v <каталог_словников_на_хосте>:<каталог_словников_в_контейнере> secsi/dirb <url> <каталог_словников_в_контейнере>/<файл_словника>

Как произносить

Мы итальянцы, поэтому, вероятно, произносим это иначе, чем вы. Правильное произношение (с использованием фонетической транскрипции) следующее:

/ˈraʊdi/

Или представьте себе плюшевую собаку из известного телешоу Клиника: Rowdy

Вклад

Каждый может внести свой вклад! Мы создали очень подробный документ, описывающий как внести вклад в RAUDI.

Авторы

RAUDI разработан @SecSI следующими людьми:

• Angelo Delicato
• Daniele Capone
• Gaetano Perrone
• Gabriele Previtera

Другие участники:

• frost19k

Лицензия

RAUDI — это программное обеспечение с открытым исходным кодом, распространяемое под лицензией GNU GPL v3.