Incident Response
Relevant source files
The following files were used as context for generating this wiki page:
Incident Response within the Numan Registry project encompasses the operational procedures for managing security vulnerabilities, compromised artifacts, signing-key exposure, and index corruption. The primary goal is to maintain the integrity of the signed official registry index, which Numan clients rely on for verifying and installing Nushell packages.
This system relies on a trust model where production clients verify Ed25519 signatures over canonical JSON bytes of the index.json. Incident response actions—such as yanking versions or rolling back the index—result in a newly reviewed and signed index revision rather than in-place rewrites of existing artifact bytes.
Sources: SECURITY.md:4-6, SECURITY.md:43-51, README.md:5-9
Vulnerability Reporting and Scope
The project maintains a strict protocol for reporting vulnerabilities to prevent the public exposure of exploit details or private keys. The preferred method is via private GitHub security advisories. If a fallback public issue is required, it must not contain technical details.
Reporting Channels
| Method | Action |
|---|---|
| Preferred | Open a private GitHub security advisory at the provided security link. |
| Fallback | Open a public issue titled "Security contact request" without technical details. |
Sources: SECURITY.md:11-18
Incident Scope
The project distinguishes between issues that are in-scope for this repository and those that must be routed to upstream projects or sibling repositories.
- In-Scope: Mismatched or malicious artifacts in the signed index, signing-key exposure, signature bypass in CI, and secret leakage (private keys/tokens) in the repo.
- Out-of-Scope: Bugs in the Numan CLI, build/release pipeline issues in
numan-pluginsthat didn't reach the index, and vulnerabilities in third-party packages.
Sources: SECURITY.md:27-41
Operational Remediation Procedures
Operational procedures for incidents are defined as reviewed, newly signed index revisions. This ensures that artifact URLs and digests remain immutable even during remediation.
Remediation Workflow
The following diagram illustrates the high-level flow from incident detection to user remediation.
The diagram shows the lifecycle of a security incident from detection to the point where a user synchronizes a fixed index.
Sources: SECURITY.md:11-18, SECURITY.md:47-51, SECURITY.md:54-57
Key Response Actions
| Action | Description |
|---|---|
| Yank | Removing a specific version from the signed index to prevent new installs. |
| Rollback | Reverting the registry to a previous known-good signed state. |
| Key Rotation | Generating a new Ed25519 keypair and updating the trust root if the private key is exposed. |
| User Remediation | Instructions for users to sync a fixed index and follow advisory specific steps. |
Sources: SECURITY.md:6, SECURITY.md:47-51, README.md:83-88
Signing-Key Compromise and Recovery
The registry private key (NUMAN_REGISTRY_PRIVATE_KEY) is a critical asset that must never be committed to the source tree. If compromised, a manual recovery process is required using the provision-production-key.sh script to generate a new keypair.
Key Management Safety
- No Private Keys in Tree: Scripts like
scan_for_secrets.pyand gitignore rules (*.key,*.pem) prevent accidental commits. - Manual Provisioning: Maintainers generate keys locally; the private key is never printed to stdout.
- Protected Environment: Production signing only occurs within a protected GitHub environment that exposes the secret to the signing job.
Sources: README.md:105-115, REVIEW.md:38-40, AGENTS.md:54-57, scripts/provision-production-key.sh:6-14
Verification Sequence
During an incident, maintainers can verify the integrity of the public key and signatures without exposing private material using the --verify mode of the provisioning script.
The sequence demonstrates how a maintainer verifies a signed index during an incident response scenario using the provided CLI tools.
Sources: scripts/provision-production-key.sh:65-81
User Remediation
Users are responsible for remediating their local environments by synchronizing with the fixed production index. Security fixes are only applied to the current production index and the main branch; older catalog revisions are preserved for evidence in lockfiles but are not patched.
The remediation process typically involves:
- Running
numan registry syncto fetch the latest signed index. - Following specific instructions provided in the security advisory (e.g., updating to a fixed version or removing a yanked version).
Sources: SECURITY.md:54-59, registry/index.html:565-570
Summary
Incident response in the Numan Registry is focused on maintaining the integrity of the signed package index through immutable artifact records and transparent remediation revisions. By strictly separating private key material from the source tree and using a multi-stage validation process, the project ensures that security incidents—from artifact compromise to key exposure—can be addressed without breaking the trust model of the package manager.
Sources: SECURITY.md:43-51, README.md:118-125, REVIEW.md:47-52