hostlink

package
v0.7.22 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package hostlink is the runner's host link: the MCP server through which an agent works a target host, a machine the person named when the run started. It runs in its own container, on the agentry-hostlink image (OpenSSH) with this binary copied in, launched by the run's gateway like any declared server, behind one relay per target host to the address and port the person named. It holds each host's credential in files bound into it alone, and makes every SSH session itself: the agent never does, and neither the agent container nor the tools server gains a route out.

Stdlib only, like everything else in this binary.

Index

Constants

View Source
const (
	RefusedAuth    = "host-auth"
	RefusedHostKey = "host-key-changed"
	RefusedReach   = "host-unreachable"
)

The start check's refusals, as the receipt names them (host-refused).

View Source
const (
	MaxShellsPerHost = 4
	DefaultShellIdle = 30 * time.Minute
)

The bounds. The exported ones are stated in the Drafter's runtime facts, generated from these.

View Source
const (
	// SpecMount is the plan's hostspec.json, read-only.
	SpecMount = "/run/agentry/hostspec.json"
	// HostsMount is the run's cfg/hosts, read-only: one folder per target
	// host (its credential, its known_hosts, target.json) and passwd.
	HostsMount = "/run/agentry/hosts"
	// LogMount is the run's cfg/hostlog, writable: one log a target host,
	// LogFile(id), which the engine copies into the receipts.
	LogMount = "/run/agentry/hostlog"
	// FilesMount is the folder host_put copies from and host_get copies
	// into, writable; the tools server sees the same folder at FilesPath,
	// inside the agent's scratch folder.
	FilesMount = "/files"
	// FilesPath is that folder as the agent and the tools server name it.
	FilesPath = "/scratch/hosts"
	// PasswdFile is the passwd file in HostsMount that the engine binds
	// over /etc/passwd: ssh refuses to start for a uid with no entry, and
	// the host link runs as the person's uid.
	PasswdFile = "passwd"
	// AskpassProgram is the name this binary answers to as OpenSSH's
	// SSH_ASKPASS (a link to it in the image): it prints the one file
	// AskpassFileEnv names, below HostsMount, and nothing else.
	AskpassProgram = "/usr/local/bin/agentry-askpass"
	AskpassFileEnv = "AGENTRY_ASKPASS_FILE"
)

Where the host link finds what the engine gives it, inside its container.

View Source
const (
	TargetFile     = "target.json"
	KeyFile        = "key"
	PasswordFile   = "password"
	PassphraseFile = "passphrase"
	SudoFile       = "sudo"
	KnownHostsFile = "known_hosts"
)

The files in a target host's folder (HostsMount/<id>/), each 0600.

View Source
const (
	AuthKey      = "key"
	AuthPassword = "password"
)

The ways a target host is signed in to.

View Source
const (
	ToolRun   = "host_run"
	ToolRead  = "host_read"
	ToolWrite = "host_write"
	ToolPut   = "host_put"
	ToolGet   = "host_get"

	ToolShellOpen  = "host_shell_open"
	ToolShellSend  = "host_shell_send"
	ToolShellRead  = "host_shell_read"
	ToolShellClose = "host_shell_close"
)

The host link's tools: the one-shot five and the shell's four.

View Source
const (
	DefaultRunTimeout = 300
	MaxRunTimeout     = 1800
)

The bounds. The exported ones are stated in the Drafter's runtime facts, generated from these.

View Source
const HostKeyAlias = "agentry-target"

HostKeyAlias is the name every target host's key is kept under in its own known_hosts: ssh dials the relay, never the host, so the key is checked under this alias (HostKeyAlias), and each host's file holds only its own key.

View Source
const KeySudoPassword = "sudo-password"

KeySudoPassword is the key that types the run's sudo password.

View Source
const MinScrub = 6

