Guides / Policy reference

Policy reference

kosa8 reads two documents an organisation signs. The organisation policy sets rules for the machine: which registries, which network, which models, who may approve. The MCP policy sets rules for AI tools: which tool servers, which tools, with which arguments. This page lists every field of both, where each one is enforced, and what you see when it refuses.

If you have not installed a policy before, start with Company rules, which walks through it. This page is the reference you return to.

Part A. The organisation policy

A JSON object. Every field except name is optional, and a field left out restricts nothing. "Enforced" names the place in kosa8 that can refuse.

An approver

An approval rule

A policy is checked before it is signed. A rule nobody listed could satisfy is refused then, with the count: approval rule for "network-create" needs 2 distinct approvers with role security, but the profile lists only 1 who qualify — add approvers or lower required.

An approved model

A complete organisation policy

{
  "name": "example-corp",
  "allowed_registries": ["docker.io", "ghcr.io"],
  "default_egress": "deny",
  "require_sandbox": true,
  "allowed_mcp": ["ghcr.io/example-corp/github-mcp:1.4.2"],
  "require_fips": false,
  "approvers": [
    {"name": "Asha Rao", "email": "[email protected]",
     "public_key": "AoNDqYXXYG2QK5C0P+qk+xFn0a6fxXQlp7dairJCqzg=", "roles": ["security"]},
    {"name": "Ben Ortiz", "email": "[email protected]",
     "public_key": "PjsMrSBl7Xa0U/NmpPSbq/7sZEz777lQUbrjEzCHenE=", "roles": ["security", "release-manager"]}
  ],
  "approval_rules": [
    {"match": "escalating", "required": 1},
    {"match": "network-create", "required": 2, "roles": ["security"]}
  ],
  "allow_unlisted_requesters": false,
  "require_audit_forwarding": true,
  "min_audit_retention_days": 400,
  "labels": {
    "levels": [
      {"name": "UNCLASSIFIED"},
      {"name": "CUI", "max_egress": "deny",
       "mount_paths": ["/Users/Shared/cui"],
       "destinations": ["remote:r2.example.com/cui-snapshots"]}
    ],
    "downgrade_approvals": 2
  },
  "allowed_models": [
    {"name": "qwen2.5-coder-7b-q4",
     "digest": "sha256:9f2c1e0b7a6d5c4f3e2d1c0b9a8f7e6d5c4b3a2918070605f4e3d2c1b0a99887"}
  ],
  "model_recording": "digests",
  "require_snapshot_encryption": true,
  "snapshot_key_scope": "snapshot",
  "require_agent_identity": true
}

kosa8 policy init prints a much shorter starting point:

$ kosa8 policy init
{
  "name": "example-corp",
  "allowed_registries": [
    "docker.io",
    "ghcr.io"
  ],
  "default_egress": "deny",
  "require_sandbox": true
}

Part B. The MCP policy

MCP (Model Context Protocol) is how an AI client calls tools. A tool server is a program that offers tools; kosa8's gateway runs each third-party server in a sandbox and passes calls through. The MCP policy says which of those calls may happen.

How a call is decided

The policy

A scope

A server rule

An argument rule

A condition

An argument of a type the test cannot handle counts as matching in a deny or ask rule and as not matching in an allow rule, so odd input can only make the outcome stricter. Each operator, with worked examples, is in Rules for tool calls.

A pin

The classifier

The scorer is consulted only for a call a rule answered ask. It can spare a person the question; it has no answer that means deny, and anything short of a confident allow leaves the question with the person.

kosa8's own tools: the server named kosa8

The name kosa8 is reserved. In a policy it stands for kosa8's own tools, such as sandbox_create and container_run. A scope that lists it governs those tools with the same lists and rules as any other server. A scope that does not list it leaves them as they were, because a policy written before this existed said nothing about them. kosa8 mcp add refuses to register a third-party server under that name.

A complete MCP policy

