Build Status Coverage Status

sshd-shell-spring-boot

This artifact is a spring boot starter that provides SSH access to spring boot applications. It is primarily designed for developers who want to roll out custom shell commands for various purposes.

The motivation for this starter was due to the fact that spring-boot had officially dropped support for spring-boot-starter-remote-shell for the 2.x versions.

This starter has been tested with spring-boot 2.0.x to 2.2.x releases with support for its new endpoint infrastructure.

To import into Maven project, add the following dependency inside pom.xml:

<dependency>
    <groupId>io.github.anand1st</groupId>
    <artifactId>sshd-shell-spring-boot-starter</artifactId>
    <version>4.1</version>
</dependency>

For Gradle users, add these lines inside build.gradle:

dependencies {
    compile group: 'io.github.anand1st', name: 'sshd-shell-spring-boot-starter', version: '4.1'
}

Note

Versions < 2.1 are deprecated and unsupported. The artifact above supports the following functionalities:

Version 4.1

Supports Spring Boot 2.2.x versions. Updated dependencies to jline 3.13.1, Apache SSHD 2.3.0. Additional system commands for the following endpoints i.e. Flyway, IntegrationGraph, Liquibase, Sessions, Logfile and Prometheus:

sshd.system.command.roles.flyway=${sshd.system.command.roles}
sshd.system.command.roles.integrationGraph=${sshd.system.command.roles}
sshd.system.command.roles.liquibase=${sshd.system.command.roles}
sshd.system.command.roles.sessions=${sshd.system.command.roles}
sshd.system.command.roles.logfile=${sshd.system.command.roles}
sshd.system.command.roles.prometheus=${sshd.system.command.roles}

Version 4.0

Updated dependencies to jline 3.11.0. One of the biggest 'noise' of this library was the various management commands that were visible to all users. Version 4.0 introduces some properties to help manage these commands (hereby called system commands).

sshd.system.command.roles=ADMIN #Defaults to ADMIN, use comms-separated values for multiple admin roles
sshd.system.command.roles.auditEvents=${sshd.system.command.roles}
sshd.system.command.roles.beans=${sshd.system.command.roles}
sshd.system.command.roles.caches=${sshd.system.command.roles}
sshd.system.command.roles.conditionsReport=${sshd.system.command.roles}
sshd.system.command.roles.configurationPropertiesReport=${sshd.system.command.roles}
sshd.system.command.roles.environment=${sshd.system.command.roles}
sshd.system.command.roles.health=${sshd.system.command.roles}
sshd.system.command.roles.heapDump=${sshd.system.command.roles}
sshd.system.command.roles.httpTrace=${sshd.system.command.roles}
sshd.system.command.roles.info=${sshd.system.command.roles}
sshd.system.command.roles.loggers=${sshd.system.command.roles}
sshd.system.command.roles.mappings=${sshd.system.command.roles}
sshd.system.command.roles.metrics=${sshd.system.command.roles}
sshd.system.command.roles.scheduledTasks=${sshd.system.command.roles}
sshd.system.command.roles.shutdown=${sshd.system.command.roles}
sshd.system.command.roles.threadDump=${sshd.system.command.roles}

The user just need to set the sshd.system.command.roles to an admin role or to * if any authenticated user should be able to have access to these commands. For individual configuration of management endpoints, setting the roles in the above system command properties manually should suffice. Please note that these changes may affect the functionality in previous versions of this library. Sufficient testing with this version is recommended.

Version 3.7

Running with latest jline 3.10.0 and Apache SSHD version 2.2.0 and some code refactoring and cleanup. Fixed bug with exception handling of ShellException and IllegalArgumentException in methods with SshdShellCommand annotation. These exceptions can now be safely thrown and handled correctly by the CommandExecutor. Other exceptions are considered unexpected and will result in a error log.

Version 3.6

Getting a user's root directory for the purposes of SCP/SFTP is now made easier with the following approach:

SshSessionContext.getUserDir()

