enforcement

package
v0.27.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 5 Imported by: 0

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

View Source
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.

View Source
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

func HasDotSegments(escapedPath string) bool

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

func NormalizedPort(u *url.URL) string

NormalizedPort returns the explicit port or the scheme's default port.

func ParseClientURL added in v0.27.0

func ParseClientURL(rawURL string) (*url.URL, string, error)

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

func ResolvePath(escapedPath string) string

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

type Decision struct {
	Allow  bool
	Reason string
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL