Gå til hovedinnhold

Push-beskyttelse

Hver push til et fremforge-repository går gjennom en Gitleaks pre-receive-hook på Forgejo-serveren, også den aller første pushen til et nytt repository. Finner skanneren en legitimasjon, avvises pushen, og utvikleren ser regelen som traff (ingen verdi og ingen commit-SHA lekkes tilbake til en tredjepart).

Dette er noe annet enn SAST-funn og skanning av containerimager: push-beskyttelse kjører idet du pusher, før commitene lagres noe sted fremforge må forsvare. De andre skannerne kjører senere på det lagrede resultatet.

Hva som fanges opp

Gitleaks’ standard regelsett pluss tillegg fra fremforge:

  • Nøkler fra skyleverandører (AWS, JSON for tjenestekontoer i GCP, Azure SAS-tokener, T Cloud Public AK/SK)
  • Vanlige API-nøkler for SaaS (Stripe, Mollie, SendGrid, Twilio, Lettermint, OpenAI)
  • Generiske mønstre med høy entropi (private PEM-nøkler, JWT, private SSH-nøkler)
  • Spesifikt for fremforge: personlige tilgangstokener (ffp_*), OAuth-klient-ID-er (ffc_*) + secrets (ffs_*), private OIDC-nøkler for runnere, bootstrap-legitimasjon for OBS-bøtter, HMAC-secrets for signering av kvitteringer

Signaturpakken til Gitleaks er låst til en versjon, gjennomgås når den oppgraderes, og leveres via det samme SWR-speilet som resten av utviklerverktøyene våre. Vi henter ikke fra GitHubs innholdsregister når du pusher.

Organisasjonen din kan også legge til sine egne mønstre, for alle repositoryer eller for ett. Se Egendefinerte mønstre. De brukes ved push på samme måte, og en avvisning navngir mønsterets regel-ID, custom-<name>.

Hva utvikleren ser

Når en push treffer en secret, ser utvikleren:

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 legitimasjonsverdi logges eller gjentas. Utvikleren har allerede kildekoden åpen og kan finne det falske positive treffet selv.

Alltid på, og den ene innstillingen

Push-beskyttelse kan ikke slås av for en organisasjon eller et repository. Den ene innstillingen er feilmodusen for skanneren, under Sikkerhet › Policyer › Push-beskyttelse. Den bestemmer hva som skjer med en push når selve skanneren ikke er tilgjengelig:

  • Blokker (standard): pushen avvises med en tydelig feilmelding, og du prøver igjen når skanneren er tilbake.
  • Tillat: pushen går gjennom, og en hendelse om tillatelse ved feil registreres i revisjonssporet. Secrets som pushes i det vinduet, blir funnet senere av den ukentlige secret-skanningen av hele historikken.

Endringen trer i kraft ved neste push og registreres i revisjonsloggen.

Et nytt repository er dekket fra første push. Hooken kobles til når repositoryet opprettes, så selv en git push rett etter at det er opprettet, skannes.

Overstyringer

