Administer · v0.0.1

Security model

Review trust boundaries, release integrity, secret handling, authorization, audit, and safe-failure behavior.

AudienceSecurity architects, platform owners, auditorsReading time17 minCommands in context12 guided stepsReviewed sourcefcc5871 · 30 July 2026

Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.

Security principles

✓
Customer-controlled deployment: no mandatory shared SaaS control plane.
✓
Fail closed when mandatory production settings, signatures, digests, trust, or compatibility evidence are absent.
✓
Separate human identity, machine identity, agent identity, and operation-scoped target credentials.
✓
Authorize every sensitive endpoint and apply capability gates independently of RBAC.
✓
Use immutable artifacts and explicit plans before mutation.
✓
Redact secret-bearing inputs and preserve auditable, integrity-checked evidence.

Trust boundaries

Boundary	Primary threats	Required controls
Browser/client → API	Session theft, CSRF, injection, over-privilege.	TLS, secure session, CSRF, validation, RBAC, rate limit, audit.
API/worker → PostgreSQL/artifacts	Data loss, tampering, secret exposure.	Private network, service identity, encryption, durable backup, integrity checks.
Control plane → agent	Agent impersonation, replay, incompatible work.	TLS/mTLS as approved, bootstrap identity, heartbeat negotiation, leases, contract versions.
Agent → provider/hosts/clusters	Credential theft, broad mutation, command injection.	SecretRef materialization, typed plans, bounded commands, least privilege, cleanup.
Release source → runtime	Substitution, vulnerable or mutable artifacts.	Checksums, signatures, digest pinning, SBOM, provenance, promotion evidence.

Secret handling

ClusterPilot encrypts protected secret material with a customer-managed 32-byte master key. The key ID identifies the active key; the key itself must be supplied at runtime and backed up separately. Provider tokens, SSH keys, registry credentials, object-store credentials, kubeconfigs, and temporary cluster credentials must never be placed in plan options or logs.

Commands for this step

Upsert protected secret material without command-line exposure

Send the JSON payload through standard input. Never place secret values in shell history, URLs, values files, or documentation.

Use when neededDo not run these commands unless the described condition applies.

01
PrivilegedLinux
Upsert protected secret material through stdin
Write JSON secret material through the application CLI without putting the material in arguments, environment files or command history.
Before you run it
- Application container access inside the approved administration boundary
- Durable database and master key available
- Named secret ID and least-privilege allowed context
Linux · secret-cli-upsert-json
```
read -rsp 'Secret JSON: ' CP_SECRET_JSON && echo
printf '%s' "$CP_SECRET_JSON" | docker exec -i <clusterpilot-api-container> \
  dotnet ClusterPilot.Api.dll secrets upsert \
  --secret-id <sec_id> \
  --name <display-name> \
  --allowed-context <context> \
  --stdin-json \
  --require-json-fields username,password
unset CP_SECRET_JSON
```
Expected result
JSON returns secretId, opaque references, state and allowed contexts; raw material is never returned.
Stop conditions and operator notes
- Repeat --allowed-context for each approved context.
- Use --stdin-text instead of --stdin-json for a single text secret; --require-json-fields is valid only with JSON.
- Exit 64 is invalid input, 65 invalid JSON and 69 an upsert conflict.
Reviewed sourcebackend/src/ClusterPilot.Api/Features/Secrets/SecretAdminCli.cs

Software supply chain

Evidence	Operator use
SHA-256 checksums	Verify release-bundle bytes before extraction and use.
Compatibility signature	Confirm supported versions, subjects, and release contract.
Image signature	Verify the exact API and agent digest before mirroring or deployment.
SBOM	Review included components and retain with the deployed release.
Vulnerability evidence	Apply the customer's policy to the exact digest and approval date.
Provenance	Verify build identity and promotion chain.

Commands for this step

Independently inspect the shipped runtime evidence

Customers and validators use the signed release evidence and exact image digests; they do not rebuild the release.

Run in orderComplete each step successfully before continuing.

Read-onlyCross-platform

Inspect SBOM, vulnerabilities and attestations

Review release-owned SBOMs and independently inspect the exact runtime digests.

Before you run it

jq
Grype
GitHub CLI for attestation verification
Exact release evidence files

Cross-platform · release-sbom-provenance

jq '.metadata.component.name, (.components | length)' sbom/clusterpilot-image.cyclonedx.json
jq '.metadata.component.name, (.components | length)' sbom/clusterpilot-agent-image.cyclonedx.json
syft scan sbom:sbom/clusterpilot-image.cyclonedx.json
syft scan sbom:sbom/clusterpilot-agent-image.cyclonedx.json
grype ghcr.io/<owner>/clusterpilot-api@sha256:<digest>
grype ghcr.io/<owner>/clusterpilot-agent@sha256:<digest>
gh attestation verify oci://ghcr.io/<owner>/clusterpilot-api@sha256:<digest> --repo <owner>/<repo>
gh attestation verify oci://ghcr.io/<owner>/clusterpilot-agent@sha256:<digest> --repo <owner>/<repo>

