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