Upgraded jline to 3.9.0 and Apache SSHD version to 2.0.0. heapDump command now zips the dump and places it into the session user's directory if SCP/SFTP is enabled so that it can be downloaded.

Version 3.5

Modified SshdShellProperties to add the properties

sshd.filetransfer.enabled
sshd.filesystem.base.dir

Added also username into SshSessionContext that can be accessed via

SshSessionContext.get(Constants.USER)

With these changes, one can now figure out the rooted filesystem for a session user by autowiring SshdShellProperties into the custom command classes to access the sshd.filesystem.base.dir property and by the session username.

Version 3.4

Support for SFTP and SCP with configurable Root File System. Upgraded jline to 3.7.0. See Usage section below for properties to be set. Tested with OSX only. Usage:

sftp -P 8022 [email protected]
scp -P 8022 <localFile> [email protected]:<filename>

Version 3.3

Adheres to the management enabled endpoint for actuators. If the endpoint is enabled/disabled, the ssh command likewise is enabled/disabled according to this setting.

Version 3.2.1

Support for spring boot 2.0.0.RC1, 2.0.0.RC2 and 2.0.0.RELEASE. Upgraded to jline 3.6.0 and sshd-core 1.7.0. Minor code fixes and refactorings.

Please do not use version 3.2 as there seems to be some Jackson incompatibilities on Linux. Version 3.2.1 fixes

these issues.

Version 3.1

Added support for SSH exec in addition to SSH shell.

Version 3.0

Only for spring boot versions 2.0.0.M4 and (hopefully) above. Added support for spring boot 2.0.0.M4 endpoint infrastructure which is very different from versions below this.

Version 2.5

Supports spring boot versions from 1.5.x till 2.0.0.M3 (tested for these versions only). Upgraded to jline-3.5.1. Added support for highlighting of response output based on searched text using postprocessors (highlighting tested on OSX). Added support for the emailing response output using postprocessors. Examples of post processors can be seen below.

Version 2.4

Upgraded to jline-3.4.0. Refactored I/O related activity from SshSessionContext to ConsoleIO. Separated console processing into separate packages from SSH server packages.

Version 2.3

Support for auto-completion of commands and subcommands using tab.

Version 2.2

Fixed bug with prompt & text color.

Version 2.1

Support for role-based access control using spring-security's AuthenticationProvider bean. SshdShellCommand annotation includes a 'roles' parameter (defaults to * denoting permission to all commands) which should use spring-security's role tag if sshd.shell.authType=AUTH_PROVIDER and spring-security is in the classpath. If a user's role matches the roles in the command classes, he/she should be able to execute the command.

Every user session has a session context which a developer can use to manage state between command invocations

Usage

All the developer needs to do it to create a class similar to below and make sure it's loaded by the Application Context:

@Component
@SshdShellCommand(value = "echo", description = "Echo by users. Type 'echo help' for supported subcommands")
public class EchoCommand {

    @SshdShellCommand(value = "bob", description = "Bob's echo. Usage: echo bob <arg>")
    public String bobSays(String arg) throws IOException {
        ConsoleIO.writeOutput("Need user info");
        String name = ConsoleIO.readInput("What's your name?");
        SshSessionContext.put("name", name);
        return "bob echoes " + arg + " and your name is " + name;
    }

    @SshdShellCommand(value = "alice", description = "Alice's echo. Usage: echo alice <arg>")
    public String aliceSays(String arg) {
        String str = "";
        if (SshSessionContext.containsKey("name")) {
            str = ", Name " + SshSessionContext.get("name") + " exists";
        }
        return "alice says " + arg + str;
    }

    @SshdShellCommand(value = "admin", description = "Admin's echo. Usage: echo admin <arg>", roles = "ADMIN")
    public String adminSays(String arg) {
        return "admin says " + arg;
    }
}

Supported properties in application.properties (defaults are as below):

sshd.shell.port=8022            #Set to 0 for random port
sshd.shell.enabled=false        #Set this to true to startup SSH daemon
sshd.shell.username=admin
sshd.shell.password=            #A random string is generated if password is not set and shown in logs
sshd.shell.publicKeyFile=
sshd.shell.host=127.0.0.1       #Allowed IP addresses
sshd.shell.hostKeyFile=hostKey.ser
sshd.shell.prompt.title=app

