stacklok / stacklok/toolhive

Distinguish tool discovery from tool invocation in authorization and audit

Open
#4,048 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

api audit authentication enhancement go kubernetes
Dominant language
Go
Stars
2.2k
Forks
300
Avg merge
1d 15h
Merged PRs (30d)
184

Description

Summary

The current authorization model uses the tool:call verb for both the ingress check
on tool listing requests (tools/list) and for egress response filtering of the tool
list. This conflates two semantically distinct operations and creates two practical
problems:

  1. Policy granularity: There is no way to write a Cedar policy that allows a
    client to discover which tools are available without also granting permission to
    invoke them. This prevents least-privilege policy designs.

  2. Audit ambiguity: An audit trail showing tool:call events cannot distinguish
    between a user who listed tools (a read-only, side-effect-free operation) and one who
    actually invoked a tool (a potentially mutable action). This reduces the forensic
    value of logs.

Proposed Change

Introduce a clear semantic split:

  • Ingress: Add a new tool:list verb (mapped to MCPOperationList on
    MCPFeatureTool) so that incoming tools/list requests are authorized independently
    of tool:call.
  • Egress: Change the per-tool filtering of tools/list responses from tool:call
    to tool:read (mapped to MCPOperationRead on MCPFeatureTool), reflecting that
    determining visibility of a tool is a read-only discovery check, not an invocation.

The resulting verb taxonomy becomes:

Verb Meaning
tool:list Client is requesting the list of available tools
tool:read A specific tool is visible/discoverable to the client
tool:call Client is invoking a tool (may have side effects)

Impact

Breaking change for users with existing Cedar policies. Any policy that previously
used tool:call to control access to tools/list will need to be updated to use
tool:list (for the list request itself) and/or tool:read (for per-tool visibility
in the response).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing authorization for incoming tools/list requests and the per-tool filtering of tools/list responses, focusing on MCPFeatureTool and the MCPOperationList and MCPOperationRead mappings. Update the verb handling so tool:list governs ingress, tool:read governs visibility, and tool:call remains invocation, with corresponding Cedar policy and audit behavior covered by the repository's relevant tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
authorization, backend-api-design, security
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.