Documentation
¶
Overview ¶
Package enforcement contains the pure decision logic that decides whether a normalized tool call is permitted by an MDMConfiguration's EnforcementAllowlist.
The evaluator is deliberately I/O-free: it takes a NormalizedCall plus an allowlist and returns an allow/deny Decision. The decision endpoint and the device-side hook both build a NormalizedCall and feed it here.
Index ¶
- Constants
- func CanonicalPackageName(source types.AllowlistServerPackageSource, name string) string
- func HasDotSegments(escapedPath string) bool
- func NormalizedPort(u *url.URL) string
- func ParseClientURL(rawURL string) (*url.URL, string, error)
- func ResolvePath(escapedPath string) string
- type Decision
- type NormalizedCall
- type PackageIdentity
- type ServerIdentity
Constants ¶
const ( KindMCP = "mcp" KindShell = "shell" KindRead = "read" KindWrite = "write" KindTask = "task" KindGeneric = "generic" // Supported local agents. AgentClaudeCode = "claude_code" AgentCodex = "codex" AgentCursor = "cursor" AgentKiro = "kiro" )
Tool-call kinds produced by the device-side tool classifier. These mirror the classifications obot-sentry derives from a runtime tool name.
const ( // MaxMatchedPathBytes bounds the path of a URL that URL entries will consider. // Resolving a path costs memory in proportion to its segments, and a device can // report a URL as large as the request body, so a longer one matches no URL entry. // The query and fragment are cut off first, because they are never matched. MaxMatchedPathBytes = 64 << 10 )
Variables ¶
This section is empty.
Functions ¶
func CanonicalPackageName ¶
func CanonicalPackageName(source types.AllowlistServerPackageSource, name string) string
CanonicalPackageName reduces a package name to the single spelling its registry considers canonical, so that packageMatches — which compares names as exact strings — cannot be sidestepped by an alias form.
func HasDotSegments ¶ added in v0.27.0
HasDotSegments reports whether resolving escapedPath with ResolvePath does more than decode "%2e", i.e. whether it holds a "." or ".." segment, written plainly or encoded.
func NormalizedPort ¶
NormalizedPort returns the explicit port or the scheme's default port.
func ParseClientURL ¶ added in v0.27.0
ParseClientURL parses rawURL the way browsers and Node parse it and returns its path escaped as such a client sends it. For an http(s) URL, a literal backslash in the path is read as "/"; an encoded backslash ("%5C") is not. A literal backslash in the authority, or ending it, is an error, because clients disagree on which host it names. The path is taken from rawURL rather than from url.URL.EscapedPath, which decodes "%2F" into "/" whenever the path also holds a character Go would escape.
func ResolvePath ¶ added in v0.27.0
ResolvePath returns an escaped path from ParseClientURL with dot-segments removed the way browsers and Node resolve them, which is the path an MCP client actually requests. Empty segments are kept and encoded slashes stay encoded, so "/a//../b" becomes "/a/b", not "/b", and "/a/..//b" becomes "//b", not "/b".
Types ¶
type Decision ¶
Decision is the result of evaluating a NormalizedCall against an allowlist.
func Evaluate ¶
func Evaluate(call NormalizedCall, allowlist types.EnforcementAllowlist) Decision
Evaluate decides whether call is permitted by allowlist. It is fail-closed: anything that does not positively match an allow rule is denied.
type NormalizedCall ¶
type NormalizedCall struct {
// Agent is the coding agent that issued the call (claude_code | codex | vscode | cursor | kiro).
Agent string
// Tool is the runtime tool name (for an MCP call this is the tool within the server).
Tool string
// Kind is the classified tool kind: mcp | shell | read | write | task | generic.
Kind string
// ServerName is the MCP server hint derived from the tool name (e.g. the
// "<server>" in mcp__<server>__<tool>). It may be empty when the agent does
// not expose a server hint. It is used to match the built-in agent MCP set.
ServerName string
// Server identifies the resolved target MCP server (for mcp calls).
Server ServerIdentity
// ObotHosted is true when the resolved server maps to an Obot-hosted or
// system MCP server.
ObotHosted bool
// Unresolved reports that the device could not establish what the call
// targets, and UnresolvedReason names the specific cause. Such a call is
// denied ahead of every allowlist toggle: nothing can be said to match a
// target that was never identified.
Unresolved bool
UnresolvedReason string
}
NormalizedCall is the parameter-free description of a single tool call that the evaluator decides on. It is produced by the device-side pre-tool hook (resolving the target server from the agent's MCP config) and by the decision endpoint before evaluation.
type PackageIdentity ¶
type PackageIdentity struct {
Source types.AllowlistServerPackageSource
Name string
Version string
}
PackageIdentity is the canonical package identity of a stdio MCP server that is launched via a package runner (npx / uvx).
type ServerIdentity ¶
type ServerIdentity struct {
URL string
Package *PackageIdentity
Command string
Hostname string
// Connector is the display name of a hosted agent-account connector, which
// has no local URL and no local command.
Connector string
}
ServerIdentity identifies a resolved MCP server. For an MCP call at most one of URL / Package / Command / Connector is populated; Hostname is derived from URL when present.