Crate openmoat_core

Expand description

openmoat-core: the trusted decision core of OpenMoat.

This crate is pure: it performs no I/O and makes no OS calls. Callers (the CLI, host adapters) read files, resolve the environment and pass everything in. That keeps the security-relevant logic small, testable and portable (it also builds for wasm32).

Pipeline: an Action is classified into AtomicActions, each atomic action is evaluated deny → allow → ask → defaults by a CompiledPolicy, and the strictest verdict across them becomes the Decision. Facts that need the filesystem reach the engine through ProgramResolver and PathResolver. The policy compiler (ir::lower()) derives from the same policy what an operating-system layer can enforce (ADR-019).

Modules§

ir: The policy compiler’s intermediate representation (ADR-019).
lint: Policy warnings: valid policies that probably do not mean what they say.
token: Well-known token formats with a vendor prefix, and the services they belong to.
yaml: The one place OpenMoat reads and writes YAML (ADR-024).

Structs§

CompiledPolicy: A policy with all patterns compiled for one evaluation context.
Decision: A verdict with the rule ids and human-readable reasons that produced it.
EvalContext: Everything the engine needs from the environment. Supplied by the caller.
MapPathResolver: In-memory resolver for tests and conformance fixtures: symlink path → target, and the files that exist. The longest link that is the path itself or one of its ancestors is replaced by its target.
MapResolver: In-memory resolver for tests and conformance fixtures.
McpSettings: The mcp: section (ADR-032).
NoResolver: Resolver for callers without a search path (tests, policy check without state).
Policy: The policy document (policy.yaml), as written by users.
Push: A command that publishes local commits.
RepoPolicy: A repository policy. Only rules: defaults, executables and sandbox stay the user’s, so any other key is a parse error.
RuleGroup: One named group of patterns. A group matches when any of its patterns matches the atomic action of the corresponding kind.
SandboxSettings: The sandbox: section (ADR-018, ADR-019).
Secret: One brokered secret. Its Debug output names only the id: where the value lives and where it goes say which secrets exist.
Taint: What earlier calls of one session exposed it to.
TaintSecret: Where secret material in a session came from.
TaintSettings: The taint: section. Absent in policies written before it existed.
UnknownKind: A name that is not one of Kind::ALL.
UnknownVerdict: A name that is not allow, defer, ask or deny.

Enums§

Action: A tool call as seen from a host, before classification.
AtomicAction: The primitive operations an Action decomposes into.
Defaults: Fallback verdicts when no rule matches: one verdict for everything, or a map from action kind (shell, fs.read, fs.write, net, fetch, web.search, tool.unknown, env.read, env.set, mcp, or "*") to a verdict; a fetch without its own entry takes the net one. This is how “outbound network is deny-by-default” is expressed, because deny rules are absolute and cannot be punched through by allow rules (ADR-002).
Kind: One kind of atomic action. Ordered as policy files list them.
PolicyError: Why a policy file cannot be used. Any of these keeps guard from deciding.
SecretSource: Where OpenMoat reads a secret’s value. The agent should not be able to read it there; moat policy lint warns when no deny rule covers the source.
Verdict: Outcome of evaluating one or more atomic actions.

Constants§

DEFAULT_POLICY: The shipped default policy, as YAML: what moat init installs and what the conformance suite pins. Parse it with Policy::parse.
MAX_DNS_LABEL_LEN: Longest label of a DNS name (RFC 1035 §2.3.4).
MAX_DNS_NAME_LEN: Longest DNS name in text form, without the trailing dot (RFC 1035 §2.3.4).
REPO_RULE_PREFIX: Prefix of every rule id a repository policy contributes, so decisions and the audit log say where a rule came from, and a repository rule can never pass for one of the user’s (kernel-self) or collide with it.
SECRET_RULE_PREFIX: What a brokered secret’s id is prefixed with where it stands for a rule id (secrets.<id>): lint warnings, policy errors and sandbox losses.
TAINT_RULE: The rule id a decision tightened by session taint carries.
UNCHECKED_RULE: The rule id of a call the hook payload shows only in part (Action::Unchecked): it asks whatever else it is decided.

Traits§

PathResolver: Resolves symlinks in normalised, slash-separated absolute paths.
ProgramResolver: Resolves program names using a search path the kernel controls.

Functions§

evaluate: Compile policy for ctx and decide a single action.
file_url_path: The local path a file: URL names (file:///p, file://localhost/p, FILE:/p), percent-decoded, also as the value of --opt=URL. Programs that fetch URLs (curl, wget, git) read that file.
leaves_unknown_directory: Whether command, run in a shell that stays open for later commands (an agent host’s persistent shell session), may leave that shell in a directory that cannot be known from the command alone: a cd or pushd to a target that is not written out (cd "$X", cd -), popd, or eval, outside a subshell. source and . are not counted: what a sourced file runs is unchecked anyway, as any script’s commands are, and counting them would ask on every source .venv/bin/activate. A later command in that shell would then be checked against the wrong directory. A command line that cannot be read counts as such a move. A cd to a written-out target is checked by the classifier itself, as a read of that directory.
literal_shell_pattern: A shell pattern that matches command token for token and nothing wider.
malformed_port_pattern: Whether a net or fetch pattern reads as host:port but its port is not one port_pattern accepts (example.com:*, example.com:0, example.com:08443), or names an IPv6 address with a port ([::1]:8443): such a pattern matches no host the hook or the proxy sees. A pattern whose part before the one : is hex digits and globs (fe80:*) is an IPv6 glob.
package_near_misses: Each @package-near-miss <ecosystem> <name> <popular> atom command gives, as one line, wherever on the line the install is (cd app && pip install …, sh -c '…'): what moat allow --always adds to its rule so the install a person approved is not asked about again. Package names are not paths, so the directories the command runs in do not matter here.
patch_writes: Every file the patch text writes, in the order it names them.
port_pattern: The host part and port of a net or fetch pattern written host:port (api.example.com:8443, *.example.com:8443, 10.0.0.5:5432): exactly one :, then a port of 1 to 65535 in decimal digits with no sign and no leading zero. None for any other pattern: one without a port, an IPv6 address (more than one :, which takes no port), or a port written another way (malformed_port_pattern). A leading ! (an exclusion) is not part of it.
resolve_path: normalise for a word a shell will expand, against a working directory that may be unknown (None). None when the result depends on a directory that is not known: a relative path and an unknown cwd, ~-, or a ~name of another user (OpenMoat cannot know where other users’ homes live, so a cross-user path is unresolvable; a shell token with it asks through unparseable).