tegwick
2be217f51a
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 <noreply@anthropic.com>
26 KiB
26 KiB
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:
sudoroot- 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.
{
"$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:
{
"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