sshguard

type Artifacts struct {
	Stage            Stage
	NodeID           string
	SSHPort          int
	KeepLegacyPort   bool
	ConfirmWindowSec int
	// Durable is the plan's claim that this arm needs no confirm: it installs
	// no firewall, changes no port, and the node showed a key path in at plan
	// time. The arm script re-checks the key on the host before it honours
	// the claim, and ParseApprovalPlan refuses the claim on any plan that
	// carries a firewall or a port.
	Durable bool

	SSHDDropIn string
	KnockNFT   string
	KnockdConf string
	GatedPorts []int
}

type Finding struct {
	Code     string   `json:"code"`
	Severity Severity `json:"severity"`
	Message  string   `json:"message"`
}

type Hardening struct {
	// LoginGraceTimeSec is the single highest-value field here. The sshd
	// default is 120s, and brute-force clients hold that window open to
	// occupy connection slots; dropping it to ~20s removes the noise more
	// cheaply than any ban list.
	LoginGraceTimeSec int
	MaxAuthTries      int
	// MaxStartups is a raw "start:rate:full" triple because sshd's own syntax
	// is the clearest expression of it.
	MaxStartups          string
	PasswordAuth         bool
	KbdInteractiveAuth   bool
	PermitRootLogin      string
	X11Forwarding        bool
	AllowAgentForwarding bool
}

type KnockPolicy struct {
	Ports         []int
	SeqTimeoutSec int
	// OpenFor is an nftables timeout literal such as "12h". Membership expires
	// on its own, which is why there is no close sequence: forgetting to close
	// the door is a failure mode this design does not have.
	OpenFor string

	// PreviousPorts is the sequence being rotated out, when this arm is a
	// rotation. It is rendered as a second knockd stanza that opens its own
	// nftables set, so the sequence the operator already holds keeps opening
	// the gate until the confirm approval retires it. Without this a rotation
	// cut over the moment knockd restarted, and an operator who could not
	// produce confirm evidence from a source the node sees had nothing but
	// the revert timer between him and a lockout.
	PreviousPorts []int
}

type KnockSequence struct {
	Ports         []int
	SeqTimeoutSec int
	// OpenFor is the nftables set timeout the knock installs, as written
	// (for example "12h"). Empty when the start_command does not carry one.
	OpenFor string
	// PreviousPorts is the sequence a rotation kept alive beside Ports. It is
	// on the node only until the confirm retires the stanza, so a reader has
	// to pair it with whether the arm was confirmed.
	PreviousPorts []int
}

type NodeReality struct {
	// Reported is false when the node has never sent a reality snapshot.
	Reported bool
	// ListeningTCPPorts is what the node currently has bound.
	ListeningTCPPorts []int
	// ManagedByNetGuard is true when netguard has a lattice_guard table in
	// front of this node: the binding is managed and a table has been applied
	// from it, or the node reports one. A binding record on its own is not
	// enough; an observe-only binding describes nothing on the node.
	ManagedByNetGuard bool
	// GuardAcceptedTCPPorts is what that guard ruleset would accept. Only
	// meaningful when ManagedByNetGuard is true.
	GuardAcceptedTCPPorts []int
	// GuardAcceptsAllTCP is set when the guard has a rule that accepts every
	// TCP port (an any-protocol accept, or a tcp accept with no port list).
	// It is a flag rather than a 65535-entry slice because this is assembled on
	// a request path.
	GuardAcceptsAllTCP bool
	// GuardPolicyDrop reports whether the guard chain's policy is drop. A guard
	// with an accept policy cannot override this table's accepts, so the
	// override check does not apply.
	GuardPolicyDrop bool

	// SSHPorts are the ports a shell daemon is observed bound to. The caller
	// copies these into the profile so the gate covers where sshd is rather
	// than where it is assumed to be.
	SSHPorts []int

	// TerminalAvailable is true when this node can currently give an operator a
	// shell without SSH: it is online and its agent reports the terminal
	// capability. Both halves matter. A capability flag on a node that stopped
	// reporting is a fallback on paper.
	TerminalAvailable bool
}

