Documentation
¶
Overview ¶
Package gosshd is an SSH server for WinPE guests.
Win32-OpenSSH cannot serve a session there. Per connection it spawns a pre-auth child as a virtual account — LsaManageSidNameMapping, then LogonUserExExW with LOGON32_PROVIDER_VIRTUAL — and authenticates the user with an S4U logon. WinPE supports no user logons at all, so both stages fail and the connection closes before authentication. Privilege separation has been mandatory upstream since 7.5, so there is no configuration that avoids it.
This server answers with a password callback in its own process and starts children with a plain CreateProcess, so no part of a session touches the Windows logon subsystem. The guest is a throwaway PE behind a host-only NAT reached over a per-run forwarded port, which is what makes a fixed password acceptable here.
Index ¶
- Constants
- func ListenVsock(port uint32) (net.Listener, error)
- func SessionCommand(request string) []string
- func SessionCommandShell(request, shell string) []string
- type Client
- func (c *Client) Close() error
- func (c *Client) Run(ctx context.Context, cmd string) (stdout, stderr []byte, exitCode int, err error)
- func (c *Client) RunInput(ctx context.Context, cmd string, input io.Reader, stdout, stderr io.Writer) (int, error)
- func (c *Client) RunStream(ctx context.Context, cmd string, stdout, stderr io.Writer) (int, error)
- type Server
- type VsockAddr
Constants ¶
const ( // DefaultAddr is the guest-side listen address. The host reaches it // through a per-run forwarded port, never directly. DefaultAddr = ":22" // DefaultUser and DefaultPassword are the credentials the guest is // built with. WinPE's Administrator has no password and no usable // account database, so these name nothing in Windows — they are only // this server's own shared secret with the harness. DefaultUser = "admin" DefaultPassword = "admin" )
Variables ¶
This section is empty.
Functions ¶
func ListenVsock ¶ added in v0.3.0
ListenVsock returns an error on non-Windows platforms. The viosock.sys driver that provides AF_VSOCK is Windows-only (virtio-win).
func SessionCommand ¶
SessionCommand is the argv for a session under cmd.exe. An empty request means the client asked for a shell rather than a single command.
cmd.exe rather than pwsh: WinPE always has it, and the harness stages pwsh at a path that is not on PATH.
func SessionCommandShell ¶ added in v0.3.0
SessionCommandShell is the argv for a session under the named shell: "cmd" (default) or "powershell". Under powershell the request is passed as a single -Command argument, so the host can send a PowerShell one-liner verbatim with no cmd re-parsing — what the wsl provisioning path relies on.
Types ¶
type Client ¶ added in v0.3.0
type Client struct {
// contains filtered or unexported fields
}
Client connects to a gosshd server running inside a WinPE guest.
func Dial ¶ added in v0.3.0
Dial connects to a gosshd server at addr using the default credentials. The context deadline controls the connection timeout.
func (*Client) Run ¶ added in v0.3.0
func (c *Client) Run(ctx context.Context, cmd string) (stdout, stderr []byte, exitCode int, err error)
Run executes a command and returns captured stdout, stderr, and exit code. Cancelling ctx closes the session and returns ctx.Err() instead of blocking on a guest that never answers.
func (*Client) RunInput ¶ added in v0.3.0
func (c *Client) RunInput(ctx context.Context, cmd string, input io.Reader, stdout, stderr io.Writer) (int, error)
RunInput executes a command with stdin fed from input and output streamed to the writers. The server pipes session stdin into the command, so this is the transport for pushing files into a guest that has no sftp. Cancelling ctx closes the session, like Run.
type Server ¶
type Server struct {
// Addr is the listen address, ":22" when empty.
Addr string
// User and Password are the only accepted credentials. Both empty
// means no credentials are accepted at all.
User, Password string
// Log receives connection events. Discarded when nil.
Log *log.Logger
// Shell selects the interpreter sessions run under. "" or "cmd" uses
// cmd.exe — the WinPE-safe default, because full Windows PowerShell is not
// guaranteed on WinPE's PATH (pwsh is staged elsewhere). "powershell" uses
// Windows PowerShell (System32\...\powershell.exe), which the wsl
// provisioning server runs under so the host can send PowerShell directly.
Shell string
// Events receives one structured JSON line per session (command, exit
// code, captured stdout/stderr, duration). Discarded when nil. In the
// guest this is the virtio-serial structured port whose host end is
// build.jsonl, giving a durable 1:1 record of everything run over SSH.
Events io.Writer
// contains filtered or unexported fields
}
Server serves one WinPE guest.
func (Server) Authenticate ¶
Authenticate reports whether the offered credentials are the configured ones. A Server with no credentials configured accepts nothing, so a zero-value Server cannot be reached with an empty password.
func (Server) ListenAndServe ¶
ListenAndServe serves until the listener fails.
Source Files
Directories