API Reference

List policies

This API endpoint responds with a list of all policy modules on the server (result response)

Params:

• pretty::Bool

Return: GetPolicyListSuccessResponse, OpenAPI.Clients.ApiResponse

Get a policy module

This API endpoint returns the details of the specified policy module ({id})

Params:

• id::String (required)
• pretty::Bool

Return: GetPolicyModuleSuccessResponse, OpenAPI.Clients.ApiResponse

Create or update a policy module

• If the policy module does not exist, it is created. - If the policy module already exists, it is replaced. If the policy module isn't correctly defined, a bad request (400) response is returned. ### Example policy module yaml package opa.examples import data.servers import data.networks import data.ports public_servers[server] { some k, m server := servers[_] server.ports[_] == ports[k].id ports[k].networks[_] == networks[m].id networks[m].public == true }

Params:

• id::String (required)
• body::String (required)
• pretty::Bool
• metrics::Bool

Return: PutPolicySuccessResponse, OpenAPI.Clients.ApiResponse

Delete a policy module

This API endpoint removes an existing policy module from the server

Params:

• id::String (required)
• pretty::Bool
• metrics::Bool

Return: Nothing, OpenAPI.Clients.ApiResponse

Get a document

This API endpoint returns the document specified by path. The path separator is used to access values inside object and array documents. If the path indexes into an array, the server will attempt to convert the array index to an integer. If the path element cannot be converted to an integer, the server will respond with 404. The server will return a bad request (400) response if either: - The query requires an input document and you do not provide it - You provide the input document but the query has already defined it.

Params:

• path::String (required)
• input::Dict{String, Any}
• pretty::Bool
• provenance::Bool
• explain::String
• metrics::Bool
• instrument::Bool
• strictbuiltinerrors::Bool

Return: GetDocumentSuccessResponse, OpenAPI.Clients.ApiResponse

Get a document that required an input

The request body contains an object that specifies a value for the input document. The path separator is used to access values inside object and array documents. If the path indexes into an array, the server will attempt to convert the array index to an integer. If the path element cannot be converted to an integer, the server will respond with 404. The server will return a bad request (400) response if either: - The query requires an input document and you do not provide it - You provided an input document but the query has already defined it.

Params:

• path::String (required)
• request_body::Dict{String, Any} (required)
• pretty::Bool
• provenance::Bool
• explain::String
• metrics::Bool
• instrument::Bool
• strictbuiltinerrors::Bool

Return: GetDocumentSuccessResponse, OpenAPI.Clients.ApiResponse

Get a document from a webhook.

Use this API if you are enforcing policy decisions via webhooks that have pre-defined request/response formats. Note, the API path prefix is /v0 instead of /v1. The request message body defines the content of the The input Document. The request message body may be empty. The path separator is used to access values inside object and array documents.

Params:

• path::String (required)
• request_body::Dict{String, Any} (required)
• pretty::Bool

Return: GetDocumentSuccessResponse, OpenAPI.Clients.ApiResponse

Create or overwrite a document.

If the path does not refer to an existing document, the server will attempt to create all of the necessary containing documents. This behavior is similar in principle to the Unix command mkdir -p. The server will respect the If-None-Match header if it is set to *. In this case, the server will not overwrite an existing document located at the path.

Params:

• path::String (required)
• request_body::Dict{String, Any} (required)
• metrics::Bool

Return: CreateDocumentSuccessResponse, OpenAPI.Clients.ApiResponse

Patch a document

Update a document. The patch operation is specified in the request body.

Params:

• path::String (required)
• patch_operation::Vector{PatchOperation} (required)

Return: Nothing, OpenAPI.Clients.ApiResponse

Delete a document

The server processes the DELETE method as if the client had sent a PATCH request containing a single remove operation.

Params:

• path::String (required)
• metrics::Bool

Return: DeleteDocumentSuccessResponse, OpenAPI.Clients.ApiResponse

Execute an ad-hoc query and return bindings for variables found in the query.

For queries that have large JSON values it is recommended to use the POST method with the query included as the POST body

Params:

• q::String (required)
• pretty::Bool
• explain::String
• metrics::Bool

Return: GetDocumentSuccessResponse, OpenAPI.Clients.ApiResponse

Execute an ad-hoc query and return bindings for variables found in the query.

Query included as the POST body. E.g.: { "query": "input.servers[i].ports[_] = \"p2\"; input.servers[i].name = name", "input": { "servers": [ ... ], } }

Params:

• queryparameterpost::QueryParameterPost (required)
• pretty::Bool
• explain::String
• metrics::Bool

