Що таке secrets management і чому токени не живуть у коді

Зачіпка

Secrets management — це дисципліна, яка не дає токенам, паролям і ключам перетворитися на міну всередині репозиторію. Код можна показувати команді, рев’юерам і CI/CD. Секрети так не працюють.

Якщо API key потрапив у git, проблема не зникає після видалення одного рядка. Він уже міг потрапити в історію комітів, форки, кеші, логи build-системи або чужий локальний клон. Тому головне правило просте: секрети не живуть у коді.

Проблема / Контекст

На малих проєктах усе часто починається невинно. Один токен кладуть у .env, другий пересилають у чаті, пароль від бази записують у нотатку, а ключ для deploy додають у GitHub Actions. Поки команда маленька, здається, що це контрольовано.

Потім з’являються staging, production, кілька розробників, підрядник, CI/CD, Docker, моніторинг і інтеграції. Стає незрозуміло, який токен де використовується, хто має доступ, коли його востаннє міняли і що зламається після rotation. У цей момент секрети вже не просто налаштування. Це частина security-моделі продукту.

Secrets management потрібен саме для цієї точки. Він відповідає на практичні питання:

• де секрети зберігаються;
• хто може їх читати;
• як вони потрапляють у застосунок;
• як обмежені їхні права;
• як швидко їх можна відкликати;
• як команда дізнається, що секрет випадково засвітився.

Хороша система не змушує розробника копіювати production-пароль у локальний файл. Вона дає окремі секрети для різних середовищ, мінімальні права для кожного токена і зрозумілу процедуру заміни.

Чому це важливо

Витік секрету часто виглядає як дрібна помилка, але наслідки можуть бути дуже дорогими. Через один токен можна прочитати приватний репозиторій, видалити дані, створити дорогі cloud-ресурси, відправити spam, зламати deploy pipeline або отримати доступ до production.

Найнеприємніше, що секрети часто використовуються машинами, а не людьми. Людина може помітити підозрілий login. А токен може тихо працювати тижнями, якщо його права надто широкі і немає audit log. Саме тому важливі token scope, secret scanning і регулярна rotation.

Secrets management також зменшує людський стрес. Коли все лежить у випадкових місцях, кожен incident перетворюється на пошук: де цей ключ, хто його створив, чи можна його вимкнути, чи впаде production. Коли є vault або хоча б дисциплінований secrets store у платформі, відповідь швидша і спокійніша.

Схема в голові

Уяви репозиторій як інструкцію до будинку, а секрети як ключі від дверей. Інструкцію можна показувати будівельникам. Ключі від квартири не вклеюють у кожну копію інструкції.

Практична схема така:

• код містить назви змінних і очікувану конфігурацію;
• local development бере тестові значення з локального .env, який не потрапляє в git;
• CI/CD бере секрети з налаштувань платформи;
• production отримує секрети з vault або secrets manager;
• кожне середовище має окремі значення;
• кожен токен має мінімальний token scope;
• secret scanning ловить випадкові витоки до merge або одразу після push.

Це не обов’язково має бути складний enterprise vault із першого дня. Для маленького проєкту нормальний старт — .gitignore, приклад .env.example, секрети в GitHub Actions, окремі production-змінні на хостингу і ввімкнений secret scanning. Важливо, щоб це була система, а не набір випадкових домовленостей.

Як це зробити

1. Проведи інвентаризацію

Спочатку склади список усього, що є секретом. Зазвичай це:

• database URL;
• API key зовнішнього сервісу;
• OAuth client secret;
• webhook secret;
• SSH key або deploy token;
• JWT signing key;
• encryption key;
• admin password;
• cloud access token.

Не обмежуйся .env. Перевір README, документацію, Dockerfile, docker compose, CI/CD logs, issue, старі snippets і історію git. Секрети часто живуть там, де їх колись було “зручно тимчасово залишити”.

2. Розділи середовища

Development, staging і production не мають ділити один і той самий токен. Якщо локальний ноутбук отримує production-доступ, будь-який локальний malware або випадковий commit стає production-ризиком.

Мінімальна здорова модель:

• development використовує тестові ключі або sandbox;
• staging має окремі інтеграції і тестові дані;
• production має найвужчі права і найсуворіший доступ;
• break-glass access існує, але не використовується щодня.

3. Прибери секрети з коду

У коді мають лишатися тільки імена змінних: DATABASE_URL, STRIPE_SECRET_KEY, GITHUB_TOKEN. Значення приходять із середовища виконання.

Для локальної роботи:

• додай .env у .gitignore;
• створи .env.example без реальних значень;
• опиши, де взяти тестові ключі;
• не проси людей копіювати production-секрети.

Для CI/CD:

• використовуй secrets store платформи;
• не друкуй секрети в logs;
• не передавай секрети в build args, якщо вони потім можуть залишитися в image layer;
• розділяй secrets для pull request, staging і production workflow.

4. Обмеж права

Токен “на все” зручний лише до першого витоку. Краще мати кілька вузьких токенів:

• read-only token для читання API;
• deploy token тільки для конкретного середовища;
• окремий webhook secret для перевірки підпису;
• service account без доступу до зайвих проєктів.

Principle of least privilege звучить сухо, але в житті означає просту річ: якщо токен потрібен тільки для читання, він не має вміти видаляти дані.

5. Увімкни detection і rotation

Secret scanning має працювати до того, як витік стане новиною. У GitHub це можна зробити на рівні репозиторію або організації. Для self-hosted Git можна додати перевірку в CI/CD або pre-commit.

Якщо секрет уже потрапив у git, не достатньо видалити його з файлу. Правильний порядок такий:

1. відкликати старий секрет;
2. створити новий із мінімальними правами;
3. оновити secrets store;
4. перевірити deploy і runtime;
5. прибрати секрет з історії, якщо це потрібно для зменшення майбутнього ризику;
6. зафіксувати incident і причину.

Rotation має бути не героїчним нічним ритуалом, а звичайною процедурою. Якщо команда боїться міняти токен, значить secrets management ще не дороблений.

Типові помилки

• комітити .env і сподіватися, що приватний репозиторій усе захистить;
• використовувати один production-токен у development, staging і CI/CD;
• зберігати секрети в README, Notion, чатах або issue;
• давати токену admin-права, коли потрібен read-only доступ;
• друкувати секрети в logs для “debug на хвилинку”;
• передавати секрети в Docker image так, що вони лишаються в layer history;
• видаляти засвічений ключ із файлу, але не відкликати його;
• не мати відповідального за rotation;
• не перевіряти secret scanning на старих комітах.

Висновок / План дій

Secrets management — це не параноя і не enterprise-розкіш. Це базова гігієна проєкту, який має токени, базу даних, CI/CD або production.

Почни з малого:

1. знайди всі секрети в проєкті;
2. прибери реальні значення з коду;
3. додай .env.example;
4. перенеси CI/CD і production-секрети в secrets store;
5. розділи development, staging і production;
6. обмеж token scope;
7. увімкни secret scanning;
8. напиши короткий rotation-план.

Коли секрети живуть окремо від коду, deploy стає спокійнішим, рев’ю безпечнішим, а incident не починається з фрази “здається, ми закомітили ключ”.

Офіційні джерела:

• https://12factor.net/config
• https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning
• https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
• https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html