{
  "name": "example-corp",
  "default_scope": "engineering",
  "scopes": [
    {
      "name": "engineering",
      "description": "application engineers",
      "servers": [
        {
          "server": "github",
          "allow_tools": ["list_*", "get_*", "search_*", "create_issue", "merge_*"],
          "deny_tools": ["*_delete", "delete_*"],
          "rules": [
            {"id": "only-acme", "tools": ["create_issue"], "effect": "deny",
             "when": [{"arg": "/repo", "op": "not_glob", "value": "acme/*"}],
             "reason": "issues go in acme repositories"},
            {"id": "merge-needs-a-person", "tools": ["merge_*"], "effect": "ask",
             "reason": "merging changes what ships"}
          ]
        },
        {
          "server": "kosa8",
          "deny_tools": ["sandbox_delete", "snapshot_rm"],
          "rules": [
            {"id": "open-network-needs-a-person", "tools": ["sandbox_create"], "effect": "ask",
             "when": [{"arg": "/egress", "op": "eq", "value": "any"}],
             "reason": "an open network is reviewed"}
          ]
        }
      ]
    },
    {
      "name": "contractors",
      "description": "read-only access to the docs server",
      "servers": [
        {
          "server": "docs",
          "allow_tools": ["search", "read_page"],
          "pins": [
            {"tool": "search",
             "digest": "sha256:3b1f0c9a7e5d2b4861f0a9c8e7d6b5a4938271605f4e3d2c1b0a9f8e7d6c5b4a"},
            {"tool": "read_page",
             "digest": "sha256:7b1f0c9a7e5d2b4861f0a9c8e7d6b5a4938271605f4e3d2c1b0a9f8e7d6c5b4a"}
          ]
        }
      ]
    }
  ],
  "rules_mode": "enforce",
  "classifier": {
    "scorer": "local-model",
    "endpoint": "http://127.0.0.1:7434",
    "model": "qwen",
    "threshold": 0.95,
    "timeout_ms": 2000
  }
}

What that policy answers, for an agent in the default scope:

An agent in contractors may call the two pinned docs tools and no other server. That scope does not list kosa8, so kosa8's own tools are not governed for it.

Part C. Signing, pinning, installing

$ kosa8 policy keygen -o org.key
public:  kQ+JPoaWWs9JC1Nic/sRli1nJOAgQFAmmm+xtD0oEeo=
private key written to org.key (keep it secret)

$ kosa8 policy init > policy.json           # a template to edit
$ kosa8 policy sign org.key policy.json > policy.signed.json
$ kosa8 mcp-policy init > mcp.json
$ kosa8 mcp-policy sign org.key mcp.json > mcp.signed.json

$ kosa8 policy trust org.key.pub
trusted policy signer set
$ kosa8 policy install policy.signed.json
installed and activated policy "example-corp"
$ kosa8 mcp-policy install mcp.signed.json
installed MCP policy "example-corp" (2 scope(s))
  servers not listed in a scope are now denied

no trusted policy signer is pinned, so any key would be accepted here —
pin your org's public key first with `kosa8 policy trust <PUBLIC_KEY>`

$ kosa8 policy show                       # the organisation policy and its signer
$ kosa8 mcp-policy show                   # scopes, servers, allow and deny lists
$ kosa8 mcp-policy scopes                 # the scopes, with the default marked
$ kosa8 mcp-policy check github list_issues
$ kosa8 mcp-policy check --scope contractors github list_issues
$ kosa8 mcp-policy check --args '{"repo":"other/api"}' github create_issue
$ kosa8 mcp-policy events --denied        # the decisions, for a SIEM

Making a key, signing, pinning and installing need the Governance subscription or a trial. Enforcing an installed policy does not.

Part D. When a policy is missing or wrong

Both documents fail closed, with one deliberate difference in the second row.

The organisation policy is read from disk each time a rule is consulted, so a change takes effect at once. A tool gateway (kosa8 mcp serve) reads the MCP policy once, when it starts, so that the rules do not change under a running agent: a newly installed, edited or deleted MCP policy applies from the next time the gateway starts.

"Refuses" for the organisation policy means each place that consults it stops, with its own words in front of the reason above:

Part E. Checking a machine

kosa8 doctor --compliance checks this machine against the hardening baseline: whether a policy is installed and what it requires, among other controls. It reports; the fields above are what enforce. See the doctor reference page.

Where to go next