`maqpna policy`

Test a tool call against policies, offline or on the live gateway

Govern-o json | yaml

Synopsis#

maqpna policy test --policy FILE|DIR --ns NS --agent A --server S --tool T [--args JSON] [--session S] [--user U] [--expect ACTION]
                   [--group G]... [--scope S]... [--taint LABEL]... [--sink LABEL]... [--at RFC3339] [--explain]
maqpna policy test --gateway URL --tool T ...      (evaluate with the gateway's live policies and session taints)
maqpna policy test DIR|FILE... [-f maqpna-test.yaml] [--require-tests] [-o table|json|junit]   (test suites)
maqpna policy lint FILE|DIR... [--strict] [-o table|json]
maqpna policy list [--gateway URL] [-n NS]
maqpna policy get [NS/]NAME [--gateway URL]

Description#

Policy files: ToolPolicy custom resources (YAML or JSON, several per file, or a List) and the operator-rendered policies.json bundle are both accepted. ToolPolicies are rendered with the operator's own renderer (pkg/policyload), so a test evaluates exactly what the gateway would load. A ToolPolicy that the operator would refuse to publish (bad regex, timezone, Cedar, ...) is an error.

Suite mode: policy test DIR runs every maqpna-test.yaml under DIR (FILE runs that suite). A suite is:

  apiVersion: maqpna.com/v1alpha1
  kind: PolicyTest
  name: coder                      # optional
  policies: [../policies/]         # files or dirs, relative to the suite
  defaults: {namespace: team-a, agent: coder, user: alice@acme.eu}
  cases:                           # one tool call each
    - name: prod writes blocked
      server: kubernetes
      tool: delete
      args: {namespace: prod-eu}
      expect: deny
      expectRule: k8s-no-prod-mutations
  tasks: []                        # optional multi-step tasks (maqpna eval format)

Exit status 3 when a case fails (or, with --require-tests, a policy file is not covered by any suite).

Subcommands#

maqpna policy testTest a tool call, or a suite of cases, against policies offline or on the live gateway maqpna policy lintCheck policy files for errors and risky rules maqpna policy listList the policies the gateway has loaded maqpna policy getShow one policy as the gateway has loaded it

Examples#

# Would coder be allowed to call github.create_issue?
$ maqpna policy test --policy policies/ --ns team-a --agent coder --server github --tool create_issue
$ maqpna policy test policies/ --require-tests -o junit > policy-tests.xml
$ maqpna policy lint policies/ --strict
$ maqpna policy list -n team-a

What happens when you run it#

Prints a table by default; -o json or -o yaml print the data, and --jq EXPR filters the JSON.

Exit codes#

Code	Meaning
`0`	success
`1`	error (the message says what failed, with a hint when there is one)
`2`	usage error: unknown flag, missing argument or bad value; the synopsis is printed
`3`	a check failed, a change is blocked, or a result did not match (tamper, policy mismatch) (not used by this command)

Terminal demo#

maqpna policy.cast

maqpna policy