MinScrub is the shortest value the scrub masks: shorter, and it would mask ordinary text (a password that short is the person's to change; the receipt says when one is).

View Source
const Redacted = "[redacted: a sign-in of this run's target host]"

Redacted is what a run credential is replaced by.

View Source
const ResourceURI = "agentry://hosts"

ResourceURI names the embedded resource a host tool's answer travels in.

View Source
const ServerName = "agentry-hostlink"

ServerName is the host link's name in the gateway's catalog.

View Source
const SpecVersion = "1"

SpecVersion is the hostspec.json version this server implements.

Variables

View Source
var ShellLogRE = regexp.MustCompile(`^host-([a-z0-9_]{1,64})-shell-([1-9][0-9]{0,5})\.log$`)

ShellLogRE matches a shell transcript's name, giving the host's id.

View Source
var Tools = append([]string{ToolRun, ToolRead, ToolWrite, ToolPut, ToolGet}, shellTools...)

Tools are the host link's tools, in the order it lists them. Their results reach the agent unchanged, past the gateway's secret block and the harness's scrub, so a client that scrubs tool output by name leaves these out.

Functions

func Askpass

func Askpass(stdout, stderr io.Writer) int

Askpass is this binary as OpenSSH's SSH_ASKPASS (no sshpass): ssh runs it with its prompt as the one argument and reads a line from its standard output. It prints the file AskpassFileEnv names, which must be a password or a passphrase file in a target host's folder under HostsMount, and nothing else: whoever can run it in the host link's container can read those files anyway, and nothing else of the run's is there to print. It answers the exit status.

func LogFile

func LogFile(id string) string

LogFile is a target host's log under LogMount: one JSON line a call.

func RefusedLine

func RefusedLine(id, detail, why string) string

RefusedLine is the start failure's one line on stderr, which the gateway relays into its log ("- agentry-hostlink: …") and the engine reads to say why the run stopped: the host's id and one of the Refused* details.

func Serve

func Serve(ctx context.Context, in io.Reader, out, logw io.Writer, cfg Config) error

Serve readies every target host, checks that each takes the run's credential, then serves the MCP loop until in closes. A host that will not take its credential, or whose key is not the one checked, ends the server before it serves: the run is not the one the person started (RefusedLine says why on logw).

func ShellLogFile

func ShellLogFile(id string, n int) string

ShellLogFile is the transcript of a target host's shell session n under LogMount: what was typed and what the shell printed, as text, masked of the run's own sign-ins.

func ShellLogPattern

func ShellLogPattern(id string) string

ShellLogPattern names every shell transcript of a target host, as a receipt line says where they are.

func Spellings

func Spellings(c string) []string

Spellings are the ways a credential can appear in what a command prints: as it is, trimmed, in base64 (with and without the line end a command adds, standard, unpadded and URL-safe), and for a private key each line of its body and the body whole. The host link's scrub and the engine's redactor take the same list, so the two cannot drift.

func ValidID

func ValidID(id string) bool

ValidID says whether id is an intake question's id, the shape a target host's folder and log are named by.

func ValidUser

func ValidUser(user string) bool

ValidUser says whether user is an account name the host link passes to ssh: a name, never an option or a path.

Types

type Config

type Config struct {
	SpecPath, HostsDir, LogDir, FilesDir, TmpDir string
	Run                                          Runner
	// Lookup finds the relay of a target host's address (relayLookup).
	Lookup func(address string) (string, error)
	Now    func() time.Time
	// Shell starts a shell session's ssh (startTerminal); ShellIdle and
	// ShellSettle are a session's idle time and the quiet that ends a
	// wait for its output (DefaultShellIdle, defaultSettle).
	Shell                  func(argv, env []string) (Terminal, error)
	ShellIdle, ShellSettle time.Duration
}

Config is where a host link finds its files, and how it runs ssh.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig is the host link as its catalog entry mounts it.

type LogEntry

type LogEntry struct {
	Time    string `json:"time"`
	Tool    string `json:"tool"`
	Command string `json:"command,omitempty"`
	Sudo    bool   `json:"sudo,omitempty"`
	Path    string `json:"path,omitempty"`
	To      string `json:"to,omitempty"`
	Exit    *int   `json:"exit,omitempty"`
	Stdout  int64  `json:"stdoutBytes,omitempty"`
	Stderr  int64  `json:"stderrBytes,omitempty"`
	Bytes   int64  `json:"bytes,omitempty"`
	// Session is a shell call's session, and Keys the keys it typed after
	// its text (Command), by name: the sudo password is "sudo-password".
	Session int      `json:"session,omitempty"`
	Keys    []string `json:"keys,omitempty"`
	Error   string   `json:"error,omitempty"`
}

LogEntry is one line of a target host's log: the tool, the command or the paths, the exit status and the byte counts. The engine masks it with the run's redactor before it is a receipt.

type Runner

type Runner func(ctx context.Context, argv, env []string, stdin io.Reader, stdout, stderr io.Writer) (int, error)

Runner runs one program to its end: the ssh and sftp the host link calls, or a test's stand-in.

type Spec

type Spec struct {
	SpecVersion string `json:"specVersion"`
	// Hosts are the release's target hosts, by question id, in intake
	// order.
	Hosts []string `json:"hosts"`
	// MaxResultBytes and MaxResultLines are the harness's result limit,
	// as the tools server's (toolsrv.Limits).
	MaxResultBytes int64 `json:"maxResultBytes,omitempty"`
	MaxResultLines int   `json:"maxResultLines,omitempty"`
}

Spec is hostspec.json: what the compiled plan says of the host link. It names the target hosts by their intake question's id and holds no address, user, port or credential, which are the run's (Target).

func ParseSpec

func ParseSpec(b []byte) (*Spec, error)

ParseSpec reads hostspec.json, refusing a version it does not implement, an unknown field, or a host id not in the question id form.

type Target

type Target struct {
	// ID is the intake question's id.
	ID string `json:"id"`
	// Named is the host as the person wrote it (a name or an address).
	Named string `json:"named"`
	// Address is the IPv4 address the person's machine resolved it to,
	// which the relay dials, and the relay's own alias on the host link's
	// network.
	Address string `json:"address"`
	Port    int    `json:"port"`
	User    string `json:"user"`
	// HostKeyAlgorithm is what ssh offers to accept for the one key
	// known_hosts holds: its type (ssh-ed25519, ecdsa-sha2-nistp256), or
	// for an RSA key "rsa-sha2-512,rsa-sha2-256".
	HostKeyAlgorithm string `json:"hostKeyAlgorithm"`
	// Auth is AuthKey or AuthPassword.
	Auth string `json:"auth"`
	// Passphrase says the key has one, in PassphraseFile.
	Passphrase bool `json:"passphrase,omitempty"`
	// Sudo says the person gave a sudo password, in SudoFile.
	Sudo bool `json:"sudo,omitempty"`
}

Target is target.json: one target host as the engine resolved and checked it at run start.

func ParseTarget

func ParseTarget(b []byte) (Target, error)

ParseTarget reads target.json the same way.

func (Target) Check

func (t Target) Check() error

Check refuses a target the engine should never have written: every value reaches ssh's arguments, so each is held to its form here as well.

type Terminal

type Terminal interface {
	io.ReadWriter
	// Wait waits for the process to end, after a read has returned an
	// error, and gives its exit status.
	Wait() (int, error)
	// Kill ends the process, which ends the session on the host.
	Kill()
}

Terminal is a shell session's process: what is written to it is typed into the shell, and what it reads is everything the shell and ssh print, io.EOF once it has ended.

Jump to

Keyboard shortcuts

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