🔴🟡🟢 AMPEL Policy Framework

The AMPEL Policy Framework provides the data structures, tooling, and libraries for defining, distributing, and managing security policies that evaluate software supply chain attestations.

This framework is used by the AMPEL policy engine to verify that software artifacts meet specific security and compliance requirements based on in-toto attestations.

🚀 Quick Start

Installation

go get github.com/carabiner-dev/policy

Parse and Compile a Policy

package main

import (
    "fmt"
    "github.com/carabiner-dev/policy"
)

func main() {
    // Create a compiler
    compiler := policy.NewCompiler()

    // Compile a policy from a file
    set, pcy, group, err := compiler.CompileFile("my-policy.json")
    if err != nil {
        panic(err)
    }

    if set != nil {
        fmt.Printf("Compiled PolicySet: %s\n", set.GetId())
        fmt.Printf("Contains %d policies\n", len(set.GetPolicies()))
    }
}

Simple Policy Example

{
  "id": "sbom-check",
  "meta": {
    "description": "Verify an SBOM exists"
  },
  "tenets": [
    {
      "id": "has-packages",
      "runtime": "cel@v0",
      "code": "has(sbom.packages) && sbom.packages.size() > 0",
      "predicates": {
        "types": ["https://spdx.dev/Document"]
      },
      "error": {
        "message": "No SBOM found",
        "guidance": "Ensure your build generates an SBOM attestation"
      }
    }
  ]
}

📖 Documentation

New to the AMPEL Policy Framework? Start here:

• Overview - Introduction to concepts and how the framework works
• Policy Materials Reference - Complete guide to Policy, PolicyGroup, and PolicySet
• Tooling Reference - Parser, Compiler, and Storage Backend documentation

Technical References:

• Protocol Buffer Definitions - Schema definitions
• Go Package Documentation - API reference

✨ Key Features

📦 Policy Materials

Define security requirements using three policy material types:

• Policy: Fundamental evaluation unit containing executable checks (tenets)
• PolicyGroup: Complex security controls with multiple evaluation strategies
• PolicySet: Top-level container bringing policies and groups together

🌐 Remote Referencing

Store policies in git repositories or on HTTPS servers, reference them by URI:

{
  "policies": [
    {
      "source": {
        "location": {
          "uri": "git+https://github.com/org/policies@commit-sha#path/to/policy.json"
        }
      }
    }
  ]
}

Features:

• Centralized policy management
• Version control with git
• Content integrity verification
• Efficient caching

🔄 Flexible Evaluation

Control how policies are evaluated with:

• Assert Modes: Require ALL checks to pass (AND) or just ONE (OR)
• Enforce Modes: Block on failures (ON) or warn only (OFF)
• Mix and match at different levels for sophisticated compliance modeling

🔗 Evidence Chaining

Connect attestations across related artifacts:

{
  "chain": [
    {
      "predicate": {
        "type": "https://slsa.dev/provenance/v1",
        "selector": "materials[0].digest.sha1",
        "runtime": "cel@v0"
      }
    }
  ]
}

Trace from binaries → images → commits → source code.

🎯 Context Values

Parameterize policies for reusability:

{
  "context": {
    "allowed_licenses": {
      "type": "array",
      "required": true,
      "description": "List of approved SPDX license identifiers"
    }
  }
}

Same policy, different parameters per organization/project.

✅ Identity Verification

Specify expected signers for attestations:

• Sigstore identities: OIDC issuer + identity
• Key-based: Public key verification
• Identity references: Reuse common identities

🚄 High Performance

• Parallel remote resource fetching
• Intelligent content caching
• Deduplication by content hash
• Optimized for large policy sets

🏗️ Architecture

Components

This repository contains:

1. Protocol Buffer Definitions

The policy.proto file defines the structure of:

• Policy, PolicyGroup, PolicySet
• Identities, Tenets, Metadata
• Remote references and chain links

Generated Go code is available in api/v1/.

2. Parser

Reads policy files and converts them to structured protobuf objects:

• Supports JSON and HJSON formats
• Handles cryptographic signature envelopes
• Applies default values
• Computes content hashes

See Parser Documentation →

3. Compiler

Assembles complete policies by resolving remote references:

• Fetches remote policies from git/HTTPS
• Validates and assembles policy structures
• Manages recursive dependencies
• Caches fetched content

See Compiler Documentation →

4. Storage Backend

Caching layer for remote content:

• Indexes by hash, URL, and ID
• Deduplicates content
• Optimizes repeated compilations

See Storage Backend Documentation →

Workflow

Policy Files (JSON/HJSON)
         ↓
    [Parser]
         ↓
Policy Objects (Protobuf)
         ↓
    [Compiler] ←→ [Storage Backend]
         ↓           ↑
Remote Fetching -----┘
         ↓
Complete PolicySet
         ↓
  [AMPEL Engine]
         ↓
   Evaluation Results

🧪 Policy Material Elements

Policy

A policy contains one or more tenets (executable checks) evaluated against attestations:

{
  "id": "license-check",
  "meta": {
    "description": "Verify approved licenses",
    "assert_mode": "AND"
  },
  "context": {
    "allowed_licenses": {
      "type": "array",
      "required": true
    }
  },
  "tenets": [
    {
      "id": "check-licenses",
      "runtime": "cel@v0",
      "code": "sbom.packages.all(p, p.license in allowed_licenses)",
      "predicates": {
        "types": ["https://spdx.dev/Document"]
      }
    }
  ]
}

