targethost

package
v0.7.12 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package targethost readies a run's target hosts before anything starts: a target host is a machine the person names when a run starts, as the answer to an intake question of type host, and the runner reaches it over SSH from the host link (runnerimage/hostlink), never from the agent's containers. Here the answer is read, its address resolved and checked, its host key checked against the person's known_hosts and the runner's own, and its credential taken from a flag, the keychain or a prompt. Nothing here connects to the host but to read its key.

Index

Constants

View Source
const (
	RefusedAddress    = receipt.HostAddress
	RefusedKeyUnknown = receipt.HostKeyUnknown
	RefusedKeyChanged = receipt.HostKeyChanged
	RefusedCredential = receipt.HostCredential
	RefusedUnreached  = receipt.HostUnreachable
)

The details of a refusal: the receipt's own words (receipt.Host*).

View Source
const (
	FromFlag     = "flag"
	FromKeychain = "keychain"
	FromPrompt   = "prompt"
)

Where a credential came from, as the receipt says it.

View Source
const (
	TrustPersonsFile = "your known_hosts"
	TrustRunnersFile = "Agentry's known hosts"
	TrustedNow       = "accepted at this run's start"
)

Where a host key's trust came from, as the receipt says it.

View Source
const DefaultPort = 22

DefaultPort is SSH's.

View Source
const HostlinkPackagesFile = "/etc/agentry/hostlink/packages"

HostlinkPackagesFile is where the hostlink image records the version apk resolved for each of its packages.

Variables

This section is empty.

Functions

func Algorithms

func Algorithms(k ssh.PublicKey) string

Algorithms is the host key algorithms ssh is held to for k: its type, and for an RSA key the two SHA-2 signatures OpenSSH accepts.

func BaseRef

func BaseRef(pol *policy.Policy) (string, error)

BaseRef is the base the policy names, refused unless pinned by digest.

func CheckAddress

func CheckAddress(a netip.Addr) error

CheckAddress refuses an address a target host is never at: this machine's own loopback, a link-local address (a cloud's metadata service among them), and addresses that are no one host. Private, LAN and Tailscale addresses are reached.

func Fingerprint

func Fingerprint(k ssh.PublicKey) string

Fingerprint says a key as ssh-keygen -l does: its type and SHA256.

func HasSavedSignIn

func HasSavedSignIn(a Answer) (bool, error)

