Gå til hovedindhold

Push-beskyttelse

Hvert push til et fremforge-repo går gennem et Gitleaks-pre-receive-hook på Forgejo-serveren, også et nyt repositorys allerførste push. Finder scanneren en legitimationsoplysning, afvises pushet, og udvikleren ser den regel, der matchede (ingen værdi og ingen commit-SHA lækkes videre til en tredjepart).

Det er noget andet end SAST-fund og scanning af container-images: push-beskyttelsen kører på tidspunktet for git push, før commits gemmes noget sted, som fremforge skal beskytte. De andre scannere kører senere på det gemte resultat.

Hvad der matches

Gitleaks’ standardregelsæt plus fremforges tilføjelser:

  • Nøgler fra cloududbydere (AWS, JSON for GCP-servicekonti, Azure SAS-tokens, T Cloud Public AK/SK)
  • Almindelige API-nøgler til SaaS (Stripe, Mollie, SendGrid, Twilio, Lettermint, OpenAI)
  • Generiske mønstre med høj entropi (private PEM-nøgler, JWT, private SSH-nøgler)
  • Specifikke for fremforge: personlige adgangstokens (ffp_*), OAuth-klient-id’er (ffc_*) og -secrets (ffs_*), private OIDC-nøgler til runners, bootstrap-legitimationsoplysninger til OBS-buckets og HMAC-secrets til signering af kvitteringer

Gitleaks’ signaturpakke er fastlåst, gennemgås, når den opdateres, og leveres via det samme SWR-spejl som vores øvrige udviklerværktøjer. Vi henter ikke fra GitHubs indholdsregistry ved push.

Din organisation kan også tilføje sine egne mønstre, for alle repositorier eller for ét. Se Egne mønstre. De anvendes ved push på samme måde, og en afvisning angiver mønstrets regel-id, custom-<name>.

Hvad udvikleren ser

Når et push rammer en matchet secret, ser udvikleren:

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>

Ingen værdi af en legitimationsoplysning logges eller gentages. Udvikleren har allerede kildekoden åben og kan selv finde den falske positiv.

Altid slået til, og den ene indstilling

Push-beskyttelse kan ikke slås fra for en organisation eller et repository. Den ene indstilling er Scannerens fejltilstand under Sikkerhed › Politikker › Push-beskyttelse. Den afgør, hvad der sker med et push, når selve scanneren ikke er tilgængelig:

  • Bloker (standard): pushet afvises med en tydelig fejl, og du prøver igen, når scanneren er oppe igen.
  • Tillad: pushet går igennem, og en hændelse om tilladelse ved fejl registreres i revisionssporet. Secrets, der pushes i det tidsrum, findes senere af den ugentlige hemmelighedsscanning af hele historikken.

Ændringen træder i kraft ved næste push og registreres i revisionsloggen.

Et nyt repository er dækket fra sit første push. Hooket knyttes til, når repositoriet oprettes, så selv et git push lige efter oprettelsen scannes.

Tilsidesættelser

