detect-secrets: titkos kulcsok vizsgálata becommitolt baseline-nal

A detect-secrets a Yelp Apache-2.0 licenceű titkos kulcsfigyelője Git-repókhoz, és az, ami megkülönbözteti minden mástól, a baseline. Elfogadod, hogy a repóban már lehetnek titkok, rögzíted, mi van benne, és onnantól csak az újat blokkolja. Ez szándékosan lehangolt tervezés, és egy olyan kódbázisnál, amelyre senkinek nincs ideje rendrakni, továbbra is ez a jó forma. A probléma a karbantartottság: az 1.5.0-s verzió 2024. május 6-áról származik és még mindig a legfrissebb kiadás, a masteren landoló utolsó commit pedig 2026 áprilisában volt.

Ugyanoda tartozik, mint a gitleaks és a TruffleHog: a commit vagy a pipeline elé. Nem secret manager, hanem keres, blokkol, és átad egy listát a rotáláshoz. A GitHub saját secret scanningje csak a GitHubon tárolt repókat fedi le, a privát repókhoz GitHub Secret Protection kell, GitLabhez, Bitbuckethez vagy saját szerverhez pedig semmi. Hogy illeszkedik egy szkenner az ügynökök sandboxolásának történetébe, arról a coding agentek sandboxolása a CI-ban cikk szól.

Mi ez

A csomag három parancsot ad, és a README szokatlanul egyértelmű arról, melyik mikor kell. A detect-secrets scan létrehozza vagy frissíti a baseline-t, a detect-secrets-hook egy fájllistát ellenőriz vele, és nem nulla kilépési kóddal tér vissza, ha bármi új jelenik meg, a detect-secrets audit pedig egy interaktív menet, amely valódi titkosnak vagy zajnak jelöli a találatokat, és ezeket a jelöléseket visszaírja a baseline-ba.

• Python, Apache-2.0, 1.5.0 verzió, 2024. május 6-án jelent meg, 4.649 csillaggal és 573 forkkal. A PyPI-osztályozó production/stable értéket ír, ami inkább az API-ra vonatkozik, mint az ütemtervre.
• 27 detektor listáz a --list-all-plugins kapcsolóval, három családban: regex szabályok az AWS, GitHub, GitLab, Slack, Stripe, OpenAI, npm, PyPI, Telegram, Twilio és privát kulcsok számára; entrópia-detektorok Base64 és hex stringekre; és egy kulcsszó-detektor, amely az értéket figyelmen kívül hagyja, és a password jellegű nevekre való hozzárendeléseket jelöli.
• A szűrők a pluginek után futnak, és döntik el, mi marad: --exclude-files, --exclude-lines, --exclude-secrets, a saját azonosítóidból álló szólista és a soron belüli pragmák.
• Az ellenőrzés alapból be van kapcsolva. A felismert mintáknál a tool rákérdez a kibocsátó szolgáltatásnál, hogy valódi-e a titok. A -n (--no-verify) kikapcsolja, a --only-verified pedig csak a megerősítetteket hagyja meg.
• A baseline maga az egész állapot. Egy JSON-fájl a repóban, amely a plugin- és szűrőbeállításokat meg minden találat lenyomtatott ujjlenyomatát tartalmazza.
• Az audit a mérés. A jelölések miatt a detect-secrets audit --stats megmondja, hogy egy-egy detektor mennyire teljesít a te kódodban, és ez az egyetlen becsületes hangolási út.
• Három felhasználási mód: pre-commit hook, CI-feladat a stage-elt vagy verziózott fájlokra, vagy könyvtárként a SecretsCollection osztályon keresztül, ha a saját eszközláncodba kell.

Hogyan működik

A motor két lépcsős. A pluginek potenciális titkokat állítanak elő, majd a szűrők és az ellenőrzési szabály dönti el, mi kerül ténylegesen a jelentésbe. A transformerek előbb normalizálják a bemenetet, ezért az INI-, YAML-, XML- és Markdown-fájlok formányonkénti külön esetek nélkül vizsgálhatók soronként. A két felet összekötő, szerializálható settings-objektum a baseline-ban utazik, így a CI-futón futó vizsgálat pontosan azt a konfigurációt használja, amelyik a fájlt a gépeden létrehozta.

