Skip to content

README.md

Latest commit

 

History

History
137 lines (100 loc) · 6.25 KB

README.md

File metadata and controls

137 lines (100 loc) · 6.25 KB
Raw

mtls.sh

CLI/TUI-менеджер mTLS-сертификатов для Traefik

CI License: MIT

Управляйте CA, клиентскими сертификатами, PKCS#12, отзывом и Traefik-конфигурацией из одного Bash-скрипта — без сетевых уведомлений и без передачи паролей через argv.

Возможности

  • создание и просмотр собственного CA;
  • выпуск, продление, проверка, отзыв и удаление клиентских сертификатов;
  • защищённые .p12-файлы и зашифрованный ключ CA;
  • shared или per-service CA bundle — отзыв в Traefik выполняется пересборкой bundle;
  • сервисы в режимах new и patch;
  • сохранение и применение именованных пресетов путей;
  • JSONL-аудит с ограниченной ротацией;
  • неинтерактивный CLI для автоматизации;
  • CI с Bash syntax check, ShellCheck и smoke/security tests.

Требования

  • Linux;
  • Bash 4+;
  • OpenSSL, Python 3, flock, gzip;
  • запуск от root — скрипт работает с приватным материалом.

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

Скрипт намеренно требует UID 0: он создаёт и читает приватные ключи CA и клиентов. Варианты запуска:

# Вариант A: каждый вызов получает root через sudo
sudo ./mtls.sh help
sudo ./mtls.sh ca create --cn my-root-ca

# Вариант B: открыть root-shell и запускать без повторного sudo
sudo -i
cd /path/to/mtls
bash ./mtls.sh help
bash ./mtls.sh ca create --cn my-root-ca
exit

После инициализации можно продолжить командами от root:

sudo ./mtls.sh service add --name api --domain api.example.test --target http://127.0.0.1:8080
sudo ./mtls.sh gen
sudo ./mtls.sh cert issue --service api --name alice --pass 'use-a-strong-password'
sudo ./mtls.sh cert verify --service api --name alice

sudo -i не является обязательным — это только удобный способ выполнить несколько операций в одной root-сессии. Никогда не запускайте скрипт от обычного пользователя.

Для production не передавайте секреты в командной строке: значение --pass может попасть в history или process list. Используйте интерактивный режим либо контролируемое окружение CI с защищёнными секретами.

CLI

ca create|info|backup|restore
cert issue|list|revoke|delete|renew|verify|scan
service add|list|delete|delete-full
preset save|apply|list|delete
config show|set
gen
audit [--last N]

Полная справка доступна командой sudo ./mtls.sh help.

Пресеты

sudo ./mtls.sh preset save --name staging \
  --traefik-path /etc/traefik/dynamic \
  --ca-path /etc/traefik/certs/mtls \
  --clients-path /etc/traefik/certs/mtls/clients \
  --output-file mtls-manager.yml
sudo ./mtls.sh preset apply --name staging
sudo ./mtls.sh preset list

Имена проходят строгую валидацию: запрещены /, .., __ и shell-метасимволы.

Модель безопасности

  • state-файлы создаются с mode 0600, каталоги с 0700;
  • запись выполняется атомарно, а symlink в destination отклоняется;
  • все внешние имена проходят whitelist-валидацию;
  • пароль OpenSSL передаётся через временный файл 0600, а не через argv;
  • CA и клиентский ключевой материал доступен только root;
  • блокировка БД предотвращает конкурентную порчу состояния;
  • audit log не отправляется по сети и ротируется после заданного лимита;
  • перед заменой Traefik YAML результат валидируется, исходный файл сохраняется как .bak;
  • crl.pem — дополнительный артефакт для внешних потребителей. Traefik использует bundle caFiles, поэтому отзыв в этом инструменте реализован исключением сертификата из bundle.

Это не заменяет hardening хоста: защищайте /etc/traefik, домашний каталог root, резервные копии и права доступа к CI secrets.

Конфигурация и файлы состояния

По умолчанию используются:

Файл Назначение
~/.mtls-manager.conf конфигурация
~/.mtls-manager.db записи сертификатов
~/.mtls-manager.services сервисы
~/.mtls-manager.presets пресеты путей
~/.mtls-manager.audit.jsonl audit log

Для тестов и изолированных установок доступны MTLS_CONFIG_FILE, MTLS_DB_FILE, MTLS_SERVICES_FILE, MTLS_PRESETS_FILE, MTLS_AUDIT_FILE.

CI/CD

Workflow .github/workflows/ci.yml запускается на push и pull request и выполняет:

  1. bash -n;
  2. ShellCheck;
  3. smoke-тест CLI;
  4. security invariants: отсутствие webhook/network/eval-пути, root guard, safe replace и файловых прав.

Локальный запуск:

bash -n mtls.sh tests/mtls_smoke.sh
bash tests/mtls_smoke.sh

Лицензия

MIT — opensophy-projects.