README
¶
RCE Agent
rce-agent is a gRPC-based Remote Command Execution (RCE) client and server. The server (or "agent") runs on a remote host and executes a whitelist of shell commands specified in a file. The client calls the agent to execute whitelist commands. TLS is used to secure and authenticate both client and server.
rce-agent replaces SSH and other methods of remote code execution. There are no passwords—only TLS certificates—and commands are limited to a whitelist. This eliminates the need for SSH keys, passwords, or forwarding.
This package is meant to be integrated into your code. The rce.Client and rce.Server objects do all the heavy lifting
so your client and agent code can focus on their domain-specific logic. See example/ for example code.
RCE Agent is also meant to be used with your private certificate authority (CA) for TLS-encrypted
communication and mutual authentication of client and agent.
(Setting up a private CA is beyond the scope of this project, but we highly suggest you use one!)
Normally, only the client verifies the server's TLS certificate (cert). For additional security,
your code should use rce.TLSFiles
to create Go tls.Config which makes the server (agent) verify the client's cert, too.
Documentation
¶
Overview ¶
Package rce provides a gRPC-based Remote Code Execution client and server. The server (or "agent") runs on a remote host and executes a whitelist of shell commands specified in a config file. The client calls the server to execute whitelist commands. Commands from different clients run concurrently; there are no safeguards against conflicting or incompatible commands.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ConnectTimeout describes the total timeout for establishing a client // connection to the rceagent server. ConnectTimeout = time.Duration(10) * time.Second // ConnectBackoffMaxDelay configures the dialer to use the // provided maximum delay when backing off after // failed connection attempts. ConnectBackoffMaxDelay = time.Duration(2) * time.Second // KeepaliveTime is the interval at which the client sends keepalive // probes to the server. KeepaliveTime = time.Duration(30) * time.Second // KeepaliveTimeout is the amount of time the client waits to receive // a response from the server after a keepalive probe. KeepaliveTimeout = time.Duration(20) * time.Second )
var ( // ErrInvalidServerConfigAllowAnyCommand is returned by Server.StartServer() when // ServerConfig.AllowAnyCommand is true but ServerConfig.AllowedCommands is non-nil. ErrInvalidServerConfigAllowAnyCommand = errors.New("invalid ServerConfig: AllowAnyCommand is true but AllowedCommands is non-nil") // ErrInvalidServerConfigDisableSecurity is returned by Server.StartServer() // when ServerConfig.AllowAnyCommand is true and ServerConfig.TLS is nil but // ServerConfig.DisableSecurity is false. ErrInvalidServerConfigDisableSecurity = errors.New("invalid ServerConfig: AllowAnyCommand enabled but TLS is nil") // ErrCommandNotAllowed is safeguard error returned by the internal gRPC server when // ServerConfig.AllowedCommands is nil and ServerConfig.AllowAnyCommand is false. // This should not happen because these values are validated in Server.StartServer() // before starting the internal gRPC server. If this error occurs, there is a bug // in ServerConfig validation code. ErrCommandNotAllowed = errors.New("command not allowed") )
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
// Connect to a remote agent.
Open(host, port string) error
// Close connection to a remote agent.
Close() error
// Return hostname and port of remote agent, if connected.
AgentAddr() (string, string)
// Start a command on the remote agent. Must be connected first by calling
// Connect. This call is non-blocking. It returns the ID of the command or
// an error.
Start(cmdName string, args []string) (id string, err error)
// Wait for a command on the remote agent. This call blocks until the command
// completes. It returns the final statue of the command or an error.
Wait(id string) (*pb.Status, error)
// Get the status of a running command. This is safe to call by multiple
// goroutines. ErrNotFound is returned if Wait or Stop has already been
// called.
GetStatus(id string) (*pb.Status, error)
// Stop a running command. ErrNotFound is returne if Wait or Stop has already
// been called.
Stop(id string) error
// Return a list of all running command IDs.
Running() ([]string, error)
}
A Client calls a remote agent (server) to execute commands.
type Server ¶
type Server interface {
// Start the gRPC server, non-blocking.
StartServer() error
// Stop the gRPC server gracefully.
StopServer() error
pb.RCEAgentServer
}
A Server executes a whitelist of commands when called by clients.
func NewServer ¶
NewServer makes a new Server that listens on laddr and runs the whitelist of commands. If tlsConfig is nil, the sever is insecure.
func NewServerWithConfig ¶ added in v1.1.0
func NewServerWithConfig(cfg ServerConfig) Server
type ServerConfig ¶ added in v1.1.0
type ServerConfig struct {
// Addr is the required host:post listen address.
Addr string
// AllowedCommands is the list of commands the server is allowed to run.
// By default, no commands are allowed; commands must be explicitly allowed.
AllowedCommands cmd.Runnable
// AllowAnyCommand allows any commands if AllowedCommands is nil.
// This is not recommended. If true, TLS must be specified (non-nil);
// or, to enable AllowAnyCommand without TLS, DisableSecurity must be true.
AllowAnyCommand bool
// DisableSecurity allows AllowAnyCommand without TLS: an insecure server that
// can execute any command from any client.
//
// This option should not be used.
DisableSecurity bool
// TLS specifies the TLS configuration for secure and verified communication.
// Use TLSFiles.TLSConfig() to load TLS files and configure for server and
// client verification.
TLS *tls.Config
}
ServerConfig configures a Server.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd provides command file specs and structures used by an rce.Server.
|
Package cmd provides command file specs and structures used by an rce.Server. |
|
example
|
|
|
Package rce is a generated protocol buffer package.
|
Package rce is a generated protocol buffer package. |