Return: GetDocumentSuccessResponse, OpenAPI.Clients.ApiResponse

Execute a simple query.

OPA serves POST requests without a URL path by querying for the document at path /data/system/main. The content of that document defines the response entirely.

Params:

• request_body::Dict{String, Any} (required)
• pretty::Bool

Return: Dict{String, Any}, OpenAPI.Clients.ApiResponse

Partially evaluate a query.

The Compile API allows you to partially evaluate Rego queries and obtain a simplified version of the policy. This is most useful when building integrations where policy logic is to be translated and evaluated in another environment. <br/> For example, this post on the OPA blog shows how SQL can be generated based on Compile API output. For more details on Partial Evaluation in OPA, please refer to this blog post. <br/> The example below assumes that OPA has been given the following policy (use PUT /v1/policies/{path}): <br/> <pre> package example allow { input.subject.clearancelevel >= data.reports[].clearancelevel } </pre> <br/> Compile API request body so that it contain the following fields: <br/> <table> <tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr> <tr><td><code>query</code></td><td><code>string</code></td><td>Yes</td><td>The query to partially evaluate and compile.</td></tr> <tr><td><code>input</code></td><td><code>any</code></td><td>No</td><td>The input document to use during partial evaluation (default: undefined).</td></tr> <tr><td><code>options</code></td><td><code>object[string, any]</code></td><td>No</td><td>Additional options to use during partial evaluation. Only <code>disableInlining</code> option is supported. (default: undefined).</td></tr> <tr><td><code>unknowns</code></td><td><code>array[string]</code></td><td>No</td><td>The terms to treat as unknown during partial evaluation (default: <code>["input"]</code>]).</td></tr> </table> <br/> For example: <br/> <code> { "query": "data.example.allow == true", "input": { "subject": { "clearancelevel": 4 } }, "unknowns": [ "data.reports" ] } </code> <br/> <b>Unconditional Results from Partial Evaluation</b> When you partially evaluate a query with the Compile API, OPA returns a new set of queries and supporting policies. However, in some cases, the result of Partial Evaluation is a conclusive, unconditional answer. <br/> See the guidance for details.

Params:

• pretty::Bool
• explain::String
• metrics::Bool
• instrument::Bool
• partialqueryschema::PartialQuerySchema

Return: CompileSuccessResponse, OpenAPI.Clients.ApiResponse

Health

This API endpoint verifies that the server is operational. The response from the server is either 200 or 500: - 200 - OPA service is healthy. If bundles is true, then all configured bundles have been activated. If plugins is true, then all plugins are in an 'OK' state. - 500 - OPA service is not healthy. If bundles is true, at least one of configured bundles has not yet been activated. If plugins is true, at least one plugins is in a 'not OK' state. –- Note This check is only for initial bundle activation. Subsequent downloads will not affect the health check. Use the status endpoint (in the (management API)[management.html]) for more fine-grained bundle status monitoring. –-

Params:

• bundles::Bool
• plugins::Bool
• exclude_plugin::String

Return: Nothing, OpenAPI.Clients.ApiResponse

Get configurations

The /config API endpoint returns OPA's active configuration. When the discovery feature is enabled, this API can be used to fetch the discovered configuration in the last evaluated discovery bundle. The credentials field in the Services configuration and the private_key and key fields in the Keys configuration will be omitted from the API response.

Params:

• pretty::Bool

Return: Dict{String, Any}, OpenAPI.Clients.ApiResponse

Get status

The /status API endpoint returns the status of the OPA server. This includes the status of the bundles and plugins.

Params:

• pretty::Bool

Return: Dict{String, Any}, OpenAPI.Clients.ApiResponse

MonitoredOPAServer(configfile::String;
    host::String = "localhost",
    port::Int = DEFAULT_PORT,
    stdout = nothing,
    stderr = nothing,
)

A server that is monitored and restarted if it dies.

Arguments:

• configfile: The path to the OPA configuration file.

Keyword arguments:

• host: The host to bind to.
• port: The port to bind to.
• stdout: The stream or file to redirect stdout to.
• stderr: The stream or file to redirect stderr to.

start!(server::MonitoredOPAServer)

Starts the server. If the server is already started, an error is thrown. Monitors the server and restarts it if it dies.

stop!(server::MonitoredOPAServer)

Stops the server. If the server is not started, an error is thrown.

CommandLine execution context.

exec: a no argument function that provides the base command to execute in a julia do block. cmdopts: keyword arguments that should be used to further customize the Cmd creation pipelineopts: keyword arguments that should be used to further customize the pipeline creation

opa Run the opa command. Open Policy Agent (OPA)

Options:

