Secrets en API-keys veilig beheren

Een secret hoort op één plek: in een secrets manager of in de secret store van je CI. Je applicatie haalt hem daar op bij het deployen of opstarten. Op je laptop staan alleen ontwikkelkeys met weinig rechten, in een .env die nooit in git komt, en elke key moet je kunnen vervangen zonder dat er iets stilvalt.

Wat in .env hoort

Een .env-bestand is prima voor lokale ontwikkeling. Zet het vanaf de eerste commit in .gitignore en commit een .env.example met alle namen en nepwaarden. Een nieuwe developer ziet dan meteen welke variabelen hij nodig heeft.

Gebruik lokaal alleen keys met weinig rechten, zoals de testmodus van je betaalprovider of een eigen ontwikkeldatabase. Productiesecrets horen niet op een laptop, ook niet op die van de lead.

Secrets blijven soms ongemerkt ergens hangen. Docker schrijft zelf dat build arguments en environment variables niet geschikt zijn om secrets aan een build mee te geven, omdat ze in het uiteindelijke image blijven staan. Gebruik daarvoor RUN --mount=type=secret. Log ook nooit je volledige configuratie bij het opstarten, zelfs niet in debugmodus.

Onze developers werken op beheerde, versleutelde laptops met centraal beheerde accounts en SSO met tweestapsverificatie (zie onze werkwijze). Dat beschermt de laptop, maar niet tegen een key die in een repository terechtkomt.

Een vault voor alles buiten je laptop

Voor staging en productie gebruik je een secrets manager. Dat kan die van je cloud zijn, zoals AWS Secrets Manager, Azure Key Vault of Google Secret Manager, of een losse tool als HashiCorp Vault. Welke je kiest, maakt minder uit dan dat er maar één is.

Regel de toegang per omgeving. Een developer kan de secrets van staging lezen, die van productie gaan alleen via de deploypipeline. In de audit log van de vault zie je wie wat heeft opgevraagd.

In CI wil je het liefst helemaal geen langlevende cloudkeys. GitHub Actions kan via OpenID Connect kortlevende tokens rechtstreeks bij je cloudprovider ophalen, onder andere bij AWS, Azure en Google Cloud. Dan staat er in je repository-instellingen geen cloudkey meer die kan uitlekken.

Regel rotatie voordat je het nodig hebt

Leg per secret vast wie de eigenaar is en hoe je hem vervangt. Doe dat nu, want midden in een incident wil je niet uitzoeken welke services hetzelfde databasewachtwoord gebruiken.

Roteer in elk geval als iemand het team verlaat, als een laptop kwijt is en als een key ergens heeft gestaan waar hij niet hoort. Voor keys met veel rechten spreek je daarnaast een vast ritme af.

Bouw je applicatie zo dat er tijdelijk twee geldige keys kunnen zijn, de oude en de nieuwe. Dan zet je de nieuwe erbij, deployt en trekt daarna de oude in, zonder downtime. Kortlevende tokens zijn nog beter: een token dat na een uur verloopt, hoef je niet te roteren.

Bij offboarding trek je ook de tokens in die iemand zelf heeft aangemaakt, zoals persoonlijke access tokens voor git of voor de cloud-CLI. Meer over toegang en offboarding staat in security en AVG bij remote developers.

Als een secret toch in git belandt

Ga ervan uit dat een gepushte key gelekt is, ook in een private repository. Er bestaan clones, forks, CI-caches en backups die je niet kunt overzien.

De eerste stap is daarom de key intrekken of roteren. GitHub zegt dat ook: trek de secret eerst in of roteer hem, en daarna is het herschrijven van de geschiedenis misschien niet eens meer nodig. Kijk vervolgens in de logs van de provider of de key is gebruikt.

Wil je de secret toch uit de geschiedenis halen, dan raadt GitHub git-filter-repo aan. Dat herschrijft commits, dus iedereen in het team moet daarna opnieuw clonen of rebasen. Spreek dat af voordat je force-pusht.

Voorkomen kost minder werk. Laat een secret scanner zoals gitleaks draaien als pre-commit hook, zodat een key je laptop niet verlaat, en zet op GitHub push protection aan. Voor je eigen account staat die standaard aan bij pushes naar publieke repositories. Op repositoryniveau moet een beheerder hem zelf aanzetten, en daarvoor is GitHub Secret Protection nodig.

AI-codeertools en secrets

Een AI-agent zoals Claude Code leest bestanden in je werkmap en voert commando's uit. Wat hij leest, gaat als context naar het model. Een .env met echte keys in je project is dus een risico, ook als je de tool vertrouwt.

Wij gebruiken Claude Code elke dag en hebben daarvoor twee afspraken.

Ten eerste staan er deny-regels in de gedeelde projectinstellingen, zoals Read(./.env) en Read(./.env.*) in .claude/settings.json, zodat ze voor iedereen in het team gelden. Volgens de documentatie blokkeren die regels de ingebouwde bestandstools en commando's die Claude Code herkent, zoals cat. Een script dat zelf een bestand opent, valt er niet onder. Voor een harde grens op OS-niveau verwijst de documentatie naar de sandbox.

Ten tweede houden we productiesecrets uit de werkmap. Wat er niet staat, kan geen enkele tool lezen, ook geen extensie of script waar je niet meer aan dacht.

Plak verder nooit een key in een prompt of een ticket, en let in code review op hardcoded keys, ook als een agent de code schreef. Meer afspraken over deze tools staan in AI-codeertools in een remote team.

Een checklist voor je repository

• .env staat in .gitignore en er is een .env.example.
• Een secret scanner draait als pre-commit hook en in CI.
• Push protection staat aan.
• Productiesecrets staan alleen in de vault of in de secret store van je CI.
• CI krijgt cloudtoegang via OIDC in plaats van met een vaste key.
• Per secret is bekend wie de eigenaar is en hoe je hem roteert.
• Deny-regels voor AI-tools staan in de gedeelde projectinstellingen.

Bronnen

• Docker: build secrets
• GitHub: OpenID Connect in GitHub Actions
• GitHub: gevoelige data uit een repository verwijderen
• GitHub: over push protection
• gitleaks
• Claude Code: permissions