Waarom we TruffleHog gebruiken: geheime sleutels uit uw code houden

Elke app die ik bouw praat met andere systemen: een database met klantgegevens, cloudopslag met ondertekende documenten en foto’s, een e-maildienst. Elk van die deuren gaat open met een geheime sleutel. Belandt zo’n sleutel in de code, en belandt die code op GitHub, dan kan iedereen die hem vindt naar binnen.

Voor een van de portalen die ik bouw, heb ik TruffleHog ingericht, een gratis open-source scanner voor geheimen, op twee controlepunten. Ik heb er ook een korte film over gemaakt voor iedereen die bij het project betrokken is, technisch of niet. De film is Engels gesproken, met Nederlandse ondertiteling. Bekijk hem hieronder en lees daarna verder voor de details en de precieze configuratie, klaar om over te nemen.

Het probleem in één minuut

Een geheim is een sleutel. API-sleutels, databasewachtwoorden, OAuth-clientgeheimen en tokens laten uw app een ander systeem openen. Wie de sleutel heeft, kan naar binnen, met dezelfde rechten als uw app.

Git vergeet niets. Elke commit is een momentopname, en GitHub bewaart elke momentopname, voor altijd. Een sleutel die één keer is gecommit, blijft in de geschiedenis staan, ook nadat u het bestand verwijdert.

Gelekte sleutels worden snel gevonden. Criminelen laten bots dag en nacht nieuwe openbare code doorzoeken. In het honeypotonderzoek van Orca Security uit 2023 werd een sleutel op GitHub al na zo’n twee minuten misbruikt. GitGuardian telde alleen al in 2024 23,8 miljoen nieuwe geheimen in openbare GitHub-commits.

Verwijderen is geen oplossing. De enige echte oplossing is roteren: maak een nieuwe sleutel en trek de oude in. Veel teams doen dat nooit. Volgens GitGuardian was 70% van de geheimen die in 2022 uitlekten jaren later nog steeds geldig.

Hoe TruffleHog helpt

TruffleHog snuffelt sleutels op die in code verstopt zitten, zoals een truffelvarken truffels in de grond opsnuffelt. Het herkent standaard meer dan 800 soorten inloggegevens, en u kunt eigen detectors toevoegen voor geheimen die het nog niet kent. Ik heb er een toegevoegd voor de vijf sleutels van deze app.

Ik laat het op twee controlepunten draaien.

Controlepunt 1: op uw eigen computer (pre-commit hook)

Voordat Git een commit opslaat, scant een hook wat er klaarstaat (de staged changes). Dat duurt minder dan een seconde. Vindt de hook een sleutel, dan wordt de commit geweigerd en ziet u het bestand en de regel. De sleutel verlaat uw computer nooit: de hook draait met --no-verification, dus TruffleHog stuurt een kandidaat niet eens naar de aanbieder om te testen of hij nog werkt.

Sla dit op als .githooks/pre-commit in uw repository:

#!/bin/sh
# Scans what is staged for secrets before it becomes a commit.
# Switch it on once per clone with:  git config core.hooksPath .githooks

# Windows: an editor keeps the PATH it started with, so also look where
# TruffleHog is installed by hand.
if ! command -v trufflehog >/dev/null 2>&1 && [ -n "$LOCALAPPDATA" ]; then
  dir="$LOCALAPPDATA/Programs/TruffleHog"
  if command -v cygpath >/dev/null 2>&1; then dir=$(cygpath -u "$dir"); fi
  if [ -x "$dir/trufflehog.exe" ]; then PATH="$dir:$PATH"; fi
fi

if ! command -v trufflehog >/dev/null 2>&1; then
  echo "pre-commit: trufflehog is not installed, staged changes were NOT scanned for secrets." >&2
  echo "pre-commit: install it from https://github.com/trufflesecurity/trufflehog/releases" >&2
  exit 0
fi

# --no-verification: a candidate is never sent out to test whether it is live.
trufflehog git file://. \
  --since-commit HEAD \
  --trust-local-git-config \
  --no-verification \
  --results=verified,unknown,unverified \
  --fail \
  --no-update
status=$?

if [ "$status" -eq 183 ]; then
  echo "pre-commit: TruffleHog found a secret in the staged changes. Commit refused." >&2
  exit 1
fi
if [ "$status" -ne 0 ]; then
  echo "pre-commit: TruffleHog could not finish the scan (exit $status). Commit refused." >&2
  exit 1
fi

Zet hem daarna aan, één keer per kloon:

git config core.hooksPath .githooks

Een paar keuzes die uitleg verdienen:

• Niet-geverifieerde resultaten tellen mee. Veel eigen geheimen van een app, zoals een service-role-sleutel van de database of een refresh token, kunnen niet via een openbare API worden bevestigd. Een controle die alleen bevestigde, werkende sleutels tegenhoudt, zou die doorlaten.
• Geen TruffleHog, geen blokkade. Is TruffleHog niet geïnstalleerd, dan gaat de commit door met een waarschuwing, omdat de GitHub-controle hieronder toch elke push scant. Een echte vondst blokkeert altijd.
• Valse meldingen. Zet een opmerking trufflehog:ignore op die regel. Sla de controle nooit over met git commit --no-verify.
• Collega’s op macOS en Linux. Maakt u de hook op Windows, markeer hem dan als uitvoerbaar in Git met git update-index --chmod=+x .githooks/pre-commit.
• Uw eigen geheimen. Detectors voor sleutels die TruffleHog niet kent, zet u in een .trufflehog.yml; voeg dan --config .trufflehog.yml toe aan beide controlepunten.

