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
- Variables
- func Askpass(stdout, stderr io.Writer) int
- func LogFile(id string) string
- func RefusedLine(id, detail, why string) string
- func Serve(ctx context.Context, in io.Reader, out, logw io.Writer, cfg Config) error
- func ShellLogFile(id string, n int) string
- func ShellLogPattern(id string) string
- func Spellings(c string) []string
- func ValidID(id string) bool
- func ValidUser(user string) bool
- type Config
- type LogEntry
- type Runner
- type Spec
- type Target
- type Terminal
Constants ¶
const ( RefusedAuth = "host-auth" RefusedHostKey = "host-key-changed" RefusedReach = "host-unreachable" )
The start check's refusals, as the receipt names them (host-refused).
const ( MaxShellsPerHost = 4 DefaultShellIdle = 30 * time.Minute )
The bounds. The exported ones are stated in the Drafter's runtime facts, generated from these.
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.
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.
const ( AuthKey = "key" AuthPassword = "password" )
The ways a target host is signed in to.
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.
const ( DefaultRunTimeout = 300 MaxRunTimeout = 1800 )
The bounds. The exported ones are stated in the Drafter's runtime facts, generated from these.
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.
const KeySudoPassword = "sudo-password"
KeySudoPassword is the key that types the run's sudo password.
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).
const Redacted = "[redacted: a sign-in of this run's target host]"
Redacted is what a run credential is replaced by.
const ResourceURI = "agentry://hosts"
ResourceURI names the embedded resource a host tool's answer travels in.
const ServerName = "agentry-hostlink"
ServerName is the host link's name in the gateway's catalog.
const SpecVersion = "1"
SpecVersion is the hostspec.json version this server implements.
Variables ¶
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.
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 ¶
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 RefusedLine ¶
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 ¶
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 ¶
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 ¶
ShellLogPattern names every shell transcript of a target host, as a receipt line says where they are.
func Spellings ¶
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.
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).
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 ¶
ParseTarget reads target.json the same way.
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.