Skip to content

policy_spec.md

Latest commit

 

History

History
95 lines (77 loc) · 3.51 KB

policy_spec.md

File metadata and controls

95 lines (77 loc) · 3.51 KB

TORII Policy Specification v1

This document defines the schema for TORII's declarative policy engine. Policies are attached to Repositories (or hierarchies of Repositories) and evaluated by the Control Plane during Git operations.

Guiding Principles

  1. Deny by Default: Unless explicitly allowed, actions should be blocked (though configurable).
  2. Context-Aware: Rules can evaluate on the Actor, the Git Object (commit, tag, ref), and the Operation (push, fetch).
  3. Versioned: The policy schema itself is versioned (apiVersion).

Schema Structure

Policies are defined in YAML/JSON.

apiVersion: torii.io/v1beta1
kind: RepositoryPolicy
metadata:
  name: "security-high-compliance"
  description: "Enforces signed commits and strict branching."
spec:
  # Global default action if no specific rule matches
  defaultAction: "deny" 

  rules:
    # 1. Branch Protection
    # "Protect 'main' branch: No force push, strictly linear history"
    - name: "protect-main"
      scope:
        refs: ["refs/heads/main"]
      actions:
        - "git:push"
      conditions:
        - type: "attribute"
          key: "git.force_push"
          operator: "eq"
          value: false
      decision: "allow"

    # 2. Author Identity
    # "All commits must have an author email ending in @acme.corp"
    - name: "corporate-email-only"
      scope:
        refs: ["refs/heads/*"]
      actions:
        - "git:receive-pack" # Applies to the push operation as a whole, or per-commit
      conditions:
        - type: "commit_metadata"
          key: "author.email"
          operator: "ends_with"
          value: "@acme.corp"
      decision: "allow"

    # 3. GPG/SSH Signing
    # "Commits must be GPG signed"
    - name: "require-signing"
      scope: 
        refs: ["refs/heads/*"]
      conditions:
        - type: "commit_signature"
          key: "valid"
          operator: "eq"
          value: true
      decision: "allow"

Rule Evaluation Logic (Additive Constraints)

When a git push or fetch occurs, TORII evaluates the active RepositoryPolicy. The model is "Restrictive Composition" (Implicit AND).

  1. Filter: TORII identifies ALL rules where the scope matches the current Operation and Refs.
  2. Evaluate: Every matching rule is evaluated against the request context.
  3. Decide:
    • All Pass: The operation is allowed ONLY if ALL matching rules return allow.
    • Any Fail: If ANY matching rule returns deny (or fails to match its strict conditions), the entire operation is blocked.
    • No Match: If no rules match the operation (and it falls outside comprehensive allow-lists), the global defaultAction applies (typically deny).

This ensures that adding a new policy (e.g., "Legal Compliance Check") strictly tightens security; it cannot accidentally loosen existing protections.

Condition Types

Type Description
attribute Operation attributes (is_force, protocol).
identity The authenticated Actor (SSH user ID, token scopes).
commit_metadata Git commit headers (Author, Committer, Message).
commit_signature GPG/SSH signature verification status.
path_filter Files modified in the commits (e.g. "Only admins edit /policy").

Inheritance (Draft)

Policies can benefit from composition (e.g., Organization-wide Defaults + Repo-specific Overrides). TORII will support binding multiple Policies to a Repository.

Evaluation Order: Organization Policy -> Repository Policy. Most restrictive result wins.