Organisasjonsadministratorer kan legge til overstyringer for tilfeller der skanneren tar feil (testfixtures, eksempelkode for SDK-er, dokumentasjon som med vilje viser formen på en nøkkel).

  1. Organisasjonsadministrasjon → Sikkerhet › Policyer › Push-beskyttelse. Utvid Aktive overstyringer og klikk Legg til overstyring. Fra en avvist push fyller Godkjenn ut skjemaet fra den avvisningen.
  2. Velg hva den dekker: just this commit (en regel i én pushet commit), just this rule (alle treff for én regel), just this path (et stimønster som test/fixtures/**) eller en egendefinert kombinasjon. Hvert felt du fyller ut, må stemme; et felt du lar stå tomt, stemmer med alt. Minst ett av commit, regel og sti er påkrevd.
  3. Avgrens den eventuelt til ett repository; ellers gjelder den alle repositoryer i organisasjonen.
  4. Sett utløpsdatoen. Hver overstyring tar slutt: datoen er som standard 90 dager fra i dag og kan ligge høyst 1 år frem. En utløpt eller tilbakekalt overstyring respekteres ikke lenger, og du legger til en ny hvis den fortsatt trengs.
  5. Oppgi en begrunnelse (påkrevd, revideres).

Hvordan en push vurderes. Pre-receive-hooken samler alle secrets den finner i commitene en push introduserer (regel, sti og linje; aldri verdien), og spør fremforge om hver av dem er dekket av en aktiv overstyring. Pushen går gjennom bare hvis hvert funn er dekket; ett udekket funn avviser den som før. Når en overstyring slipper en push gjennom, ser utvikleren hvilke overstyringer som ble brukt, og push-protection.override.used skrives til organisasjonens revisjonslogg. Hvis fremforge ikke kan spørres (for eksempel under et driftsavbrudd), avvises pushen: overstyringer slipper aldri gjennom ved feil. En commit-overstyring dekker den pushede commiten (toppen av branchen), som er commiten en avvisning navngir. En secret i et arkiv matches på arkivets sti.

Overstyringer fra før grensen. Overstyringer opprettet før 2026-10-18 kunne stå uten utløpstid. De fungerer fortsatt som før, og konsollen og revisjonsloggen viser dem som no expiry (created before the limit). Tilbakekall og opprett en på nytt for å gi den en utløpstid.

Overstyringer gjelder bare push-beskyttelse. En secret som allerede ligger i historikken og som den ukentlige gjennomgangen lister, håndteres ved å avvise funnet, ikke med en overstyring.

Via REST API

Overstyringer, avvisninger og feilmodus for push-beskyttelse kan styres programmatisk, noe som er nyttig når du skripter klargjøring av organisasjoner, integrerer med en CI-pipeline eller styrer fra en AI-agent.

  • List overstyringer GET /_app/api/v1/orgs/:slug/push-protection/overrides
  • Opprett overstyring 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" }
  • Tilbakekall overstyring DELETE /_app/api/v1/orgs/:slug/push-protection/overrides/:id
  • Sett feilmodus PUT /_app/api/v1/orgs/:slug/push-protection/failure-mode body: { "mode": "block" }

Uten expires_at utløper en ny overstyring 90 dager etter at den er opprettet; svaret inneholder datoen. expires_at (en ISO 8601-dato eller et tidsstempel) må ligge frem i tid og høyst 1 år frem. En senere dato avvises med 400 expires-at-too-far og blir ikke forkortet. I listen markerer no_expiry_legacy: true en overstyring som ble opprettet før grensen, den eneste typen med expires_at: null.

Å opprette eller tilbakekalle en overstyring krever et token med policy:write, fordi en overstyring unntar pusher fra secret-skanning; runner-tokenet til en CI-jobb har aldri det. Å sette feilmodusen krever også policy:write, fordi den kan slå av push-beskyttelsen for hele organisasjonen. Å liste krever findings:read, og å avvise en avvisning krever 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 referansen for det offentlige REST-API-et for den fullstendige OpenAPI-spesifikasjonen.

Be om å slippe gjennom

En utvikler som blir blokkert, trenger ikke finne en administrator som kan legge til en overstyring. Avvisningen skriver ut en lenke til et forespørselsskjema for akkurat den commiten. Alle i organisasjonen med skrivetilgang til repositoryet kan åpne det og oppgi en begrunnelse. Lenken inneholder ikke noe token, så du logger inn for å bruke den.

  • Hvem bestemmer. Organisasjonens eiere og medlemmene organisasjonen din har gjort til godkjennere av unntak. Personen som spurte, kan aldri godkjenne sin egen forespørsel. De får e-post når en forespørsel kommer inn, og webhook-hendelsen security.exception.requested sendes.
  • Hva en godkjenning gjør. Den oppretter en vanlig overstyring for push-beskyttelse, bundet til det repositoryet og den commiten, gyldig i 7 dager. Pusher du den samme commiten igjen innen den tiden, går den gjennom. En annen commit med den samme secreten blokkeres fortsatt og trenger sin egen forespørsel.
  • Hvor lenge en forespørsel er åpen. Hvis ingen bestemmer seg innen 7 dager, utløper forespørselen.
  • Hvem kan godkjenne, og hvordan. Godkjenning krever en person som har logget inn med tofaktorautentisering (eller gjennom SSO-en din), på forespørselssiden eller med et OAuth-token fra Forgejo i API-et. Et API-token for organisasjonen kan ikke avgjøre en forespørsel.
  • Ingen unntak. En blokkert push fra en bot går gjennom den samme flyten. Et medlem med skrivetilgang spør på dens vegne.
  • Grense mot misbruk. En person kan sende inn høyst 10 forespørsler om dagen i én organisasjon.
  • Hva som vises. Repositoryet, commiten og regel-ID-ene, aldri secreten. Forespørsler, avgjørelser og overstyringen registreres i revisjonsloggen din (push-protection.bypass.requested, .approved, .rejected, .cancelled). Den som spurte, får vite utfallet via e-post og webhook (security.exception.approved eller security.exception.rejected).

Eiere ser åpne og nylige forespørsler på siden Push protection, under Forespørsler om å slippe gjennom. Over API-et:

  • Liste GET /_app/api/v1/orgs/:slug/push-protection/bypass-requests (?status=requested for de åpne)
  • Spør POST /_app/api/v1/orgs/:slug/push-protection/bypass-requests body: { "repository": "app", "commit_sha": "<full sha>", "reason": "..." }
  • Avgjør POST .../bypass-requests/:id/approve eller .../reject, valgfritt { "comment": "..." }
  • Trekk tilbake POST .../bypass-requests/:id/cancel (bare den som spurte)

Slippe gjennom legitimasjon som allerede er lekket

At push-beskyttelsen blokkerer, betyr ikke at legitimasjonen er trygg. Når du treffer blokkeringen, har du allerede en legitimasjon liggende i en commit på maskinen din. Roter legitimasjonen før du gjør noe annet. Når den er rotert, kan du rebase commiten ut av branchen eller pushe med en overstyring; begge veier fungerer så snart legitimasjonen er ugyldig.

Pusher og committer-regelen

Hver push registreres også med kontoen som autentiserte den (HTTPS-token, OAuth-token, SSH-nøkkel, deploy-nøkkel eller Actions-jobb), og organisasjonen din kan kreve at nye commits bruker en av de bekreftede e-postadressene til den som pusher: av, advar eller blokker. Se Pusher og committer-regelen.

Hva den ikke gjør

  • Den skanner ikke historikken bakover. Hvis en legitimasjon ble committet før push-beskyttelse ble slått på, forblir den committet. Bruk et verktøy for å skrive om historikken (migreringsveiledningen går gjennom dette).
  • Den fanger ikke opp alle tenkelige former for legitimasjon. Egendefinerte regler per organisasjon dekker hullene som betyr noe for din stack.
  • Den kjører ikke på git push --force av en branch som fremforge allerede kjenner (pre-receive-hooken kjører fortsatt, men sammenligningen gjøres mot den nye toppen; en force-push som overskriver en lekket commit med en ren en, tillates).