Controlepunt 2: op GitHub (GitHub Actions)

Het tweede controlepunt vangt op wat langs het eerste is geglipt: een collega zonder de hook, of een commit met --no-verify. Elke push, op elke branch, wordt gescand op de commits die hij toevoegt. Elke maandag, en wanneer u hem met de hand start, wordt de hele geschiedenis gescand, omdat een detector die sinds de vorige keer aan TruffleHog is toegevoegd kan vinden wat een eerdere scan miste.

Sla dit op als .github/workflows/secret-scan.yml:

name: Secret scan

on:
  push:
  schedule:
    - cron: "40 4 * * 1" # Mondays: the whole history
  workflow_dispatch:

permissions:
  contents: read

jobs:
  trufflehog:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: TruffleHog
        uses: trufflesecurity/trufflehog@e76dff8a7e57d6df0c60ad8cbf5d5cba505a8fc9 # v3.99.2
        with:
          version: 3.99.2
          extra_args: --results=verified,unknown,unverified

Wordt er iets gevonden, dan kleurt de run rood met exitcode 183 en een annotatie die naar het bestand en de regel wijst, en GitHub stuurt een e-mail over de mislukte run. Beide actions zijn vastgezet op een commit, zodat de controle nooit draait wat er toevallig als laatste is gepubliceerd.

We hebben het getest

Met verzonnen sleutels die nergens ooit hebben gewerkt:

• Een testupload naar GitHub: de controle kleurde rood.
• Een sleutel in een commit: geweigerd op de computer, niets verstuurd.
• Een editor die TruffleHog niet in zijn PATH kon vinden: toch geweigerd.
• De hele geschiedenis van het project: schoon, geen sleutels gevonden.

Wat het niet doet

TruffleHog herkent echte sleutels in echte formaten, plus de detectors die u zelf toevoegt. Het slaat niet aan op mijn geheim: 1234 alleen omdat het woord “geheim” erin staat. Goede gewoontes blijven dus belangrijk. Sleutels horen in:

• een lokaal instellingenbestand zoals .env, dat in .gitignore staat en nooit wordt geüpload, of
• de omgevingsvariabelen van uw hostingdienst, zoals Netlify, Vercel of Azure.

Nooit in de code zelf.

Waarom het best practice is

• Het kost niets. TruffleHog is gratis en open source, en een controle duurt minder dan een seconde.
• Het voorkomt dure ongelukken. Misbruikte cloudaccounts, onverwachte rekeningen, gelekte klantgegevens. Onder de AVG moet een datalek met persoonsgegevens meestal binnen 72 uur worden gemeld bij de Autoriteit Persoonsgegevens.
• Het is wat beveiligingsexperts adviseren. De OWASP Secrets Management Cheat Sheet zegt het duidelijk: houd geheimen uit code, en spoor ze automatisch op.

Als er toch een sleutel lekt

Ga ervan uit dat hij al wordt gebruikt:

1. Roteer hem meteen. Maak een nieuwe sleutel, werk uw app bij en trek de oude in.
2. Meld het aan de verantwoordelijke, en controleer de logboeken van de aanbieder op activiteit die u niet herkent.
3. Pas daarna kunt u overwegen de Git-geschiedenis op te schonen. Geschiedenis herschrijven maakt een gelekte sleutel niet weer veilig; roteren wel.

Nu u

1. Installeer TruffleHog: brew install trufflehog op macOS, of download het van de officiële releasepagina voor Windows en Linux.
2. Zet het controlepunt aan: voeg de hook toe en voer git config core.hooksPath .githooks uit op elke computer.
3. Laat de GitHub-controle aan staan: bij elke push, en elke maandag.

Houdt TruffleHog u ooit tegen, ga er dan niet omheen: haal de sleutel eruit. Een kleine moeite, voor een grote bescherming.

Wilt u dit ingericht hebben voor de repositories van uw team, of een snelle controle van wat er al in uw Git-geschiedenis staat? Neem contact op en ik help u beide controlepunten in te richten.

Bronnen

• GitGuardian, The State of Secrets Sprawl 2025: 23,8 miljoen geheimen op openbaar GitHub in 2024; 70% van de in 2022 gelekte geheimen nog geldig.
• Orca Security, Honeypotting in the Cloud Report 2023: een sleutel op GitHub werd zo’n twee minuten later misbruikt.
• AVG, artikel 33: een datalek met persoonsgegevens wordt binnen 72 uur gemeld bij de toezichthouder, tenzij het waarschijnlijk geen risico voor mensen oplevert.
• OWASP, Secrets Management Cheat Sheet: houd geheimen uit code en spoor ze automatisch op.
• TruffleHog op GitHub: de gratis open-source scanner die hier wordt gebruikt.