Administer

Security model

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

AudienceSecurity architects, platform owners, auditorsReading time17 minCommands in context3 guided stepsReviewed source9552586 · 1 August 2026

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 bootstrap/run authorization, 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.	Server-authenticated TLS with explicit CA trust, bootstrap-token enrollment, run-/agent-scoped expiring tokens, heartbeat negotiation, leases and 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
GitHub CLI authenticated when repository access requires it
Exact v0.0.5 release evidence asset

Cross-platform · release-sbom-provenance

gh release download v0.0.5 \
  --repo ClusterPilot-System/clusterpilot \
  --pattern clusterpilot-candidate-evidence-0.0.5.tar.gz
tar -xzf clusterpilot-candidate-evidence-0.0.5.tar.gz
jq '.metadata.component.name, (.components | length)' sbom/api.cyclonedx.json
jq '.metadata.component.name, (.components | length)' sbom/agent.cyclonedx.json
jq '.' cve/api-cve-summary.json
jq '.' cve/agent-cve-summary.json
jq '.' provenance/api-provenance.json
jq '.' provenance/agent-provenance.json

Expected result

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

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

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.