SshSharp 1.0.0

<img src="https://raw.githubusercontent.com/zcsizmadia/SshSharp/main/assets/logo/sshsharp-512.png" alt="SshSharp logo" width="96">

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: 1.0: the public API follows semantic versioning, so breaking changes wait for a major version. 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, the Windows OpenSSH agent and PuTTY's Pageant), FIDO security keys held by the agent, 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), 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.
• Dependency injection: SshSharp.Extensions.DependencyInjection registers named endpoints from configuration, with a factory for new connections, a shared connection that is opened again when it drops, and a health check.
• 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, 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
dotnet add package SshSharp.Extensions.DependencyInjection # optional: named endpoints, a shared connection, health checks

Examples

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

using SshSharp;
using SshSharp.Config;

using var key = await SshPrivateKey.LoadAsync("/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
• Dependency injection: named endpoints, a shared reconnecting connection, health checks
• Errors and diagnostics: exceptions, logging, tracing, metrics
• Migrating from SSH.NET: the same tasks, side by side
• Samples: an ssh-like tool (commands, streaming, shell, port forwarding, SOCKS, SCP, SFTP, IFileSystem, a Windows CNG key), ASP.NET Core with dependency injection, static files and a health check, and a worker service that survives dropped connections
• 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, testing and validation, threat model, cryptography review, benchmarks

Testing

Every pull request runs about 1,300 unit tests on Linux, Windows and macOS (x64 and Arm64), each on .NET 8 and .NET 10, and the interop tests against real servers: OpenSSH old and new on Linux and Windows, Dropbear, AsyncSSH, Apache MINA SSHD, Erlang/OTP, and SFTP-only servers. The cryptography is checked against reference vectors and about 6,400 Project Wycheproof edge cases. A fault-injection proxy cuts, stalls and slows connections at any point, the parsers are fuzzed nightly, and stress runs loop the whole suite with an instrumented build that catches buffer misuse. Testing and validation has the details, what the testing found, and what is not covered yet.

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