KeyStore
About 931 wordsAbout 3 min
KeyStore introduces the high-security repository provided by Cloud Native Build for storing sensitive information.
When to use: when passwords, API keys, or certificates must be read by a pipeline — for example using credentials from a KeyStore to log in to a registry or sign a release package during a build, with access controls and audit logs limiting the risk.
A KeyStore is a high-security code repository provided by Cloud Native Build, specifically designed for storing and managing sensitive information like passwords, API keys, certificates, tokens, etc. It employs multiple security mechanisms—strict access controls, operational restrictions, audit logs, and watermarks—to ensure security.
Create a KeyStore
Go to the Creation Page Log in to your account and click here to go to the repository creation page.
Select Repository Type and Fill in Info Under repository type, select
KeyStore, and fill in the repository name and description.
Create KeyStore Complete Creation Click the create button to complete the setup.
Core Features
1. Operational Restrictions
KeyStores have strict operational restrictions compared to standard repositories:
| Capability | Standard Repo | KeyStore | Description |
|---|---|---|---|
| Git Clone to Local | ✅ | ❌ | Prevents downloading sensitive data to local environments |
| Push Code from Local | ✅ | ❌ | Prevents pushing changes from local, mitigating risks |
| Edit Files via Web UI | ✅ | ✅ | All changes must be made through the audited Web interface |
| Create Branches/Tags/PRs | ✅ | ✅ | Supports code management within a controlled scope |
| Reference in Pipelines | ✅ | ✅ | Core functionality: enables secure use of secrets |
2. Security Enhancements
- Dynamic Watermark: A semi-transparent watermark with the current username is added on all pages, preventing screenshot leaks and enabling traceability.
- Comprehensive Audit Logs: Records every file reference (when, and by which pipeline), supporting full traceability.
- Web-Only Operations: Files can only be edited in the platform's Web interface, eliminating leakage risks from local environments.
- Strict Permission Controls: Adheres to the system's unified Role Permissions Model for fine-grained access control.
- Declarative Access Scope: Allows precise control over the conditions under which secret files can be referenced. See Permission Checks for details.
Reference in Pipelines
1. Store Secret Files
Within a KeyStore, it's common to use YAML or JSON files to store secrets in a structured way, e.g. production and development:
DOCKER_USER: "prod_username"
DOCKER_TOKEN: "prod_token_123456"
DOCKER_REGISTRY: "registry.prod.com"DOCKER_USER: "dev_username"
DOCKER_TOKEN: "dev_token_123456"
DOCKER_REGISTRY: "registry.dev.com"2. Inject as Environment Variables
In your pipeline configuration (.cnb.yml), use imports to reference files from a KeyStore. Their contents are automatically injected as environment variables.
main:
push:
- services:
- docker
imports:
- https://cnb.cool/<your-repo-slug>/-/blob/main/env.prod.yml
stages:
- name: Build and Push Image
script: |
docker login -u $DOCKER_USER -p "$DOCKER_TOKEN" $DOCKER_REGISTRY
docker build -t $DOCKER_REGISTRY/$CNB_REPO_SLUG_LOWERCASE:latest .
docker push $DOCKER_REGISTRY/$CNB_REPO_SLUG_LOWERCASE:latest3. Reference Authorization & Scope Control
By default, only pipelines triggered by members with the KeyStore's Admin or Owner role can reference its files.
To let pipelines triggered by a broader set of members reference them, declare allow_* fields in the secret file:
allow_slugs: Restrict which repositories' pipelines can reference this file.allow_events: Restrict which events (e.g.,tag_push) can trigger a pipeline that references this file.allow_branches: Restrict which branches (e.g.,main,prod) can reference this file in their pipelines.allow_images: Restrict which specific plugin tasks (by image) can reference this file.Important: Once
allow_*rules are configured, the system ignores the triggerer's role permissions and validates solely against these rules; all of them must pass.See Permission Checks for details.
4. Preventing Leakage Within Pipelines
The KeyStore itself is secure, but once secrets are injected into a pipeline you still need to watch for leakage in scripts, for example environment variables accidentally printed to logs.
Protection Recommendations:
- Secure the Pipeline Configuration: Keep pipeline configurations containing
importsin a separate, access-controlled repository, and expose them to other repos viainclude. - Use Protected Branches: Combine with
allow_branchesto restrict usage to protected branches; changes to protected branches go through a pull request and code review, adding a manual audit step. - Audit and Log Monitoring: Regularly check pipeline logs for unusual activity.
Best Practices
Isolation and Categorization
- Environment Isolation: Create different KeyStores or files for production, staging, and development/testing environments.
- Project Isolation: Use separate KeyStores for different projects to isolate permissions and impact.
- Centralized Management: Manage all KeyStores within a dedicated top-level organization, strictly limiting membership.
Principle of Least Privilege
- Role Control: Assign KeyStore Admin and Owner roles judiciously, following the need-to-know principle.
- Scope Control: Use
allow_*configurations to declare the minimal allowed scope for each secret file.allow_slugs: Limit which projects can reference it.allow_events: Limit triggering to deployment events (tag_push,tag_deploy.*), not every code push.allow_branches: Limit usage to stable, protected branches.
Reduce Configuration Leak Risk
- Encapsulate pipeline logic containing sensitive references in controlled, shared config repositories and expose them to other projects via
include, concentrating risk control points to a few repositories.
- Encapsulate pipeline logic containing sensitive references in controlled, shared config repositories and expose them to other projects via
Regular Rotation and Auditing
- Secret Rotation: Rotate secrets on a routine. Just update the file content in the KeyStore's Web interface, and every pipeline referencing it picks up the new values automatically.
- Permission Audits: Regularly review audit logs, clean up invalid references and authorization rules, and promptly revoke access for members who have left or changed roles.