Az ellenőrzés az a mechanizmus, amely eldönti, hogy használható-e a tool a gyakorlatban. A 0.12.4 óta egy plugin implementálhat verify függvényt, amely rákérdez a kibocsátó szolgáltatásnál, hogy él-e még a titok, a keyhacks projektben összegyűjtött technikákat használva. Az ellenőrzés öt sor kontextust is kap a találat előtt és után, mert az ezt alátámasztó kutatás szerint 80 százalék eséllyel megtalálható a többfaktoros titok második fele a közelben. A pontosságnövekedés nagy; az ár az egy kimenő hálózati kérés minden olyan commitnál, amely érint egy megfelelő sort.

A baseline utána elvégzi a belügyek szétválasztását. A detect-secrets scan --baseline .secrets.baseline újra átvizsgálja a fát, a fájlt a jelenlegi formátumra migrálja, hozzáadja az új találatokat, eldobja az eltűnteket, és megőrzi az audit jelöléseit, így a diff átnézhető marad. A --slim kapcsoló tovább megy, és minimalizálja a commitok közötti diffet, de ez az audit funkció ára: a karcsú baseline-okat később már nem lehet auditálni, újra kell őket gyártani.

Első lépések

A telepítés a pip install detect-secrets vagy a brew install detect-secrets. Az 1.5.0 a Python 3.8 és 3.12 közötti verziókat támogatja, a 3.6-ot és 3.7-et eldobta; a masteren már ott a Python 3.13 támogatás is, de ez egy kiadásban sincs bent, ezért 3.13 környezetben gitből kell telepíteni. A dokumentált beállítás egy pre-commit hook, aminek a baseline az argumentuma.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']
        exclude: package.lock.json

Ezután egyszer hozd létre a baseline-t a repó gyökerében, és commitold be. Attól kezdve a hook minden commitnál fut, és csak azoknál a soroknál bukik el, amelyek nincsenek a fájlban. Egy régi repó első vizsgálata több ezer találatot is visszaadhat, és pontosan erre való a baseline.

pip install detect-secrets

# once, from the repository root: record what is already there
detect-secrets scan > .secrets.baseline

# after real leaks are rotated, or the repo legitimately grew
detect-secrets scan --baseline .secrets.baseline

# label findings once, then keep the labels
detect-secrets audit .secrets.baseline

# CI: fail the build on anything the baseline does not list
git diff --staged --name-only -z | xargs -0 \
  detect-secrets-hook --baseline .secrets.baseline

A soron belüli engedélyezés a munkafolyamat másik fele. Az a sor, amely # pragma: allowlist secret végződéssel zárul, vagy amely fölött // pragma: allowlist nextline secret áll, kimarad anélkül, hogy hozzáérne a baseline-hoz, és ez a jó eszköz egy tesztfixture-höz vagy egy dokumentációs példához. A detect-secrets scan --only-allowlisted megfordítja az ellenőrzést, és pont azokat a sorokat jelenti, így a pragma nem válhat csendben a valódi titkok búvóhelyévé.

Jel és zaj

Alapállapotban a detektorok egy általános repóra vannak hangolva, és a következő munka az, hogy a tieidre hangoljuk őket. Az audit lépés nem Formság: ez az egyetlen elérhető mérés, és kézzel végzik.

1. Generáld a baseline-t, majd jelölj egy reprezentatív mintát a detect-secrets audit paranccsal. A lista többi pontja enélkül nem működik.
2. Olvasd el a statisztikát. Azokat a detektorokat, amelyek nagyrészt zajt termelnek, kapcsold ki a --disable-plugin kapcsolóval, vagy szűkítsd a --exclude-files és --exclude-lines szabályokkal.
3. Ne detektorokat törölj, hanem az entrópia-küszöböket told: a --base64-limit alapértéke 4.5, a --hex-limit értéke 3.0, és ez a két tekerő, amit a tool ad.
4. Adj hozzá saját azonosítólistát a --word-list kapcsolóval, ehhez a detect-secrets[word_list] extra kell.
5. Érdemes megfontolni az opcionális gibberish modellt azokhoz a titkokhoz, amelyek szónak látszanak. Alapból nincs bekapcsolva, mert a password jellegű értékeket is átugorja.
6. Minden változtatás után futtasd újra a vizsgálatot a --baseline kapcsolóval, és olvasd el a baseline-fájl diffjét. A kisebb diff kevesebb zajt jelent, nem kevesebb titkot.

A rotálási munkafolyamat

A harmadik parancs fizeti meg a hangolást, és nem új dolgot keres. Az audit jelölések is_secret értéket írnak a baseline-ba; a --report kapcsolóval együtt ebből jön ki az a lista, amelyen a repóban még meglepő titkok vannak, és amelyeket cserélni kell. Ez a lista alakítja a vizsgálatot tulajdonossal és határidővel rendelkező biztonsági feladattá.

