Pakkettoegang

Standaard bereikt iedereen met pakkettoegang in je organisatie elk pakket daarin: een lid van een team met schrijfrechten op pakketten kan naar elk pakket van de organisatie publiceren en het verwijderen, bij welke repository het ook hoort. Toegang per pakket beperkt dat, zoals GitHub Packages en GitLab het doen.

Er verandert niets totdat een eigenaar van de organisatie het aanzet, voor één pakket of voor de hele organisatie.

Wat toegang per pakket doet

Voor een pakket met toegang per pakket:

• Lezen downloadt het pakket. Schrijven publiceert, voegt een bestand toe en verplaatst een tag. Beheer verwijdert daarnaast versies en koppelt de repository of ontkoppelt hem. Een registry-robot verwijdert nooit, welke toekenningen hij ook heeft.
• De zichtbaarheid verandert niet. In een openbare organisatie kan iedereen nog steeds elk pakket lezen, en in een beperkte organisatie elke ingelogde gebruiker. Toegang per pakket beperkt dan wie mag publiceren en verwijderen. In een privé-organisatie beperkt het ook het lezen.
• Het kan alleen beperken. Toegang per pakket geeft nooit iemand meer dan de eigen pakketinstellingen van de organisatie. Wil je een team één pakket laten publiceren, dan hebben de leden schrijfrechten op pakketten in de organisatie nodig (het team Members heeft die), en toegang per pakket houdt ze dan bij dat ene pakket. De enige uitzondering is de Actions-toekenning met schrijfrechten, waarmee de jobs van een andere repository een pakket kunnen publiceren dat elders is gekoppeld.
• Gekoppelde repository. Een pakket wordt aan een repository gekoppeld wanneer een Actions-job van die repository het publiceert, via de metadata ervan (npm repository, het containerlabel org.opencontainers.image.source), of in de instellingen van het pakket. Zet Overnemen van de gekoppelde repository uit om alleen op toekenningen te vertrouwen.

Toegang per pakket is beschikbaar voor elk pakkettype dat het register levert: Alpine, ALT, Arch, Cargo, Chef, Composer, Conan, Conda, container, CRAN, Debian, generiek, Go, Helm, Maven, npm, NuGet, Pub, PyPI, RPM, RubyGems, Swift en Vagrant.

Aanzetten

In de console: Beveiliging › Toegang › Pakkettoegang.

• Standaard van de organisatie: Hele organisatie (de standaard) of Per pakket, voor elk pakket van een ondersteund type dat geen eigen instelling heeft.
• Een pakket configureren: per pakket Per pakket, Hele organisatie of Volg de organisatie, en of het van de gekoppelde repository overneemt. Het pakket hoeft nog niet te bestaan: een instelling van vóór de eerste publicatie geldt ervoor.
• Toekenning toevoegen op een geconfigureerd pakket: een team (lezen, schrijven of beheer) of de Actions-jobs van een repository (lezen of schrijven).

Of via de API, met een API-token met de scope policy:write (policy:read om te lezen). Een / in een pakketnaam stuur je als %2F:

API=https://frem.sh/_app/api/v1/orgs/acme
curl -X PUT -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"mode":"granular","inherit_repo":true}' "$API/packages/container/team%2Fapp/access"
curl -X PUT -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"permission":"write"}' "$API/packages/container/team%2Fapp/access/teams/release-managers"
curl -X PUT -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"permission":"write"}' "$API/packages/container/team%2Fapp/access/actions/release-pipeline"

Beschermde namen

Een beschermingsregel wijst pakketten aan op type (of elk ondersteund type) en een naampatroon, en somt op wie er mag publiceren en wie ze mag verwijderen: eigenaren van de organisatie, registry-robots, leden van genoemde teams en de Actions-jobs van genoemde repository’s. Ieder ander wordt geweigerd, wat de toegangsinstelling van het pakket ook is. Komen meerdere regels overeen met een pakket, dan moeten ze het allemaal toestaan.

In het patroon komt * overeen met willekeurige tekens, ook een /, en ? met één teken; hoofdletters maken niet uit. Zo houdt release/* met Mag publiceren: registry-robots, Actions-jobs van release-pipeline release-images voorbehouden aan CI.

curl -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"type":"container","name_pattern":"release/*","push":{"owners":false,"robots":true,"actions":["release-pipeline"]},"delete":{"owners":true}}' \
  "$API/packages/protection-rules"

Pakketlijsten en indexen

In een organisatie die toegang per pakket gebruikt, laten lijsten en indexen de pakketten weg die de aanvrager niet kan lezen, met naam en al hun versies:

• de pakketlijst van de API, /api/v1/packages/<org>;
• npm search, de Helm-index.yaml, de NuGet-zoekfunctie (query), Composer search.json en list.json, Cargo search, Chef search en universe, Conda repodata.json, RubyGems versions, CRAN PACKAGES, Conan search en de Swift-opvraging identifiers.

Het register controleert de lijst op de weg naar buiten, wat deze verzoeken doorgaans minder dan een tiende seconde langer maakt. Kan het een lijst niet controleren, dan geeft het 503 met Retry-After terug in plaats van de lijst ongefilterd te tonen. Organisaties die geen toegang per pakket gebruiken, krijgen de lijsten van het register ongewijzigd.

Hoe een weigering eruitziet

Een geweigerd verzoek geeft 403 terug met de reden (DENIED in het foutformaat van de containerregistry), voordat er iets wordt geschreven. Elke weigering staat in het auditlog van de organisatie als package_access.denied, en een geweigerde publicatie of verwijdering ook als package.upload.refused of package.delete.refused met reden package_access:<reason>.

Als code

De configuration-as-code-module beheert dit allemaal:

module "org" {
  source = "./modules/fremforge-org"
  org    = "acme"

  package_access_default = "legacy"
  packages = {
    "container/team/app" = {
      mode    = "granular"
      teams   = { release-managers = "admin" }
      actions = { release-pipeline = "write" }
    }
  }
  package_protection_rules = {
    releases = { type = "container", name_pattern = "release/*", push = { owners = false, robots = true } }
  }
}

Beperkingen

• Een wijziging van een instelling, een toekenning, een regel of de leden van een team geldt binnen een minuut: het register cachet zijn beslissingen kort.
• Deze lijsten worden niet gefilterd: de pakketlijst in de webinterface, ondertekende repository-indexen (de Debian-Release/Packages, RPM-repodata, Alpine-APKINDEX, de Arch-database en de ALT-basisbestanden, waarvan een herschrijving de handtekening zou breken), gecomprimeerde varianten (PACKAGES.gz, repodata.json.bz2, de RubyGems-familie specs.4.8.gz), de NuGet v2-XML-feeds en de taglijst van containers. Ze tonen pakketnamen en versies aan iedereen die de pakketten van de organisatie kan lezen, maar niet de inhoud van de pakketten.
• Een upload die zijn pakket alleen binnen het geüploade bestand noemt, wordt gecontroleerd op die naam. Waar het register de naam niet kan lezen (een Conda-.tar.bz2, een met xz gecomprimeerd Debian-controlarchief of Arch-pakket), wordt de upload geweigerd in een organisatie die voor dat type toegang per pakket gebruikt. Gebruik .conda, of compressie met gzip of zstd.
• Een RubyGems-yank moet de gem in de querystring noemen, bijvoorbeeld curl -X DELETE ".../rubygems/api/v1/gems/yank?gem_name=mygem&version=1.0.0". Een yank die hem alleen in een formulierbody noemt, wordt geweigerd in een organisatie die toegang per pakket gebruikt voor RubyGems.