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