• Előbb jelölj, aztán riportálj. A baseline-ban valódi titkosként megjelölt találat egy migrációs lista bejegyzése.
• A szolgáltatónál rotálj, ne a repóban. A fájl törlése nem változtat semmit azon, hogy a kulcs működik-e.
• Utána futtasd újra a --baseline kapcsolóval. A találat eltűnik a fájliból, és ez a diff bizonyítja, hogy a migráció kész van.
• A history vizsgálatát tartsd külön. A tool soha nem néz bele régi commitokba, az átírás vagy az egyszeri history-scan más feladat.

Ez az a belügyek szétválasztása, amit a README leír, és még mindig a legjobb érv a tool mellett. Nem követeli meg, hogy rendrakd a repót, mielőtt hasznossá válik, és pont ezt követelik meg azok a szkennerek, amelyeket utólag tesznek egy megnövekedett kódbázisra.

Hol csúszik el

A gyengeségek strukturálisak, nem kosmetikaiak. Több soros titkot nem talál, és olyan alapértelmezett jelszót sem, amelyet a kulcsszó-detektor nem ismer, és ezt a README a Caveats szakaszban ki is mondja. A git-históriát szándékosan nem vizsgálja, így egy évekkel ezelőtt commitolt, majd törölt titok láthatatlanok számára. Az egyedi plugineket egy tetszőleges fájl importálásával tölti be, amit a plugin-dokumentáció maga is biztonsági feltételezésként jelöl. A projekt pedig karbantartási módban van: az 1.5.0 a 2024. május 6-áról még mindig a legfrissebb tag, a Python 3.13 támogatás 2025 januárja óta a masteren ütközik, és a hibajegyben 184 nyitott tétel várakozik.

A lényeges összehasonlítás az, hová megy a munka. A gitleaks egyetlen Go bináris, kiváló TOML szabályformátummal, gyorsabban bevezethető, és a szerzője ma már nyíltan kimondja, hogy a projekt feature complete, csak biztonsági javításokat kap, az új munka pedig másik projektbe költözött. A TruffleHog a másik irány: valós API-k ellen ellenőrizi a hitelesítő adatokat, és ez az egyetlen módja biztosan megmondani, hogy egy találat sürgős, ezt pedig körülbelül 800 adattípussal és AGPL-3.0 licencsel fizeti meg, amelyet egyes jogi osztályok nem írnak alá. A detect-secrets cserébe a szélességet adja fel az egyetlen munkafolyamat kedvéért, amely másoknál nincs: egy auditált, becommitolt lista arról, mi ismert már, és a kivezetés róla.

Foglalat

Vedd fel, de infrastruktúraként, nem projektként. A baseline modell a helyes válasz egy több éves előzményekkel rendelkező repóhoz, ahol nincs keret a rendrakásra, és azt az artefaktumot állítja elő, amit egy biztonsági átnézés valójában kér: egy listát a rotálandó kulcsokról. Nem ez a tool az új repóhoz, ahol a gitleaks egyszerűbb, és nem az a csapaté, amelynek tudnia kell, hogy egy kiszivárgott kulcs még működik-e, az a TruffleHog dolga.

1. Akkor válaszd, ha a repóban már vannak titkok, a history nem írható újra, és a cél a vérzés leállítása egy migrációs projekt indítása nélkül.
2. Tartsd a baseline-t a repóban, és a diffjét vidd be a review-ba. A magyarázat nélkül változó baseline az a hibaforma, amit figyelni kell.
3. Egy napot szánj a hangolásra. A tool pontosan olyan jó, mint a jelölt baseline, és a jelölés kézi munka.
4. Egészítsd ki szerveroldali vizsgálattal, ne helyettesítsd. A detect-secrets egy fejlesztő gépén blokkol; valaminek a már becommolt dolgokat is át kell néznie.
5. Ne építs új automatizálást arra a feltételezésre, hogy a detektorok még szaporodnak. Pineld az 1.5.0-ot, olvasd a mastert, ha Python 3.13 kell, és tervezz utódot, ha a projekt csendes marad.

Források

1. Yelp/detect-secrets: README and usage
2. Yelp/detect-secrets: CHANGELOG (v1.5.0, 6 May 2024)
3. Yelp/detect-secrets: plugin and verification documentation
4. detect-secrets 1.5.0 on PyPI
5. Yelp/detect-secrets: releases
6. Gitleaks README (MIT, Go)
7. TruffleHog README (AGPL-3.0, credential verification)
8. GitHub Docs: About secret scanning
9. betterleaks/betterleaks