From 2be217f51a65109736db93595a25c2776adf12ac Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 11 Mar 2026 01:13:02 +0100 Subject: [PATCH] feat(canon): add Privileged Execution Control standard v0.2 and schemas Maturity model and schemas for handling necessary privilege escalation across three contexts: OS sudo, Kubernetes RBAC, and CI/CD pipelines. To be applied to the codebase once initial Railiance setup is complete. Files: - privileged-execution-control_v0.2 (standard) - privileged-execution-control-schema_v0.2.1.md (base schema) - privileged-execution-control-schema-os-sudo_v0.2.1.md - privileged-execution-control-schema-kubernetes-rbac_v0.2.1.md - privileged-execution-control-schema-cicd_v0.2.1.md Co-Authored-By: Claude Sonnet 4.6 --- ...ed-execution-control-schema-cicd_v0.2.1.md | 1265 ++++++++++++++++ ...n-control-schema-kubernetes-rbac_v0.2.1.md | 1315 +++++++++++++++++ ...execution-control-schema-os-sudo_v0.2.1.md | 1125 ++++++++++++++ ...vileged-execution-control-schema_v0.2.1.md | 1191 +++++++++++++++ .../privileged-execution-control_v0.2 | 540 +++++++ 5 files changed, 5436 insertions(+) create mode 100644 canon/standards/privileged-execution-control-schema-cicd_v0.2.1.md create mode 100644 canon/standards/privileged-execution-control-schema-kubernetes-rbac_v0.2.1.md create mode 100644 canon/standards/privileged-execution-control-schema-os-sudo_v0.2.1.md create mode 100644 canon/standards/privileged-execution-control-schema_v0.2.1.md create mode 100644 canon/standards/privileged-execution-control_v0.2 diff --git a/canon/standards/privileged-execution-control-schema-cicd_v0.2.1.md b/canon/standards/privileged-execution-control-schema-cicd_v0.2.1.md new file mode 100644 index 0000000..f39693e --- /dev/null +++ b/canon/standards/privileged-execution-control-schema-cicd_v0.2.1.md @@ -0,0 +1,1265 @@ +PecsSchemaCiCd + +*PECS profile schema for `ci-cd` environments* + +Below is a **second-layer PECS profile schema for `ci-cd` environments**. + +It specializes the generic PECS schema for systems where privileged execution is mediated primarily through: + +* CI/CD pipelines +* runners and worker identities +* build/deploy jobs +* OIDC / workload identities +* secret-scoped automation +* gated deployment and infrastructure actions +* pipeline-controlled invocation of privileged entry points in downstream environments + +You can store it as `pecs-cicd-profile.schema.json`. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.org/schemas/pecs-cicd-profile.schema.json", + "title": "PECS CI/CD Profile Schema", + "description": "Second-layer PECS profile schema for CI/CD environments where privileged execution is mediated through pipelines, runners, job identities, deployment actions, and automation trust boundaries.", + "allOf": [ + { + "$ref": "https://example.org/schemas/pecs.schema.json" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "schemaVersion", + "documentType", + "metadata", + "system", + "privilegedExecutionSurface" + ], + "properties": { + "schemaVersion": { + "const": "1.0.0" + }, + "documentType": { + "enum": [ + "pecs-model", + "pecs-assessment", + "pecs-authorization-artifact", + "pecs-profile", + "pecs-combined" + ] + }, + "system": { + "$ref": "#/$defs/cicdSystem" + }, + "privilegedExecutionSurface": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/cicdPrivilegedEntryPoint" + } + }, + "authorizationArtifacts": { + "type": "array", + "items": { + "$ref": "#/$defs/cicdAuthorizationArtifact" + } + }, + "implementationMappings": { + "type": "array", + "items": { + "$ref": "#/$defs/cicdImplementationMapping" + } + }, + "evidence": { + "type": "array", + "items": { + "$ref": "#/$defs/cicdEvidence" + } + } + } + } + ], + "$defs": { + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "identifier": { + "type": "string", + "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" + }, + "hashValue": { + "type": "string", + "pattern": "^[A-Fa-f0-9]{64,128}$" + }, + "uriString": { + "type": "string", + "format": "uri" + }, + "cicdSystem": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "scope", + "environmentTypes", + "cicdProfile" + ], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "environmentTypes": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { + "type": "string", + "enum": [ + "ci-cd", + "os-sudo", + "kubernetes-rbac", + "cloud-iam", + "container-runtime", + "api-admin", + "other" + ] + }, + "contains": { + "const": "ci-cd" + } + }, + "criticality": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "domainProfile": { + "type": "object" + }, + "cicdProfile": { + "$ref": "#/$defs/cicdProfile" + } + } + }, + "cicdProfile": { + "type": "object", + "additionalProperties": false, + "required": [ + "platformType", + "runnerTrustModel", + "identityModel", + "promotionModel" + ], + "properties": { + "platformType": { + "type": "string", + "enum": [ + "github-actions", + "gitlab-ci", + "jenkins", + "azure-devops", + "buildkite", + "tekton", + "argo-workflows", + "generic", + "other" + ] + }, + "runnerTrustModel": { + "type": "string", + "enum": [ + "shared-runners", + "dedicated-runners", + "ephemeral-runners", + "self-hosted-static", + "mixed" + ] + }, + "identityModel": { + "type": "string", + "enum": [ + "static-secrets", + "oidc-federated", + "workload-identity", + "mixed" + ] + }, + "promotionModel": { + "type": "string", + "enum": [ + "branch-driven", + "artifact-promotion", + "gitops-promotion", + "manual-approval-gated", + "mixed" + ] + }, + "repositoryScope": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "environmentsInScope": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "requiredReviewersForPrivilegedChanges": { + "type": "integer", + "minimum": 0 + }, + "artifactSigningUsed": { + "type": "boolean" + }, + "provenanceGenerated": { + "type": "boolean" + }, + "policyEngines": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "none", + "opa", + "conftest", + "slsa-verifier", + "custom-policy", + "other" + ] + }, + "default": [] + }, + "notes": { + "type": "string" + } + } + }, + "cicdPrivilegedEntryPoint": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "kind", + "command", + "privilegeDomain", + "executionContext", + "declaredEffects", + "riskLevel", + "invocationContract", + "cicdControls" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "kind": { + "type": "string", + "enum": [ + "pipeline-step", + "job", + "workflow", + "deployment-action", + "release-action", + "gateway", + "secret-bearing-step", + "runner-operation", + "other" + ] + }, + "path": { + "type": "string" + }, + "command": { + "type": "string", + "minLength": 1 + }, + "privilegeDomain": { + "type": "string", + "enum": [ + "ci-cd", + "cloud-admin", + "kubernetes-rbac", + "root", + "sudo", + "api-admin", + "artifact-signing", + "other" + ] + }, + "executionContext": { + "$ref": "#/$defs/cicdExecutionContext" + }, + "declaredEffects": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "riskLevel": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "integrityBinding": { + "$ref": "#/$defs/cicdIntegrityBinding" + }, + "authorizationReference": { + "$ref": "#/$defs/identifier" + }, + "invocationContract": { + "$ref": "#/$defs/cicdInvocationContract" + }, + "reviews": { + "type": "array", + "items": { + "$ref": "#/$defs/cicdReviewRecord" + }, + "default": [] + }, + "evidenceRefs": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + }, + "cicdControls": { + "$ref": "#/$defs/cicdControls" + } + } + }, + "cicdExecutionContext": { + "type": "object", + "additionalProperties": false, + "required": [ + "environmentType", + "runAs", + "allowedCallers", + "networkAccess", + "runnerClass" + ], + "properties": { + "environmentType": { + "type": "string", + "enum": [ + "ci-cd", + "os-sudo", + "kubernetes-rbac", + "cloud-iam", + "container-runtime", + "other" + ] + }, + "allowedCallers": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "runAs": { + "type": "string", + "enum": [ + "pipeline-identity", + "runner-identity", + "oidc-federated-identity", + "workload-identity", + "service-account", + "user", + "other" + ] + }, + "runAsIdentity": { + "type": "string" + }, + "runnerClass": { + "type": "string", + "enum": [ + "shared", + "dedicated", + "ephemeral", + "self-hosted-static", + "other" + ] + }, + "targetEnvironment": { + "type": "string" + }, + "networkAccess": { + "type": "string", + "enum": [ + "none", + "restricted", + "full", + "unknown" + ] + }, + "interactiveAllowed": { + "type": "boolean" + }, + "automationAllowed": { + "type": "boolean" + }, + "environmentRestrictions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "sourceTrustConstraints": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + } + } + }, + "cicdIntegrityBinding": { + "type": "object", + "additionalProperties": false, + "required": [ + "type" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "none", + "commit-hash", + "artifact-digest", + "signed-artifact", + "provenance-attestation", + "workflow-definition-hash", + "other" + ] + }, + "algorithm": { + "type": "string", + "enum": [ + "sha256", + "sha384", + "sha512", + "git-commit", + "sigstore", + "x509", + "slsa", + "other" + ] + }, + "digest": { + "$ref": "#/$defs/hashValue" + }, + "gitRevision": { + "type": "string" + }, + "artifactRef": { + "type": "string" + }, + "attestationRef": { + "type": "string" + }, + "signatureRef": { + "type": "string" + }, + "verifiedBeforeExecution": { + "type": "boolean" + }, + "reviewRenewalRequiredOnChange": { + "type": "boolean" + } + } + }, + "cicdInvocationContract": { + "type": "object", + "additionalProperties": false, + "required": [ + "allowedArgumentsPolicy", + "expectedEffects", + "failureMode", + "privilegeExpectation", + "startupChecks" + ], + "properties": { + "allowedArgumentsPolicy": { + "$ref": "#/$defs/cicdArgumentsPolicy" + }, + "expectedEffects": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "forbiddenEffects": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "preconditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "postconditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "failureMode": { + "type": "string", + "enum": [ + "fail-closed", + "best-effort" + ] + }, + "privilegeExpectation": { + "type": "string", + "enum": [ + "must-run-on-approved-runner", + "must-use-approved-federated-identity", + "must-use-reviewed-workflow-definition", + "must-be-approved-for-target-environment", + "must-be-invoked-via-reviewed-pipeline" + ] + }, + "startupChecks": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "check-source-ref-policy", + "check-runner-class", + "check-target-environment", + "check-required-approvals", + "check-identity-binding", + "check-secret-scope", + "check-artifact-digest", + "check-provenance-attestation", + "check-workflow-definition-hash", + "check-argument-contract", + "check-caller-identity", + "check-concurrency-lock" + ] + } + } + } + }, + "cicdArgumentsPolicy": { + "type": "object", + "additionalProperties": false, + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "none", + "fixed", + "allowlist", + "schema-validated", + "policy-evaluated" + ] + }, + "fixedArguments": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "allowedPatterns": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "jsonSchema": { + "type": "object" + }, + "notes": { + "type": "string" + } + } + }, + "cicdControls": { + "type": "object", + "additionalProperties": false, + "required": [ + "entryPointModel", + "runnerRestricted", + "identityEphemeralWherePossible", + "reviewedWorkflowRequired", + "environmentApprovalRequired", + "secretExposureRisk" + ], + "properties": { + "entryPointModel": { + "type": "string", + "enum": [ + "direct-pipeline-step", + "reviewed-deployment-gateway", + "release-workflow", + "promotion-pipeline", + "runner-mediated-operation", + "other" + ] + }, + "runnerRestricted": { + "type": "boolean" + }, + "runnerIsolationLevel": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "ephemeral-strong", + "unknown" + ] + }, + "identityEphemeralWherePossible": { + "type": "boolean" + }, + "reviewedWorkflowRequired": { + "type": "boolean" + }, + "workflowPinnedToTrustedRef": { + "type": "boolean" + }, + "environmentApprovalRequired": { + "type": "boolean" + }, + "requiresTwoPersonReview": { + "type": "boolean" + }, + "artifactProvenanceVerified": { + "type": "boolean" + }, + "artifactSigningRequired": { + "type": "boolean" + }, + "secretExposureRisk": { + "type": "string", + "enum": [ + "none", + "low", + "moderate", + "high", + "unknown" + ] + }, + "runnerEscapeRisk": { + "type": "string", + "enum": [ + "none", + "low", + "moderate", + "high", + "unknown" + ] + }, + "targetPrivilegeAmplificationRisk": { + "type": "string", + "enum": [ + "none", + "low", + "moderate", + "high", + "unknown" + ] + }, + "policyEvaluated": { + "type": "boolean" + }, + "requiresDedicatedReview": { + "type": "boolean" + }, + "reviewRenewalOnHashChange": { + "type": "boolean" + }, + "approvalGateRefs": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + }, + "targetBindings": { + "type": "array", + "items": { + "$ref": "#/$defs/targetBinding" + }, + "default": [] + } + } + }, + "targetBinding": { + "type": "object", + "additionalProperties": false, + "required": [ + "targetType", + "targetIdentifier", + "bindingMode" + ], + "properties": { + "targetType": { + "type": "string", + "enum": [ + "os-sudo", + "kubernetes-rbac", + "cloud-iam", + "artifact-signing", + "api-admin", + "other" + ] + }, + "targetIdentifier": { + "type": "string" + }, + "bindingMode": { + "type": "string", + "enum": [ + "oidc-federation", + "static-secret", + "approved-kubeconfig", + "reviewed-sudoers-path", + "service-connection", + "other" + ] + }, + "bindingRef": { + "type": "string" + } + } + }, + "cicdReviewRecord": { + "type": "object", + "additionalProperties": false, + "required": [ + "reviewer", + "date", + "reviewType", + "decision" + ], + "properties": { + "reviewer": { + "$ref": "#/$defs/nonEmptyString" + }, + "date": { + "type": "string", + "format": "date" + }, + "reviewType": { + "type": "string", + "enum": [ + "code-review", + "security-review", + "risk-review", + "renewal-review", + "workflow-review", + "runner-review", + "identity-review", + "exception-review" + ] + }, + "decision": { + "type": "string", + "enum": [ + "approved", + "approved-with-conditions", + "rejected", + "expired" + ] + }, + "notes": { + "type": "string" + } + } + }, + "cicdAuthorizationArtifact": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "entries" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "type": { + "type": "string", + "enum": [ + "allowlist", + "signed-approval-manifest", + "policy-bundle", + "attestation-set", + "release-approval-set", + "environment-gate-set" + ] + }, + "path": { + "type": "string" + }, + "signed": { + "type": "boolean" + }, + "signatureRef": { + "type": "string" + }, + "entries": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/cicdAuthorizationEntry" + } + } + } + }, + "cicdAuthorizationEntry": { + "type": "object", + "additionalProperties": false, + "required": [ + "entryId", + "privilegedEntryPointId", + "approvalStatus", + "approvedBy" + ], + "properties": { + "entryId": { + "$ref": "#/$defs/identifier" + }, + "privilegedEntryPointId": { + "$ref": "#/$defs/identifier" + }, + "approvalStatus": { + "type": "string", + "enum": [ + "approved", + "conditional", + "revoked", + "expired", + "draft" + ] + }, + "integrityBinding": { + "$ref": "#/$defs/cicdIntegrityBinding" + }, + "approvedBy": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "approvedAt": { + "type": "string", + "format": "date-time" + }, + "expiresAt": { + "type": "string", + "format": "date-time" + }, + "conditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "pipelineBinding": { + "$ref": "#/$defs/pipelineAuthorizationBinding" + }, + "policyRef": { + "type": "string" + } + } + }, + "pipelineAuthorizationBinding": { + "type": "object", + "additionalProperties": false, + "required": [ + "pipelineRef", + "workflowRef", + "environmentRef" + ], + "properties": { + "pipelineRef": { + "type": "string" + }, + "workflowRef": { + "type": "string" + }, + "jobRef": { + "type": "string" + }, + "environmentRef": { + "type": "string" + }, + "sourceRefPolicy": { + "type": "string", + "enum": [ + "main-only", + "release-branches-only", + "tagged-releases-only", + "reviewed-pr-merge-only", + "custom" + ] + }, + "runnerClass": { + "type": "string", + "enum": [ + "shared", + "dedicated", + "ephemeral", + "self-hosted-static", + "other" + ] + }, + "identityBindingMode": { + "type": "string", + "enum": [ + "oidc-federation", + "workload-identity", + "static-secret", + "service-connection", + "other" + ] + } + } + }, + "cicdImplementationMapping": { + "type": "object", + "additionalProperties": false, + "required": [ + "environmentType", + "pattern", + "tooling" + ], + "properties": { + "environmentType": { + "type": "string", + "enum": [ + "ci-cd", + "os-sudo", + "kubernetes-rbac", + "cloud-iam", + "other" + ] + }, + "pattern": { + "type": "string", + "enum": [ + "reviewed-privileged-workflow", + "environment-gated-deploy", + "oidc-federated-deployment", + "artifact-promotion-gateway", + "runner-isolated-privileged-step", + "signed-release-pipeline", + "provenance-verified-deploy", + "other" + ] + }, + "tooling": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "github-actions", + "gitlab-ci", + "jenkins", + "azure-devops", + "buildkite", + "tekton", + "argo-workflows", + "cosign", + "in-toto", + "slsa-verifier", + "opa", + "conftest", + "vault", + "other" + ] + } + }, + "notes": { + "type": "string" + }, + "references": { + "type": "array", + "items": { + "$ref": "#/$defs/uriString" + }, + "default": [] + } + } + }, + "cicdEvidence": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "description" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "type": { + "type": "string", + "enum": [ + "file", + "log", + "review-record", + "policy", + "attestation", + "report", + "workflow-definition", + "runner-config", + "environment-gate", + "release-record", + "other" + ] + }, + "description": { + "type": "string" + }, + "path": { + "type": "string" + }, + "uri": { + "$ref": "#/$defs/uriString" + }, + "collectedAt": { + "type": "string", + "format": "date-time" + }, + "collectedBy": { + "type": "string" + }, + "hash": { + "$ref": "#/$defs/cicdIntegrityBinding" + } + } + } + } +} +``` + +Here is a **minimal valid example instance** for this profile: + +```json +{ + "schemaVersion": "1.0.0", + "documentType": "pecs-combined", + "metadata": { + "id": "deploy-pipeline-cicd-profile", + "title": "Deploy Pipeline CI/CD PECS Profile", + "version": "0.1.0", + "status": "draft" + }, + "system": { + "name": "deploy-pipeline", + "scope": "Privileged deployment pipeline for production releases using reviewed workflows and OIDC-bound identities.", + "environmentTypes": [ + "ci-cd", + "kubernetes-rbac" + ], + "criticality": "high", + "cicdProfile": { + "platformType": "github-actions", + "runnerTrustModel": "ephemeral-runners", + "identityModel": "oidc-federated", + "promotionModel": "artifact-promotion", + "repositoryScope": [ + "org/platform-deploy" + ], + "environmentsInScope": [ + "staging", + "production" + ], + "requiredReviewersForPrivilegedChanges": 2, + "artifactSigningUsed": true, + "provenanceGenerated": true, + "policyEngines": [ + "opa", + "slsa-verifier" + ] + } + }, + "privilegedExecutionSurface": [ + { + "id": "production-deploy-job", + "name": "production-deploy-job", + "kind": "job", + "path": ".github/workflows/deploy.yml", + "command": "deploy production", + "privilegeDomain": "kubernetes-rbac", + "executionContext": { + "environmentType": "ci-cd", + "runAs": "oidc-federated-identity", + "runAsIdentity": "github-actions:org/platform-deploy:production", + "allowedCallers": [ + "release-workflow" + ], + "runnerClass": "ephemeral", + "targetEnvironment": "production", + "networkAccess": "restricted", + "interactiveAllowed": false, + "automationAllowed": true, + "sourceTrustConstraints": [ + "tagged releases only", + "workflow file changes require two approvals" + ] + }, + "declaredEffects": [ + "Deploy approved signed artifact to production cluster", + "Update release state after successful deployment" + ], + "riskLevel": "critical", + "integrityBinding": { + "type": "workflow-definition-hash", + "algorithm": "sha256", + "digest": "3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677", + "gitRevision": "f4f4d2b1c8d9e0a11223344556677889900aabbc", + "verifiedBeforeExecution": true, + "reviewRenewalRequiredOnChange": true + }, + "invocationContract": { + "allowedArgumentsPolicy": { + "mode": "fixed", + "fixedArguments": [ + "production" + ] + }, + "expectedEffects": [ + "Deploy only reviewed artifacts to approved production target" + ], + "forbiddenEffects": [ + "Deploy from unreviewed branch refs", + "Use static long-lived cloud credentials" + ], + "failureMode": "fail-closed", + "privilegeExpectation": "must-use-approved-federated-identity", + "startupChecks": [ + "check-source-ref-policy", + "check-runner-class", + "check-target-environment", + "check-required-approvals", + "check-identity-binding", + "check-artifact-digest", + "check-provenance-attestation", + "check-workflow-definition-hash" + ] + }, + "cicdControls": { + "entryPointModel": "reviewed-deployment-gateway", + "runnerRestricted": true, + "runnerIsolationLevel": "ephemeral-strong", + "identityEphemeralWherePossible": true, + "reviewedWorkflowRequired": true, + "workflowPinnedToTrustedRef": true, + "environmentApprovalRequired": true, + "requiresTwoPersonReview": true, + "artifactProvenanceVerified": true, + "artifactSigningRequired": true, + "secretExposureRisk": "low", + "runnerEscapeRisk": "low", + "targetPrivilegeAmplificationRisk": "moderate", + "policyEvaluated": true, + "requiresDedicatedReview": true, + "reviewRenewalOnHashChange": true, + "approvalGateRefs": [ + "prod-env-gate" + ], + "targetBindings": [ + { + "targetType": "kubernetes-rbac", + "targetIdentifier": "prod-cluster/deployer", + "bindingMode": "oidc-federation", + "bindingRef": "github-oidc-prod-deployer" + } + ] + } + } + ], + "authorizationArtifacts": [ + { + "id": "deploy-pipeline-approval-set", + "type": "signed-approval-manifest", + "path": "security/cicd-privileged-allowlist.yaml", + "signed": true, + "signatureRef": "cosign://deploy-pipeline-approval-set", + "entries": [ + { + "entryId": "production-deploy-approved", + "privilegedEntryPointId": "production-deploy-job", + "approvalStatus": "approved", + "approvedBy": [ + "platform-security", + "release-management" + ], + "integrityBinding": { + "type": "workflow-definition-hash", + "algorithm": "sha256", + "digest": "3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677", + "gitRevision": "f4f4d2b1c8d9e0a11223344556677889900aabbc", + "verifiedBeforeExecution": true, + "reviewRenewalRequiredOnChange": true + }, + "pipelineBinding": { + "pipelineRef": "org/platform-deploy", + "workflowRef": ".github/workflows/deploy.yml", + "jobRef": "deploy-production", + "environmentRef": "production", + "sourceRefPolicy": "tagged-releases-only", + "runnerClass": "ephemeral", + "identityBindingMode": "oidc-federation" + } + } + ] + } + ] +} +``` + +xxx diff --git a/canon/standards/privileged-execution-control-schema-kubernetes-rbac_v0.2.1.md b/canon/standards/privileged-execution-control-schema-kubernetes-rbac_v0.2.1.md new file mode 100644 index 0000000..d638cae --- /dev/null +++ b/canon/standards/privileged-execution-control-schema-kubernetes-rbac_v0.2.1.md @@ -0,0 +1,1315 @@ +PecsSchemaKubernetesRbac + +*PECS profile schema for `kubernetes-rbac` environments* + +Below is a **second-layer PECS profile schema for `kubernetes-rbac` environments**. + +It specializes the generic PECS schema for systems where privileged execution is mediated primarily through: + +* Kubernetes RBAC +* ServiceAccounts +* Roles / ClusterRoles +* RoleBindings / ClusterRoleBindings +* controllers, operators, jobs, and CI/CD identities acting against the cluster API +* admission and policy controls associated with cluster privilege + +You can store it as `pecs-kubernetes-rbac-profile.schema.json`. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.org/schemas/pecs-kubernetes-rbac-profile.schema.json", + "title": "PECS Kubernetes-RBAC Profile Schema", + "description": "Second-layer PECS profile schema for Kubernetes environments where privileged execution is mediated through RBAC, service accounts, controllers, and cluster API permissions.", + "allOf": [ + { + "$ref": "https://example.org/schemas/pecs.schema.json" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "schemaVersion", + "documentType", + "metadata", + "system", + "privilegedExecutionSurface" + ], + "properties": { + "schemaVersion": { + "const": "1.0.0" + }, + "documentType": { + "enum": [ + "pecs-model", + "pecs-assessment", + "pecs-authorization-artifact", + "pecs-profile", + "pecs-combined" + ] + }, + "system": { + "$ref": "#/$defs/kubernetesRbacSystem" + }, + "privilegedExecutionSurface": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/kubernetesPrivilegedEntryPoint" + } + }, + "authorizationArtifacts": { + "type": "array", + "items": { + "$ref": "#/$defs/kubernetesAuthorizationArtifact" + } + }, + "implementationMappings": { + "type": "array", + "items": { + "$ref": "#/$defs/kubernetesImplementationMapping" + } + }, + "evidence": { + "type": "array", + "items": { + "$ref": "#/$defs/kubernetesEvidence" + } + } + } + } + ], + "$defs": { + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "identifier": { + "type": "string", + "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" + }, + "hashValue": { + "type": "string", + "pattern": "^[A-Fa-f0-9]{64,128}$" + }, + "k8sName": { + "type": "string", + "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$" + }, + "k8sApiGroup": { + "type": "string" + }, + "kubernetesRbacSystem": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "scope", + "environmentTypes", + "kubernetesRbacProfile" + ], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "environmentTypes": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { + "type": "string", + "enum": [ + "kubernetes-rbac", + "ci-cd", + "container-runtime", + "cloud-iam" + ] + }, + "contains": { + "const": "kubernetes-rbac" + } + }, + "criticality": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "domainProfile": { + "type": "object" + }, + "kubernetesRbacProfile": { + "$ref": "#/$defs/kubernetesRbacProfile" + } + } + }, + "kubernetesRbacProfile": { + "type": "object", + "additionalProperties": false, + "required": [ + "clusterScopeModel", + "rbacPolicyModel", + "privilegedExecutionModel" + ], + "properties": { + "clusterScopeModel": { + "type": "string", + "enum": [ + "single-cluster", + "multi-cluster", + "fleet-managed", + "other" + ] + }, + "rbacPolicyModel": { + "type": "string", + "enum": [ + "direct-role-binding", + "controller-mediated", + "gitops-mediated", + "mixed" + ] + }, + "privilegedExecutionModel": { + "type": "string", + "enum": [ + "dedicated-privileged-serviceaccounts", + "controller-operator-gateway", + "job-based-privileged-actions", + "mixed" + ] + }, + "clusterIdentifiers": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "namespacesInScope": { + "type": "array", + "items": { + "$ref": "#/$defs/k8sName" + }, + "default": [] + }, + "policyEngines": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "none", + "opa-gatekeeper", + "kyverno", + "validating-admission-policy", + "other" + ] + }, + "default": [] + }, + "auditLoggingEnabled": { + "type": "boolean" + }, + "serviceAccountTokenPolicy": { + "type": "string", + "enum": [ + "bound-tokens", + "legacy-secrets", + "mixed", + "unknown" + ] + }, + "notes": { + "type": "string" + } + } + }, + "kubernetesPrivilegedEntryPoint": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "kind", + "command", + "privilegeDomain", + "executionContext", + "declaredEffects", + "riskLevel", + "invocationContract", + "kubernetesControls" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "kind": { + "type": "string", + "enum": [ + "controller", + "operator", + "job", + "pipeline-step", + "api-call", + "gateway", + "serviceaccount-binding", + "other" + ] + }, + "path": { + "type": "string" + }, + "command": { + "type": "string", + "minLength": 1 + }, + "privilegeDomain": { + "type": "string", + "enum": [ + "kubernetes-rbac", + "kubernetes-admin", + "container-privileged", + "cloud-admin" + ] + }, + "executionContext": { + "$ref": "#/$defs/kubernetesExecutionContext" + }, + "declaredEffects": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "riskLevel": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "integrityBinding": { + "$ref": "#/$defs/kubernetesIntegrityBinding" + }, + "authorizationReference": { + "$ref": "#/$defs/identifier" + }, + "invocationContract": { + "$ref": "#/$defs/kubernetesInvocationContract" + }, + "reviews": { + "type": "array", + "items": { + "$ref": "#/$defs/kubernetesReviewRecord" + }, + "default": [] + }, + "evidenceRefs": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + }, + "kubernetesControls": { + "$ref": "#/$defs/kubernetesControls" + } + }, + "allOf": [ + { + "if": { + "properties": { + "kind": { + "const": "controller" + } + }, + "required": [ + "kind" + ] + }, + "then": { + "properties": { + "kubernetesControls": { + "properties": { + "entryPointModel": { + "enum": [ + "controller-gateway", + "operator" + ] + } + }, + "required": [ + "entryPointModel" + ] + } + } + } + }, + { + "if": { + "properties": { + "kind": { + "const": "serviceaccount-binding" + } + }, + "required": [ + "kind" + ] + }, + "then": { + "properties": { + "kubernetesControls": { + "required": [ + "rbacBindings" + ] + } + } + } + } + ] + }, + "kubernetesExecutionContext": { + "type": "object", + "additionalProperties": false, + "required": [ + "environmentType", + "runAs", + "allowedCallers", + "networkAccess", + "clusterScope" + ], + "properties": { + "environmentType": { + "type": "string", + "enum": [ + "kubernetes-rbac", + "ci-cd", + "container-runtime", + "cloud-iam" + ] + }, + "allowedCallers": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "runAs": { + "type": "string", + "enum": [ + "serviceaccount", + "user", + "external-ci-identity", + "controller", + "operator" + ] + }, + "runAsIdentity": { + "type": "string" + }, + "clusterScope": { + "type": "string", + "enum": [ + "namespace", + "cluster", + "fleet" + ] + }, + "targetNamespaces": { + "type": "array", + "items": { + "$ref": "#/$defs/k8sName" + }, + "default": [] + }, + "networkAccess": { + "type": "string", + "enum": [ + "none", + "restricted", + "full", + "unknown" + ] + }, + "interactiveAllowed": { + "type": "boolean" + }, + "automationAllowed": { + "type": "boolean" + }, + "environmentRestrictions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + } + } + }, + "kubernetesIntegrityBinding": { + "type": "object", + "additionalProperties": false, + "required": [ + "type" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "none", + "manifest-hash", + "image-digest", + "signed-artifact", + "attestation", + "gitops-revision" + ] + }, + "algorithm": { + "type": "string", + "enum": [ + "sha256", + "sha384", + "sha512", + "sigstore", + "x509", + "git-commit", + "other" + ] + }, + "digest": { + "$ref": "#/$defs/hashValue" + }, + "imageRef": { + "type": "string" + }, + "gitRevision": { + "type": "string" + }, + "attestationRef": { + "type": "string" + }, + "signatureRef": { + "type": "string" + }, + "verifiedAtAdmission": { + "type": "boolean" + }, + "verifiedAtRuntime": { + "type": "boolean" + }, + "reviewRenewalRequiredOnChange": { + "type": "boolean" + } + } + }, + "kubernetesInvocationContract": { + "type": "object", + "additionalProperties": false, + "required": [ + "allowedArgumentsPolicy", + "expectedEffects", + "failureMode", + "privilegeExpectation", + "startupChecks" + ], + "properties": { + "allowedArgumentsPolicy": { + "$ref": "#/$defs/kubernetesArgumentsPolicy" + }, + "expectedEffects": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "forbiddenEffects": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "preconditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "postconditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "failureMode": { + "type": "string", + "enum": [ + "fail-closed", + "best-effort" + ] + }, + "privilegeExpectation": { + "type": "string", + "enum": [ + "must-run-under-approved-serviceaccount", + "must-be-admitted-by-policy", + "must-be-invoked-via-approved-controller", + "must-use-approved-kubeconfig" + ] + }, + "startupChecks": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "check-serviceaccount-identity", + "check-rbac-scope", + "check-target-namespace", + "check-admission-policy-compliance", + "check-image-digest", + "check-gitops-revision", + "check-argument-contract", + "check-caller-identity", + "check-locking", + "check-prerequisite-resources" + ] + } + } + } + }, + "kubernetesArgumentsPolicy": { + "type": "object", + "additionalProperties": false, + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "none", + "fixed", + "allowlist", + "schema-validated", + "policy-evaluated" + ] + }, + "fixedArguments": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "allowedPatterns": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "jsonSchema": { + "type": "object" + }, + "notes": { + "type": "string" + } + } + }, + "kubernetesControls": { + "type": "object", + "additionalProperties": false, + "required": [ + "entryPointModel", + "rbacRestricted", + "namespaceScopedWherePossible", + "serviceAccountDedicated", + "admissionControlled", + "privilegedPodRisk" + ], + "properties": { + "entryPointModel": { + "type": "string", + "enum": [ + "direct-rbac-bound-identity", + "controller-gateway", + "operator", + "job-runner", + "gitops-controller", + "pipeline-mediated" + ] + }, + "serviceAccountDedicated": { + "type": "boolean" + }, + "rbacRestricted": { + "type": "boolean" + }, + "namespaceScopedWherePossible": { + "type": "boolean" + }, + "clusterAdminBound": { + "type": "boolean" + }, + "admissionControlled": { + "type": "boolean" + }, + "policyEngine": { + "type": "string", + "enum": [ + "none", + "opa-gatekeeper", + "kyverno", + "validating-admission-policy", + "other" + ] + }, + "privilegedPodRisk": { + "type": "string", + "enum": [ + "none", + "low", + "moderate", + "high", + "unknown" + ] + }, + "hostAccessRisk": { + "type": "string", + "enum": [ + "none", + "low", + "moderate", + "high", + "unknown" + ] + }, + "tokenExposureRisk": { + "type": "string", + "enum": [ + "none", + "low", + "moderate", + "high", + "unknown" + ] + }, + "requiresDedicatedReview": { + "type": "boolean" + }, + "reviewRenewalOnChange": { + "type": "boolean" + }, + "rbacBindings": { + "type": "array", + "items": { + "$ref": "#/$defs/rbacBindingReference" + }, + "default": [] + }, + "rbacRules": { + "type": "array", + "items": { + "$ref": "#/$defs/rbacRule" + }, + "default": [] + } + } + }, + "rbacBindingReference": { + "type": "object", + "additionalProperties": false, + "required": [ + "kind", + "name" + ], + "properties": { + "kind": { + "type": "string", + "enum": [ + "RoleBinding", + "ClusterRoleBinding" + ] + }, + "name": { + "$ref": "#/$defs/k8sName" + }, + "namespace": { + "$ref": "#/$defs/k8sName" + }, + "roleRefKind": { + "type": "string", + "enum": [ + "Role", + "ClusterRole" + ] + }, + "roleRefName": { + "$ref": "#/$defs/k8sName" + } + } + }, + "rbacRule": { + "type": "object", + "additionalProperties": false, + "required": [ + "apiGroups", + "resources", + "verbs" + ], + "properties": { + "apiGroups": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/k8sApiGroup" + } + }, + "resources": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + } + }, + "resourceNames": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "verbs": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + } + }, + "nonResourceURLs": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + } + } + }, + "kubernetesReviewRecord": { + "type": "object", + "additionalProperties": false, + "required": [ + "reviewer", + "date", + "reviewType", + "decision" + ], + "properties": { + "reviewer": { + "$ref": "#/$defs/nonEmptyString" + }, + "date": { + "type": "string", + "format": "date" + }, + "reviewType": { + "type": "string", + "enum": [ + "code-review", + "security-review", + "risk-review", + "renewal-review", + "rbac-review", + "admission-policy-review", + "exception-review" + ] + }, + "decision": { + "type": "string", + "enum": [ + "approved", + "approved-with-conditions", + "rejected", + "expired" + ] + }, + "notes": { + "type": "string" + } + } + }, + "kubernetesAuthorizationArtifact": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "entries" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "type": { + "type": "string", + "enum": [ + "allowlist", + "signed-approval-manifest", + "policy-bundle", + "attestation-set", + "gitops-approval-set" + ] + }, + "path": { + "type": "string" + }, + "signed": { + "type": "boolean" + }, + "signatureRef": { + "type": "string" + }, + "entries": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/kubernetesAuthorizationEntry" + } + } + } + }, + "kubernetesAuthorizationEntry": { + "type": "object", + "additionalProperties": false, + "required": [ + "entryId", + "privilegedEntryPointId", + "approvalStatus", + "approvedBy" + ], + "properties": { + "entryId": { + "$ref": "#/$defs/identifier" + }, + "privilegedEntryPointId": { + "$ref": "#/$defs/identifier" + }, + "approvalStatus": { + "type": "string", + "enum": [ + "approved", + "conditional", + "revoked", + "expired", + "draft" + ] + }, + "integrityBinding": { + "$ref": "#/$defs/kubernetesIntegrityBinding" + }, + "approvedBy": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "approvedAt": { + "type": "string", + "format": "date-time" + }, + "expiresAt": { + "type": "string", + "format": "date-time" + }, + "conditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "rbacBinding": { + "$ref": "#/$defs/rbacAuthorizationBinding" + }, + "policyRef": { + "type": "string" + } + } + }, + "rbacAuthorizationBinding": { + "type": "object", + "additionalProperties": false, + "required": [ + "subjectKind", + "subjectName", + "bindingKind", + "roleRefKind", + "roleRefName" + ], + "properties": { + "subjectKind": { + "type": "string", + "enum": [ + "ServiceAccount", + "User", + "Group" + ] + }, + "subjectName": { + "type": "string" + }, + "subjectNamespace": { + "$ref": "#/$defs/k8sName" + }, + "bindingKind": { + "type": "string", + "enum": [ + "RoleBinding", + "ClusterRoleBinding" + ] + }, + "bindingName": { + "$ref": "#/$defs/k8sName" + }, + "bindingNamespace": { + "$ref": "#/$defs/k8sName" + }, + "roleRefKind": { + "type": "string", + "enum": [ + "Role", + "ClusterRole" + ] + }, + "roleRefName": { + "$ref": "#/$defs/k8sName" + } + } + }, + "kubernetesImplementationMapping": { + "type": "object", + "additionalProperties": false, + "required": [ + "environmentType", + "pattern", + "tooling" + ], + "properties": { + "environmentType": { + "type": "string", + "enum": [ + "kubernetes-rbac", + "ci-cd", + "container-runtime", + "cloud-iam" + ] + }, + "pattern": { + "type": "string", + "enum": [ + "dedicated-serviceaccount", + "controller-gateway", + "operator-pattern", + "namespace-scoped-rbac", + "cluster-scoped-reviewed-rbac", + "admission-policy-enforced", + "gitops-approved-privileged-change", + "ci-approved-cluster-action" + ] + }, + "tooling": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "kubectl", + "helm", + "kustomize", + "opa-gatekeeper", + "kyverno", + "validating-admission-policy", + "argo-cd", + "flux", + "cosign", + "in-toto", + "trivy", + "stern", + "audit-policy", + "other" + ] + } + }, + "notes": { + "type": "string" + }, + "references": { + "type": "array", + "items": { + "type": "string", + "format": "uri" + }, + "default": [] + } + } + }, + "kubernetesEvidence": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "description" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "type": { + "type": "string", + "enum": [ + "file", + "log", + "review-record", + "policy", + "attestation", + "report", + "rbac-manifest", + "audit-policy", + "image-signature", + "gitops-record", + "other" + ] + }, + "description": { + "type": "string" + }, + "path": { + "type": "string" + }, + "uri": { + "type": "string", + "format": "uri" + }, + "collectedAt": { + "type": "string", + "format": "date-time" + }, + "collectedBy": { + "type": "string" + }, + "hash": { + "$ref": "#/$defs/kubernetesIntegrityBinding" + } + } + } + } +} +``` + +Here is a **minimal valid example instance** for this profile: + +```json +{ + "schemaVersion": "1.0.0", + "documentType": "pecs-combined", + "metadata": { + "id": "backup-controller-k8s-profile", + "title": "Backup Controller Kubernetes RBAC PECS Profile", + "version": "0.1.0", + "status": "draft" + }, + "system": { + "name": "backup-controller", + "scope": "Privileged Kubernetes backup control via dedicated service account and reviewed RBAC.", + "environmentTypes": [ + "kubernetes-rbac", + "ci-cd" + ], + "criticality": "high", + "kubernetesRbacProfile": { + "clusterScopeModel": "single-cluster", + "rbacPolicyModel": "controller-mediated", + "privilegedExecutionModel": "controller-operator-gateway", + "clusterIdentifiers": [ + "prod-eu-1" + ], + "namespacesInScope": [ + "backup-system" + ], + "policyEngines": [ + "kyverno" + ], + "auditLoggingEnabled": true, + "serviceAccountTokenPolicy": "bound-tokens" + } + }, + "privilegedExecutionSurface": [ + { + "id": "backup-operator", + "name": "backup-operator", + "kind": "controller", + "path": "deploy/backup-operator", + "command": "backup-operator reconcile", + "privilegeDomain": "kubernetes-rbac", + "executionContext": { + "environmentType": "kubernetes-rbac", + "runAs": "serviceaccount", + "runAsIdentity": "system:serviceaccount:backup-system:backup-operator", + "allowedCallers": [ + "kube-controller-manager", + "argo-cd" + ], + "clusterScope": "namespace", + "targetNamespaces": [ + "backup-system" + ], + "networkAccess": "restricted", + "interactiveAllowed": false, + "automationAllowed": true + }, + "declaredEffects": [ + "Create backup jobs in approved namespace", + "Read PVC metadata", + "Write backup status resources" + ], + "riskLevel": "high", + "integrityBinding": { + "type": "image-digest", + "algorithm": "sha256", + "digest": "3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677", + "imageRef": "registry.example.org/backup-operator@sha256:3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677", + "verifiedAtAdmission": true, + "reviewRenewalRequiredOnChange": true + }, + "invocationContract": { + "allowedArgumentsPolicy": { + "mode": "fixed", + "fixedArguments": [ + "reconcile" + ] + }, + "expectedEffects": [ + "Operate only in approved namespace and resource scope" + ], + "forbiddenEffects": [ + "Create cluster-wide RBAC", + "Launch privileged hostPath pods" + ], + "failureMode": "fail-closed", + "privilegeExpectation": "must-run-under-approved-serviceaccount", + "startupChecks": [ + "check-serviceaccount-identity", + "check-rbac-scope", + "check-target-namespace", + "check-admission-policy-compliance", + "check-image-digest" + ] + }, + "kubernetesControls": { + "entryPointModel": "controller-gateway", + "serviceAccountDedicated": true, + "rbacRestricted": true, + "namespaceScopedWherePossible": true, + "clusterAdminBound": false, + "admissionControlled": true, + "policyEngine": "kyverno", + "privilegedPodRisk": "low", + "hostAccessRisk": "none", + "tokenExposureRisk": "low", + "requiresDedicatedReview": true, + "reviewRenewalOnChange": true, + "rbacBindings": [ + { + "kind": "RoleBinding", + "name": "backup-operator-binding", + "namespace": "backup-system", + "roleRefKind": "Role", + "roleRefName": "backup-operator-role" + } + ], + "rbacRules": [ + { + "apiGroups": [ + "", + "batch" + ], + "resources": [ + "pods", + "persistentvolumeclaims", + "jobs" + ], + "verbs": [ + "get", + "list", + "watch", + "create" + ] + } + ] + } + } + ], + "authorizationArtifacts": [ + { + "id": "backup-rbac-allowlist", + "type": "signed-approval-manifest", + "path": "security/k8s-privileged-allowlist.yaml", + "signed": true, + "signatureRef": "cosign://backup-rbac-allowlist", + "entries": [ + { + "entryId": "backup-operator-approved", + "privilegedEntryPointId": "backup-operator", + "approvalStatus": "approved", + "approvedBy": [ + "platform-security" + ], + "integrityBinding": { + "type": "image-digest", + "algorithm": "sha256", + "digest": "3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677", + "imageRef": "registry.example.org/backup-operator@sha256:3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677", + "verifiedAtAdmission": true, + "reviewRenewalRequiredOnChange": true + }, + "rbacBinding": { + "subjectKind": "ServiceAccount", + "subjectName": "backup-operator", + "subjectNamespace": "backup-system", + "bindingKind": "RoleBinding", + "bindingName": "backup-operator-binding", + "bindingNamespace": "backup-system", + "roleRefKind": "Role", + "roleRefName": "backup-operator-role" + } + } + ] + } + ] +} +``` + + +xxx diff --git a/canon/standards/privileged-execution-control-schema-os-sudo_v0.2.1.md b/canon/standards/privileged-execution-control-schema-os-sudo_v0.2.1.md new file mode 100644 index 0000000..05f50d9 --- /dev/null +++ b/canon/standards/privileged-execution-control-schema-os-sudo_v0.2.1.md @@ -0,0 +1,1125 @@ +PecsSchemaOsSudo + +*PECS profile schema for `os-sudo` environments* + +Below is a **second-layer PECS profile schema for `os-sudo` environments**. + +It specializes the generic PECS schema for systems where privileged execution is mediated primarily through: + +* `sudo` +* `root` +* optional Linux capabilities +* local scripts, binaries, and gateways +* CI/CD runners invoking approved privileged commands on Linux hosts + +You can store it as `pecs-os-sudo-profile.schema.json`. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.org/schemas/pecs-os-sudo-profile.schema.json", + "title": "PECS OS-Sudo Profile Schema", + "description": "Second-layer PECS profile schema for Linux host environments using sudo/root mediated privileged execution.", + "allOf": [ + { + "$ref": "https://example.org/schemas/pecs.schema.json" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "schemaVersion", + "documentType", + "metadata", + "system", + "privilegedExecutionSurface" + ], + "properties": { + "schemaVersion": { + "const": "1.0.0" + }, + "documentType": { + "enum": [ + "pecs-model", + "pecs-assessment", + "pecs-authorization-artifact", + "pecs-profile", + "pecs-combined" + ] + }, + "system": { + "$ref": "#/$defs/osSudoSystem" + }, + "privilegedExecutionSurface": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/osSudoPrivilegedEntryPoint" + } + }, + "authorizationArtifacts": { + "type": "array", + "items": { + "$ref": "#/$defs/osSudoAuthorizationArtifact" + } + }, + "implementationMappings": { + "type": "array", + "items": { + "$ref": "#/$defs/osSudoImplementationMapping" + } + }, + "evidence": { + "type": "array", + "items": { + "$ref": "#/$defs/osSudoEvidence" + } + } + } + } + ], + "$defs": { + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "identifier": { + "type": "string", + "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" + }, + "hashValue": { + "type": "string", + "pattern": "^[A-Fa-f0-9]{64,128}$" + }, + "osSudoSystem": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "scope", + "environmentTypes", + "osSudoProfile" + ], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "environmentTypes": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { + "type": "string", + "enum": [ + "os-sudo", + "ci-cd", + "os-capabilities" + ] + }, + "contains": { + "const": "os-sudo" + } + }, + "criticality": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "domainProfile": { + "type": "object" + }, + "osSudoProfile": { + "$ref": "#/$defs/osSudoProfile" + } + } + }, + "osSudoProfile": { + "type": "object", + "additionalProperties": false, + "required": [ + "hostClass", + "sudoPolicyModel", + "privilegedExecutionModel" + ], + "properties": { + "hostClass": { + "type": "string", + "enum": [ + "developer-workstation", + "server", + "ci-runner", + "admin-host", + "appliance", + "other" + ] + }, + "sudoPolicyModel": { + "type": "string", + "enum": [ + "direct-command-allowlist", + "gateway-only", + "mixed", + "manual-only" + ] + }, + "privilegedExecutionModel": { + "type": "string", + "enum": [ + "dedicated-root-scripts", + "single-rootctl-gateway", + "mixed" + ] + }, + "sudoersPaths": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "requireTty": { + "type": "boolean" + }, + "usePasswordlessSudoForAutomation": { + "type": "boolean" + }, + "allowedAutomationIdentities": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "notes": { + "type": "string" + } + } + }, + "osSudoPrivilegedEntryPoint": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "kind", + "path", + "command", + "privilegeDomain", + "executionContext", + "declaredEffects", + "riskLevel", + "integrityBinding", + "invocationContract", + "osSudoControls" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "kind": { + "type": "string", + "enum": [ + "script", + "binary", + "gateway" + ] + }, + "path": { + "type": "string", + "pattern": "^(/|\\./|\\.\\./|[A-Za-z0-9._/-]+)" + }, + "command": { + "type": "string", + "minLength": 1 + }, + "privilegeDomain": { + "type": "string", + "enum": [ + "root", + "sudo", + "linux-capability" + ] + }, + "executionContext": { + "$ref": "#/$defs/osSudoExecutionContext" + }, + "declaredEffects": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "riskLevel": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "integrityBinding": { + "$ref": "#/$defs/osSudoIntegrityBinding" + }, + "authorizationReference": { + "$ref": "#/$defs/identifier" + }, + "invocationContract": { + "$ref": "#/$defs/osSudoInvocationContract" + }, + "reviews": { + "type": "array", + "items": { + "$ref": "#/$defs/osSudoReviewRecord" + }, + "default": [] + }, + "evidenceRefs": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + }, + "osSudoControls": { + "$ref": "#/$defs/osSudoControls" + } + }, + "allOf": [ + { + "if": { + "properties": { + "kind": { + "const": "gateway" + } + }, + "required": [ + "kind" + ] + }, + "then": { + "properties": { + "osSudoControls": { + "properties": { + "entryPointModel": { + "const": "gateway" + } + }, + "required": [ + "entryPointModel" + ] + } + } + } + }, + { + "if": { + "properties": { + "kind": { + "const": "script" + } + }, + "required": [ + "kind" + ] + }, + "then": { + "properties": { + "path": { + "pattern": ".*" + } + } + } + } + ] + }, + "osSudoExecutionContext": { + "type": "object", + "additionalProperties": false, + "required": [ + "environmentType", + "runAs", + "allowedCallers", + "networkAccess" + ], + "properties": { + "environmentType": { + "type": "string", + "enum": [ + "os-sudo", + "ci-cd", + "os-capabilities" + ] + }, + "allowedCallers": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "workingDirectory": { + "type": "string" + }, + "runAs": { + "type": "string", + "enum": [ + "root", + "service-account", + "specific-user" + ] + }, + "runAsIdentity": { + "type": "string" + }, + "networkAccess": { + "type": "string", + "enum": [ + "none", + "restricted", + "full", + "unknown" + ] + }, + "environmentRestrictions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "interactiveAllowed": { + "type": "boolean" + }, + "automationAllowed": { + "type": "boolean" + } + }, + "allOf": [ + { + "if": { + "properties": { + "runAs": { + "const": "specific-user" + } + } + }, + "then": { + "required": [ + "runAsIdentity" + ] + } + } + ] + }, + "osSudoIntegrityBinding": { + "type": "object", + "additionalProperties": false, + "required": [ + "type", + "algorithm" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "checksum", + "hash-verified", + "signed-artifact", + "attestation" + ] + }, + "algorithm": { + "type": "string", + "enum": [ + "sha256", + "sha384", + "sha512", + "blake2b", + "sigstore", + "x509" + ] + }, + "digest": { + "$ref": "#/$defs/hashValue" + }, + "signatureRef": { + "type": "string" + }, + "attestationRef": { + "type": "string" + }, + "verifiedAtExecution": { + "type": "boolean" + }, + "reviewRenewalRequiredOnChange": { + "type": "boolean" + } + }, + "allOf": [ + { + "if": { + "properties": { + "algorithm": { + "enum": [ + "sha256", + "sha384", + "sha512", + "blake2b" + ] + } + } + }, + "then": { + "required": [ + "digest" + ] + } + } + ] + }, + "osSudoInvocationContract": { + "type": "object", + "additionalProperties": false, + "required": [ + "allowedArgumentsPolicy", + "expectedEffects", + "failureMode", + "privilegeExpectation", + "startupChecks" + ], + "properties": { + "allowedArgumentsPolicy": { + "$ref": "#/$defs/osSudoArgumentsPolicy" + }, + "expectedEffects": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "forbiddenEffects": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "preconditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "postconditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "failureMode": { + "type": "string", + "enum": [ + "fail-closed", + "best-effort" + ] + }, + "privilegeExpectation": { + "type": "string", + "enum": [ + "must-start-as-root", + "must-be-invoked-via-sudo", + "capability-based" + ] + }, + "startupChecks": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "check-euid-root", + "check-sudo-user", + "check-argv-contract", + "check-working-directory", + "check-environment-sanitized", + "check-integrity-binding", + "check-caller-identity", + "check-locking", + "check-prerequisite-tools" + ] + } + } + } + }, + "osSudoArgumentsPolicy": { + "type": "object", + "additionalProperties": false, + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed", + "allowlist", + "schema-validated", + "policy-evaluated" + ] + }, + "fixedArguments": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "allowedPatterns": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "jsonSchema": { + "type": "object" + }, + "notes": { + "type": "string" + } + }, + "allOf": [ + { + "if": { + "properties": { + "mode": { + "const": "fixed" + } + } + }, + "then": { + "required": [ + "fixedArguments" + ] + } + }, + { + "if": { + "properties": { + "mode": { + "const": "allowlist" + } + } + }, + "then": { + "required": [ + "allowedPatterns" + ] + } + } + ] + }, + "osSudoControls": { + "type": "object", + "additionalProperties": false, + "required": [ + "entryPointModel", + "selfPrivilegeCheck", + "sudoersRestricted", + "shellEscapeRisk", + "environmentSanitization" + ], + "properties": { + "entryPointModel": { + "type": "string", + "enum": [ + "dedicated-root-script", + "gateway", + "capability-bound-binary" + ] + }, + "selfPrivilegeCheck": { + "type": "boolean" + }, + "sudoersRestricted": { + "type": "boolean" + }, + "sudoersDigestBound": { + "type": "boolean" + }, + "passwordlessAllowed": { + "type": "boolean" + }, + "interactiveOnly": { + "type": "boolean" + }, + "shellEscapeRisk": { + "type": "string", + "enum": [ + "none", + "low", + "moderate", + "high", + "unknown" + ] + }, + "environmentSanitization": { + "type": "string", + "enum": [ + "strict", + "partial", + "none", + "unknown" + ] + }, + "usesNoexec": { + "type": "boolean" + }, + "requiresDedicatedReview": { + "type": "boolean" + }, + "reviewRenewalOnHashChange": { + "type": "boolean" + } + } + }, + "osSudoReviewRecord": { + "type": "object", + "additionalProperties": false, + "required": [ + "reviewer", + "date", + "reviewType", + "decision" + ], + "properties": { + "reviewer": { + "$ref": "#/$defs/nonEmptyString" + }, + "date": { + "type": "string", + "format": "date" + }, + "reviewType": { + "type": "string", + "enum": [ + "code-review", + "security-review", + "risk-review", + "renewal-review", + "sudoers-review", + "exception-review" + ] + }, + "decision": { + "type": "string", + "enum": [ + "approved", + "approved-with-conditions", + "rejected", + "expired" + ] + }, + "notes": { + "type": "string" + } + } + }, + "osSudoAuthorizationArtifact": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "entries" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "type": { + "type": "string", + "enum": [ + "allowlist", + "signed-approval-manifest", + "policy-bundle" + ] + }, + "path": { + "type": "string" + }, + "signed": { + "type": "boolean" + }, + "signatureRef": { + "type": "string" + }, + "entries": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/osSudoAuthorizationEntry" + } + } + } + }, + "osSudoAuthorizationEntry": { + "type": "object", + "additionalProperties": false, + "required": [ + "entryId", + "privilegedEntryPointId", + "approvalStatus", + "integrityBinding", + "approvedBy" + ], + "properties": { + "entryId": { + "$ref": "#/$defs/identifier" + }, + "privilegedEntryPointId": { + "$ref": "#/$defs/identifier" + }, + "approvalStatus": { + "type": "string", + "enum": [ + "approved", + "conditional", + "revoked", + "expired", + "draft" + ] + }, + "integrityBinding": { + "$ref": "#/$defs/osSudoIntegrityBinding" + }, + "approvedBy": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "approvedAt": { + "type": "string", + "format": "date-time" + }, + "expiresAt": { + "type": "string", + "format": "date-time" + }, + "conditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "sudoersBinding": { + "$ref": "#/$defs/sudoersBinding" + }, + "policyRef": { + "type": "string" + } + } + }, + "sudoersBinding": { + "type": "object", + "additionalProperties": false, + "required": [ + "sudoIdentity", + "commandPattern" + ], + "properties": { + "sudoIdentity": { + "$ref": "#/$defs/nonEmptyString" + }, + "runAs": { + "type": "string", + "default": "root" + }, + "commandPattern": { + "type": "string" + }, + "nopasswd": { + "type": "boolean" + }, + "digestBound": { + "type": "boolean" + }, + "sudoersFile": { + "type": "string" + } + } + }, + "osSudoImplementationMapping": { + "type": "object", + "additionalProperties": false, + "required": [ + "environmentType", + "pattern", + "tooling" + ], + "properties": { + "environmentType": { + "type": "string", + "enum": [ + "os-sudo", + "ci-cd", + "os-capabilities" + ] + }, + "pattern": { + "type": "string", + "enum": [ + "dedicated-root-script", + "rootctl-gateway", + "sudoers-allowlist", + "sudoers-digest-binding", + "ci-approved-privileged-step", + "capability-bound-helper" + ] + }, + "tooling": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "sudo", + "sudoers", + "visudo", + "sha256sum", + "systemd", + "make", + "bash", + "python", + "aide", + "opa", + "cosign", + "in-toto", + "other" + ] + } + }, + "notes": { + "type": "string" + }, + "references": { + "type": "array", + "items": { + "type": "string", + "format": "uri" + }, + "default": [] + } + } + }, + "osSudoEvidence": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "description" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "type": { + "type": "string", + "enum": [ + "file", + "log", + "review-record", + "policy", + "attestation", + "report", + "sudoers-fragment", + "hash-record", + "other" + ] + }, + "description": { + "type": "string" + }, + "path": { + "type": "string" + }, + "uri": { + "type": "string", + "format": "uri" + }, + "collectedAt": { + "type": "string", + "format": "date-time" + }, + "collectedBy": { + "type": "string" + }, + "hash": { + "$ref": "#/$defs/osSudoIntegrityBinding" + } + } + } + } +} +``` + +Here is a **minimal valid example instance** for this second-layer profile: + +```json +{ + "schemaVersion": "1.0.0", + "documentType": "pecs-combined", + "metadata": { + "id": "backup-os-sudo-profile", + "title": "Backup Service OS-Sudo PECS Profile", + "version": "0.1.0", + "status": "draft" + }, + "system": { + "name": "backup-service", + "scope": "Privileged backup execution on Linux hosts via sudo and reviewed root helpers.", + "environmentTypes": [ + "os-sudo", + "ci-cd" + ], + "criticality": "high", + "osSudoProfile": { + "hostClass": "server", + "sudoPolicyModel": "gateway-only", + "privilegedExecutionModel": "single-rootctl-gateway", + "sudoersPaths": [ + "/etc/sudoers.d/backup-service" + ], + "requireTty": false, + "usePasswordlessSudoForAutomation": true, + "allowedAutomationIdentities": [ + "ci-backup" + ] + } + }, + "privilegedExecutionSurface": [ + { + "id": "rootctl", + "name": "rootctl", + "kind": "gateway", + "path": "/usr/local/bin/rootctl", + "command": "sudo /usr/local/bin/rootctl backup", + "privilegeDomain": "sudo", + "executionContext": { + "environmentType": "os-sudo", + "runAs": "root", + "allowedCallers": [ + "ci-backup", + "ops-admin" + ], + "networkAccess": "restricted", + "interactiveAllowed": true, + "automationAllowed": true + }, + "declaredEffects": [ + "Create approved backup snapshot", + "Read protected source paths", + "Write backup archive to approved target path" + ], + "riskLevel": "high", + "integrityBinding": { + "type": "hash-verified", + "algorithm": "sha256", + "digest": "3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677", + "verifiedAtExecution": true, + "reviewRenewalRequiredOnChange": true + }, + "invocationContract": { + "allowedArgumentsPolicy": { + "mode": "fixed", + "fixedArguments": [ + "backup" + ] + }, + "expectedEffects": [ + "Execute only approved backup flow" + ], + "failureMode": "fail-closed", + "privilegeExpectation": "must-be-invoked-via-sudo", + "startupChecks": [ + "check-euid-root", + "check-argv-contract", + "check-integrity-binding", + "check-caller-identity", + "check-prerequisite-tools" + ] + }, + "osSudoControls": { + "entryPointModel": "gateway", + "selfPrivilegeCheck": true, + "sudoersRestricted": true, + "sudoersDigestBound": true, + "passwordlessAllowed": true, + "interactiveOnly": false, + "shellEscapeRisk": "low", + "environmentSanitization": "strict", + "usesNoexec": true, + "requiresDedicatedReview": true, + "reviewRenewalOnHashChange": true + } + } + ], + "authorizationArtifacts": [ + { + "id": "backup-allowlist", + "type": "signed-approval-manifest", + "path": "security/privileged-allowlist.yaml", + "signed": true, + "signatureRef": "cosign://backup-allowlist", + "entries": [ + { + "entryId": "rootctl-backup-approved", + "privilegedEntryPointId": "rootctl", + "approvalStatus": "approved", + "integrityBinding": { + "type": "hash-verified", + "algorithm": "sha256", + "digest": "3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677", + "verifiedAtExecution": true, + "reviewRenewalRequiredOnChange": true + }, + "approvedBy": [ + "security-team" + ], + "sudoersBinding": { + "sudoIdentity": "ci-backup", + "runAs": "root", + "commandPattern": "/usr/local/bin/rootctl backup", + "nopasswd": true, + "digestBound": true, + "sudoersFile": "/etc/sudoers.d/backup-service" + } + } + ] + } + ] +} + +xxx diff --git a/canon/standards/privileged-execution-control-schema_v0.2.1.md b/canon/standards/privileged-execution-control-schema_v0.2.1.md new file mode 100644 index 0000000..1858217 --- /dev/null +++ b/canon/standards/privileged-execution-control-schema_v0.2.1.md @@ -0,0 +1,1191 @@ +PriviledgedExecutionControlSchema + +*Machine-readable PECS JSON Schema Draft* + +Below is a **machine-readable PECS schema** as a **JSON Schema Draft 2020-12** document. + +It is designed to represent: + +* PECS document metadata +* system scope +* privileged entry points +* privileged authorization artifacts +* invocation contracts +* maturity assessments +* gap analysis tasks +* implementation mappings for concrete environments + +You can store it as `pecs.schema.json`. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.org/schemas/pecs.schema.json", + "title": "Privileged Execution Control Standard (PECS) Schema", + "description": "Machine-readable schema for describing privileged execution control in software systems, including privileged entry points, authorization artifacts, integrity bindings, maturity assessments, and remediation planning.", + "type": "object", + "additionalProperties": false, + "required": [ + "schemaVersion", + "documentType", + "metadata", + "system", + "privilegedExecutionSurface" + ], + "properties": { + "schemaVersion": { + "type": "string", + "const": "1.0.0" + }, + "documentType": { + "type": "string", + "enum": [ + "pecs-model", + "pecs-assessment", + "pecs-authorization-artifact", + "pecs-profile", + "pecs-combined" + ] + }, + "metadata": { + "$ref": "#/$defs/metadata" + }, + "system": { + "$ref": "#/$defs/system" + }, + "privilegedExecutionSurface": { + "type": "array", + "description": "Declared privileged entry points and gateways in scope.", + "items": { + "$ref": "#/$defs/privilegedEntryPoint" + } + }, + "authorizationArtifacts": { + "type": "array", + "items": { + "$ref": "#/$defs/authorizationArtifact" + }, + "default": [] + }, + "maturityProfile": { + "$ref": "#/$defs/maturityProfile" + }, + "gapAnalysis": { + "$ref": "#/$defs/gapAnalysis" + }, + "implementationMappings": { + "type": "array", + "items": { + "$ref": "#/$defs/implementationMapping" + }, + "default": [] + }, + "evidence": { + "type": "array", + "items": { + "$ref": "#/$defs/evidence" + }, + "default": [] + }, + "customExtensions": { + "type": "object", + "description": "Domain-specific extensions for a PECS profile.", + "additionalProperties": true, + "default": {} + } + }, + "$defs": { + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "uriString": { + "type": "string", + "format": "uri" + }, + "dateString": { + "type": "string", + "format": "date" + }, + "dateTimeString": { + "type": "string", + "format": "date-time" + }, + "identifier": { + "type": "string", + "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" + }, + "hashValue": { + "type": "string", + "pattern": "^[A-Fa-f0-9]{32,128}$" + }, + "metadata": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "title", + "version", + "status" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "title": { + "$ref": "#/$defs/nonEmptyString" + }, + "version": { + "type": "string", + "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" + }, + "status": { + "type": "string", + "enum": [ + "draft", + "candidate", + "approved", + "deprecated", + "retired" + ] + }, + "owner": { + "$ref": "#/$defs/nonEmptyString" + }, + "authors": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "createdAt": { + "$ref": "#/$defs/dateTimeString" + }, + "updatedAt": { + "$ref": "#/$defs/dateTimeString" + }, + "description": { + "type": "string" + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + } + } + }, + "system": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "scope", + "environmentTypes" + ], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "type": "string" + }, + "scope": { + "type": "string", + "description": "Narrative statement of what is in and out of scope." + }, + "environmentTypes": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "os-sudo", + "os-capabilities", + "container-runtime", + "kubernetes-rbac", + "cloud-iam", + "ci-cd", + "database-admin", + "api-admin", + "other" + ] + }, + "minItems": 1, + "uniqueItems": true + }, + "criticality": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "domainProfile": { + "$ref": "#/$defs/domainProfile" + } + } + }, + "domainProfile": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "type": "string" + }, + "minimumRequiredLevels": { + "$ref": "#/$defs/maturityLevelsByDimension" + }, + "weighting": { + "$ref": "#/$defs/maturityWeights" + }, + "notes": { + "type": "string" + } + } + }, + "maturityWeights": { + "type": "object", + "additionalProperties": false, + "properties": { + "privilegeBoundaryIsolation": { + "type": "number", + "minimum": 0 + }, + "authorizationGovernance": { + "type": "number", + "minimum": 0 + }, + "integrityAssurance": { + "type": "number", + "minimum": 0 + }, + "executionEnforcement": { + "type": "number", + "minimum": 0 + }, + "auditability": { + "type": "number", + "minimum": 0 + } + } + }, + "maturityLevelsByDimension": { + "type": "object", + "additionalProperties": false, + "properties": { + "privilegeBoundaryIsolation": { + "$ref": "#/$defs/maturityLevel" + }, + "authorizationGovernance": { + "$ref": "#/$defs/maturityLevel" + }, + "integrityAssurance": { + "$ref": "#/$defs/maturityLevel" + }, + "executionEnforcement": { + "$ref": "#/$defs/maturityLevel" + }, + "auditability": { + "$ref": "#/$defs/maturityLevel" + } + } + }, + "maturityLevel": { + "type": "integer", + "minimum": 0, + "maximum": 5 + }, + "privilegedEntryPoint": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "kind", + "privilegeDomain", + "declaredEffects", + "invocationContract" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "kind": { + "type": "string", + "enum": [ + "script", + "binary", + "gateway", + "controller", + "pipeline-step", + "job", + "api-call", + "role-binding", + "other" + ] + }, + "path": { + "type": "string", + "description": "Filesystem path, repository path, or logical path." + }, + "command": { + "type": "string", + "description": "Command or logical invocation string." + }, + "privilegeDomain": { + "type": "string", + "enum": [ + "root", + "sudo", + "linux-capability", + "container-privileged", + "kubernetes-admin", + "kubernetes-rbac", + "cloud-admin", + "database-admin", + "api-admin", + "other" + ] + }, + "executionContext": { + "$ref": "#/$defs/executionContext" + }, + "declaredEffects": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "minItems": 1 + }, + "riskLevel": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "integrityBinding": { + "$ref": "#/$defs/integrityBinding" + }, + "authorizationReference": { + "type": "string", + "description": "Reference to an authorization artifact entry ID." + }, + "invocationContract": { + "$ref": "#/$defs/invocationContract" + }, + "reviews": { + "type": "array", + "items": { + "$ref": "#/$defs/reviewRecord" + }, + "default": [] + }, + "evidenceRefs": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + } + }, + "allOf": [ + { + "anyOf": [ + { "required": ["path"] }, + { "required": ["command"] } + ] + } + ] + }, + "executionContext": { + "type": "object", + "additionalProperties": false, + "properties": { + "environmentType": { + "type": "string", + "enum": [ + "os-sudo", + "os-capabilities", + "container-runtime", + "kubernetes-rbac", + "cloud-iam", + "ci-cd", + "other" + ] + }, + "allowedCallers": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "workingDirectory": { + "type": "string" + }, + "runAs": { + "type": "string", + "description": "Effective identity or service account." + }, + "networkAccess": { + "type": "string", + "enum": [ + "none", + "restricted", + "full", + "unknown" + ] + }, + "environmentRestrictions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + } + } + }, + "integrityBinding": { + "type": "object", + "additionalProperties": false, + "required": [ + "type" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "none", + "checksum", + "hash-verified", + "signed-artifact", + "attestation" + ] + }, + "algorithm": { + "type": "string", + "enum": [ + "sha256", + "sha384", + "sha512", + "blake2b", + "sigstore", + "x509", + "other" + ] + }, + "digest": { + "$ref": "#/$defs/hashValue" + }, + "attestationRef": { + "type": "string" + }, + "signatureRef": { + "type": "string" + } + } + }, + "invocationContract": { + "type": "object", + "additionalProperties": false, + "required": [ + "allowedArgumentsPolicy", + "expectedEffects", + "failureMode" + ], + "properties": { + "allowedArgumentsPolicy": { + "$ref": "#/$defs/argumentsPolicy" + }, + "expectedEffects": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "minItems": 1 + }, + "forbiddenEffects": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "preconditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "postconditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "failureMode": { + "type": "string", + "enum": [ + "fail-closed", + "fail-open", + "best-effort", + "unknown" + ] + } + } + }, + "argumentsPolicy": { + "type": "object", + "additionalProperties": false, + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "none", + "fixed", + "allowlist", + "schema-validated", + "policy-evaluated" + ] + }, + "fixedArguments": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "allowedPatterns": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "jsonSchema": { + "type": "object", + "description": "Optional JSON Schema describing structured arguments." + }, + "notes": { + "type": "string" + } + } + }, + "reviewRecord": { + "type": "object", + "additionalProperties": false, + "required": [ + "reviewer", + "date", + "reviewType", + "decision" + ], + "properties": { + "reviewer": { + "$ref": "#/$defs/nonEmptyString" + }, + "date": { + "$ref": "#/$defs/dateString" + }, + "reviewType": { + "type": "string", + "enum": [ + "code-review", + "security-review", + "risk-review", + "renewal-review", + "exception-review" + ] + }, + "decision": { + "type": "string", + "enum": [ + "approved", + "approved-with-conditions", + "rejected", + "expired" + ] + }, + "notes": { + "type": "string" + } + } + }, + "authorizationArtifact": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "entries" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "type": { + "type": "string", + "enum": [ + "allowlist", + "signed-approval-manifest", + "policy-bundle", + "attestation-set" + ] + }, + "path": { + "type": "string" + }, + "signed": { + "type": "boolean", + "default": false + }, + "signatureRef": { + "type": "string" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/$defs/authorizationEntry" + }, + "minItems": 1 + } + } + }, + "authorizationEntry": { + "type": "object", + "additionalProperties": false, + "required": [ + "entryId", + "privilegedEntryPointId", + "approvalStatus" + ], + "properties": { + "entryId": { + "$ref": "#/$defs/identifier" + }, + "privilegedEntryPointId": { + "$ref": "#/$defs/identifier" + }, + "approvalStatus": { + "type": "string", + "enum": [ + "approved", + "conditional", + "revoked", + "expired", + "draft" + ] + }, + "integrityBinding": { + "$ref": "#/$defs/integrityBinding" + }, + "approvedBy": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "approvedAt": { + "$ref": "#/$defs/dateTimeString" + }, + "expiresAt": { + "$ref": "#/$defs/dateTimeString" + }, + "conditions": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "policyRef": { + "type": "string" + } + } + }, + "maturityProfile": { + "type": "object", + "additionalProperties": false, + "required": [ + "assessmentDate", + "dimensions" + ], + "properties": { + "assessmentDate": { + "$ref": "#/$defs/dateString" + }, + "assessedBy": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "method": { + "type": "string", + "enum": [ + "self-assessment", + "peer-review", + "security-review", + "automated-scan", + "hybrid" + ] + }, + "dimensions": { + "type": "object", + "additionalProperties": false, + "required": [ + "privilegeBoundaryIsolation", + "authorizationGovernance", + "integrityAssurance", + "executionEnforcement", + "auditability" + ], + "properties": { + "privilegeBoundaryIsolation": { + "$ref": "#/$defs/maturityAssessmentDimension" + }, + "authorizationGovernance": { + "$ref": "#/$defs/maturityAssessmentDimension" + }, + "integrityAssurance": { + "$ref": "#/$defs/maturityAssessmentDimension" + }, + "executionEnforcement": { + "$ref": "#/$defs/maturityAssessmentDimension" + }, + "auditability": { + "$ref": "#/$defs/maturityAssessmentDimension" + } + } + }, + "overallLevel": { + "$ref": "#/$defs/maturityLevel" + }, + "overallComputation": { + "type": "string", + "enum": [ + "minimum-dimension", + "weighted-average-floor", + "manual", + "domain-profile-specific" + ] + }, + "summary": { + "type": "string" + } + } + }, + "maturityAssessmentDimension": { + "type": "object", + "additionalProperties": false, + "required": [ + "level", + "justification" + ], + "properties": { + "level": { + "$ref": "#/$defs/maturityLevel" + }, + "justification": { + "type": "string" + }, + "evidenceRefs": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + }, + "gaps": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "targetLevel": { + "$ref": "#/$defs/maturityLevel" + } + } + }, + "gapAnalysis": { + "type": "object", + "additionalProperties": false, + "properties": { + "targetProfile": { + "$ref": "#/$defs/maturityLevelsByDimension" + }, + "identifiedGaps": { + "type": "array", + "items": { + "$ref": "#/$defs/gapItem" + }, + "default": [] + }, + "recommendedTasks": { + "type": "array", + "items": { + "$ref": "#/$defs/task" + }, + "default": [] + } + } + }, + "gapItem": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "dimension", + "currentLevel", + "targetLevel", + "description" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "dimension": { + "type": "string", + "enum": [ + "privilegeBoundaryIsolation", + "authorizationGovernance", + "integrityAssurance", + "executionEnforcement", + "auditability" + ] + }, + "currentLevel": { + "$ref": "#/$defs/maturityLevel" + }, + "targetLevel": { + "$ref": "#/$defs/maturityLevel" + }, + "description": { + "type": "string" + }, + "severity": { + "type": "string", + "enum": [ + "low", + "moderate", + "high", + "critical" + ] + }, + "relatedEntryPoints": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + } + } + }, + "task": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "title", + "category", + "priority", + "status" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "title": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "type": "string" + }, + "category": { + "type": "string", + "enum": [ + "inventory", + "refactor", + "review", + "policy", + "integrity", + "logging", + "enforcement", + "documentation", + "automation", + "training", + "other" + ] + }, + "priority": { + "type": "string", + "enum": [ + "low", + "medium", + "high", + "critical" + ] + }, + "status": { + "type": "string", + "enum": [ + "open", + "planned", + "in-progress", + "blocked", + "done", + "dropped" + ] + }, + "owner": { + "type": "string" + }, + "dueDate": { + "$ref": "#/$defs/dateString" + }, + "relatedGapIds": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + }, + "relatedEntryPointIds": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "default": [] + } + } + }, + "implementationMapping": { + "type": "object", + "additionalProperties": false, + "required": [ + "environmentType", + "pattern" + ], + "properties": { + "environmentType": { + "type": "string", + "enum": [ + "os-sudo", + "os-capabilities", + "container-runtime", + "kubernetes-rbac", + "cloud-iam", + "ci-cd", + "other" + ] + }, + "pattern": { + "$ref": "#/$defs/nonEmptyString" + }, + "tooling": { + "type": "array", + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "default": [] + }, + "notes": { + "type": "string" + }, + "references": { + "type": "array", + "items": { + "$ref": "#/$defs/uriString" + }, + "default": [] + } + } + }, + "evidence": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "description" + ], + "properties": { + "id": { + "$ref": "#/$defs/identifier" + }, + "type": { + "type": "string", + "enum": [ + "file", + "log", + "review-record", + "policy", + "attestation", + "screenshot", + "report", + "other" + ] + }, + "description": { + "type": "string" + }, + "path": { + "type": "string" + }, + "uri": { + "$ref": "#/$defs/uriString" + }, + "collectedAt": { + "$ref": "#/$defs/dateTimeString" + }, + "collectedBy": { + "type": "string" + }, + "hash": { + "$ref": "#/$defs/integrityBinding" + } + } + } + } +} +``` + +Here is a **minimal example instance** that validates against the schema: + +```json +{ + "schemaVersion": "1.0.0", + "documentType": "pecs-combined", + "metadata": { + "id": "pecs-demo", + "title": "PECS Demo Assessment", + "version": "0.1.0", + "status": "draft" + }, + "system": { + "name": "backup-service", + "scope": "Backup scripts and CI automation for host-level backups.", + "environmentTypes": ["os-sudo", "ci-cd"], + "criticality": "high" + }, + "privilegedExecutionSurface": [ + { + "id": "backup-root", + "name": "backup-root", + "kind": "script", + "path": "scripts/backup-root", + "privilegeDomain": "root", + "declaredEffects": [ + "Create filesystem snapshot", + "Read protected backup source paths" + ], + "integrityBinding": { + "type": "hash-verified", + "algorithm": "sha256", + "digest": "3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677" + }, + "invocationContract": { + "allowedArgumentsPolicy": { + "mode": "fixed", + "fixedArguments": ["snapshot"] + }, + "expectedEffects": [ + "Create approved snapshot only" + ], + "failureMode": "fail-closed" + } + } + ], + "authorizationArtifacts": [ + { + "id": "main-allowlist", + "type": "allowlist", + "entries": [ + { + "entryId": "backup-root-approved", + "privilegedEntryPointId": "backup-root", + "approvalStatus": "approved", + "approvedBy": ["security-team"], + "integrityBinding": { + "type": "hash-verified", + "algorithm": "sha256", + "digest": "3d9c9c21d0c82a4c9f0aa7b7c8d1d839d6cf4dbf54d4b56caa11223344556677" + } + } + ] + } + ], + "maturityProfile": { + "assessmentDate": "2026-03-10", + "method": "self-assessment", + "dimensions": { + "privilegeBoundaryIsolation": { + "level": 2, + "justification": "Privileged logic is isolated in dedicated root scripts." + }, + "authorizationGovernance": { + "level": 3, + "justification": "Approved allowlist with review records and hash renewal." + }, + "integrityAssurance": { + "level": 3, + "justification": "Hash verification is used for approved scripts." + }, + "executionEnforcement": { + "level": 2, + "justification": "Execution constrained through sudoers and reviewed entry points." + }, + "auditability": { + "level": 1, + "justification": "Only local logs currently exist." + } + }, + "overallLevel": 1, + "overallComputation": "minimum-dimension", + "summary": "Strong isolation and integrity controls, weak centralized auditability." + } +} +``` + +A few design notes for the next iteration: + +* This schema is deliberately **generic and implementation-agnostic** in the core. +* It can model both `sudo`-style systems and `kubernetes-rbac` systems. +* The `documentType` field lets you use one schema for: + + * full combined documents + * standalone assessments + * standalone allowlists + * reusable profiles + +The most useful next step is a **second schema layer** with stricter profiles, for example: + +* `pecs-os-sudo-profile.schema.json` +* `pecs-kubernetes-rbac-profile.schema.json` +* `pecs-cicd-profile.schema.json` + +These can constrain the generic schema for each operational domain. + + +xxx diff --git a/canon/standards/privileged-execution-control_v0.2 b/canon/standards/privileged-execution-control_v0.2 new file mode 100644 index 0000000..58e9bfe --- /dev/null +++ b/canon/standards/privileged-execution-control_v0.2 @@ -0,0 +1,540 @@ +PrivilegedExecutionControlStandard + +*Maturity model to minimize privileged attack surfaces* + +# Privileged Execution Control Standard (PECS) + +### A maturity model and reference framework for controlling privileged execution in software systems + +**Version:** 0.2 (Draft) +**Status:** Candidate Architecture Standard +**Authoring Context:** DevSecOps / Platform Engineering / Secure Automation +**Audience:** + +* Software architects +* DevOps engineers +* Security engineers +* CI/CD maintainers +* AI coding agents operating within repositories + +--- + +# 1. Purpose + +The **Privileged Execution Control Standard (PECS)** defines a structured approach to controlling **privileged operations** in software systems. + +It provides: + +1. **Terminology and conceptual model** +2. **A multidimensional maturity assessment** +3. **Design patterns for privilege boundaries** +4. **Implementation guidance for common environments** +5. **Mapping to existing security frameworks** + +The goal is to ensure that systems: + +* minimize privileged attack surfaces +* provide deterministic authorization of privileged operations +* enable secure automation +* remain auditable and maintainable + +--- + +# 2. Scope + +PECS applies to **software systems that contain privileged operations**, including: + +* DevOps pipelines +* build systems +* operational tooling +* infrastructure automation +* platform management systems +* cluster orchestration + +Privileged execution environments include: + +* OS-level root privileges +* container runtime privileges +* Kubernetes cluster permissions +* administrative API credentials +* infrastructure automation roles + +--- + +# 3. Core Security Principles + +PECS builds on established security principles. + +## 3.1 Least Privilege + +Privileged permissions must be limited to **the smallest possible scope**. + +--- + +## 3.2 Explicit Privilege Boundaries + +All privileged execution must occur through **clearly defined entry points**. + +--- + +## 3.3 Deterministic Authorization + +Privilege elevation must rely on **explicit authorization mechanisms**, not implicit behavior. + +--- + +## 3.4 Integrity Binding + +Authorization must bind to **specific executable artifacts**. + +--- + +## 3.5 Auditability + +The system must provide verifiable answers to: + +* What privileged operations exist? +* Who approved them? +* What code was approved? +* What executed? + +--- + +# 4. Conceptual Model + +The PECS conceptual model is **implementation independent**. + +## 4.1 Privileged Execution + +An operation requiring elevated authority beyond the normal execution context. + +Examples: + +* root access +* administrative API access +* cluster-level operations +* privileged containers + +--- + +## 4.2 Privileged Entry Point (PEP) + +A programmatic interface that performs privileged actions. + +Examples: + +``` +backup-root +rootctl snapshot +kubectl apply (cluster-admin) +``` + +--- + +## 4.3 Privileged Invocation + +The act of executing a privileged entry point. + +--- + +## 4.4 Privileged Execution Surface (PES) + +The set of all privileged entry points in a system. + +--- + +## 4.5 Privileged Authorization Artifact (PAA) + +A machine-readable document defining which privileged operations are approved. + +--- + +## 4.6 Integrity Binding + +A mechanism that links approval to a **specific artifact version**. + +Examples: + +* SHA256 digest +* signed binary +* provenance metadata + +--- + +## 4.7 Privileged Execution Gateway (PEG) + +A centralized system responsible for executing privileged actions. + +Example: + +``` +rootctl +``` + +--- + +# 5. Multidimensional Maturity Model + +PECS maturity is evaluated along **five independent dimensions**. + +| Dimension | Description | +| ------------------------ | ----------------------------- | +| Privilege Boundary | isolation of privileged logic | +| Authorization Governance | approval workflow | +| Integrity Assurance | binding approvals to code | +| Execution Enforcement | runtime enforcement | +| Auditability | execution tracking | + +--- + +# 6. Maturity Levels + +Each dimension has maturity levels from **0–5**. + +--- + +# 6.1 Dimension 1 — Privilege Boundary Isolation + +| Level | Description | +| ----- | --------------------------------- | +| 0 | privilege used anywhere | +| 1 | privilege isolated in scripts | +| 2 | dedicated privileged entry points | +| 3 | centralized gateway | +| 4 | restricted execution environment | +| 5 | formally defined privileged API | + +--- + +# 6.2 Dimension 2 — Authorization Governance + +| Level | Description | +| ----- | --------------------------------- | +| 0 | no approval process | +| 1 | manual review | +| 2 | documented allowlist | +| 3 | fingerprint approval | +| 4 | signed approvals | +| 5 | policy-based automated governance | + +--- + +# 6.3 Dimension 3 — Integrity Assurance + +| Level | Description | +| ----- | ------------------------- | +| 0 | no verification | +| 1 | manual checks | +| 2 | checksums | +| 3 | hash verification | +| 4 | signed artifacts | +| 5 | supply chain attestations | + +--- + +# 6.4 Dimension 4 — Execution Enforcement + +| Level | Description | +| ----- | ------------------------------ | +| 0 | uncontrolled privilege use | +| 1 | wrapper enforcement | +| 2 | tool-level restrictions | +| 3 | platform enforcement | +| 4 | policy engines | +| 5 | zero-trust privilege mediation | + +--- + +# 6.5 Dimension 5 — Auditability + +| Level | Description | +| ----- | -------------------------- | +| 0 | no logging | +| 1 | local logs | +| 2 | structured logs | +| 3 | centralized logging | +| 4 | tamper-resistant logs | +| 5 | cryptographic audit trails | + +--- + +# 7. Example Maturity Assessment + +Example system: + +| Dimension | Level | +| ------------ | ----- | +| Boundary | 2 | +| Governance | 2 | +| Integrity | 3 | +| Enforcement | 2 | +| Auditability | 1 | + +Result: + +``` +PECS maturity profile: +(2,2,3,2,1) +``` + +This allows targeted improvements. + +--- + +# 8. Reference Authorization Artifact + +Example YAML: + +```yaml +version: 1 + +privileged_commands: + + - id: backup + entrypoint: scripts/backup-root + sha256: 3d9c9c21d0c82a4c9f + reviewer: security-team + approved: 2026-03-10 + + - id: snapshot + entrypoint: scripts/snapshot-root + sha256: 7e2f15b1c93b +``` + +--- + +# 9. Privileged Invocation Contract + +Every PEP should define: + +* command identity +* allowed arguments +* execution context +* expected effects + +Example: + +``` +rootctl snapshot +arguments: + volume: string +allowed-callers: + CI-backup +``` + +--- + +# 10. Implementation Guides + +The following chapters map PECS to practical environments. + +--- + +# 11. Implementation Guide — Linux / sudo + +## Design Pattern + +``` +make backup + | +prepare.sh + | +sudo rootctl backup +``` + +--- + +## Example root entrypoint + +```bash +#!/usr/bin/env bash + +set -euo pipefail + +if [[ "$EUID" -ne 0 ]]; then + echo "ERROR: must run as root" + exit 1 +fi + +case "$1" in +backup) + ./backup-logic.sh + ;; +*) + echo "unknown command" + exit 1 +esac +``` + +--- + +## sudoers example + +``` +ci-runner ALL=(root) NOPASSWD: /usr/local/bin/rootctl +``` + +--- + +## Hash validation example + +``` +sha256sum rootctl +``` + +--- + +# 12. Implementation Guide — Kubernetes / RBAC + +Privilege boundaries map to **cluster roles**. + +Example: + +``` +ClusterRole: backup-controller +``` + +--- + +Example policy: + +``` +apiGroups: +- "" +resources: +- persistentvolumes +verbs: +- get +- list +``` + +--- + +Privileged gateway concept becomes: + +``` +controller operator +``` + +--- + +# 13. Implementation Guide — CI/CD Pipelines + +Example: + +``` +pipeline + | +build + | +privileged step + | +deploy +``` + +Privileged step invokes **approved gateway**. + +--- + +Example GitHub Action: + +``` +sudo rootctl deploy +``` + +--- + +Policy checks verify: + +* artifact fingerprint +* approval metadata + +--- + +# 14. Assessment Procedure + +Assess a system using: + +1. Identify privileged operations +2. Map entry points +3. Evaluate each maturity dimension +4. Produce maturity profile +5. Identify gaps +6. generate improvement roadmap + +--- + +# 15. Regulatory Mapping + +PECS aligns with: + +| Standard | Relevant Controls | +| --------------- | ---------------------- | +| NIST 800-53 | AC-6, CM-3, SI-7 | +| NIST Zero Trust | policy enforcement | +| OWASP CI/CD | least privilege | +| CIS Controls | privilege management | +| SLSA | supply chain integrity | + +--- + +# 16. Enterprise Tooling Mapping + +Common enterprise tools implementing similar concepts. + +| Category | Examples | +| -------------- | --------------------- | +| PAM systems | CyberArk, BeyondTrust | +| Policy engines | OPA | +| CI/CD security | GitHub OIDC policies | +| Audit logging | Splunk | + +PECS can integrate with these. + +--- + +# 17. Appendix — Terminology + +PEP — Privileged Entry Point +PES — Privileged Execution Surface +PAA — Privileged Authorization Artifact +PEG — Privileged Execution Gateway + +--- + +# 18. Appendix — Relationship to Existing Patterns + +Similar concepts exist in: + +* sudo command restrictions +* Microsoft JEA +* Kubernetes RBAC +* in-toto supply chain controls + +PECS unifies these into **one architectural model**. + +--- + +# 19. Future Extensions + +Potential additions: + +* signed execution policies +* hardware root of trust +* runtime policy agents +* AI-assisted security review + +--- + +# Summary + +This refined standard provides: + +✔ stable abstract model +✔ multidimensional maturity framework +✔ practical implementation guides +✔ regulatory mapping +✔ extensibility across environments + + +xxx