type Posture string

type Profile struct {
	NodeID string
	Name   string

	// SSHPort is the port sshd will listen on in addition to 22. Zero means
	// the port is left alone and only the hardening and firewall apply.
	SSHPort int
	// KeepLegacyPort keeps sshd listening on 22. The default is true and the
	// reason is in RenderKnockRuleset: 22 is shrunk to the management sources
	// and knocked-open sources rather than closed, which removes the brute
	// force without removing a way in.
	KeepLegacyPort bool

	Hardening Hardening
	// Knock nil disables knocking entirely; the firewall then only shrinks the
	// ports to MgmtSources.
	Knock *KnockPolicy

	// GatePorts overrides what the gate covers.
	//
	// The escape hatch, and deliberately a small one. The ordinary path derives
	// the ports from what sshd reports, which is right for a normal host; this
	// exists for the ones that are not, without teaching the product about each
	// of them. Set it and the derivation is skipped entirely, including the
	// fallback to 22.
	GatePorts []int

	// ExistingSSHPorts are the ports sshd is observed listening on, from the
	// node's own report. The gate covers these rather than a guess: three
	// machines in this fleet run sshd on 3434, and a profile that gates 22 on
	// one of them protects nothing while reporting success.
	//
	// Empty means the node has not reported, and the profile falls back to 22
	// with a warning rather than silently gating the wrong thing.
	ExistingSSHPorts []int

	// MgmtSources are CIDRs that reach SSH without knocking, forever.
	MgmtSources []string

	// Address is the node's public address, used only to print a knock command
	// an operator can copy. It is reported by the agent, so it is validated as
	// an IP literal before it reaches the document and dropped if it is not
	// one: a plan is read by a human deciding whether to approve, and text a
	// peer chose has no business shaping it.
	Address string

	// OutOfBandFallback says the operator's fallback is a path that does not
	// use SSH at all, which on this fleet means the node's Lattice terminal.
	//
	// It exists because the obvious alternative turned out to be worse. An IP
	// allowlist looks like a safety net and is only as good as the address
	// staying put: the address written into the reference node's allowlist went
	// stale within hours of being written, and a node behind a proxy sees a
	// source that changes with the route. A fallback that silently expires is
	// more dangerous than no fallback, because nobody re-checks it.
	//
	// The Lattice terminal does not care where the operator is. It is verified
	// against the node's reported capability at plan time rather than trusted,
	// because a profile claiming a fallback that is switched off is exactly the
	// failure this field is supposed to prevent.
	OutOfBandFallback bool

	// KeyAccessObserved says the node's own sshd facts show a key path in
	// (see DerivePosture). The server sets it from the last reality report;
	// it is never taken from the request, because it decides whether the
	// arm gets a revert timer at all.
	KeyAccessObserved bool

	ConfirmWindowSec int
}

type SSHDFacts struct {
	PasswordAuthentication bool
	PubkeyAuthentication   bool
	// PermitRootLogin is the literal value sshd prints: yes, no,
	// without-password (what -T prints for prohibit-password), or
	// forced-commands-only.
	PermitRootLogin string
	// AuthorizedKeys is how many authorized keys the node reported across the
	// files sshd reads, or nil when the report carries no count. Today's
	// agent reports none, so nil is the normal value; when a count arrives it
	// takes precedence over PubkeyAuthentication as the key evidence, because
	// pubkey auth being enabled with no key on disk is not a way in.
	AuthorizedKeys *int
}

type SSHPosture struct {
	State Posture `json:"state"`
	// KeyAccess reports whether the facts show a key path in. KeyEvidence
	// says which fact backed it.
	KeyAccess   bool   `json:"key_access"`
	KeyEvidence string `json:"key_evidence,omitempty"`
	Reason      string `json:"reason"`
}

type Severity string

type Stage string