AlfredBr.SshServer.Core 1.3.0

.NET SSH Server

A lightweight SSH server library in C# (.NET 10) that allows terminal clients to connect via SSH and interact with a TUI application. Inspired by charmbracelet's wish package in Go.

Quick Start

Install the Package

dotnet add package AlfredBr.SshServer.Core

View on NuGet: AlfredBr.SshServer.Core

Create Your Application

using AlfredBr.SshServer.Core;

public class MyApp : SshShellApplication
{
    protected override string Prompt => "myapp> ";

    protected override IEnumerable<string> Completions => ["help", "quit"];

    protected override bool OnCommand(string command)
    {
        if (command == "quit") return false;
        WriteLine($"You said: {Escape(command)}");
        return true;
    }
}

Run the Server

await SshServerHost.CreateBuilder()
    .UsePort(2222)
    .AllowAnonymous()
    .UseMaxConnections(100)
    .UseConnectionRateLimit(10, TimeSpan.FromSeconds(30))
    .UseApplication<MyApp>()
    .Build()
    .RunAsync();

Connect

ssh -p 2222 localhost

See the API Manual for the complete API reference, or DEVELOPERS.md for the contributor guide.

Project Structure

Key Classes

Builder API

await SshServerHost.CreateBuilder()
    .UsePort(2222)                              // TCP port (default: 2222)
    .UseBanner("SSH-2.0-MyApp")                 // SSH protocol banner
    .UseHostKeyPath("mykey.pem")                // Host key file path
    .AllowAnonymous()                           // Enable anonymous auth
    .UseAuthorizedKeysFile("authorized_keys")   // Public key auth file
    .UseSessionTimeout(TimeSpan.FromMinutes(30)) // Idle timeout
    .UseTransportOperationTimeout(TimeSpan.FromSeconds(30)) // Active SSH transport timeout
    .UseMaxConnections(100)                     // Connection limit
    .UseConnectionRateLimit(10, TimeSpan.FromSeconds(30)) // Per-IP connection-attempt limit
    .UseLogLevel(LogLevel.Information)          // Minimum log level
    .UseApplication<MyApp>()                    // Your application class
    .ConfigureLogging(builder => { ... })       // Custom logging config
    .UseDefaultConfiguration(args)              // Load from appsettings.json
    .Build()
    .RunAsync();

Multi-Application Support

Host multiple applications with username-based routing or an interactive menu:

await SshServerHost.CreateBuilder()
    // Map usernames directly to apps
    .MapUser<DemoApp>("demo")       // ssh demo@host → DemoApp
    .MapUser<AdminApp>("admin")     // ssh admin@host → AdminApp

    // Unmapped users see a selection menu
    .UseApplicationMenu(menu => menu
        .Add<DemoApp>("Demo", "Spectre.Console showcase")
        .Add<AdminApp>("Admin", "Server administration")
        .Add<MonitoringApp>("Monitor", "Live metrics dashboard")
        .SetDefaultForExec("Demo")
        .ReturnToMenuOnExit(true))

    .Build()
    .RunAsync();

Usage:

ssh demo@localhost -p 2222       # Direct to DemoApp
ssh admin@localhost -p 2222      # Direct to AdminApp
ssh localhost -p 2222            # Shows app selection menu
ssh guest@localhost "admin:logs" # Exec 'logs' in AdminApp

Features

Authentication

• Public key authentication — supports ssh-rsa, ssh-ed25519, ecdsa-sha2-nistp256/384/521
• Anonymous access — configurable via AllowAnonymous() builder method
• Authorized keys — standard OpenSSH authorized_keys file format

Host Keys

• ECDSA — auto-generated nistp256 key on first run
• Ed25519 — client key verification (via NSec.Cryptography)
• RSA — sha2-256/512 support

Terminal Emulation

