Simplemath & Failtoban Plugins
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
In the sshpiper architecture, plugins are categorized by their function: routing plugins (🔀), additional challenge plugins (🔒), and metrics plugins (📈). The Simplemath and Failtoban plugins belong to the "additional challenge" category. These plugins do not handle the final routing to an upstream server themselves; instead, they provide secondary authentication or security layers that must be successfully navigated before a routing plugin establishes the connection.
Sources: README.md:12-16, README.md:125-144, plugin/simplemath/README.md:5-7
These plugins operate as gRPC servers, typically communicating with the main sshpiperd daemon via stdin/stdout. They are designed to be "chained" together using the -- separator in the command line, allowing sshpiperd to execute multiple security checks in sequence.
Sources: CONTRIBUTING.md:76-80, cmd/sshpiperd/internal/plugin/chain.go:13-25, plugin/simplemath/README.md:9-11
Simplemath Plugin
The Simplemath plugin serves as a demonstration of the "additional challenge" capability. It forces the downstream user to solve a basic arithmetic addition problem before the login process can proceed to the next plugin in the chain.
Sources: plugin/simplemath/main.go:17-19, plugin/simplemath/README.md:1-3
Architecture and Logic
The plugin utilizes the KeyboardInteractiveCallback to interact with the SSH client. It generates two random integers between 0 and 9 and presents a question to the user. The connection only proceeds if the user provides the correct sum.
| Component | Description |
|---|---|
| Challenge Prompt | Sends "lets do math" followed by "what is [a] + [b] = " |
| Random Generator | Uses rand.Intn(10) to create variables a and b |
| Verification | Compares user input ans against the string representation of a + b |
| Plugin Auth | On success, returns libplugin.CreateNextPluginAuth with metadata |
Sources: plugin/simplemath/main.go:21-48
Sequence of Operation
The following diagram illustrates the interaction between sshpiperd, the Simplemath plugin, and the downstream client.
Failtoban Plugin
The Failtoban plugin is an additional challenge plugin (🔒) designed to enhance security by banning IP addresses that exceed a defined threshold of failed login attempts. Like Simplemath, it is intended to be used at the beginning of a plugin chain.
Sources: README.md:141
Functional Overview
While the specific implementation details for the Failtoban plugin are abstracted through the plugin gRPC interface, its role within the system is defined by its interaction with the UpstreamAuthFailureNotice and NewConnection RPC calls.
- New Connection: Checks if the source IP is currently in the ban list.
- Auth Failure: Increments the failure count for a specific source IP when notified by
sshpiperdthat an upstream authentication attempt failed. - Banning: Once a threshold is reached, subsequent connections from that IP are rejected during the
NewConnectionphase.
Sources: libplugin/plugin.proto:46-47, libplugin/plugin.proto:132-137, README.md:141
Plugin Chaining Mechanism
The ability for Simplemath and Failtoban to function depends on the ChainPlugins logic within sshpiperd. This mechanism allows metadata to be passed between plugins via UpstreamNextPluginAuth.
Sources: cmd/sshpiperd/internal/plugin/chain.go:13-25
Data Flow in Chained Execution
When a plugin like Simplemath finishes, it returns a NextPluginAuth object. This triggers sshpiperd to move to the next plugin configured in the command line arguments.
Key Data Structures
The communication between the daemon and these plugins is governed by the libplugin protobuf definitions.
| Structure | Field | Description |
|---|---|---|
ConnMeta | from_addr | Used by Failtoban to track source IPs |
Upstream | next_plugin | Returned by challenge plugins to signal success |
UpstreamNextPluginAuth | meta | Map used to pass challenge results to the next plugin |
Sources: libplugin/plugin.proto:7-12, libplugin/plugin.proto:36-39, libplugin/plugin.proto:56-58
Usage and Deployment
To deploy these plugins, they must be specified before the routing plugin in the sshpiperd execution command. The -- symbol is used to separate the configurations for different plugins.
Example Commands
Simplemath Demo:
sshpiperd simplemath -- fixed --target 127.0.0.1:5522
Sources: plugin/simplemath/README.md:9-11
Failtoban and Math:
sshpiperd failtoban -- simplemath -- fixed --target 127.0.0.1:5522
Sources: README.md:78-83, README.md:141
Conclusion
The Simplemath and Failtoban plugins exemplify the extensibility of sshpiper. By leveraging the gRPC-based plugin architecture and the internal chaining mechanism, these modules provide flexible security layers. Simplemath demonstrates the interactive capabilities of the KeyboardInteractiveAuth flow, while Failtoban provides a critical security measure by monitoring and acting upon authentication failure notices across the plugin chain.
Sources: CONTRIBUTING.md:76-80, cmd/sshpiperd/internal/plugin/chain.go:94-118