Assert Mode: AND means all tenets must pass, OR means at least one must pass.

Learn more about Policies →

PolicyGroup

Groups policies into blocks with different evaluation strategies:

{
  "id": "build-verification",
  "blocks": [
    {
      "id": "required-checks",
      "meta": {
        "assert_mode": "AND"
      },
      "policies": [
        // ALL of these must pass
      ]
    },
    {
      "id": "alternative-checks",
      "meta": {
        "assert_mode": "OR"
      },
      "policies": [
        // At least ONE must pass
      ]
    }
  ]
}

A PolicyGroup passes when ALL blocks pass, enabling complex security controls.

Learn more about PolicyGroups →

PolicySet

The top-level container combining policies and groups:

{
  "id": "org-policy",
  "meta": {
    "description": "Organizational security policy"
  },
  "common": {
    "identities": [...],
    "context": {...}
  },
  "policies": [...],
  "groups": [...]
}

Includes shared identities and context values used by all policies.

Learn more about PolicySets →

🔧 Usage Examples

Parse a Policy

parser := policy.NewParser()
pcy, err := parser.ParsePolicyFile("policy.json")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Policy: %s\n", pcy.GetId())
fmt.Printf("Tenets: %d\n", len(pcy.GetTenets()))

Compile from Remote Location

compiler := policy.NewCompiler()

uri := "git+https://github.com/org/policies@9a70ca49@abc123#policy.json"
set, pcy, group, err := compiler.CompileLocation(uri)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Compiled: %s\n", set.GetId())

Parse with Signature Verification

import "github.com/carabiner-dev/policy/options"

parser := policy.NewParser()

opts := options.WithVerifySignatures(true)
opts = options.WithIdentityStrings([]string{
    "sigstore:https://token.actions.githubusercontent.com:https://github.com/org/repo/.github/workflows/release.yml@refs/tags/v1.0.0",
})

policySet, verification, err := parser.ParseVerifyPolicySetFile(
    "signed-policy.json",
    opts,
)

if verification != nil && verification.GetSignature().GetVerified() {
    fmt.Println("✓ Signature valid")
}

Compile PolicySet with Remote Policies

compiler := policy.NewCompiler()

// PolicySet references remote policies
set, _, _, err := compiler.CompileFile("policyset.json")
if err != nil {
    log.Fatal(err)
}

// Remote policies are fetched, cached, and assembled
for i, p := range set.GetPolicies() {
    fmt.Printf("Policy %d: %s (from %s)\n",
        i,
        p.GetId(),
        p.GetMeta().GetOrigin().GetUri(),
    )
}

More examples in the tooling documentation →

🔐 Supported Runtimes

Tenets support multiple runtimes for executing policy code:

• CEL (Common Expression Language): cel@v0 (default, recommended)
• Rego: rego@v1 (planned)
• Cedar: cedar@v1 (planned)

CEL is a non-Turing complete expression language designed for safe, fast policy evaluation.

🔗 Supported Remote Locations

Git Repositories (VCS Locators)

git+https://github.com/org/repo@commit-sha#path/to/policy.json
git+ssh://git@github.com/org/repo@commit-sha#path/to/policy.json

Best Practice: Always pin to commit SHAs for reproducibility.

HTTPS URLs

https://policies.example.com/policy.json

Best Practice: Include content digests for integrity verification:

{
  "source": {
    "location": {
      "uri": "https://example.com/policy.json",
      "digest": {
        "sha256": "abc123..."
      }
    }
  }
}

🤝 Integration with AMPEL

This framework provides the policy definitions and tooling. To evaluate policies against attestations, use the AMPEL policy engine.

import (
    "context"
    "github.com/carabiner-dev/policy"
    "github.com/carabiner-dev/ampel/pkg/verifier"
)

// Compile the policy
compiler := policy.NewCompiler()
set, _, _, err := compiler.CompileFile("policy.json")
if err != nil {
    log.Fatal(err)
}

// Create AMPEL verifier
ampel := verifier.New()

// Verify subject against the compiled PolicySet
results, err := ampel.Verify(
    context.Background(),
    &verifier.VerificationOptions{},
    set,  // Can be *Policy, *PolicySet, or *PolicyGroup
    subject,
)
if err != nil {
    log.Fatal(err)
}

// Check results
if results.Passed() {
    fmt.Println("✓ Policy verification passed")
} else {
    fmt.Println("✗ Policy verification failed")
}

The typical workflow is:

1. Use this framework to compile a PolicySet (resolving remote references, etc.)
2. Pass the compiled PolicySet to AMPEL's Verify() method
3. AMPEL executes the policy tenets and returns results

See the AMPEL documentation for details on policy evaluation.

🧩 Related Projects

• AMPEL - The policy evaluation engine
• policyctl - CLI tool for working with policies
• in-toto attestation - Attestation format specification

📋 Format and Compatibility

Policies are defined using Protocol Buffers for:

• Strong typing and validation
• Cross-language compatibility
• Efficient serialization
• Clear schema evolution

The framework is designed to work with the in-toto attestation framework, the industry standard for software supply chain evidence.

🧪 Testing

Run tests:

go test ./...

Run specific test suites:

go test -v -run TestParseLocalPolicies ./...
go test -v -run TestCompileLocalPolicies ./...

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

📄 License

This project is Copyright © 2025 by Carabiner Systems, Inc and released under the terms of the Apache 2.0 license.

🙏 Acknowledgments

Built on the in-toto attestation framework and inspired by the need for flexible, powerful software supply chain security policies.