SshSharp 0.5.0

SshSharp

A managed, async-first SSH client library for .NET, with OpenSSH ssh_config and known_hosts support. Connect to a host by its ssh_config alias and get the same host name, user, keys, agent, jump hosts and host key policy that ssh would use.

await using var client = await SshClient.ConnectAsync("prod-db");   // an alias from ~/.ssh/config
var result = await client.RunCommandAsync("uptime");
Console.WriteLine(result.StandardOutputText);

Status: pre-1.0 (0.x releases). The API may still change before 1.0, and the managed cryptography has had an internal constant-time review but not yet an outside one. See SECURITY.md.

Features

• Pure managed C#, no native dependencies; .NET 8 and .NET 10, tested on Windows and Linux (x64 and Arm64) and macOS (Arm64); trimming- and Native AOT-compatible, with an AOT-compiled smoke test against a real server in CI.
• Async all the way: CancellationToken on every network operation, IAsyncDisposable, System.IO.Pipelines I/O with zero-copy packet handling.
• OpenSSH configuration: ssh_config (Host, Match, Include, tokens) and known_hosts (hashed hosts, @cert-authority, @revoked), resolved like ssh -G.
• Authentication: password, public keys (OpenSSH, PKCS#8, PKCS#1/SEC1 and PuTTY .ppk formats, encrypted too), OpenSSH user certificates, ssh-agent (Unix sockets and the Windows OpenSSH agent) and agent forwarding, keyboard-interactive (one-time codes, PAM), and multi-factor chains. Key generation, saved as ssh-keygen does; signing and verifying files and git commits with SSH keys (ssh-keygen -Y).
• Host verification: StrictHostKeyChecking policies, host certificates, UpdateHostKeys, key pinning, or your own verifier. There is no "accept anything" default. Host key scanning, as ssh-keyscan does it.
• Connections: ProxyJump chains, ProxyCommand, HTTP and SOCKS proxies, connect over any Stream or from a chosen local address (BindAddress, BindInterface), keep-alive and dead-connection detection; HttpClient through the SSH connection; TCP and Unix-socket tunnels; local, remote and dynamic (SOCKS) port forwarding (ssh -L, -R, -D) and remote dynamic and Unix-socket forwarding (-R port, -R /socket:target), also started from ssh_config.
• Sessions: run commands, stream stdin/stdout/stderr, interactive shells with a pseudo-terminal, environment variables, signals and window resizing; subsystems (ssh -s) such as netconf; expect-style scripting of shells.
• Modern algorithms: post-quantum mlkem768x25519-sha256, and the FIPS-compatible mlkem768nistp256-sha256 and mlkem1024nistp384-sha384 (on .NET 10 where the platform has ML-KEM), and sntrup761x25519-sha512 (managed, on every platform), curve25519-sha256, ECDH and DH group 14/16 key exchange; ChaCha20-Poly1305, AES-GCM and AES-CTR with HMAC-SHA2 ETM; Ed25519, ECDSA and RSA (SHA-2) keys; strict key exchange (Terrapin) always on; a FIPS mode.
• File transfer: SFTP (version 3 with OpenSSH's extensions: pipelined uploads and downloads, seekable remote file streams, directories, links and attributes; the API is experimental for now), and SCP uploads and downloads of files, streams and directories, with progress, kept times, and checks that stop a hostile server from writing outside the target.
• Files for the rest of .NET: SshSharp.IO.Abstractions implements System.IO.Abstractions' IFileSystem over SFTP (code written against IFileSystem reads and writes the server unchanged), and SshSharp.FileProviders serves a directory as an IFileProvider, for ASP.NET Core static files, Razor views and configuration; nothing is mounted, so only your application sees the files.
• Observability: ILogger logging, ActivitySource tracing and Meter metrics, with no secrets recorded.

Why not SSH.NET?

SSH.NET is the established .NET SSH library, and for some projects it is the better choice (see below). SshSharp is for applications that should behave like OpenSSH's ssh: connect by ssh_config alias, trust what known_hosts says, sign with the user's agent, hop through jump hosts, and do all of it asynchronously.

Use SSH.NET instead when you need .NET Framework or .NET Standard, a settled (non-experimental) SFTP API, servers that only speak legacy algorithms, or a long track record. Moving from SSH.NET? See the migration guide.

Install

dotnet add package SshSharp
dotnet add package SshSharp.IO.Abstractions # optional: an IFileSystem over SFTP
dotnet add package SshSharp.FileProviders   # optional: an IFileProvider over SFTP

Examples

Connect with a key and verify the host against ~/.ssh/known_hosts:

using SshSharp;
using SshSharp.Config;

using var key = await SshPrivateKey.LoadFileAsync("/home/me/.ssh/id_ed25519");
await using var client = await SshClient.ConnectAsync("example.com", 22, new SshClientOptions
{
    UserName = "deploy",
    PrivateKeys = [key],
    HostKeyVerifier = KnownHostsVerifier.ForCurrentUser(StrictHostKeyChecking.Yes),
});

var result = await client.RunCommandAsync("df -h /");
Console.WriteLine($"exit {result.ExitStatus}: {result.StandardOutputText}");

Stream a long-running command:

await using var session = await client.StartCommandAsync("tail -f /var/log/syslog");
using var reader = new StreamReader(session.StandardOutput);
while (await reader.ReadLineAsync() is { } line)
{
    Console.WriteLine(line);
}

Use the keys in ssh-agent:

var agent = SshAgent.FromEnvironment();
var keys = agent is null ? [] : await agent.GetKeysAsync();

Documentation

zcsizmadia.github.io/SshSharp: the guides below and the full API reference, for the latest release.

• Getting started
• Connecting: TCP, streams, ssh_config aliases, ProxyJump, keep-alive, algorithms
• Authentication: passwords, keys, certificates, the agent, keyboard-interactive
• Host keys: known_hosts, policies, pinning
• Commands and shells
• File transfer (SFTP)
• File transfer (SCP)
• Signing files and commits: SSH signatures (ssh-keygen -Y) and allowed-signers files
• Configuration files
• Errors and diagnostics: exceptions, logging, tracing, metrics
• Migrating from SSH.NET: the same tasks, side by side
• Samples: a small ssh-like tool (commands, streaming, shell, port forwarding, SOCKS, SCP)
• API reference: generated from the XML documentation with DocFX (to build it locally: dotnet tool restore, then dotnet docfx docs/docfx.json --serve); every public member is documented, and IntelliSense shows the same text.
• Design notes, threat model, cryptography review, benchmarks

Building

• .NET SDK 10.0.401 or later (see global.json).
• Build: dotnet build -c Release
• Test (TUnit): dotnet test --project tests/SshSharp.Tests -c Release. Tests against real servers run when SSHSHARP_TEST_SSHD and related variables are set; CI sets them up on Linux, and . ./scripts/test-server.ps1 starts the same server in Docker locally (-Server dropbear for Dropbear, -Stop to remove it).
• Coverage report: ./scripts/coverage.ps1 (target 95%+, not enforced in CI).
• Mutation testing (Stryker.NET, weekly in CI): dotnet tool restore, then in tests/SshSharp.Tests: dotnet stryker --test-runner mtp --project SshSharp.csproj --target-framework net10.0 -m "**/Crypto/X25519.cs".
• Releases: pushing a v* tag on main publishes to nuget.org (.github/workflows/publish.yml).

License

MIT