KeySloth
Ruby gem для безопасного управления зашифрованными секретами в Git репозиториях.
Описание
KeySloth решает проблему безопасного хранения и распространения секретов (сертификаты, ключи, конфигурационные файлы) в команде разработки. Вместо хранения секретов напрямую в репозитории, KeySloth шифрует их с использованием AES-256-GCM и позволяет безопасно синхронизировать между участниками команды и CI/CD системами.
Основные возможности
- 🔐 Надежное шифрование: AES-256-GCM с защитой целостности данных
- 🚀 Простота использования: Одна команда для получения/отправки секретов
- 🔄 Git интеграция: Работает с любыми Git репозиториями через SSH
- 🛡️ Безопасность: Многоуровневая защита с SSH ключами и шифрованием
- 📦 Backup'ы: Автоматическое создание резервных копий
- 🎯 CI/CD готовность: Поддержка переменных окружения для автоматизации
Типы файлов
Поддерживаются любые типы файлов (сертификаты, конфиги, изображения, бинарные и т.д.).
По умолчанию игнорируются при сборе и шифровании:
-
*.enc
(зашифрованные артефакты в репозитории) - содержимое
.git/
-
.DS_Store
,Thumbs.db
- локальный
README.md
в директории секретов
Зависимости
Для работы KeySloth требуются системные инструменты:
- Git CLI (должен быть доступен в PATH)
- SSH-клиент (обычно OpenSSH), используемый через переменную
GIT_SSH_COMMAND
Установка
gem install keysloth
Или добавьте в Gemfile:
gem 'keysloth'
Быстрый старт
1. Получение секретов
keysloth pull -r git@github.com:company/secrets.git -p your_password
2. Отправка секретов
keysloth push -r git@github.com:company/secrets.git -p your_password -m "Update certificates"
3. Проверка состояния
keysloth status
Использование
Команды
pull - Получение секретов
Получает зашифрованные секреты из Git репозитория и расшифровывает их локально:
keysloth pull --repo git@github.com:company/secrets.git \
--password your_secret_password \
--branch main \
--path ./secrets
Параметры:
-
--repo, -r
- URL Git репозитория (обязательно) -
--password, -p
- Пароль для расшифровки (обязательно) -
--branch, -b
- Ветка репозитория (по умолчанию: main) -
--path, -d
- Локальный путь для секретов (по умолчанию: ./secrets)
push - Отправка секретов
Шифрует локальные секреты и отправляет их в Git репозиторий:
keysloth push --repo git@github.com:company/secrets.git \
--password your_secret_password \
--message "Update mobile certificates" \
--branch main \
--path ./secrets
Параметры:
-
--repo, -r
- URL Git репозитория (обязательно) -
--password, -p
- Пароль для шифрования (обязательно) -
--branch, -b
- Ветка репозитория (по умолчанию: main) -
--path, -d
- Локальный путь с секретами (по умолчанию: ./secrets) -
--message, -m
- Сообщение коммита (опционально)
status - Проверка состояния
Показывает информацию о локальных секретах и доступных backup'ах:
keysloth status --path ./secrets
# без --path возьмёт путь из .keyslothrc (или дефолт)
restore - Восстановление из backup'а
Восстанавливает секреты из резервной копии:
keysloth restore secrets_backup_20231215_143022 --path ./secrets
# без --path возьмёт путь из .keyslothrc (или дефолт)
Конфигурационный файл
KeySloth поддерживает файл конфигурации .keyslothrc
в формате YAML:
# .keyslothrc
repo_url: "git@github.com:company/secrets.git"
branch: "main"
local_path: "./secrets"
backup_count: 3
Параметры командной строки имеют приоритет над конфигурационным файлом.
Дополнительно: файл конфигурации ищется автоматически, если путь не указан флагом --config
:
- сначала в текущей директории (
./.keyslothrc
) - затем в домашней директории (
~/.keyslothrc
)
Дефолтные значения при отсутствии флагов CLI и отсутствующих полях в конфиге:
-
branch
:main
-
local_path
:./secrets
-
backup_count
:3
-
repo_url
: отсутствует (должен быть указан явно через CLI или в конфиге)
Логирование
KeySloth поддерживает три уровня логирования:
# Подробное логирование (DEBUG)
keysloth pull -r repo_url -p password --verbose
# Тихий режим (только ошибки)
keysloth pull -r repo_url -p password --quiet
# Обычное логирование (INFO) - по умолчанию
keysloth pull -r repo_url -p password
Безопасность
Архитектура безопасности
KeySloth обеспечивает многоуровневую защиту:
- SSH аутентификация - доступ к репозиторию только через SSH ключи
- AES-256-GCM шифрование - надежное шифрование с защитой целостности
- PBKDF2 деривация ключей - безопасная генерация ключей из паролей
- Зашифрованное хранение - секреты хранятся зашифрованными в репозитории
Настройка SSH ключей
Локальная работа
Используйте стандартные SSH ключи:
# Генерируем SSH ключ если нет
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" # RSA
# или современный вариант:
ssh-keygen -t ed25519 -C "your_email@example.com" # Ed25519
# Добавляем публичный ключ в GitHub/GitLab
cat ~/.ssh/id_rsa.pub
# или
cat ~/.ssh/id_ed25519.pub
CI/CD настройка
Для автоматизации используйте переменные окружения:
# Экспортируем SSH ключ в переменную окружения
export SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)" # может быть RSA или Ed25519
export SSH_PUBLIC_KEY="$(cat ~/.ssh/id_rsa.pub)" # опционально
# Используем в CI/CD
keysloth pull -r git@github.com:company/secrets.git -p $SECRET_PASSWORD
Использование системного SSH (GIT_SSH_COMMAND)
При использовании ключей из переменных окружения в CI создаются временные файлы ключей и применяется GIT_SSH_COMMAND
, например:
export GIT_SSH_COMMAND='ssh -i /tmp/keysloth_ssh/id_rsa -o IdentitiesOnly=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'
Для локальной разработки отключать проверку хостов не рекомендуется.
Также можно явно указать путь к ключу через переменную окружения KEYSLOTH_SSH_KEY_PATH
(поддерживаются как RSA, так и Ed25519):
export KEYSLOTH_SSH_KEY_PATH="~/.ssh/id_ed25519"
Требования к автору коммита
Перед отправкой изменений должны быть настроены глобальные параметры Git:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
Поведение git-операций
- Клонирование по умолчанию:
git clone --depth 1
(shallow). - Если
git pull --ff-only
требует историю, выполняетсяgit fetch --unshallow
, затем повторpull
. - Перед записью новых файлов очищаются все
.enc
в репозитории:**/*.enc
.
Рекомендации по безопасности
- Сильные пароли: Используйте пароли длиной минимум 16 символов
- Ротация ключей: Регулярно обновляйте SSH ключи и пароли шифрования
- Ограниченный доступ: Предоставляйте доступ к репозиторию только необходимым участникам
- Аудит: Регулярно проверяйте логи доступа к репозиторию
- Backup'ы: Используйте автоматические backup'ы для восстановления
Интеграция с CI/CD
GitHub Actions
name: Deploy with Secrets
on: [push]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup SSH key
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
run: |
mkdir -p ~/.ssh
echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa
ssh-keyscan github.com >> ~/.ssh/known_hosts
- name: Install KeySloth
run: gem install keysloth
- name: Pull secrets
env:
SECRET_PASSWORD: ${{ secrets.SECRET_PASSWORD }}
run: |
keysloth pull -r git@github.com:company/secrets.git -p "$SECRET_PASSWORD"
- name: Deploy application
run: |
# Используем расшифрованные секреты для развертывания
./deploy.sh
GitLab CI
deploy:
stage: deploy
before_script:
- gem install keysloth
- mkdir -p ~/.ssh
- echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
- chmod 600 ~/.ssh/id_rsa
- ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
script:
- keysloth pull -r git@gitlab.com:company/secrets.git -p "$SECRET_PASSWORD"
- ./deploy.sh
variables:
SSH_PRIVATE_KEY: $SSH_PRIVATE_KEY
SECRET_PASSWORD: $SECRET_PASSWORD
Разработка
Установка для разработки
git clone https://github.com/keysloth/keysloth.git
cd keysloth
bundle install
Запуск тестов
# Все тесты
bundle exec rake spec
# Тесты с покрытием кода
COVERAGE=true bundle exec rake spec
# Линтинг кода
bundle exec rake rubocop
# Все проверки
bundle exec rake check
Структура проекта
keysloth/
├── lib/keysloth/ # Основная логика
│ ├── crypto.rb # Криптографические операции
│ ├── git_manager.rb # Работа с Git
│ ├── file_manager.rb # Файловые операции
│ ├── cli.rb # CLI интерфейс
│ ├── config.rb # Конфигурация
│ ├── logger.rb # Логирование
│ └── errors.rb # Обработка ошибок
├── bin/keysloth # Исполняемый файл
├── spec/ # Тесты RSpec
└── keysloth.gemspec # Спецификация gem'а
Лицензия
MIT License. См. LICENSE для деталей.
Поддержка
- Документация: GitHub Wiki
- Issues: GitHub Issues
- Обсуждения: GitHub Discussions
Troubleshooting
Часто встречающиеся проблемы
Ошибки аутентификации Git
Проблема: Permission denied (publickey)
при выполнении pull/push
Решение:
# Проверьте SSH ключи
ssh-add -l
# Добавьте SSH ключ если необходимо
ssh-add ~/.ssh/id_rsa
# или
ssh-add ~/.ssh/id_ed25519
# Проверьте соединение с GitHub/GitLab
ssh -T git@github.com
ssh -T git@gitlab.com
Ошибки расшифровки
Проблема: Неверный пароль или поврежденные данные
Решение:
- Проверьте правильность пароля
- Убедитесь что файлы не повреждены:
keysloth validate
- Попробуйте восстановить из backup'а:
keysloth restore
Ошибки файловой системы
Проблема: Permission denied
при создании/чтении файлов
Решение:
# Проверьте права доступа к директории
ls -la ./secrets
# Измените права если необходимо
chmod 755 ./secrets
chmod 644 ./secrets/*
Проблемы с Git репозиторием
Проблема: Repository not found
или Could not read from remote repository
Решение:
- Проверьте URL репозитория
- Убедитесь что у вас есть доступ к репозиторию
- Для приватных репозиториев проверьте SSH ключи
Ошибки в CI/CD
Проблема: Команды KeySloth не работают в CI/CD
Решение:
# Настройка SSH ключей в GitHub Actions
- name: Setup SSH key
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
run: |
mkdir -p ~/.ssh
echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa
ssh-keyscan github.com >> ~/.ssh/known_hosts
# Установка gem'а
- name: Install KeySloth
run: gem install keysloth
# Использование с переменными окружения
- name: Pull secrets
env:
SECRET_PASSWORD: ${{ secrets.SECRET_PASSWORD }}
run: keysloth pull -r $REPO_URL -p "$SECRET_PASSWORD"
Логирование для отладки
Используйте различные уровни логирования для диагностики:
# Подробное логирование для отладки
keysloth pull -r repo_url -p password --verbose
# Тихий режим для CI/CD
keysloth pull -r repo_url -p password --quiet
Backup и восстановление
При проблемах с секретами используйте backup'ы:
# Посмотреть доступные backup'ы
keysloth status
# Восстановить из backup'а
keysloth restore secrets_backup_20231215_143022
Получение помощи
Если проблема не решается:
-
Проверьте логи с флагом
--verbose
- Создайте минимальный пример для воспроизведения
-
Откройте issue в GitHub Issues с:
- Версией KeySloth (
keysloth version
) - Версией Ruby (
ruby --version
) - Полным текстом ошибки
- Шагами для воспроизведения
- Версией KeySloth (
Changelog
См. CHANGELOG.md для истории изменений.