OPA can be extended with custom built-in functions and plugins that implement functionality like support for new protocols. This page explains how to customize and extend OPA in different ways.

Custom Built-in Functions in Go

Read this section if you want to extend OPA with custom built-in functions.

This section assumes you are embedding OPA as a library and executing policies via the github.com/open-policy-agent/opa/rego package. If you are NOT embedding OPA as a library and instead want to customize the OPA runtime, read this section anyway because it provides useful information on implementing built-in functions. For a complete example that shows how to add custom built-in functions to the OPA runtime, see the Adding Built-in Functions to the OPA Runtime appendix.

OPA supports built-in functions for simple operations like string manipulation and arithmetic as well as more complex operations like JWT verification and executing HTTP requests. If you need to to extend OPA with custom built-in functions for use cases or integrations that are not supported out-of-the-box you can supply the function definitions when you prepare queries.

Using custom built-in functions involves providing a declaration and implementation. The declaration tells OPA the function’s type signature and the implementation provides the callback that OPA can execute during query evaluation.

To get started you need to import three packages:

  1. import "github.com/open-policy-agent/opa/ast"
  2. import "github.com/open-policy-agent/opa/types"
  3. import "github.com/open-policy-agent/opa/rego"

The ast and types packages contain the types for declarations and runtime objects passed to your implementation. Here is a trivial example that shows the process:

  1. r := rego.New(
  2.     rego.Query(`x = hello("bob")`),
  3.     rego.Function1(
  4.         &rego.Function{
  5.             Name: "hello",
  6.             Decl: types.NewFunction(types.Args(types.S), types.S),
  7.         },
  8.         func(_ rego.BuiltinContext, a *ast.Term) (*ast.Term, error) {
  9.             if str, ok := a.Value.(ast.String); ok {
  10.                 return ast.StringTerm("hello, " + string(str)), nil
  11.             }
  12.             return nil, nil
  13.         }),
  14. )
  16. query, err := r.PrepareForEval(ctx)
  17. if err != nil {
  18.     // handle error.
  19. }

At this point you can execute the query:

  1. rs, err := query.Eval(ctx)
  2. if err != nil {
  3.     // handle error.
  4. }
  6. // Do something with result.
  7. fmt.Println(rs[0].Bindings["x"])

If you executed this code you the output would be:

  1. "hello, bob"

The example above highlights a few important points.

  • The rego package includes variants of rego.Function1 for accepting different numbers of operands (e.g., rego.Function2, rego.Function3, etc.)
  • The rego.Function#Name struct field specifies the operator that queries can refer to.
  • The rego.Function#Decl struct field specifies the function’s type signature. In the example above the function accepts a string and returns a string.
  • The function indicates it’s undefined by returning nil for the first return argument.

Let’s look at another example. Imagine you want to expose GitHub repository metadata to your policies. One option is to implement a custom built-in function to fetch the data for specific repositories on-the-fly.

  1. r := rego.New(
  2.     rego.Query(`github.repo("open-policy-agent", "opa")`),
  3.     rego.Function2(
  4.         &rego.Function{
  5.             Name: "github.repo",
  6.             Decl: types.NewFunction(types.Args(types.S, types.S), types.A),
  7.             Memoize: true,
  8.         },
  9.         func(bctx rego.BuiltinContext, a, b *ast.Term) (*ast.Term, error) {
  10.             // see implementation below.
  11.         },
  12.     ),
  13. )

Built-in function names can include . characters. Consider namespacing your built-in functions to avoid collisions. This declaration indicates the function accepts two strings and returns a value of type any. The any type is the union of all types in Rego.

types.S and types.A are shortcuts for constructing Rego types. If you need to define use-case specific types (e.g., a list of objects that have fields foo, bar, and baz, you will need to construct them using the types packages APIs.)

The declaration also sets rego.Function#Memoize to true to enable memoization across multiple calls in the same query. If your built-in function performs I/O, you should enable memoization as it ensures function evaluation is deterministic.

The implementation wraps the Go standard library to perform HTTP requests to GitHub’s API:

  1. func(bctx rego.BuiltinContext, a, b *ast.Term) (*ast.Term, error) {
  2.     var org, repo string
  4.     if err := ast.As(a.Value, &org); err != nil {
  5.         return nil, err
  6.     } else if ast.As(b.Value, &repo); err != nil {
  7.         return nil, err
  8.     }
  10.     req, err := http.NewRequest("GET", fmt.Sprintf("https://api.github.com/repos/%v/%v", org, repo), nil)
  11.     if err != nil {
  12.         return nil, err
  13.     }
  15.     resp, err := http.DefaultClient.Do(req.WithContext(bctx.Context))
  16.     if err != nil {
  17.         return nil, err
  18.     }
  20.     defer resp.Body.Close()
  22.     if resp.StatusCode != http.StatusOK {
  23.         return nil, fmt.Errorf(resp.Status)
  24.     }
  26.     v, err := ast.ValueFromReader(resp.Body)
  27.     if err != nil {
  28.         return nil, err
  29.     }
  31.     return ast.NewTerm(v), nil
  32. }