Expected result

Component identities match the release and no unreviewed policy-blocking result is accepted.

Reviewed sourcedocs/operations/supply-chain-security.md

Commands for this step

Create and evaluate protected release security evidence

These commands run only on approved security or release systems. Private keys and unredacted reports must never enter tickets or documentation.

Protected workflowRun only on an approved maintainer, security, or release system.

01
PrivilegedLinux
Create a release signing key in an offline ceremony
Generate a new Cosign key pair only inside the approved offline key-management boundary.
Before you run it
- Approved key-rotation ceremony
- Offline protected workstation or HSM-backed process
- Named key custodian and backup/revocation plan
Linux · release-offline-signing-key
```
umask 077
cd <offline-protected-key-directory>
cosign generate-key-pair
chmod 0600 cosign.key
cp cosign.pub release-signing-public-key.pem
```
Expected result
Private and public material are generated with recorded key identity; only the public key leaves the protected boundary.
Stop conditions and operator notes
- Never run this on an ordinary CI runner.
- The Cosign private key, password and recovery material must not enter Git, logs, artifacts or support bundles.
Reviewed sourcedocs/operations/supply-chain-security.md
02
Read-onlyCross-platform
Verify a CI candidate image signature
Verify a pre-release candidate against the CI workflow identity before it is considered by protected release gates.
Before you run it
- Cosign
- Exact candidate digest
- Expected repository/workflow identity
Cross-platform · release-candidate-image-signature
```
cosign verify \
  --certificate-identity-regexp '^https://github.com/<owner>/<repo>/.github/workflows/ci.yml@.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/<owner>/<image>@sha256:<digest>
```
Expected result
The candidate signature matches the GitHub OIDC issuer and CI workflow identity.
Stop conditions and operator notes
- Customers install only release-workflow-signed artifacts; a CI signature is candidate evidence, not a GA release claim.
Reviewed sourcedocs/agent/self-hosted-install.md
03
Changes stateLinux
Install a checksum-pinned release tool
Download, checksum, extract and version-probe one release tool without trusting a mutable package-manager result.
Before you run it
- Reviewed upstream/mirror URL
- Independently recorded SHA-256
- Writable isolated tool directory
Linux · release-install-verified-tool
```
./scripts/install-verified-tool.sh \
  --url https://<approved-source>/<archive> \
  --sha256 <64-hex-sha256> \
  --install-dir ./artifacts/tools/bin \
  --install-name <tool-name> \
  --binary-name <binary-name> \
  --archive-type tar.gz
```
Expected result
The exact bytes verify and the installed binary accepts --version or version.
Stop conditions and operator notes
- --archive-type accepts raw or tar.gz.
- Never write into a global system path from an unreviewed source.
Reviewed sourcescripts/install-verified-tool.sh
04
Changes stateLinux
Install the repository-pinned k6 tool
Install the only repository-approved k6 version through the verified-tool helper.
Before you run it
- Linux amd64 release runner
- Approved GitHub release egress or mirror
- curl and sha256sum
Linux · release-install-k6
```
./scripts/install-k6.sh 1.5.0
```
Expected result
k6 1.5.0 verifies against the repository-pinned checksum and reports its version from the runner temp bin directory.
Stop conditions and operator notes
- Any other version fails until its checksum is reviewed and added in source.
Reviewed sourcescripts/install-k6.sh
05
Read-onlyPowerShell
Validate the vulnerability allow-list
Validate schema, required governance fields and expiry posture at a deterministic date.
Before you run it
- PowerShell 7
- Repository allow-list and schema
- Release decision date
PowerShell · release-vulnerability-allowlist-validate
```
& ./scripts/validate-vulnerability-allowlist.ps1 `
  -AllowListPath ./security/cve-allowlist.json `
  -SchemaPath ./schemas/v1/vulnerability-allowlist.schema.1.0.0.json `
  -AsOfDate <yyyy-mm-dd>
```
Expected result
Every exception has valid schema and governance data and is unexpired at the supplied date.
Reviewed sourcescripts/validate-vulnerability-allowlist.ps1
06
Changes statePowerShell
Evaluate the .NET vulnerability policy
Convert the .NET scanner JSON into a governed summary using the dependency allow-list and fail threshold.
Before you run it
- Complete .NET vulnerability JSON report
- Reviewed dependency allow-list
PowerShell · release-dotnet-policy-evaluate
```
& ./scripts/evaluate-dotnet-vulnerability-report.ps1 `
  -ReportPath ./artifacts/vulnerability/dotnet.json `
  -AllowListPath ./security/dotnet-vulnerability-allowlist.json `
  -SummaryPath ./artifacts/vulnerability/dotnet.summary.json `
  -FailThreshold high
