Documentation
¶
Overview ¶
Package policyguard wraps a toolboxv0.ToolboxServer with policy decision point (PDP) enforcement. Every CallTool request hits the PDP first; a deny short-circuits with the PDP's reason as a tool- level error (NOT a transport error — the model should be able to see and reason about the refusal).
Three-layer defense recap:
- canonical registry — refuses commands routed to other toolboxes
- policy guard (this package) — refuses tool calls per policy
- OS sandbox — refuses syscalls outside the manifest's grant
The PDP layer is BETWEEN the canonical registry (which decides "should this be in this toolbox?") and the OS sandbox (which decides "can this syscall happen?"). It's the layer that says "even though git owns this and even though the sandbox would allow it, the operator's policy doesn't allow this caller to invoke it right now."
Index ¶
- type Guard
- func (g *Guard) CallTool(ctx context.Context, req *toolboxv0.CallToolRequest) (*toolboxv0.CallToolResponse, error)
- func (g *Guard) DescribeTool(ctx context.Context, req *toolboxv0.DescribeToolRequest) (*toolboxv0.DescribeToolResponse, error)
- func (g *Guard) GetPrompt(ctx context.Context, req *toolboxv0.GetPromptRequest) (*toolboxv0.GetPromptResponse, error)
- func (g *Guard) Identity(ctx context.Context, req *toolboxv0.IdentityRequest) (*toolboxv0.IdentityResponse, error)
- func (g *Guard) ListPrompts(ctx context.Context, req *toolboxv0.ListPromptsRequest) (*toolboxv0.ListPromptsResponse, error)
- func (g *Guard) ListResources(ctx context.Context, req *toolboxv0.ListResourcesRequest) (*toolboxv0.ListResourcesResponse, error)
- func (g *Guard) ListToolSummaries(ctx context.Context, req *toolboxv0.ListToolSummariesRequest) (*toolboxv0.ListToolSummariesResponse, error)
- func (g *Guard) ListTools(ctx context.Context, req *toolboxv0.ListToolsRequest) (*toolboxv0.ListToolsResponse, error)
- func (g *Guard) ReadResource(ctx context.Context, req *toolboxv0.ReadResourceRequest) (*toolboxv0.ReadResourceResponse, error)
- func (g *Guard) WithIdentity(identity map[string]any) *Guard
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Guard ¶
type Guard struct {
toolboxv0.UnimplementedToolboxServer
// contains filtered or unexported fields
}
Guard wraps a ToolboxServer with PDP enforcement. Identity / ListTools / list-style RPCs pass through unmolested — those are "what does this toolbox claim it can do" and don't mutate state. CallTool, ReadResource, and GetPrompt pass through the PDP because they're side-effecting (or at least information-disclosing).
func New ¶
New wraps inner. If pdp is nil, an AllowAllPDP is substituted — the wrapper is then a no-op. This makes Guard always-safe-to- install: code paths that haven't migrated their config to a real PDP get the same behavior they had before.
func (*Guard) CallTool ¶
func (g *Guard) CallTool(ctx context.Context, req *toolboxv0.CallToolRequest) (*toolboxv0.CallToolResponse, error)
CallTool is the load-bearing PDP gate. Refused calls return a CallToolResponse with the deny reason in Error — the SAME envelope a tool that refused itself would produce. The model sees an actionable refusal, not a transport error or a panic-style disconnect.
func (*Guard) DescribeTool ¶ added in v0.1.158
func (g *Guard) DescribeTool(ctx context.Context, req *toolboxv0.DescribeToolRequest) (*toolboxv0.DescribeToolResponse, error)
DescribeTool is the per-tool spec half of the two-phase API. Same trust class as ListTools — pass through unmolested. The PDP gates the actual side-effecting RPC (CallTool) below; describing a tool is not itself a privileged operation.
func (*Guard) GetPrompt ¶
func (g *Guard) GetPrompt(ctx context.Context, req *toolboxv0.GetPromptRequest) (*toolboxv0.GetPromptResponse, error)
GetPrompt is also gated — prompts may template in private context (paths, secrets) that the operator wants to deny per caller.
func (*Guard) Identity ¶
func (g *Guard) Identity(ctx context.Context, req *toolboxv0.IdentityRequest) (*toolboxv0.IdentityResponse, error)
func (*Guard) ListPrompts ¶
func (g *Guard) ListPrompts(ctx context.Context, req *toolboxv0.ListPromptsRequest) (*toolboxv0.ListPromptsResponse, error)
func (*Guard) ListResources ¶
func (g *Guard) ListResources(ctx context.Context, req *toolboxv0.ListResourcesRequest) (*toolboxv0.ListResourcesResponse, error)
func (*Guard) ListToolSummaries ¶ added in v0.1.158
func (g *Guard) ListToolSummaries(ctx context.Context, req *toolboxv0.ListToolSummariesRequest) (*toolboxv0.ListToolSummariesResponse, error)
ListToolSummaries is the lightweight catalog half of the two-phase API. Same trust class as ListTools — pass through unmolested.
func (*Guard) ListTools ¶
func (g *Guard) ListTools(ctx context.Context, req *toolboxv0.ListToolsRequest) (*toolboxv0.ListToolsResponse, error)
func (*Guard) ReadResource ¶
func (g *Guard) ReadResource(ctx context.Context, req *toolboxv0.ReadResourceRequest) (*toolboxv0.ReadResourceResponse, error)
ReadResource is policy-gated for the same reason CallTool is — the resource URI may name a sensitive file the operator wants to keep out of agent context. PDP key for ReadResource: Tool is the URI string. Rules can match on the URI prefix via the suffix-match shorthand (e.g. Tool="config.yaml" matches any URI ending in /config.yaml).
Source Files