Tenant-administratorer kan tilføje tilsidesættelser for tilfælde, hvor scanneren tager fejl (testdata, eksempler fra SDK’er, dokumentation, der med vilje viser en nøgles form).

  1. Tenant-administrator → Sikkerhed › Politikker › Push-beskyttelse. Fold Aktive tilsidesættelser ud, og klik på Tilføj tilsidesættelse. Fra et afvist push udfylder Godkend formularen ud fra afvisningen.
  2. Vælg, hvad den dækker: kun denne commit (en regel i én pushet commit), kun denne regel (hvert match af én regel), kun denne sti (et sti-glob som test/fixtures/**) eller en egen kombination. Hvert felt, du udfylder, skal matche; et felt, du lader stå tomt, matcher alt. Mindst ét af commit, regel og sti er påkrævet.
  3. Begræns den eventuelt til ét repository; ellers gælder den for alle repositorier i organisationen.
  4. Sæt udløbsdatoen. Alle tilsidesættelser udløber: datoen er som standard 90 dage fra i dag og kan højst ligge 1 år ude i fremtiden. En udløbet eller tilbagekaldt tilsidesættelse respekteres ikke længere, og du tilføjer en ny, hvis der stadig er brug for den.
  5. Angiv en begrundelse (påkrævet, revideres).

Sådan vurderes et push. Pre-receive-hooket samler hver secret, det finder i de commits, et push introducerer (regel, sti og linje; aldrig værdien), og spørger fremforge, om hver af dem er dækket af en aktiv tilsidesættelse. Pushet går kun igennem, hvis hvert fund er dækket; ét fund, der ikke er dækket, afviser det som før. Når en tilsidesættelse lader et push gå igennem, ser udvikleren, hvilke tilsidesættelser der blev anvendt, og push-protection.override.used skrives i din organisations revisionslog. Hvis fremforge ikke kan spørges (for eksempel under et nedbrud), afvises pushet: tilsidesættelser lukker aldrig op ved fejl. En tilsidesættelse for en commit dækker den pushede commit (spidsen af branchen), som er den commit, en afvisning nævner. En secret inde i et arkiv matches på arkivets sti.

Tilsidesættelser fra før grænsen. Tilsidesættelser oprettet før 2026-10-18 kunne være uden udløbsdato. De virker fortsat, som de er, og konsollen og revisionsloggen viser dem som ingen udløbsdato (oprettet før grænsen). Tilbagekald og opret en igen for at give den en udløbsdato.

Tilsidesættelser gælder kun for push-beskyttelse. En secret, der allerede er i historikken, og som den ugentlige gennemgang viser, håndteres ved at afvise fundet, ikke med en tilsidesættelse.

Via REST API

Tilsidesættelser, afvisninger og fejltilstand for push-beskyttelse kan styres programmatisk, hvilket er nyttigt, når du scripter onboarding af tenants, integrerer med en CI-pipeline eller styrer det fra en AI-agent.

  • Vis tilsidesættelser GET /_app/api/v1/orgs/:slug/push-protection/overrides
  • Opret tilsidesættelse 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" }
  • Tilbagekald tilsidesættelse DELETE /_app/api/v1/orgs/:slug/push-protection/overrides/:id
  • Sæt fejltilstand PUT /_app/api/v1/orgs/:slug/push-protection/failure-mode body: { "mode": "block" }

Uden expires_at udløber en ny tilsidesættelse 90 dage efter, at den er oprettet; svaret indeholder datoen. expires_at (en ISO 8601-dato eller et tidsstempel) skal ligge i fremtiden og højst 1 år ude. En senere dato afvises med 400 expires-at-too-far og afkortes ikke. På listen markerer no_expiry_legacy: true en tilsidesættelse oprettet før grænsen, den eneste slags med expires_at: null.

At oprette eller tilbagekalde en tilsidesættelse kræver et token med policy:write, fordi en tilsidesættelse undtager push fra hemmelighedsscanning; en CI-jobs runner-token har det aldrig. At sætte fejltilstanden kræver også policy:write, fordi den kan slå push-beskyttelsen fra for hele organisationen. At vise kræver findings:read, og at afvise en afvisning 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 referencen til det offentlige REST API for den fulde OpenAPI-specifikation.

Bed om en omgåelse

En udvikler, der er blokeret, behøver ikke finde en administrator til at tilføje en tilsidesættelse. Afvisningen udskriver et link til en anmodningsformular for netop den commit. Alle i organisationen med skriveadgang til repositoriet kan åbne den og angive en begrundelse. Linket indeholder intet token, så du skal logge ind for at bruge det.

  • Hvem der beslutter. Organisationens ejere og de medlemmer, din organisation har gjort til godkendere af undtagelser. Den, der har bedt om omgåelsen, kan aldrig godkende sin egen anmodning. De får en e-mail, når en anmodning kommer ind, og webhook-hændelsen security.exception.requested sendes.
  • Hvad en godkendelse gør. Den opretter en almindelig tilsidesættelse for push-beskyttelse, bundet til det repository og den commit, gyldig i 7 dage. Pusher du den samme commit igen inden for den tid, går den igennem. En anden commit med samme secret blokeres stadig og kræver sin egen anmodning.
  • Hvor længe en anmodning er åben. Hvis ingen beslutter inden for 7 dage, udløber anmodningen.
  • Hvem der kan godkende, og hvordan. Godkendelse kræver en person, der er logget ind med totrinsgodkendelse (eller gennem din SSO), på anmodningssiden eller med et Forgejo OAuth-token via API’et. Et API-token for organisationen kan ikke beslutte en anmodning.
  • Ingen undtagelser. En bots blokerede push går gennem samme forløb. Et medlem med skriveadgang anmoder på dens vegne.
  • Grænse mod misbrug. En person kan højst indsende 10 anmodninger om dagen i én organisation.
  • Hvad der vises. Repositoriet, commit’en og regel-id’erne, aldrig secreten. Anmodninger, beslutninger og tilsidesættelsen registreres i din revisionslog (push-protection.bypass.requested, .approved, .rejected, .cancelled). Den, der har anmodet, får udfaldet at vide via e-mail og webhook (security.exception.approved eller security.exception.rejected).

Ejere ser åbne og nylige anmodninger på siden Push-beskyttelse under Anmodninger om omgåelse. Via API’et:

  • Vis GET /_app/api/v1/orgs/:slug/push-protection/bypass-requests (?status=requested for de åbne)
  • Anmod POST /_app/api/v1/orgs/:slug/push-protection/bypass-requests body: { "repository": "app", "commit_sha": "<full sha>", "reason": "..." }
  • Beslut POST .../bypass-requests/:id/approve eller .../reject, valgfrit { "comment": "..." }
  • Træk tilbage POST .../bypass-requests/:id/cancel (kun den, der har anmodet)

Omgåelse for legitimationsoplysninger, der allerede er lækket

At push-beskyttelsen blokerer, betyder ikke, at legitimationsoplysningen er sikker. Når du rammer blokeringen, ligger der en legitimationsoplysning i en commit på din bærbare. Rotér legitimationsoplysningen, før du gør noget andet. Når den er roteret, kan du rebase commit’en ud af branchen eller pushe med en tilsidesættelse; begge veje virker, når legitimationsoplysningen er død.

Push og committer-reglen

Hvert push registreres også med den konto, der godkendte det (HTTPS-token, OAuth-token, SSH-nøgle, deploy-nøgle eller Actions-job), og din organisation kan kræve, at nye commits bruger en af pusherens bekræftede e-mailadresser: fra, advar eller blokér. Se Push og committer-reglen.

Hvad den ikke gør

  • Den scanner ikke historikken bagud. Blev en legitimationsoplysning committet, før push-beskyttelsen blev slået til, forbliver den committet. Brug et værktøj til at omskrive historikken (migreringsvejledningen gennemgår det).
  • Den fanger ikke alle tænkelige former for legitimationsoplysninger. Egne regler pr. tenant dækker de huller, der betyder noget for din stak.
  • Den kører ikke ved git push --force af en branch, som fremforge allerede kender (pre-receive-hooket kører stadig, men sammenligningen sker mod den nye spids; et force-push, der overskriver en lækket commit med en ren, tillades).