HasSavedSignIn reports whether a sign-in for a is saved (in the keychain, or the sealed credential of a signed-out schedule's fire): what a scheduled run, with no flag and no one to ask, signs in with.

func HostLinkKnownHosts

func HostLinkKnownHosts(k ssh.PublicKey) []byte

HostLinkKnownHosts is the one-line known_hosts the host link is given: the checked key under the alias ssh looks it up by.

func KnownLines added in v0.6.1019

func KnownLines(files KnownHostsFiles, a Answer) ([]string, error)

KnownLines are the lines of files that name a's host, as a's known_hosts name or hashed from it, each as it is written: what a device that hands a run to a remote runhost has accepted of the host's keys, for the runhost to check the key it is offered against. A marker line (@revoked, @cert-authority) is carried too, so a key revoked here stays refused there.

func ResolveAddress

func ResolveAddress(ctx context.Context, id string, a Answer, rule policy.HostsPolicy) (netip.Addr, error)

ResolveAddress is the IPv4 address a run reaches a target host at: the host if it is an address, else the first IPv4 answer this machine's resolver gives for it. It refuses what a target host is never (loopback, link-local, an unspecified, multicast or broadcast address), what the policy's hosts lists exclude, and a host with no IPv4 address: the relay that reaches it is on docker's IPv4 network.

Types

type Answer

type Answer struct {
	User string `json:"user"`
	// Host is the name or the address as written, without brackets.
	Host string `json:"host"`
	Port int    `json:"port"`
}

Answer is a host question's answer, [user@]host[:port] (an IPv6 address in brackets), as the person wrote it.

func ParseAnswer

func ParseAnswer(s string) (Answer, error)

ParseAnswer reads a host question's answer. The user defaults to this machine's user name and the port to 22; neither ever carries a credential, and an answer that holds a password (user:password@host) is refused, saying so.

func (Answer) Account

func (a Answer) Account() string

Account is the system keychain account a target host's saved sign-in is kept under (service agentry): a name, never a secret.

func (Answer) KnownHostsName

func (a Answer) KnownHostsName() string

KnownHostsName is the name the host's key is looked up and kept under in a known_hosts file, as OpenSSH writes it: the host as named, in brackets with its port when the port is not 22.

func (Answer) String

func (a Answer) String() string

String is the answer as ssh would take it: user@host, :port when not 22, an IPv6 address in brackets.

type Asker

type Asker interface {
	Ask(prompt, def string) (string, error)
	AskSecret(prompt string) (string, error)
	Confirm(prompt string, def bool) (bool, error)
}

Asker is how a person at a terminal is asked; nil is no one to ask.

type Credential

type Credential struct {
	// Auth is hostlink.AuthKey or hostlink.AuthPassword.
	Auth string
	// KeyFile is the key's path on this machine, for the receipt; Key is
	// its bytes, as the file holds them.
	KeyFile    string
	Key        []byte
	Passphrase string
	Password   string
	// Sudo is the password sudo is fed, "" for none.
	Sudo string
	// From and SudoFrom say where each came from (From*).
	From, SudoFrom string
}

Credential is a target host's sign-in.

func ResolveCredential

func ResolveCredential(id string, a Answer, f Flags, getenv func(string) string, ask Asker, warn func(string)) (Credential, error)

ResolveCredential takes a target host's sign-in, in the order above. ask nil is a run with no terminal: what no flag and no saved sign-in gives is refused (the sign-in) or gone without (sudo). warn reports a keychain that could not be read, which the run then looks past.

func (Credential) Values

func (c Credential) Values() []string

Values are the credential's secrets, for the run's redactor.

func (Credential) Words

func (c Credential) Words() string

Words say the credential as the receipt does: its kind and where it came from, never a value.

type Flags

type Flags struct {
	Key, Passphrase, Password, Sudo map[string]string
}

Flags are the target-host flags of agentry run, by host id: a key file's path, and the environment variables a passphrase, a password and a sudo password are read from.

func ParseFlags

func ParseFlags(keys, passphrases, passwords, sudos []string) (Flags, error)

ParseFlags reads --host-key id=PATH, --host-passphrase id=ENV, --host-password id=ENV and --host-sudo-password id=ENV.

func (Flags) Unknown

func (f Flags) Unknown(ids []string) []string

Unknown are the ids the flags name that are none of ids.

type Host

type Host struct {
	ID         string
	Answer     Answer
	Address    netip.Addr
	HostKey    HostKey
	Credential Credential
}

Host is a target host readied for a run: the person's answer, the address it resolved to, its checked key, and its sign-in.

func Prepare

func Prepare(ctx context.Context, id string, a Answer, o Options) (*Host, error)

Prepare readies one target host. With a person at a terminal it asks for nothing a refusal would waste: the address, the host key, and only then the sign-in. With no one to ask it takes the sign-in first: such a run has only its flags and its keychain, and one with neither (a hosted run, whose host has no keychain and passes no host flag) is refused before any name is resolved or any address dialled.

func (*Host) Document

func (h *Host) Document() map[string]any

Document is the host's entry in intake.json: where the run reached and as whom, and the key it trusted, never a credential.

func (*Host) ReceiptLine

func (h *Host) ReceiptLine(calls, shells int) string

ReceiptLine is the host's capabilities_enforced line: who, the host as named and the address it resolved to, the port, the key and where its trust came from, the sign-in's kind and source, and what the run's boundary does not cover.

func (*Host) RelayHost

func (h *Host) RelayHost() string

RelayHost is the one address and port the host's relay may reach.

func (*Host) Target

func (h *Host) Target() hostlink.Target

Target is what the host link is told of the host (target.json).

type HostKey

type HostKey struct {
	Key  ssh.PublicKey
	From string
}

HostKey is a target host's checked key.

func CheckHostKey

func CheckHostKey(ctx context.Context, id string, a Answer, addr netip.Addr, files KnownHostsFiles, ask Asker, say func(string)) (HostKey, error)

CheckHostKey reads the key the host offers at addr and decides whether the run may trust it.

func (HostKey) Fingerprint

func (k HostKey) Fingerprint() string

Fingerprint is the key's type and SHA256 fingerprint, as ssh shows it.

type Image

type Image struct {
	Tag, Base string
	Packages  []string
}

Image is a built host link image and the packages its base recorded.

func EnsureImage

func EnsureImage(ctx context.Context, d dockerx.Client, s ImageSpec, ctxDir string, logw io.Writer) (Image, error)

EnsureImage builds the host link's image when it is missing, pulling the base by digest first, and reads back the package versions it recorded.

type ImageSpec

type ImageSpec struct {
	Tag, Base, Runner string
}

ImageSpec is the host link's image for a runner image and a base.

func HostLinkImage

func HostLinkImage(runnerImage, base string) ImageSpec

HostLinkImage is the image spec; its tag is a hash of the whole build, so a new runner, base or recipe gets an image of its own.

func (ImageSpec) Dockerfile

func (s ImageSpec) Dockerfile() string

Dockerfile is the build, every step in exec form.

type KnownHostsFiles

type KnownHostsFiles struct {
	// Persons is the person's ~/.ssh/known_hosts, read only; "" or absent
	// is no file.
	Persons string
	// Runners is the runner home's known_hosts, where a key trusted at a
	// run's start is kept.
	Runners string
}

KnownHostsFiles are the two files a host key is looked up in.

func DefaultKnownHostsFiles

func DefaultKnownHostsFiles(runnerHome string) KnownHostsFiles

DefaultKnownHostsFiles are the person's file and the runner home's.

type Options

type Options struct {
	// Hosts is the policy's hosts lists.
	Hosts policy.HostsPolicy
	// KnownHosts are the files host keys are looked up in.
	KnownHosts KnownHostsFiles
	Flags      Flags
	Getenv     func(string) string
	// Ask is a person at a terminal; nil, no one is asked anything.
	Ask Asker
	// Say reports a warning or a note to the person.
	Say func(string)
	// Pin is the SHA256 fingerprint (ssh.FingerprintSHA256) of the host
	// key a schedule was made with: a run that finds another refuses, as a
	// changed key does.
	Pin string
	// Keep saves the sign-in in the keychain, without asking, wherever it
	// came from: a schedule's runs, or a persistent agent's segments,
	// read it there.
	Keep bool
}

Options are what readying a target host reads besides its answer.

type Refusal

type Refusal struct {
	ID     string
	Detail string
	Err    error
	// Of is what the message calls the host; empty is a target host. A
	// caller that checks a host in another role (a runhost's setup) names
	// that role here.
	Of string
}

Refusal is a target host the run will not reach, with the receipt's detail for why (receipt.ReasonHostRefused).

func (*Refusal) Error

func (r *Refusal) Error() string

func (*Refusal) Unwrap

func (r *Refusal) Unwrap() error

Jump to

Keyboard shortcuts

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