• help::Bool - Help for opa

help Run the help subcommand of opa command. Help about any command

Options:

• help::Bool - Help for help

version Run the version subcommand of opa command. Print the version of OPA

Options:

• check::Bool - Check for latest OPA release
• help::Bool - Help for version

build Run the build subcommand of opa command. Build an OPA bundle

Options:

• bundle::Bool - Load paths as bundle files or root directories
• capabilities::AbstractString - Set capabilities.json file path
• claims_file::AbstractString - Set path of JSON file containing optional claims (see: https://openpolicyagent.org/docs/latest/management/#signature-format)
• debug::Bool - Enable debug output
• entrypoint::AbstractString - Set slash separated entrypoint path
• excludefilesverify::AbstractString - Set file names to exclude during bundle verification
• ignore::AbstractString - Set file and directory names to ignore during loading (e.g., '.*' excludes hidden files)
• optimize::AbstractString - Set optimization level
• output::AbstractString - Set the output filename
• revision::AbstractString - Set output bundle revision
• scope::AbstractString - Scope to use for bundle signature verification
• signing_alg::AbstractString - Name of the signing algorithm
• signing_key::AbstractString - Set the secret (HMAC) or path of the PEM file containing the private key (RSA and ECDSA)
• signing_plugin::AbstractString - Name of the plugin to use for signing/verification (see https://openpolicyagent.org/docs/latest/management/#signature-plugin
• target::AbstractString - Set the output bundle target type
• verification_key::AbstractString - Set the secret (HMAC) or path of the PEM file containing the public key (RSA and ECDSA)
• verificationkeyid::AbstractString - Name assigned to the verification key used for bundle verification
• help::Bool - Help for build

check Run the check subcommand of opa command. Check Rego source files

Options:

• bundle::Bool - Load paths as bundle files or root directories
• capabilities::AbstractString - Set capabilities.json file path
• format::AbstractString - Set output format
• ignore::AbstractString - Set file and directory names to ignore during loading (e.g., '.*' excludes hidden files)
• max_errors::AbstractString - Set the number of errors to allow before compilation fails early
• schema::AbstractString - Set schema file path or directory path
• strict::Bool - Enable compiler strict mode
• help::Bool - Help for check

completion Run the completion subcommand of opa command. Generate the autocompletion script for the specified shell

Options:

• help::Bool - Help for completion

deps Run the deps subcommand of opa command. Analyze Rego query dependencies

Options:

• bundle::AbstractString - Set bundle file(s) or directory path(s). This flag can be repeated
• data::AbstractString - Set policy or data file(s). This flag can be repeated
• format::AbstractString - Set output format
• ignore::AbstractString - Set file and directory names to ignore during loading (e.g., '.*' excludes hidden files)
• help::Bool - Help for deps

eval Run the eval subcommand of opa command. Evaluate a Rego query

Options:

• bundle::AbstractString - Set bundle file(s) or directory path(s). This flag can be repeated
• capabilities::AbstractString - Set capabilities.json file path
• count::AbstractString - Number of times to repeat each benchmark
• coverage::Bool - Report coverage
• data::AbstractString - Set policy or data file(s). This flag can be repeated
• disableearlyexit::Bool - Disable 'early exit' optimizations
• disable_indexing::Bool - Disable indexing optimizations
• disable_inlining::AbstractString - Set paths of documents to exclude from inlining
• explain::AbstractString - Enable query explanations
• fail::Bool - Exits with non-zero exit code on undefined/empty result and errors
• fail_defined::Bool - Exits with non-zero exit code on defined/non-empty result and errors
• format::AbstractString - Set output format
• ignore::AbstractString - Set file and directory names to ignore during loading (e.g., '.*' excludes hidden files)
• _import::AbstractString - Set query import(s). This flag can be repeated
• input::AbstractString - Set input file path
• instrument::Bool - Enable query instrumentation metrics (implies –metrics)
• metrics::Bool - Report query performance metrics
• package::AbstractString - Set query package
• partial::Bool - Perform partial evaluation
• pretty_limit::AbstractString - Set limit after which pretty output gets truncated
• profile::Bool - Perform expression profiling
• profile_limit::AbstractString - Set number of profiling results to show
• profile_sort::AbstractString - Set sort order of expression profiler results
• schema::AbstractString - Set schema file path or directory path
• shallow_inlining::Bool - Disable inlining of rules that depend on unknowns
• stdin::Bool - Read query from stdin
• stdin_input::Bool - Read input document from stdin
• strictbuiltinerrors::Bool - Treat built-in function errors as fatal
• target::AbstractString - Set the runtime to exercise
• timeout::AbstractString - Set eval timeout (default unlimited)
• unknowns::AbstractString - Set paths to treat as unknown during partial evaluation
• help::Bool - Help for eval

exec Run the exec subcommand of opa command. Execute against input files

Options:

• bundle::AbstractString - Set bundle file(s) or directory path(s). This flag can be repeated
• config_file::AbstractString - Set path of configuration file
• decision::AbstractString - Set decision to evaluate
• format::AbstractString - Set output format
• log_format::AbstractString - Set log format
• log_level::AbstractString - Set log level
• set::AbstractString - Override config values on the command line (use commas to specify multiple values)
• set_file::AbstractString - Override config values with files on the command line (use commas to specify multiple values)
• help::Bool - Help for exec

fmt Run the fmt subcommand of opa command. Format Rego source files

Options:

• diff::Bool - Only display a diff of the changes
• fail::Bool - Non zero exit code on reformat
• list::Bool - List all files who would change when formatted
• write::Bool - Overwrite the original source file
• help::Bool - Help for fmt

inspect Run the inspect subcommand of opa command. Inspect OPA bundle(s)

Options:

• format::AbstractString - Set output format
• help::Bool - Help for inspect

parse Run the parse subcommand of opa command. Parse Rego source file

Options:

• format::AbstractString - Set output format
• help::Bool - Help for parse

run Run the run subcommand of opa command. Start OPA in interactive or server mode

Options:

• addr::AbstractString - Set listening address of the server (e.g., [ip]:<port> for TCP, unix://<path> for UNIX domain socket)
• authentication::AbstractString - Set authentication scheme
• authorization::AbstractString - Set authorization scheme
• bundle::Bool - Load paths as bundle files or root directories
• config_file::AbstractString - Set path of configuration file
• diagnostic_addr::AbstractString - Set read-only diagnostic listening address of the server for /health and /metric APIs (e.g., [ip]:<port> for TCP, unix://<path> for UNIX domain socket)
• excludefilesverify::AbstractString - Set file names to exclude during bundle verification
• format::AbstractString - Set shell output format, i.e, pretty, json
• h2c::Bool - Enable H2C for HTTP listeners
• history::AbstractString - Set path of history file
• ignore::AbstractString - Set file and directory names to ignore during loading (e.g., '.*' excludes hidden files)
• log_format::AbstractString - Set log format
• log_level::AbstractString - Set log level
• max_errors::AbstractString - Set the number of errors to allow before compilation fails early
• mintlsversion::AbstractString - Set minimum TLS version to be used by OPA's server
• pprof::Bool - Enables pprof endpoints
• ready_timeout::AbstractString - Wait (in seconds) for configured plugins before starting server (value <= 0 disables ready check)
• scope::AbstractString - Scope to use for bundle signature verification
• server::Bool - Start the runtime in server mode
• set::AbstractString - Override config values on the command line (use commas to specify multiple values)
• set_file::AbstractString - Override config values with files on the command line (use commas to specify multiple values)
• shutdowngraceperiod::AbstractString - Set the time (in seconds) that the server will wait to gracefully shut down
• shutdownwaitperiod::AbstractString - Set the time (in seconds) that the server will wait before initiating shutdown
• signing_alg::AbstractString - Name of the signing algorithm
• skip_verify::Bool - Disables bundle signature verification
• skipversioncheck::Bool - Disables anonymous version reporting (see: https://openpolicyagent.org/docs/latest/privacy)
• tlscacert_file::AbstractString - Set path of TLS CA cert file
• tlscertfile::AbstractString - Set path of TLS certificate file
• tlscertrefresh_period::AbstractString - Set certificate refresh period
• tlsprivatekey_file::AbstractString - Set path of TLS private key file
• v1_compatible::Bool - Opt-in to OPA features and behaviors that will be enabled by default in a future OPA v1.0 release
• verification_key::AbstractString - Set the secret (HMAC) or path of the PEM file containing the public key (RSA and ECDSA)
• verificationkeyid::AbstractString - Name assigned to the verification key used for bundle verification
• watch::Bool - Watch command line files for changes
• help::Bool - Help for run

sign Run the sign subcommand of opa command. Generate an OPA bundle signature

Options:

• bundle::Bool - Load paths as bundle files or root directories
• claims_file::AbstractString - Set path of JSON file containing optional claims (see: https://openpolicyagent.org/docs/latest/management/#signature-format)
• outputfilepath::AbstractString - Set the location for the .signatures.json file
• signing_alg::AbstractString - Name of the signing algorithm
• signing_key::AbstractString - Set the secret (HMAC) or path of the PEM file containing the private key (RSA and ECDSA)
• signing_plugin::AbstractString - Name of the plugin to use for signing/verification (see https://openpolicyagent.org/docs/latest/management/#signature-plugin
• help::Bool - Help for sign

test Run the test subcommand of opa command. Execute Rego test cases

Options:

• bench::Bool - Benchmark the unit tests
• benchmem::Bool - Report memory allocations with benchmark results
• bundle::Bool - Load paths as bundle files or root directories
• count::AbstractString - Number of times to repeat each test
• coverage::Bool - Report coverage (overrides debug tracing)
• exitzeroon_skipped::Bool - Skipped tests return status 0
• explain::AbstractString - Enable query explanations
• format::AbstractString - Set output format
• ignore::AbstractString - Set file and directory names to ignore during loading (e.g., '.*' excludes hidden files)
• max_errors::AbstractString - Set the number of errors to allow before compilation fails early
• run::AbstractString - Run only test cases matching the regular expression
• showfailureline::Bool - Show test failure line
• target::AbstractString - Set the runtime to exercise
• threshold::AbstractString - Set coverage threshold and exit with non-zero status if coverage is less than threshold %
• timeout::AbstractString - Set test timeout (default 5s, 30s when benchmarking)
• verbose::Bool - Set verbose reporting mode
• help::Bool - Help for test

bench Run the bench subcommand of opa command. Benchmark a Rego query

Options:

• benchmem::Bool - Report memory allocations with benchmark results
• bundle::AbstractString - Set bundle file(s) or directory path(s). This flag can be repeated
• count::AbstractString - Number of times to repeat each benchmark
• data::AbstractString - Set policy or data file(s). This flag can be repeated
• fail::Bool - Exits with non-zero exit code on undefined/empty result and errors
• format::AbstractString - Set output format
• ignore::AbstractString - Set file and directory names to ignore during loading (e.g., '.*' excludes hidden files)
• _import::AbstractString - Set query import(s). This flag can be repeated
• input::AbstractString - Set input file path
• metrics::Bool - Report query performance metrics
• package::AbstractString - Set query package
• partial::Bool - Perform partial evaluation
• schema::AbstractString - Set schema file path or directory path
• stdin::Bool - Read query from stdin
• stdin_input::Bool - Read input document from stdin
• target::AbstractString - Set the runtime to exercise
• unknowns::AbstractString - Set paths to treat as unknown during partial evaluation
• help::Bool - Help for bench

Visitor

Abstract type for AST visitors. Visitors must implement the before, visit and after methods. Visitors can keep state, the same visitor instance will be passed to all invocations of before, visit and after that happen while walking the AST.

walk(visitor, node)

Walks the AST rooted at node using the visitor. Calls before, visit and after methods of the visitor in sequence while walking the tree.

before(visitor, node)

Called before visiting a node. The node that will be visited is passed as the second argument. Any preparatory work that needs to be done before visiting the node can be done here. Return value is ignored.

visit(visitor, node)

Called when visiting a node. The node that is being visited is passed as the second argument. The actual action to be performed when visiting a node must be implemented here. The visit method must also call walk on the visitor to visit the children of the node. The result must be stored in the visitor state. Return value is ignored.

after(visitor, node)

Called after visiting a node. The node that was visited is passed as the second argument. Any cleanup work that needs to be done after visiting the node can be done here. This is the last method called when visiting a node. Must return the result of visiting the node.

Visitor that converts a partial compile result to a julia based AST. Must be used with ASTWalker.walk, providing the partial compile result as the node argument.

Output:

• QuerySet: If the partial compile result contains queries, the output is a QuerySet containing the queries.
• nothing: If the partial compile result does not contain queries, the output is nothing.

The output is returned from the walk method.

SQLVisitor

Visitor that converts an OPA partial compile AST to a SQL condition.

It requires two dictionaries to be passed in the constructor:

• schema_map: maps OPA package names to database schema names
• table_map: maps OPA rule names to database table names

Input to the visitor must be a partial compile result from OPA already converted to a julia representation using ASTWalker.AST.ASTVisitor. Walking the AST using this visitor will result in a SQL condition that can be appended to a SQL query using a where clause. Output, that is returned from the walk method, is an AbstractSQLCondition. It can be one of:

• SQLCondition: represents a SQL condition. Contains the SQL string that represents the condition that can be used in the query with a "where" clause.
• UnconditionalInclude: represents an unconditional include condition. Which means that the SQL query should return all rows.
• UnconditionalExclude: represents an unconditional exclude condition. Which means that the SQL query should not return any rows.