Governance Inheritance

Hierarchical policy inheritance system for OpenClaw agents. Enables policies to be defined at organization, team, project, and session levels with automatic...

Security Scan

The skill appears internally consistent with its stated purpose: it provides YAML-based hierarchical policy templates and a validator that reads/writes files under a governance root without requesting external credentials or performing network installs.

Purpose & Capability

Name/description (hierarchical policy inheritance) align with the included files: init_governance.py creates policy YAML templates and validate_chain.py loads and validates policy chains. Required tools and paths (read/write under a GOVERNANCE_ROOT) match the stated functionality; nothing in the code requests unrelated cloud credentials or external services.

Instruction Scope

SKILL.md instructs use of exec, read, write tools and references GOVERNANCE_ROOT. The shipped scripts only read/write policy YAML files and validate rules; they do not execute arbitrary shell commands or contact network endpoints. Minor inconsistency: SKILL.md lists 'exec' as required but the provided Python scripts do not invoke external commands (they create/read YAML files). The templates and schema allow rules that reference sensitive system paths (e.g., /etc/*, ~), so you should review any policy files before applying them because those policies could control agent file/shell/http behavior.

Install Mechanism

No install spec; this is an instruction-only skill with included scripts. Nothing is downloaded or extracted from remote URLs. Risk from install mechanism is low.

Credentials

No required environment variables or credentials are declared. SKILL.md recommends an optional GOVERNANCE_ROOT (default ~/.openclaw/governance) which is proportional to storing policy files. The skill does not request unrelated secrets.

Persistence & Privilege

The skill writes and reads policy files under the user's governance root (default ~/.openclaw/governance). That level of persistence is expected for a governance/policy tool, but note it can modify files that affect agent behavior—review and back up existing governance data before initializing. always:false (normal); autonomous invocation is allowed by default (platform default) but is not itself unusual here.

Assessment

This skill is coherent for creating and validating hierarchical policy YAMLs and does not request credentials or perform remote installs. Before installing/running: (1) review the templates and any generated policies—they can reference sensitive paths (e.g., /etc/*, ~) and will influence what the agent is allowed to do; (2) back up your existing ~/.openclaw/governance if present; (3) validate policies with validate_chain.py (it requires PyYAML) in a safe environment; (4) be aware that although the code doesn't execute shell commands, the policies produced may enable or block agent actions elsewhere—only enable autonomous invocation if you trust the policy author and integration. If anything seems unexpected (extra env vars, network calls, or an install script that fetches remote code), stop and inspect the files first.

This skill provides a hierarchical policy inheritance system that allows policies to be defined at multiple levels and automatically inherited by child contexts.

Policy Hierarchy Levels

Policies cascade from broad to specific:

Organization (broadest)
    ↓
Team
    ↓
Project
    ↓
Session (most specific)

Inheritance Rules

1. Child overrides parent: More specific policies override broader ones
2. Additive by default: Policies merge unless explicitly overridden
3. Explicit deny wins: A deny at any level blocks the action
4. Require explicit allow: Actions without an explicit allow are blocked in strict mode

Policy Structure

Each level contains a policies.yaml file:

# policies.yaml
version: "1.0"
level: organization  # organization | team | project | session
parent: null         # path to parent policy (null for root)

# Policy blocks
policies:
  http:
    - pattern: "*.internal.company.com"
      action: allow
      scope: ["GET", "POST"]
    - pattern: "*"
      action: deny
      reason: "External HTTP requires approval"
  
  shell:
    - command: "git *"
      action: allow
    - command: "rm -rf /*"
      action: deny
      reason: "Destructive command blocked"
    - command: "*"
      action: require_approval

  file:
    read:
      - path: "~/workspace/*"
        action: allow
      - path: "/etc/*"
        action: deny
    write:
      - path: "~/workspace/*"
        action: allow
      - path: "*"
        action: require_approval

# Inheritance configuration
inheritance:
  mode: merge          # merge | override | isolate
  exceptions:          # Policies that don't inherit
    - shell.sudo
  extensions:          # Child can extend these
    - http.allowlist

Quick Start

1. Initialize Organization Policies

python scripts/init_governance.py --level organization --path ~/.openclaw/governance

2. Create Team-Level Override

python scripts/init_governance.py --level team --name engineering --parent ~/.openclaw/governance/organization

3. Evaluate Policy for Action

const result = await context.tools.governanceInheritance.evaluate({
  action: "http",
  details: { method: "GET", url: "https://api.example.com/data" },
  context: {
    sessionId: "sess_123",
    project: "my-project",
    team: "engineering"
  }
});

// result: { allowed: true } | { allowed: false, reason: "...", level: "organization" }

Policy Resolution

When evaluating an action, the system:

1. Collects all applicable policies from root to leaf
2. Merges according to inheritance rules
3. Evaluates against the most specific matching rule
4. Returns decision with provenance (which level decided)

Conflict Resolution

Parent	Child	Result
allow	allow	allow
allow	deny	deny (child wins)
allow	require_approval	require_approval
deny	allow	deny (deny always wins)
deny	deny	deny

Session Context Integration

Policies automatically load based on session context:

# Session inherits from project → team → organization
session_context:
  organization: "acme-corp"
  team: "engineering"
  project: "api-gateway"
  session: "sess_abc123"

# Policy resolution path:
# ~/.openclaw/governance/organizations/acme-corp/policies.yaml
# ~/.openclaw/governance/teams/engineering/policies.yaml
# ~/.openclaw/governance/projects/api-gateway/policies.yaml
# ~/.openclaw/governance/sessions/sess_abc123/policies.yaml

Available Tools

evaluate

Evaluates an action against the inherited policy chain.

Parameters:

• action (string): Action type (http, shell, file, browser)
• details (object): Action-specific details
• context (object): Session context for policy resolution

Returns:

{
  allowed: boolean,
  reason?: string,
  level: string,        // Which policy level made the decision
  policy?: string,      // Specific policy that matched
  requiresApproval?: boolean
}

initPolicyLevel

Initializes a new policy level.

Parameters:

• level (string): organization, team, project, or session
• name (string): Identifier for this level
• parent (string, optional): Path to parent policy
• path (string): Where to create the policy

validatePolicyChain

Validates a policy chain for conflicts or errors.

Parameters:

• context (object): Session context to validate

Returns:

{
  valid: boolean,
  errors: string[],
  warnings: string[]
}

Configuration

Set the governance root in your environment:

export GOVERNANCE_ROOT="~/.openclaw/governance"

Or in openclaw.json:

{
  "skills": {
    "governance-inheritance": {
      "env": {
        "GOVERNANCE_ROOT": "~/.openclaw/governance"
      }
    }
  }
}

Policy Examples

Organization Level (Restrictive Base)

level: organization
policies:
  http:
    - pattern: "*.company.internal"
      action: allow
    - pattern: "*"
      action: require_approval
  shell:
    - command: "*"
      action: require_approval

Team Level (Engineering - More Permissive)

level: team
parent: ../organization
inheritance:
  mode: merge
policies:
  http:
    - pattern: "*.github.com"
      action: allow
    - pattern: "*.npmjs.com"
      action: allow
  shell:
    - command: "git *"
      action: allow
    - command: "npm *"
      action: allow
    - command: "docker *"
      action: allow

Project Level (Specific Overrides)

level: project
parent: ../engineering
inheritance:
  mode: merge
policies:
  http:
    - pattern: "api.stripe.com"
      action: allow  # This project uses Stripe
  file:
    write:
      - path: "./dist/*"
        action: allow

Integration with GovernClaw

This skill works alongside governclaw-middleware:

// governclaw-middleware calls governance-inheritance for policy resolution
const policyResult = await context.tools.governanceInheritance.evaluate({
  action: "http",
  details: { method, url, headers },
  context: sessionContext
});

if (!policyResult.allowed) {
  return { blocked: true, reason: policyResult.reason };
}

Best Practices

1. Start restrictive at organization level - Require approval for everything
2. Grant specific permissions at lower levels - Teams/projects opt into what they need
3. Document exceptions - Use reason field to explain why policies exist
4. Regular audits - Run validatePolicyChain to catch conflicts
5. Version your policies - Use the version field to track changes

Error Handling

Always check for policy evaluation errors:

const result = await context.tools.governanceInheritance.evaluate({...});

if (result.error) {
  // Policy chain misconfiguration
  console.error("Policy error:", result.error);
  return { error: "Governance misconfigured" };
}

if (!result.allowed) {
  // Policy blocked the action
  console.log("Blocked by", result.level, "policy:", result.reason);
}

See Also

• references/policy-schema.md - Complete policy YAML schema
• references/inheritance-algorithm.md - Detailed inheritance logic
• scripts/init_governance.py - Initialize policy levels
• scripts/validate_chain.py - Validate policy chains