Hoppa till huvudinnehållet

Push-skydd

Varje push till ett repo på fremforge går genom en Gitleaks pre-receive-hook på Forgejo-servern, även ett nytt repos allra första push. Om skannern hittar en inloggningsuppgift avvisas pushen och utvecklaren ser den regel som matchade (inget värde och ingen commit-SHA läcker tillbaka till en tredje part).

Det här skiljer sig från SAST-fynd och skanning av container-images: Push-skydd körs vid git push, innan commits lagras någonstans som fremforge måste skydda. De andra skannrarna körs senare på det lagrade resultatet.

Vad som matchas

Gitleaks standardregler plus fremforges tillägg:

  • Nycklar för molnleverantörer (AWS, JSON för GCP-tjänstkonton, Azure SAS-tokens, AK/SK för T Cloud Public)
  • Vanliga API-nycklar för SaaS (Stripe, Mollie, SendGrid, Twilio, Lettermint, OpenAI)
  • Generiska mönster med hög entropi (privata PEM-nycklar, JWT, privata SSH-nycklar)
  • Specifikt för fremforge: personliga åtkomsttokens (ffp_*), OAuth-klient-id:n (ffc_*) + hemligheter (ffs_*), privata OIDC-nycklar för runners, bootstrap-uppgifter för OBS-buckets, HMAC-hemligheter för signering av kvittenser

Signaturpaketet för Gitleaks är låst till en version, granskas när det uppdateras och levereras via samma SWR-spegel som våra övriga utvecklarverktyg. Vi hämtar inget från GitHubs innehållsregister vid push.

Din organisation kan också lägga till egna mönster, för alla repon eller för ett. Se Egna mönster. De tillämpas vid push på samma sätt, och ett avslag anger mönstrets regel-id, custom-<name>.

Vad utvecklaren ser

När en push träffar en matchad hemlighet ser utvecklaren:

remote: Push rejected by fremforge push-protection.
remote:
remote: Matched rule: aws_access_key_id
remote: Path:         src/services/uploader.ts:42
remote: Commit:       <commit-sha>
remote:
remote: If this is a false positive, ask an org owner to add an
remote: override at frem.sh/<your-org>/_admin/push-protection.
remote: Override IDs are auditable and time-boxed.
remote: Or ask for this commit to be let through:
remote:   https://frem.sh/_app/settings/push-protection/bypass/new?repo=<org>/<repo>&commit=<commit-sha>

Inget värde för inloggningsuppgiften loggas eller skrivs ut. Utvecklaren har redan källkoden öppen och kan själv hitta den falska träffen.

Alltid på, och den enda inställningen

Push-skydd kan inte stängas av för en organisation eller ett repo. Den enda inställningen är Skannerns felläge, under Säkerhet › Policyer › Push-skydd. Den avgör vad som händer med en push när själva skannern inte är tillgänglig:

  • Blockera (standard): pushen avvisas med ett tydligt felmeddelande, och du försöker igen när skannern är tillbaka.
  • Tillåt: pushen går igenom och en händelse om att den släpptes igenom vid fel registreras i granskningsspåret. Hemligheter som pushas under det fönstret hittas senare av den veckovisa hemlighetsskanningen av hela historiken.

Ändringen gäller från nästa push och registreras i granskningsloggen.

Ett nytt repo skyddas från sin första push. Hooken kopplas när repot skapas, så även en git push direkt efter att det skapats skannas.

Undantag