• PTY support — full pseudo-terminal with resize handling
• Emacs-style line editing:
  • Ctrl-A/E: beginning/end of line
  • Ctrl-B/F: back/forward character
  • Ctrl-P/N: previous/next history
  • Ctrl-D: delete char or disconnect
  • Ctrl-K/U: kill to end/beginning
  • Ctrl-Y: yank (paste) from kill ring
  • Ctrl-L: clear screen
  • Alt-B/F: back/forward word
  • Alt-D: delete word forward
  • Home/End, Delete, Arrow keys
• Tab completion — command name auto-completion
• Command history — per-connection with navigation

TUI Integration (Spectre.Console)

• Rich output — tables, panels, rules, trees, bar charts
• Interactive prompts — selection, multi-select, confirmation, text input
• Live displays — progress bars, spinners, live-updating tables

SshShellApplication Helper Methods

Run the Demo

dotnet run --project src/SshServer.Demo/SshServer.Demo.csproj
ssh -p 2222 localhost

Demo Commands

With Public Key Authentication

1. Add your public key to authorized_keys:

   cat ~/.ssh/id_ed25519.pub >> src/SshServer.Demo/authorized_keys
   

2. Set AllowAnonymous to false in appsettings.json
3. Connect: ssh -p 2222 localhost

Scripted Commands (Exec Channel)

# Run a single command without entering interactive mode
ssh -p 2222 localhost status
ssh -p 2222 localhost whoami
ssh -p 2222 localhost config

# Use in scripts
result=$(ssh -p 2222 localhost status)
echo "Server says: $result"

Configuration

Settings can be configured via appsettings.json:

{
  "SshServer": {
    "Port": 2222,
    "Banner": "SSH-2.0-SshServer",
    "HostKeyPath": "hostkey_ecdsa_nistp256.pem",
    "MaxConnections": 100,
    "ConnectionRateLimitCount": 10,
    "ConnectionRateLimitWindowSeconds": 30,
    "LogLevel": "Debug",
    "AllowAnonymous": true,
    "AuthorizedKeysPath": "./authorized_keys",
    "SessionTimeoutMinutes": 0,
    "TransportOperationTimeoutSeconds": 30
  }
}

Load configuration in your app:

await SshServerHost.CreateBuilder()
    .UseDefaultConfiguration(args)  // Loads appsettings.json + env vars + CLI args
    .UseMaxConnections(100)         // Optional explicit code default
    .UseConnectionRateLimit(10, TimeSpan.FromSeconds(30))
    .UseApplication<MyApp>()
    .Build()
    .RunAsync();

Override via environment variables (SSHSERVER_ prefix) or command-line arguments.

When MaxConnections is reached, new SSH sessions are rejected until an existing session closes. When ConnectionRateLimitCount and ConnectionRateLimitWindowSeconds are both positive, connection attempts are rate-limited per client IP using a sliding window.

Architecture

┌─────────────────────────────┐
│  Your Application           │  extends SshShellApplication
├─────────────────────────────┤
│  SshServerHost + Builder    │  Fluent API, lifecycle management
├─────────────────────────────┤
│  SshShellApplication        │  Base class with helpers
├─────────────────────────────┤
│  TUI Infrastructure         │  Spectre.Console, LineEditor
├─────────────────────────────┤
│  SSH Server Library         │  FxSsh (modernised)
├─────────────────────────────┤
│  TCP Listener               │  System.Net.Sockets
└─────────────────────────────┘

Dependencies

Project Status

Completed

• SSH transport (key exchange, encryption, MAC)
• Anonymous and public key authentication
• Connection limits
• Connection-attempt rate limiting
• PTY requests and window resize
• Emacs-style line editing with history
• Tab completion
• Spectre.Console integration (rendering + interactive prompts)
• Configuration via appsettings.json
• Graceful shutdown (Ctrl+C)
• Structured logging with connection IDs
• Ed25519 client key support
• Session timeout
• SshShellApplication base class for easy app development
• Fluent builder API
• NuGet package structure

Roadmap

• Password authentication
• Unit tests

Key RFCs

Acknowledgements

This project builds upon the work of several excellent open source projects:

License

MIT — Copyright (c) 2026 Alfred Broderick