The implementation is careful to use the context passed to the built-in function when executing the HTTP request. See the appendix at the end of this page for the complete example.

Custom built-in functions must not be used for effecting changes in external systems as OPA does not guarantee that the statement will be executed due to automatic performance optimizations that are applied during policy evaluation.

Custom Plugins for OPA Runtime

Read this section if you want to customize or extend the OPA runtime/executable with custom behaviour.

OPA defines a plugin interface that allows you to customize certain behaviour like decision logging or add new behaviour like different query APIs. To implement a custom plugin you must implement two interfaces:

  • Factory to instantiate your plugin.
  • Plugin to provide your plugin behavior.

You can register your factory with OPA by calling RegisterPlugin inside your main function.

Plugin Status

The plugin may (optionally) report its current status to the plugin Manager via the plugins.Manager#UpdatePluginStatus API.

If no status is provided the plugin is assumed to be working OK.

Typically the plugin should report StatusNotReady at creation time and update to StatusOK (or StatusErr) when appropriate.

Putting It Together

The example below shows how you can implement a custom Decision Logger that writes events to a stream (e.g., stdout/stderr).

  1. import (
  2.     "encoding/json"
  4.     "github.com/open-policy-agent/opa/plugins/logs"
  5. )
  7. const PluginName = "println_decision_logger"
  9. type Config struct {
  10.     Stderr bool `json:"stderr"` // false => stdout, true => stderr
  11. }
  13. type PrintlnLogger struct {
  14.     manager *plugins.Manager
  15.     mtx     sync.Mutex
  16.     config  Config
  17. }
  19. func (p *PrintlnLogger) Start(ctx context.Context) error {
  20.     p.manager.UpdatePluginStatus(PluginName, &plugins.Status{State: plugins.StateOK})
  21.     return nil
  22. }
  24. func (p *PrintlnLogger) Stop(ctx context.Context) {
  25.     p.manager.UpdatePluginStatus(PluginName, &plugins.Status{State: plugins.StateNotReady})
  26. }
  28. func (p *PrintlnLogger) Reconfigure(ctx context.Context, config interface{}) {
  29.     p.mtx.Lock()
  30.     defer p.mtx.Unlock()
  31.     p.config = config.(Config)
  32. }
  35. // Log is called by the decision logger when a record (event) should be emitted. The logs.EventV1 fields
  36. // map 1:1 to those described in https://www.openpolicyagent.org/docs/latest/management-decision-logs
  37. func (p *PrintlnLogger) Log(ctx context.Context, event logs.EventV1) error {
  38.     p.mtx.Lock()
  39.     defer p.mtx.Unlock()
  40.     w := os.Stdout
  41.     if p.config.Stderr {
  42.         w = os.Stderr
  43.     }
  44.     bs, err := json.Marshal(event)
  45.     if err != nil {
  46.         p.manager.UpdatePluginStatus(PluginName, &plugins.Status{State: plugins.StateErr})
  47.         return nil
  48.     }
  49.     _, err = fmt.Fprintln(w, string(bs))
  50.     if err != nil {
  51.         p.manager.UpdatePluginStatus(PluginName, &plugins.Status{State: plugins.StateErr})
  52.     }
  53.     return nil
  54. }

Next, implement a factory function that instantiates your plugin:

  1. import (
  2.     "github.com/open-policy-agent/opa/plugins"
  3.     "github.com/open-policy-agent/opa/util"
  4. )
  6. type Factory struct{}
  8. func (Factory) New(m *plugins.Manager, config interface{}) plugins.Plugin {
  10.     m.UpdatePluginStatus(PluginName, &plugins.Status{State: plugins.StateNotReady})
  12.     return &PrintlnLogger{
  13.         manager: m,
  14.         config:  config.(Config),
  15.     }
  16. }
  18. func (Factory) Validate(_ *plugins.Manager, config []byte) (interface{}, error) {
  19.     parsedConfig := Config{}
  20.     return parsedConfig, util.Unmarshal(config, &parsedConfig)
  21. }

Finally, register your factory with OPA and call cmd.RootCommand.Execute. The latter starts OPA and does not return.

  1. import (
  2.     "github.com/open-policy-agent/opa/cmd"
  3.     "github.com/open-policy-agent/opa/runtime"
  4. )
  6. func main() {
  7.     runtime.RegisterPlugin(PluginName, Factory{})
  9.     if err := cmd.RootCommand.Execute(); err != nil {
  10.         fmt.Println(err)
  11.         os.Exit(1)
  12.     }
  13. }

At this point you can build an OPA executable including your plugin.

  1. go build -o opa++

Define an OPA configuration file that will use your plugin:

config.yaml:

  1. decision_logs:
  2.   plugin: println_decision_logger
  3. plugins:
  4.   println_decision_logger:
  5.     stderr: false

Start OPA with the configuration file:

  1. ./opa++ run --server --config-file config.yaml

Exercise the plugin via the OPA API:

  1. curl localhost:8181/v1/data