Tenantens administratörer kan lägga till undantag för fall där skannern har fel (testfixturer, exempelkod för SDK:er, dokumentation som avsiktligt visar hur en nyckel ser ut).

  1. Tenantens administration → Säkerhet › Policyer › Push-skydd. Fäll ut Aktiva undantag och klicka på Lägg till undantag. Från en avvisad push fyller Godkänn… i formuläret utifrån det avslaget.
  2. Välj vad det täcker: Bara den här commiten (en regel i en pushad commit), Bara den här regeln överallt (varje träff på en regel), Bara den här sökvägen globalt (ett sökvägsmönster som test/fixtures/**), eller en anpassad kombination. Varje fält du fyller i måste matcha; ett fält du lämnar tomt matchar allt. Minst ett av commit, regel och sökväg krävs.
  3. Begränsa det eventuellt till ett repo; annars gäller det för alla repon i organisationen.
  4. Ange utgångsdatum. Varje undantag upphör: datumet är som standard 90 dagar från i dag och kan vara högst 1 år bort. Ett undantag som har gått ut eller återkallats respekteras inte längre, och du lägger till ett nytt om det fortfarande behövs.
  5. Ange en orsak (obligatorisk, granskas).

Hur en push bedöms. Pre-receive-hooken samlar in varje hemlighet den hittar i de commits som en push för in (regel, sökväg och rad; aldrig värdet) och frågar fremforge om var och en täcks av ett aktivt undantag. Pushen går igenom bara om varje fynd är täckt; ett enda fynd som inte är täckt avvisar den som tidigare. När ett undantag släpper igenom en push ser utvecklaren vilket eller vilka undantag som gällde, och push-protection.override.used skrivs till organisationens granskningslogg. Om fremforge inte kan tillfrågas (till exempel under ett avbrott) avvisas pushen: undantag släpper aldrig igenom vid fel. Ett commit-undantag täcker den pushade commiten (spetsen på branchen), som är den commit som ett avslag anger. En hemlighet i ett arkiv matchas på arkivets sökväg.

Undantag från före gränsen. Undantag som skapades före 2026-10-18 kunde lämnas utan utgångsdatum. De fortsätter att fungera som de är, och konsolen och granskningsloggen visar dem som Inget utgångsdatum (skapat före gränsen). Återkalla och skapa om ett sådant för att ge det ett utgångsdatum.

Undantag gäller bara Push-skydd. En hemlighet som redan finns i historiken och som den veckovisa genomsökningen listar hanteras genom att fyndet avfärdas, inte med ett undantag.

Via REST-API

Undantag, avslag och felläge för Push-skydd kan hanteras programmatiskt, vilket är praktiskt när du skriptar introduktionen av en tenant, integrerar med en CI-pipeline eller styr från en AI-agent.

  • Lista undantag GET /_app/api/v1/orgs/:slug/push-protection/overrides
  • Skapa undantag POST /_app/api/v1/orgs/:slug/push-protection/overrides body: { "kind": "path", "path_pattern": "test/fixtures/**", "reason": "test fixtures", "expires_at": "2027-01-01T00:00:00Z" }
  • Återkalla undantag DELETE /_app/api/v1/orgs/:slug/push-protection/overrides/:id
  • Ange felläge PUT /_app/api/v1/orgs/:slug/push-protection/failure-mode body: { "mode": "block" }

Utan expires_at går ett nytt undantag ut 90 dagar efter att det skapats; svaret innehåller datumet. expires_at (ett datum eller en tidsstämpel enligt ISO 8601) måste ligga i framtiden och högst 1 år bort. Ett senare datum avvisas med 400 expires-at-too-far, det förkortas inte. I listan markerar no_expiry_legacy: true ett undantag som skapats före gränsen, den enda sorten med expires_at: null.

Att skapa eller återkalla ett undantag kräver en token med policy:write, eftersom ett undantag undantar pushar från hemlighetsskanning; en runner-token för ett CI-jobb har aldrig det. Att ange felläget kräver också policy:write, eftersom det kan stänga av Push-skydd för hela organisationen. Att lista kräver findings:read, och att avfärda ett avslag kräver findings:write.

curl -X POST \
  -H "Authorization: Bearer ${FREMFORGE_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"kind":"path","path_pattern":"test/fixtures/**","reason":"test fixtures","expires_at":"2027-01-01T00:00:00Z"}' \
  https://frem.sh/_app/api/v1/orgs/acme/push-protection/overrides

Se referensen för det publika REST-API:et för den fullständiga OpenAPI-specifikationen.

Be om förbikoppling

En utvecklare som blockeras behöver inte leta upp en administratör som lägger till ett undantag. Avslaget skriver ut en länk till ett formulär för en begäran om exakt den commiten. Alla i organisationen med skrivåtkomst till repot kan öppna det och ange en orsak. Länken innehåller ingen token, så du loggar in för att använda den.

  • Vem som beslutar. Organisationens ägare och de medlemmar som din organisation har gjort till godkännare av undantag. Den som frågade kan aldrig godkänna sin egen begäran. De får ett mejl när en begäran kommer in, och webhook-händelsen security.exception.requested skickas.
  • Vad ett godkännande gör. Det skapar ett vanligt undantag från Push-skydd som är bundet till det repot och den commiten, giltigt i 7 dagar. Pusha samma commit igen inom den tiden så går den igenom. En annan commit med samma hemlighet blockeras fortfarande och behöver en egen begäran.
  • Hur länge en begäran är öppen. Om ingen beslutar inom 7 dagar går begäran ut.
  • Vem som kan godkänna, och hur. För att godkänna krävs en person som har loggat in med tvåfaktorsautentisering (eller via din SSO), på begärans sida eller med en Forgejo OAuth-token i API:t. En organisations API-token kan inte besluta om en begäran.
  • Inga undantag från reglerna. En bots blockerade push går genom samma flöde. En medlem med skrivåtkomst frågar för dess räkning.
  • Gräns mot missbruk. En person kan skicka högst 10 begäranden om dagen i en organisation.
  • Vad som visas. Repot, commiten och regel-id:na, aldrig hemligheten. Begäranden, beslut och undantaget registreras i din granskningslogg (push-protection.bypass.requested, .approved, .rejected, .cancelled). Den som frågade får veta utfallet via mejl och webhook (security.exception.approved eller security.exception.rejected).

Ägare ser öppna och nyliga begäranden på sidan Push-skydd, under Begäranden om förbikoppling. Via API:t:

  • Lista GET /_app/api/v1/orgs/:slug/push-protection/bypass-requests (?status=requested för de öppna)
  • Fråga POST /_app/api/v1/orgs/:slug/push-protection/bypass-requests body: { "repository": "app", "commit_sha": "<full sha>", "reason": "..." }
  • Besluta POST .../bypass-requests/:id/approve eller .../reject, valfritt { "comment": "..." }
  • Dra tillbaka POST .../bypass-requests/:id/cancel (bara den som frågade)

Förbikoppling för inloggningsuppgifter som redan läckt

Att Push-skydd blockerar betyder inte att inloggningsuppgiften är säker. När du träffar spärren har du en inloggningsuppgift i en commit på din dator. Rotera inloggningsuppgiften innan du gör något annat. När den är roterad kan du rebasa bort commiten från branchen eller pusha med ett undantag; båda vägarna fungerar när inloggningsuppgiften väl är ogiltig.

Push och committerregeln

Varje push registreras också med det konto som autentiserade den (HTTPS-token, OAuth-token, SSH-nyckel, deploy-nyckel eller Actions-jobb), och din organisation kan kräva att nya commits använder en av pusherns verifierade e-postadresser: av, varna eller blockera. Se Push och committerregeln.

Vad den inte gör

  • Den skannar inte historiken bakåt. Om en inloggningsuppgift checkades in innan Push-skydd aktiverades finns den kvar. Använd ett verktyg för att skriva om historiken (migreringsguiden går igenom det).
  • Den fångar inte alla tänkbara former av inloggningsuppgifter. Egna regler per tenant täcker de luckor som spelar roll för din stack.
  • Den körs inte vid git push --force av en branch som redan är känd för fremforge (pre-receive-hooken körs fortfarande, men jämförelsen görs mot den nya spetsen; en force-push som skriver över en läckt commit med en ren tillåts).