Secret Scanning

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/scan_for_secrets.py
• scripts/test_workflow_safety.py
• AGENTS.md
• REVIEW.md
• SECURITY.md
• README.md

Secret Scanning is a critical security gate in the Numan Registry project designed to prevent the accidental exposure of private-key material or sensitive credentials within the repository. As a data-only repository that signs a registry index, maintaining the integrity and secrecy of the production signing key is a primary trust invariant. The system scans git-tracked files for probable secrets, including PEM markers, private key filename patterns, and hardcoded base64 blobs assigned to sensitive identifiers.

This scanning process is integrated into the project's CI/CD pipeline, serving as a mandatory check for all Pull Requests and production deployments. It ensures that maintainers and automated agents adhere to the project's security policy, which strictly forbids committing private keys (*.key, *.pem) or tokens to the source tree.

Sources: SECURITY.md:16-20, README.md:126-130, AGENTS.md:21-22

Core Scanning Logic

The primary implementation of the secret scanning feature resides in scripts/scan_for_secrets.py. The script operates by identifying all git-tracked files and subjecting them to multiple layers of inspection: filename pattern matching and content-based regex analysis.

Scanning Mechanisms

The scanner employs four distinct detection strategies:

1. PEM Markers: Detecting strings like -----BEGIN PRIVATE KEY-----.
2. Filename Patterns: Identifying tracked files matching extensions like *.key or *.pem.
3. Variable Assignment: Finding literal base64 strings (40–64 characters) assigned to variables containing "priv" or "key".
4. Specific Secrets: Detecting literal values assigned to the NUMAN_REGISTRY_PRIVATE_KEY identifier.

The following diagram illustrates the high-level logic flow of the scanning script:

The logic ensures that files ignored by .gitignore but force-added to git are still caught by the filename check.
Sources: scripts/scan_for_secrets.py:10-45, scripts/scan_for_secrets.py:73-108

Key Identifiers and Regex Patterns

The scanner uses specific regular expressions to target sensitive data while avoiding false positives on public material like official.pub.

Component	Pattern / Value	Purpose
PEM Marker	-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----	Detects standard private key headers.
Filename Globs	*.key, *.pem, *-private*, *_private_key*	Catches private key files force-added to git.
Literal B64	priv(?:ate)?_?key\w*(?:_b64)?\s*[:=]\s*["'](https://github.com/numan-cli/numan-registry/blob/b01a4c780f52b8001310f2b0987e371fd7fba2f4/%5BA-Za-z0-9%2B/%5D%7B40%2C64%7D%3D%7B0%2C2%7D)["']	Detects hardcoded base64 blobs assigned to private key variables.
Registry Secret	NUMAN_REGISTRY_PRIVATE_KEY	Specifically monitors the primary project secret for literal assignments.
Allowlist	# secretscan:allow	Inline marker to bypass checks for legitimate placeholders.

Sources: scripts/scan_for_secrets.py:27-45, scripts/scan_for_secrets.py:64-70

Workflow Integration and Safety

Secret scanning is a prerequisite for all automated workflows in the project. It is defined as a primary gate in repo-safety.yml, staging.yml, and production.yml.

CI/CD Pipeline Flow

The following sequence diagram demonstrates how the secret scan protects the production signing process:

The production.yml workflow is specifically designed to ensure the validate job (containing the secret scan) succeeds before the sign-and-publish job can access the actual environment secrets.
Sources: scripts/test_workflow_safety.py:46-60, REVIEW.md:12-25, AGENTS.md:21-22

Static Safety Checks

The project includes a dedicated test suite, scripts/test_workflow_safety.py, which performs static analysis on the GitHub Actions YAML files themselves. These tests ensure that:

• Secret access is limited to protected jobs using the production environment.
• Workflows default to contents: read permissions.
• Sensitive commands (like scan_for_secrets.py) are present in the validation phase of every workflow.

Sources: scripts/test_workflow_safety.py:38-60

Trust Invariants and Review Standards

The secret scanning system enforces the project's "P0" severity invariants. Failure to pass the secret scan is considered a trust bypass or potential private-key material exposure.

Reviewer Checklist

When reviewing Pull Requests, human and automated reviewers verify the following secret-related invariants:

• No Private Keys in Tree: Never commit *.key or *.pem.
• No Force-Adds: Ensure .gitignore is not bypassed for sensitive paths.
• Placeholder Usage: Verify that registry/index.json.sig contains the literal PLACEHOLDER string rather than a real signature that might have been generated with a local private key.
• Literal Secrets: Ensure that no GitHub Actions expressions (${{ secrets.X }}) have been replaced by literal strings in the workflow files.

Sources: REVIEW.md:36-50, REVIEW.md:55-60, SECURITY.md:58-63

Conclusion

Secret scanning is the foundation of the Numan Registry's security model. By combining proactive scanning of the file tree with static analysis of CI workflows, the project ensures that the Ed25519 signing keys remain strictly within protected environments and encrypted vaults, preventing trust root compromise.

Sources: SECURITY.md:50-55, README.md:95-100