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'

keysloth pull -r git@github.com:company/secrets.git -p your_password

keysloth push -r git@github.com:company/secrets.git -p your_password -m "Update certificates"

keysloth status

Получает зашифрованные секреты из 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)

Шифрует локальные секреты и отправляет их в 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 - Сообщение коммита (опционально)

Показывает информацию о локальных секретах и доступных backup'ах:

keysloth status --path ./secrets
# без --path возьмёт путь из .keyslothrc (или дефолт)

Восстанавливает секреты из резервной копии:

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 обеспечивает многоуровневую защиту:

1. SSH аутентификация - доступ к репозиторию только через SSH ключи
2. AES-256-GCM шифрование - надежное шифрование с защитой целостности
3. PBKDF2 деривация ключей - безопасная генерация ключей из паролей
4. Зашифрованное хранение - секреты хранятся зашифрованными в репозитории

Используйте стандартные 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

Для автоматизации используйте переменные окружения:

# Экспортируем 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

При использовании ключей из переменных окружения в 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 clone --depth 1 (shallow).
• Если git pull --ff-only требует историю, выполняется git fetch --unshallow, затем повтор pull.
• Перед записью новых файлов очищаются все .enc в репозитории: **/*.enc.

1. Сильные пароли: Используйте пароли длиной минимум 16 символов
2. Ротация ключей: Регулярно обновляйте SSH ключи и пароли шифрования
3. Ограниченный доступ: Предоставляйте доступ к репозиторию только необходимым участникам
4. Аудит: Регулярно проверяйте логи доступа к репозиторию
5. Backup'ы: Используйте автоматические backup'ы для восстановления

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

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

Проблема: 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

Проблема: Неверный пароль или поврежденные данные

Решение:

1. Проверьте правильность пароля
2. Убедитесь что файлы не повреждены: keysloth validate
3. Попробуйте восстановить из backup'а: keysloth restore

Проблема: Permission denied при создании/чтении файлов

Решение:

# Проверьте права доступа к директории
ls -la ./secrets

# Измените права если необходимо
chmod 755 ./secrets
chmod 644 ./secrets/*

Проблема: Repository not found или Could not read from remote repository

Решение:

1. Проверьте URL репозитория
2. Убедитесь что у вас есть доступ к репозиторию
3. Для приватных репозиториев проверьте SSH ключи

Проблема: Команды 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'ы
keysloth status

# Восстановить из backup'а
keysloth restore secrets_backup_20231215_143022

Если проблема не решается:

1. Проверьте логи с флагом --verbose
2. Создайте минимальный пример для воспроизведения
3. Откройте issue в GitHub Issues с:
   • Версией KeySloth (keysloth version)
   • Версией Ruby (ruby --version)
   • Полным текстом ошибки
   • Шагами для воспроизведения

См. CHANGELOG.md для истории изменений.