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>
28 KiB
28 KiB
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.
{
"$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:
{
"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 andkubernetes-rbacsystems. -
The
documentTypefield 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.jsonpecs-kubernetes-rbac-profile.schema.jsonpecs-cicd-profile.schema.json
These can constrain the generic schema for each operational domain.
xxx