```
Expected result
The summary records accepted and blocking advisories; unallowlisted high/critical findings fail.
Reviewed sourcescripts/evaluate-dotnet-vulnerability-report.ps1
07
Changes statePowerShell
Evaluate the pnpm vulnerability policy
Convert pnpm audit JSON into a governed summary using the frontend allow-list and fail threshold.
Before you run it
- Complete pnpm audit JSON report
- Reviewed frontend dependency allow-list
PowerShell · release-pnpm-policy-evaluate
```
& ./scripts/evaluate-pnpm-audit-report.ps1 `
  -ReportPath ./artifacts/vulnerability/pnpm-audit.json `
  -AllowListPath ./security/pnpm-vulnerability-allowlist.json `
  -SummaryPath ./artifacts/vulnerability/pnpm.summary.json `
  -FailThreshold high
```
Expected result
The summary records accepted and blocking advisories; unallowlisted high/critical findings fail.
Reviewed sourcescripts/evaluate-pnpm-audit-report.ps1
08
Changes statePowerShell
Generate governed .NET vulnerability reports
Run the retry-bounded repository scanner and retain both machine-readable and operator-readable reports.
Before you run it
- PowerShell 7
- Repository-pinned .NET SDK
- Restored locked dependencies
- Writable evidence directory
PowerShell · release-dotnet-vulnerability-scan
```
& ./scripts/invoke-dotnet-vulnerability-scan.ps1 `
  -SolutionPath ./backend/ClusterPilot.sln `
  -JsonReportPath ./artifacts/vulnerability/dotnet.json `
  -TextReportPath ./artifacts/vulnerability/dotnet.txt `
  -MaxAttempts 3 `
  -RetryDelaySeconds 5,15 `
  -DotnetCommand dotnet
```
Expected result
JSON and text reports identify the exact solution scan and failed attempts are bounded.
Reviewed sourcescripts/invoke-dotnet-vulnerability-scan.ps1
09
Changes statePowerShell
Evaluate an image CVE report against policy
Apply severity and expiring allow-list policy to a Grype JSON report and create the governed summary.
Before you run it
- PowerShell 7
- Complete Grype JSON report
- Reviewed non-expired CVE allow-list
PowerShell · release-cve-policy-evaluate
```
& ./scripts/evaluate-cve-report.ps1 `
  -ReportPath ./artifacts/vulnerability/api.grype.json `
  -AllowListPath ./security/cve-allowlist.json `
  -SummaryPath ./artifacts/vulnerability/api.summary.json `
  -FailThreshold high `
  -ImageName "ghcr.io/<owner>/clusterpilot-api@sha256:<digest>" `
  -GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o")
```
Expected result
The summary records accepted and blocking findings; an unallowlisted finding at or above the threshold fails the gate.
Reviewed sourcescripts/evaluate-cve-report.ps1

Audit and evidence

Audit should identify actor, machine identity where applicable, tenant/workspace, action, target, decision, time, request/correlation ID, feature gate, and outcome without including credential material. Operation evidence adds plan, steps, events, commands, artifacts, and cleanup state.

Use these records to support change review, incident response, and control testing. ClusterPilot does not claim that enabling audit automatically satisfies a named regulation or certification.

Commands for this step

Export bounded audit records

Use a scoped machine identity, a bounded time window, and an approved evidence destination.

Use when neededDo not run these commands unless the described condition applies.

01
Read-onlyHTTP API
Export audit records
Create a bounded audit export for a review or support case.
Before you run it
- audit.export permission
- Approved retention and handling destination
HTTP API · api-audit-export
```
curl --fail-with-body -sS \
  -H "Authorization: Bearer $CLUSTERPILOT_API_KEY" \
  -H "Idempotency-Key: <uuid>" \
  --output audit-export.json \
  "$CP_URL/api/v1/audit/export"
```
Expected result
A secret-safe audit export is downloaded and the export action is itself audited.
Reviewed sourcedocs/operations/cloud-provider-rollout-compatibility-runbook.md

Deployment hardening checklist

✓
Private network paths for database, artifact storage, agents, and administration.
✓
Trusted TLS on every network boundary; no insecure-skip verification in production.
✓
Non-root, read-only containers with dropped capabilities and RuntimeDefault seccomp.
✓
Least-privileged operator roles, service principals, provider identities, and registry robots.
✓
NetworkPolicy/firewall rules based on the documented traffic matrix.
✓
Backups, restore tests, key escrow, log/artifact retention, and capacity alerts.
✓
Feature gates remain disabled until exact environment evidence and approval exist.