Package scope is the GitHub permission boundary that determines whether a token can read or publish packages such as container images. In GHCR, read:packages allows pulling private or public packages, while write:packages allows pushing. Correct scope selection is essential because authentication can succeed even when authorisation later fails.
Expanded Definition
Package scope is the GitHub permission boundary that decides whether an identity can read packages, publish packages, or both. In practice, it governs access to package registries such as GHCR and similar package workflows where tokens are granted only the minimum authority needed for the task. The distinction matters because authentication can succeed while authorisation still fails later in the pipeline.
In NHI security, package scope sits at the intersection of token design, CI/CD automation, and software supply chain control. A token with OWASP Non-Human Identity Top 10 relevant permissions may be valid for login but still too narrow or too broad for the intended package action. Guidance varies across vendors on how package scopes map to broader repository permissions, so practitioners should verify the exact registry behavior rather than assume consistency. The most common misapplication is granting write:packages to automation jobs that only need pull access, which occurs when teams copy a build token across multiple pipelines without revisiting scope.
Examples and Use Cases
Implementing package scope rigorously often introduces a coordination cost, requiring teams to balance deployment speed against tighter registry authorization.
- A build job needs read:packages so it can pull a private base image from GHCR during CI.
- A release pipeline needs write:packages to publish a versioned container image after tests pass.
- An internal dependency proxy uses read scope only, preventing automation from publishing unintended artifacts.
- A short-lived token is issued for a single release step, then discarded after package upload completes.
- A security review compares package scope to broader token privileges using the NIST SP 800-53 Rev 5 Security and Privacy Controls least-privilege intent.
These patterns are especially relevant when teams standardise package publishing across multiple repositories. The Ultimate Guide to NHIs — Key Challenges and Risks shows why broad, durable credentials are a recurring governance problem, while the LiteLLM PyPI package breach underscores how package-related identity compromise can spill into downstream software distribution.
Why It Matters in NHI Security
Package scope is not just an access setting, it is a control on software trust. When package permissions are too broad, a compromised token can be used to overwrite artefacts, inject malicious dependencies, or exfiltrate private packages. When they are too narrow, deployment failures appear as authentication problems even though the actual issue is authorisation. That confusion slows incident response and encourages teams to add more privilege than necessary.
NHIMG research shows that 97% of NHIs carry excessive privileges, increasing unauthorised access and broadening the attack surface, which makes scope discipline especially important for package pipelines. Mis-scoped tokens are also hard to notice because package operations often run silently inside automation. The Ultimate Guide to NHIs and the OWASP NHI guidance both point to the same operational reality: least privilege must be enforced at the token level, not assumed from login success alone. Organisations typically encounter package-scope weaknesses only after a failed release, unexpected registry access, or a tampered artefact forces them to trace which token actually had publish rights.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 address the attack and risk surface, while NIST CSF 2.0 and NIST SP 800-63 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP Non-Human Identity Top 10 | NHI-02 | Package scope governs whether NHI tokens can read or publish artefacts. |
| NIST CSF 2.0 | PR.AC-4 | Package scope is an access enforcement control for automated identities. |
| NIST SP 800-63 | AAL2 | Token privilege strength should align with the task's assurance requirement. |
Restrict package tokens to the minimum registry action required and review publish rights regularly.
Related resources from NHI Mgmt Group
- What breaks when a registry authorizes access without checking package visibility and requester scope?
- How should teams reduce risk from malicious npm package installs?
- How should security teams handle leaked credentials reported outside bug bounty scope?
- What is the difference between OAuth scope inventory and scope monitoring?