# Supported values for colors: BLACK,RED,GREEN,YELLOW,BLUE,MAGENTA,CYAN,WHITE (leave blank for default)
sshd.shell.prompt.color=           # Defaults to BLACK
sshd.shell.text.color=             # Defaults to BLACK
sshd.shell.text.highlightColor=    # Defaults to YELLOW
sshd.shell.auth.authType=SIMPLE     # Possible values: SIMPLE, AUTH_PROVIDER
sshd.shell.auth.authProviderBeanName=   # Bean name of authentication provider if authType is AUTH_PROVIDER (optional)
sshd.filetransfer.enabled=true          # Defaults to false. Must be enabled for SCP and SFTP functionality
sshd.filesystem.base.dir=/home/app      # Defaults to 'user.home' property

To connect to the application's SSH daemon (the port number can found from the logs when application starts up):

ssh -p <port> <username>@<host>

If public key file is used for SSH daemon:

ssh -p <port> -i <privateKeyFile> <username>@<host>

The following are sample inputs/outputs from the shell command if an admin user logs in:

app> help
Supported Commands
admin                              Admin functionality. Type 'admin' for supported subcommands
beans                              List beans
caches                             Caches info
conditionsReport                   Conditions report
configurationPropertiesReport      Configuration properties report
echo                               Echo by users. Type 'echo' for supported subcommands
environment                        Environment details
exit                               Exit shell
flyway                             Flyway database migration details (if applicable)
health                             System health info
heapDump                           Heap dump command
help                               Show list of help commands
info                               System status
integrationGraph                   Information about Spring Integration graph
liquibase                          Liquibase database migration details (if applicable)
logfile                            Application log file
loggers                            Logging configuration
mappings                           List http request mappings
metrics                            Metrics operations
prometheus                         Produces formatted metrics for scraping by Prometheus server
scheduledTasks                     Scheduled tasks
sessions                           Sessions management
shutdown                           Shutdown application
threadDump                         Print thread dump
Supported post processors for output
h <arg>                            Highlights <arg> in response output of command execution
                                   Example usage: help | h exit
m <emailId>                        Send response output of command execution to <emailId>
                                   Example usage: help | m [email protected]
app> echo
Supported subcommand for echo
admin                              Admin's echo. Usage: echo admin <arg>
alice                              Alice's echo. Usage: echo alice <arg>
bob                                Bob's echo. Usage: echo bob <arg>
app> echo alice hi
alice says hi
app> echo alice hi | h alice
alice says hi             ### alice is highlighted in yellow but colors can't be shown on markdown :-)
app> echo alice hi | m [email protected]
Output response sent to [email protected]
app> echo bob hi
What's your name? Jake
bob echoes hi and your name is Jake, rooted filesystem path is /Users/user/admin
app> echo alice hi
alice says hi, Name Jake exists
app> admin manage bob
bob has been managed by admin

For a non-admin user, the following is seen in the help and echo subcommand as per settings of roles in the annotation:

app> help
Supported Commands
echo                               Echo by users. Type 'echo' for supported subcommands
exit                               Exit shell
help                               Show list of help commands
Supported post processors for output
h <arg>                            Highlights <arg> in response output of command execution
                                   Example usage: help | h exit
m <emailId>                        Send response output of command execution to <emailId>
                                   Example usage: help | m [email protected]
server> echo
Supported subcommand for echo
alice                              Alice's echo. Usage: echo alice <arg>
bob                                Bob's echo. Usage: echo bob <arg>
app> admin manage Bob
Permission denied
app> exit
Exiting shell

For more information, check out the sshd-shell-spring-boot-test-app project for a fully working example.

Limitations: 1) Currently, every method must return a java.lang.String (shell output) and take in exactly one java.lang.String parameter. This parameter can be null at runtime. 2) Requires minimum JDK 8.