If everything worked you will see the Go struct representation of the decision log event written to stdout.

The source code for this example can be found here.

If there is a mask policy set (see Decision Logger for details) the Event received by the demo plugin will potentially be different than the example documented.

Setting the OPA Runtime Version

The OPA runtime version is set statically at build-time. The following global variables are exported by the github.com/open-policy-agent/opa/version package and can be set at build-time:

NameDescription
VersionHuman-readable/semantic version of the OPA runtime.
VcsGit SHA that the OPA runtime was built from.
TimestampDate/time when the OPA runtime was built.
HostnameHostname of the system where the OPA runtime was built.

These values can be set on the command-line when building OPA from source:

  1. go build -o opa++ -ldflags "-X github.com/open-policy-agent/opa/version.Version=MY_VERSION" main.go

Appendix

Custom Built-in Function in Go

  1. package main
  3. import (
  4.     "context"
  5.     "encoding/json"
  6.     "fmt"
  7.     "log"
  8.     "net/http"
  10.     "github.com/open-policy-agent/opa/ast"
  11.     "github.com/open-policy-agent/opa/rego"
  12.     "github.com/open-policy-agent/opa/types"
  13. )
  15. func main() {
  17.     r := rego.New(
  18.         rego.Query(`github.repo("open-policy-agent", "opa")`),
  19.         rego.Function2(
  20.             &rego.Function{
  21.                 Name:    "github.repo",
  22.                 Decl:    types.NewFunction(types.Args(types.S, types.S), types.A),
  23.                 Memoize: true,
  24.             },
  25.             func(bctx rego.BuiltinContext, a, b *ast.Term) (*ast.Term, error) {
  27.                 var org, repo string
  29.                 if err := ast.As(a.Value, &org); err != nil {
  30.                     return nil, err
  31.                 } else if ast.As(b.Value, &repo); err != nil {
  32.                     return nil, err
  33.                 }
  35.                 req, err := http.NewRequest("GET", fmt.Sprintf("https://api.github.com/repos/%v/%v", org, repo), nil)
  36.                 if err != nil {
  37.                     return nil, err
  38.                 }
  40.                 resp, err := http.DefaultClient.Do(req.WithContext(bctx.Context))
  41.                 if err != nil {
  42.                     return nil, err
  43.                 }
  45.                 defer resp.Body.Close()
  47.                 if resp.StatusCode != http.StatusOK {
  48.                     return nil, fmt.Errorf(resp.Status)
  49.                 }
  51.                 v, err := ast.ValueFromReader(resp.Body)
  52.                 if err != nil {
  53.                     return nil, err
  54.                 }
  56.                 return ast.NewTerm(v), nil
  57.             },
  58.         ),
  59.     )
  61.     rs, err := r.Eval(context.Background())
  62.     if err != nil {
  63.         log.Fatal(err)
  64.     } else if len(rs) == 0 {
  65.         fmt.Println("undefined")
  66.     } else {
  67.         bs, _ := json.MarshalIndent(rs[0].Expressions[0].Value, "", "  ")
  68.         fmt.Println(string(bs))
  69.     }
  70. }

Adding Built-in Functions to the OPA Runtime

  1. package main
  3. import (
  4.     "fmt"
  5.     "net/http"
  6.     "os"
  8.     "github.com/open-policy-agent/opa/ast"
  9.     "github.com/open-policy-agent/opa/cmd"
  10.     "github.com/open-policy-agent/opa/rego"
  11.     "github.com/open-policy-agent/opa/types"
  13. )
  15. func main() {
  17.     rego.RegisterBuiltin2(
  18.         &rego.Function{
  19.             Name:    "github.repo",
  20.             Decl:    types.NewFunction(types.Args(types.S, types.S), types.A),
  21.             Memoize: true,
  22.         },
  23.         func(bctx rego.BuiltinContext, a, b *ast.Term) (*ast.Term, error) {
  25.             var org, repo string
  27.             if err := ast.As(a.Value, &org); err != nil {
  28.                 return nil, err
  29.             } else if ast.As(b.Value, &repo); err != nil {
  30.                 return nil, err
  31.             }
  33.             req, err := http.NewRequest("GET", fmt.Sprintf("https://api.github.com/repos/%v/%v", org, repo), nil)
  34.             if err != nil {
  35.                 return nil, err
  36.             }
  38.             resp, err := http.DefaultClient.Do(req.WithContext(bctx.Context))
  39.             if err != nil {
  40.                 return nil, err
  41.             }
  43.             defer resp.Body.Close()
  45.             if resp.StatusCode != http.StatusOK {
  46.                 return nil, fmt.Errorf(resp.Status)
  47.             }
  49.             v, err := ast.ValueFromReader(resp.Body)
  50.             if err != nil {
  51.                 return nil, err
  52.             }
  54.             return ast.NewTerm(v), nil
  55.         },
  56.     )
  58.     if err := cmd.RootCommand.Execute(); err != nil {
  59.         fmt.Println(err)
  60.         os.Exit(1)
  61.     }
  62. }