Безопасное хранение ключей на своей машине: инструкция

API-ключ, оставленный в исходнике или файле конфигурации, может попасть в Git, резервную копию или логи. За 15–20 минут вы настроите безопасную базовую схему для локальной разработки на macOS или Linux: секрет будет лежать вне кода, файл получит закрытые права, а Git перестанет его отслеживать. Для продакшена и ключей с большими правами этого недостаточно — в конце разберём следующий уровень защиты.

Что понадобится до начала

Инструкция рассчитана на Git 2.x, Bash или Zsh и macOS либо Linux. Проверьте, что у вас есть:

• папка проекта, уже созданная на компьютере;
• установленный Git и доступ к терминалу;
• ключ, который нужно использовать локально;
• возможность перезапустить приложение после изменения переменных окружения.

На Windows те же принципы работают через PowerShell и настройки переменных среды, но команды chmod и проверки Unix-прав из этой инструкции не применяются. Не храните ключ в файле проекта до первого шага: если он уже опубликован, его нужно отозвать и выпустить заново.

Сноска. Переменная окружения — значение, которое операционная система передаёт запущенному процессу. Приложение получает его во время запуска, но значение не обязано находиться в исходном коде.

Пошаговая настройка

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

   cd /path/to/your-project
   git status

   Замените /path/to/your-project на реальный путь без вставки ключа в команду. Если проект ещё не является Git-репозиторием, команда git status сообщит об этом — это не ошибка для текущего шага. Проверка: терминал показывает путь к вашему проекту, а команда не запускается в домашней папке или другой директории.

2. Создайте локальный файл секретов. Файл .env будет находиться рядом с кодом, но не попадёт в репозиторий. Введите ключ скрытым вводом:

   read -r -s API_KEY
   printf '\n'
   printf 'API_KEY=%s\n' "$API_KEY" > .env
   unset API_KEY

   После read терминал не показывает введённые символы. Имя API_KEY замените на имя, которое ожидает ваше приложение. Проверка: команда ls -la .env показывает файл, а команда cat .env выводит только его содержимое — не публикуйте этот вывод и не вставляйте его в чат.

3. Запретите Git отслеживать секреты. Откройте или создайте .gitignore и добавьте правила:

   cat >> .gitignore <<'EOF'
   .env
   .env.*
   !.env.example
   EOF

   Правило !.env.example оставляет возможность хранить безопасный шаблон без настоящих значений. Проверка: выполните git status --short после создания или изменения .env; в списке не должно быть строки ?? .env или изменений этого файла.

4. Оставьте шаблон для команды. В шаблоне указывают только имена переменных и понятные заглушки:

   cat > .env.example <<'EOF'
   API_KEY=YOUR_API_KEY
   EOF

   Значение YOUR_API_KEY не является ключом и не должно работать с внешним сервисом. Добавьте шаблон в Git, если он нужен другим разработчикам. Проверка: команда grep -n 'YOUR_API_KEY' .env.example показывает заглушку, а команда grep -n 'YOUR_API_KEY' .env не должна применяться для проверки настоящего секрета — содержимое локального файла лучше не выводить.

5. Закройте права на файл. На macOS и Linux выполните:

   chmod 600 .env
   ls -l .env

   Режим 600 разрешает владельцу читать и изменять файл, а группе и остальным пользователям — ничего с ним не делать. Проверка: в выводе ls -l после имени файла отображается примерно -rw-------. На общей машине отдельно проверьте, кто владеет каталогом проекта.

6. Передайте значение приложению. Сам по себе файл .env не становится переменной окружения автоматически. Если ваш фреймворк или инструмент умеет читать dotenv-файлы, включите его штатный загрузчик. Для временной проверки в текущем Bash или Zsh можно загрузить собственный файл так:

   set -a
   . ./.env
   set +a
   test -n "$API_KEY" && echo 'API_KEY is set'

   Не выполняйте эту команду для файла, скачанного из интернета: конструкция с точкой исполняет команды, содержащиеся в файле. Проверка: терминал печатает API_KEY is set, но не само значение. После закрытия терминала переменная исчезнет, если приложение не загрузит её снова.

7. Проверьте репозиторий и историю. Выполните безопасные проверки:

   git status --short
   git grep -n 'API_KEY' -- ':!.env' ':!.env.example'

   Первая команда проверяет текущие изменения, вторая ищет имя переменной в отслеживаемых файлах, исключая локальный файл и шаблон. Проверка: среди результатов нет настоящего ключа и нет строки с его значением в исходниках, конфигурации или документации.

Закрытый файл — это только базовая гигиена. Если ключ уже попал в Git, удаление файла не делает его безопасным: секрет нужно отозвать у сервиса.

Если не получилось

Git показывает ?? .env

Файл создан раньше, чем правило попало в .gitignore, или правило записано не в тот репозиторий. Проверьте командой git rev-parse --show-toplevel, где находится корень репозитория, затем убедитесь, что в его корневом .gitignore есть строка .env. Если файл уже добавляли через git add, одной записи в .gitignore недостаточно: сначала уберите его из индекса командой git restore --staged .env, не удаляя локальный файл.

Приложение сообщает, что ключ не задан

Чаще всего процесс не загрузил .env, переменная названа иначе или приложение запускается из другого терминала. Сверьте имя с документацией библиотеки и проверьте наличие без вывода значения: test -n "$API_KEY" && echo set || echo missing. После изменения файла перезапустите приложение.

Команда chmod не найдена

Вы, вероятно, работаете не в macOS или Linux, а в Windows PowerShell. Не копируйте Unix-команды в PowerShell: храните секрет в пользовательской переменной среды через системные настройки Windows или используйте менеджер секретов, поддерживаемый вашим инструментом. В Git Bash команда может быть доступна, но права Windows всё равно нужно проверять через свойства файла и вкладку безопасности.

Ключ уже оказался в коммите

Сразу отзовите его в панели сервиса и создайте новый. Удаление файла новым коммитом не удаляет значение из старых коммитов, клонов, архивов и CI-логов. Переписывание истории требует отдельного плана: оно меняет хеши коммитов и может повредить работающим клонам.

Ключ появляется в логах

Проверьте отладочный режим, сообщения HTTP-клиента и обработчики ошибок. Не логируйте заголовки авторизации, строки подключения и полные ответы внешних API. После исправления считайте ключ скомпрометированным и замените его, если он мог попасть в файл лога или систему сбора ошибок.

Что эта схема не защищает

Файл .env защищает от случайного коммита, но не от вредоносной программы с правами вашего пользователя, резервной копии без шифрования или человека, который получил доступ к вашей учётной записи. Переменная окружения также может попасть в дамп процесса, диагностический отчёт или журнал CI.

Для ключей с доступом к платежам, удалению данных или продакшену используйте менеджер секретов либо системное хранилище ключей, а приложению выдавайте минимальные права. Для локальной разработки можно хранить секрет в связке ключей macOS, Windows Credential Manager или защищённом хранилище Linux, если используемый инструмент умеет обращаться к нему напрямую. Название механизма зависит от ОС и конкретного клиента, поэтому не подменяйте его самодельным шифрованием в репозитории.

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

Что делать дальше

Сначала добавьте проверку в pre-commit или CI, которая ищет секреты в изменениях, но не выводит найденные строки в лог. Затем проверьте резервные копии и историю репозитория: секрет мог попасть туда до настройки .gitignore. Для продакшена измеряйте не количество файлов с .env, а время отзыва ключа, наличие ротации и долю токенов с минимальными правами. Базовые правила работы с секретами и ограничения этой схемы описаны в руководстве OWASP.