Snowflake-Labs/sansshell

Snowflake-Labs/sansshell

Description: A non-interactive daemon for host management

Language: Go

License: Apache-2.0

Stars: 122

Forks: 17

Open issues: 25

Created: 2021-09-29T14:35:03Z

Pushed: 2026-05-04T11:42:51Z

Default branch: main

Fork: no

Archived: no

README:

SansShell

  

A secure, non-interactive daemon for remote host management and debugging

SansShell is a powerful remote host management system built on gRPC that provides a secure alternative to traditional SSH-based administration. It offers fine-grained access control, comprehensive auditing, and policy-based authorization for critical system operations.

flowchart LR;

subgraph sanssh ["sansshell client (sanssh)"]
cli;
client;
subgraph client modules
package([package]);
file([file]);
exec([exec]);
end
cli --> package --> client;
cli --> file --> client;
cli --> exec --> client;
end
subgraph proxy ["proxy (optional)"]
proxy_server[proxy-server];
opa_policy[(opa policy)];
proxy_server --> opa_policy --> proxy_server
end
subgraph sansshell server ["sansshell server (on each host)"]
server[sansshell-server];
host_apis;
s_opa_policy[(opa policy)];
subgraph service modules
s_package([package]);
s_file([file]);
s_exec([exec]);
end
server --> s_package --> host_apis;
server --> s_file --> host_apis;
server --> s_exec --> host_apis;
server --> s_opa_policy --> server
end
user{user};
user --> cli;
client --"gRPC (mTLS)"--> proxy_server
proxy_server --"grpc (mTLS)"---> server

Overview

SansShell is a modern host management platform that replaces traditional interactive shell access with a secure, auditable, and policy-driven approach. Built entirely on gRPC, it provides:

• Security First: mTLS encryption, certificate-based authentication, and OPA policy enforcement
• Fine-grained Authorization: Every operation can be evaluated against custom policies
• Comprehensive Auditing: All actions are logged and traceable
• Deterministic Operations: Reproducible results for a given system state
• Zero Trust Architecture: No persistent shell access or elevated privileges required

Core Components

SansShell Server (`sansshell-server`): A non-interactive daemon that runs on managed hosts, exposing secure gRPC services for system operations.

SansShell Client (`sanssh`): A CLI tool that provides both user-friendly commands and direct access to all gRPC endpoints.

Proxy Server (`proxy-server`) *(Optional)*: A centralized gateway that enables:

• Request fan-out to multiple hosts
• Centralized policy enforcement
• Network connectivity bridging
• Enhanced logging and monitoring

Getting Started

Prerequisites

• Go 1.21+ (check go.mod for exact version requirements)
• Protocol Buffers compiler (protoc) version 3+
• TLS certificates for mTLS authentication

Quick Start

1. Set up certificates (for development/testing):

cp -r auth/mtls/testdata ~/.sansshell

2. Run the server:

go run ./cmd/sansshell-server

3. Test with the client:

go run ./cmd/sanssh --targets=localhost file read /etc/hosts

Full Proxy Setup

For production-like testing with the proxy:

# Terminal 1: Start the server
go run ./cmd/sansshell-server

# Terminal 2: Start the proxy
go run ./cmd/proxy-server

# Terminal 3: Use client through proxy
go run ./cmd/sanssh --proxy=localhost:50043 --targets=localhost:50042 file read /etc/hosts

Monitoring and Debugging

• Server Debug UI: http://localhost:50044
• Proxy Debug UI: http://localhost:50046
• Metrics Endpoint: http://localhost:50047 (server), http://localhost:50046 (proxy)

Environment setup : protoc

When making any change to the protocol buffers, you'll also need the protocol buffer compiler (protoc) (version 3 or above) as well as the protoc plugins for Go and Go-GRPC

On MacOS, the protocol buffer can be installed via homebrew using

brew install protobuf

On Linux, protoc can be installed using either the OS package manager, or by directly installing a release version from the [protocol buffers github][1]

Environment setup : protoc plugins

On any platform, once protoc has been installed, you can install the required code generation plugins using go install.

$ go install google.golang.org/protobuf/cmd/protoc-gen-go
$ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc
$ go install github.com/Snowflake-Labs/sansshell/proxy/protoc-gen-go-grpcproxy

Note that, you'll need to make certain that your PATH includes the gobinary directory (either the value of $GOBIN, or, if unset, $HOME/go/bin)

The tools.go file contains helpful go generate directives which will do this for you, as well as re-generating the service proto files.

$ go generate tools.go

Dev Environment setup

Required tools

• pre-commit 3.8.0+
• golangci-lint 1.59.1+

Configuration:

• Set up git pre-commit hooks

pre-commit install

Creating your own certificates

As an alternative to copying auth/mtls/testdata, you can create your own example mTLS certs. See the [mtls testdata readme](/auth/mtls/testdata/README.md) for steps.

Debugging

Reflection is included in the RPC servers (proxy and sansshell-server) allowing for the use of grpc_cli.

If you are using the certificates from above in ~/.sansshell invoking grpc_cli requires some additional flags for local testing:

$ GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=$HOME/.sansshell/root.pem grpc_cli \
--ssl_client_key=$HOME/.sansshell/client.key --ssl_client_cert=$HOME/.sansshell/client.pem \
--ssl_target=127.0.0.1 --channel_creds_type=ssl ls 127.0.0.1:50043

NOTE: This connects to the proxy. Change to 50042 if you want to connect to the sansshell-server.

Testing

To run unit tests, run the following…