containerssh / containerssh

ContainerSSH: Launch containers on demand

An SSH Server that Launches Containers in Kubernetes and Docker

ContainerSSH in One Minute

In a hurry? This one-minute video explains everything you need to know about ContainerSSH.

Need help?

Join the #containerssh Slack channel on the CNCF Slack »

Use cases

Build a lab

Building a lab environment can be time-consuming. ContainerSSH solves this by providing dynamic SSH access with APIs, automatic cleanup on logout using ephemeral containers, and persistent volumes for storing data. Perfect for vendor and student labs.

Read more »

Debug a production system

Provide production access to your developers, give them their usual tools while logging all changes. Authorize their access and create short-lived credentials for the database using simple webhooks. Clean up the environment on disconnect.

Read more »

Run a honeypot

Study SSH attack patterns up close. Drop attackers safely into network-isolated containers or even virtual machines, and capture their every move using the audit logging ContainerSSH provides. The built-in S3 upload ensures you don't lose your data.

Read more »

How does it work?

1. The user opens an SSH connection to ContainerSSH.
2. ContainerSSH calls the authentication server with the users username and password/pubkey to check if its valid.
3. ContainerSSH calls the config server to obtain backend location and configuration (if configured)
4. ContainerSSH calls the container backend to launch the container with the specified configuration. All input from the user is sent directly to the backend, output from the container is sent to the user.

▶️ Watch as video » | 🚀 Get started »

Demo

🚀 Get started »

Verify provenance

Each of the releases come with a SLSA provenance data file multiple.intoto.jsonl. This file can be used to verify the source and provenance of the produced artifacts with slsa-verifier.

This aims to ensure the users that the artifacts are coming from containerssh.

An example of verification :

slsa-verifier verify-artifact <artifact-to-verify> \
--provenance-path <path-to-your-provenance> \
--source-uri github.com/containerssh/containerssh

If the verification is successful, the process should produce the following output :

Verifying artifact <artifact-to-verify>: PASSED
PASSED: Verified SLSA provenance

Contributing

If you would like to contribute, please check out our Code of Conduct as well as our contribution documentation.

containerssh's Issues

x509-based authentication

Authenticating using x509 certificates like this OpenSSH patch

SSH port forwarding

Implement SSH port forwarding using an in-container agent. Depends on #57

Add support for UDP forwarding

Add support for forwarding UDP connections (this is not standardized in an RFC yet.

Keyboard-interactive authentication

This feature should allow the auth server to perform keyboard-interactive authentication. This will allow the implementation of Single Sign-on with clients that allow clicking links.

Kubernetes backend hangs / exits after 30 seconds

Launch VMs

This feature is an extension of the #65 . The idea is to add the ability to launch VMs in the cloud that we SSH into.

add to all fields a json tag

Please describe what you need help with

this is not a Support request and not a other request, just a nice to have.
I play the first time with the operator-sdk this need by all fields a json tag. By fields not Serializable schould use json:"-"
...

Have you read the readme in its entirety?

yes
...

What have you tried to resolve this problem?

I have begin with add in line https://github.com/ContainerSSH/http/blob/main/client.go#
caCertPool *x509.CertPool `json:"-"`

and when the json tag is by all fields correct I get it work.
...

Quickstart example not working (using Docker Desktop for Mac)

Quickstart example not working (using Docker Desktop for Mac)

Cannot get the Quickstart example working on my Macbook Pro

To Reproduce

1. Installed Docker Desktop Mac, open Terminal
2. mkdir ~/Testing ; git clone https://github.com/ContainerSSH/containerssh.git
3. cd ~/Testing/containerssh/example

docker-compose build

containerssh uses an image, skipping
authconfig uses an image, skipping

docker-compose up

Recreating example_containerssh_1 ... done
Starting example_authconfig_1 ... done
Attaching to example_authconfig_1, example_containerssh_1
authconfig_1 | standard_init_linux.go:211: exec user process caused "no such file or directory"
example_authconfig_1 exited with code 1
containerssh_1 | {"timestamp":"2020-10-23T11:15:29Z","level":"warning","message":"failed to load GeoIP2 database, falling back to dummy provider (open /var/lib/GeoIP/GeoIP2-Country.mmdb: no such file or directory)"}
containerssh_1 | {"timestamp":"2020-10-23T11:15:29Z","level":"info","message":"starting SSH server on 0.0.0.0:2222"}

In a new Terminal: ssh [email protected] -p 2222

[email protected]'s password:
Permission denied, please try again.
[email protected]'s password:
Permission denied, please try again.
[email protected]'s password:
[email protected]: Permission denied (password).

Cannot login, with/without a password.
Same using ssh [email protected] -p 2222

Expected behavior

Some login possible...

Version

git branch

• stable

docker -v

Docker version 19.03.13, build 4484c46d9d

docker-compose -v

docker-compose version 1.27.4, build 40524192

Pass metadata from the auth webhook to the config server

Please describe what you would like to see in ContainerSSH

Most Auth Server allow to return groups or roles to other applications(config server)

Please describe the solution you'd like

The auth server output in the moment is only:
{"success":"true"}

I would like samething like this return value:
{ "success":"true", "groups":["group1","group2"] }

and then as input to the config server:
{ "username":"ssh username", "sessionId": "ssh session ID", "groups":["group1","group2"] }

Please describe your use case

To manage more user I will map/merge the Configuration to Groups(Roles) and not to user, at the moment connect new to a auth server to a custom endpoint or manage user to groups in config server(wrong way).

Implement exec

Currently the "exec" requests to run a specific command are not honored. This should be implemented and the command passed should be forwarded to Docker to be run in the container.

Integration tests

In-Kubernetes authentication and configuration

Please describe what you would like to see in ContainerSSH

ContainerSSH should be able to authenticate directly from Kubernetes secrets and fetch the configuration from Kubernetes configmaps.

Please describe the solution you'd like

Instead of calling out to an auth and configuration server ContainerSSH should be able to look up a secret in Kubernetes based on the username that contains the user's hashed password and/or SSH keys to authenticate them. Conversely, ContainerSSH should be able to look up a configmap to fetch the user-specific configuration.

Please describe your use case

This feature would eliminate the need for an AuthConfig server and would give Kubernetes-native developers an easier tool to manage a user database.

SSH agent forwarding

Implement SSH agent forwarding using an in-container agent. Required #57

Some SSH-related log messages don't contain the connectionId

Affected log messages:

• KUBERNETES_*
• SSH_CHANNEL_REQUEST
• SSH_CHANNEL_REQUEST_SUCCESSFUL

Stopping ContainerSSH does not remove containers

Currently, ContainerSSH cannot reliably remove containers after a crash. ContainerSSH should be able to clean up after itself.

Multi-session containers

Currently, both the dockerrun and the kuberun backend start containers/pods per-session. This allows only for a limited set of SSH features. Users cannot add port forwarding (#58) or SSH agent forwarding (#59), and they cannot run multiple sessions in parallel.

This change aims to add backends that start a container/pod when the first session connects and then uses the exec functionality to attach additional sessions to the same container/pod.

An extended feature would launch an additional container with a specialized agent for forwarding and then use network namespace sharing or volumes to support the features from the outside.

Audit facility

This issue is about an audit facility that captures all user actions and output via SSH in Asciinema or binary formats. See https://containerssh.github.io/advanced/audit/ for details.

Antivirus Backend for file transfers (scp/sftp)

It would be grate if ContainerSSH is able to do an antivirus scan on transferred files.

This could be a implemented as an external webservice.

API Endpoints:

• /sendfile - upload files
• /status/<<SCANTOKEN>> - check status of uploaded files

The path should be configurable.

Each endpoint must return a json object, with status information.

{
    "name": "document.xls", 
    "uploaddate": "2021-02-09 14:09:03",
    "token": "e5f37d22-db11-47d1-945d-9c1b6155dac6",
    "progress": 0,
    "status": "pending"
}

Fields

• name - string - filename
• uploaddate - datetime - date, when the file was uploaded
• token - uuid - unique token for the uploaded file
• progress - int - scan progress 0-100, can be ignored, when no progressbar is used
• status - str - scanstatus

Possible Scan Status Codes:

• clean - file is save
• pending - scan job is running, check again later

if the scan status code is not clean or pending, the file is not save and must not be processed.
This could be an error or a result from a DLP (data loss prevention) System.

Support ECS exec

Support ECS exec on AWS

Documentation update

https://containerssh.io/getting-started/faq/#can-i-use-my-normal-kubeconfig-files

I think this can probably be done by using 'kubectl proxy' and pointing containerssh at the proxy.

Handle flow control requests

RFC4254 Section 6.8 describes how terminal flow control can be used to speed up transfer. Investigate if an implementation is possible, and if yes implement.

Support WebAuthn

As suggested by @vorburger we should support WebAuthn for authentication purposes.

File manager

SFTP-based web file manager.

Add imagePullPolicy to dockerrun backend

Currently the dockerrun backend always pulls the image before shell start, which makes shell and program start slow. Implement an imagePullPolicy similar to Kubernetes to avoid pulling images unnecessarily.

https problem connect with own auth server

Please describe what you need help with

My repository is https://github.com/patsys/containerSSH/tree/develop use version 4.0.0-RC3

I get a connection error from the ContianerSSH to my auth server with a selfsigned Certificate.

ContainerSSH print:
{"timestamp":"2021-02-23T01:18:50+01:00","level":"warning","module":"ssh","details":"authentication backend currently unavailable (failed on HTTP request)"} {"timestamp":"2021-02-23T01:18:50+01:00","level":"warning","module":"ssh","details":"authentication backend currently unavailable (keyboard-interactive authentication not available)"}

My auth server print:
2021/02/23 01:18:50 http: TLS handshake error from [::1]:35972: remote error: tls: bad certificate

Curl work correct from authServer dir:
curl --key example/clientCert1/client.key --cert example/clientCert1/client.crt --cacert example/server/server_cert.pem -L https://localhost:8081/password -d '{"username":"user1","passwordBase64":"dGVzdA==", "remoteAddress": "10.5.4.12"}'

...

Have you read the readme in its entirety?

Yes
...

What have you tried to resolve this problem?

• Set log in ContainerSSH to debug
• Use Main Branch
• Remove client cert form ContainerSSH config
• Change file reference to cert content
• Clone ContainerSSH/http and add debug Infromations
  ...

auth server use the '-config' flag and in the authServer/example folder is the used config

Configurable logging

Make logging configurable. Log levels can be configured from the main configuration file or the configuration file:

log:
  level: "debug"

Details: https://projects.pasztor.at/containerssh/logging/

Switching code license to MIT-0

Hello everyone,

I'm proposing to switch to the MIT-0 license. This would remove the requirement to distribute the license with the source code or attribute us as the source of the code.

This would make it easier for others to take parts of the ContainerSSH code and reuse it in other projects.

What this would not affect:

• The built ContainerSSH binaries (they contain source code from various projects, so licenses are still required)
• The documentation (up for separate discussion)
• The ContainerSSH name, logos and assets (subject to the brand license in the branding repo

Are all the following contributors OK with the move? If yes please comment +1 below.

• @ecrazor1911
• @mhmxs
• @sanjabonic

SSH Key not supported by Auth

Please describe what you need help with

By Key auth I get an Error from Contianerssh, password login work correct:
{"timestamp":"2021-02-25T03:58:30+01:00","level":"warning","module":"ssh","details":"authentication backend currently unavailable (the backend handler does not support authentication)"} {"timestamp":"2021-02-25T03:58:30+01:00","level":"warning","module":"ssh","details":"authentication backend currently unavailable (keyboard-interactive authentication not available)"}

I use Version 0.4.0-RC3 mit auth v0.9.3 Library

ContainerSSH is Config can found in https://github.com/patsys/containerSSH/blob/develop/example/config.yml
...

Have you read the readme in its entirety?

Yes

...

What have you tried to resolve this problem?

• ContainerSSH log to debug level
• Check auth server work correct
  • Curl request return {"success":true}
  • Add Debug output
    ...

SSH proxy backend

The SSH proxy backend should forward SSH connections to a backend SSH server.

OpenAPI

Implement OpenAPI documentation generation.

Kubernetes backend does not display initial prompt

Currently when connecting ContainerSSH with the kuberun backend the initial prompt is not displayed. This may not be fixable as the Kubernetes attach API does not have an option to list output that happened before the attach process. (In contrast to the Docker API.)

Support Gitlab CI runners

Currently, ContainerSSH launches a new container for every connection. It was requested that we support Gitlab CI which opens a new connection for every command. It is possible to identify the connections via the environment variables CI_JOB_ID, CI_JOB_TOKEN, CI_PIPELINE_ID, or CI_JOB_IMAGE. The container should be cleaned up after it hasn't been used for a while.

Option to disable Exec Requests

An option to disable or block "Exec Requests" would be great, as this would allow additional use cases, where a user is forced into a "command" / shell(Entrypoint) and can´t escape it.
Currently it is possible to bypass any Entrypoint using ssh -f 'command'.

Auth client does not send connectionId

It seems that in 0.4.0-PR4 the authentication client does not correctly send the connectionId field, it sends an empty string.

Container configuration

Currently the container parameters are hard-coded. This should be changed such that default values can be passed from the command line, but an also be overridden by the authentication server on a per-user basis.

Specific settings that should be supported for Docker:

• Container image
• Host name
• Domain name
• Default shell
• Network disabled
• Resource limits
• Networks to attach and their configuration
• Volume mounts
• User/group to run as

Better documentation would be nice.

Please describe what you would like to see in ContainerSSH

First of all, this is a really cool and very intriguing project. That being said, I would love to see a much better documentation.

Please describe the solution you'd like

Let me give you two examples.

Under https://github.com/ContainerSSH/ContainerSSH/blob/main/example/Dockerfile it says

# Added ONLY for permission reasons. Don't use in production.
USER 0

Could you elaborate? Why is it necessary to set USER to 0? What do you put in the Dockerfile in case of a production setup? If a service can run without privileges why don't you use USER to change to a non-root user?

Under https://github.com/ContainerSSH/auditlog/blob/main/README.md it says

This section will explain how to set up and use a logging pipeline. As a first step, you must create the logger. The easiest way to do that is to pass a config object.

Is the following part of the code? Code in which of the go sources? Isn't configuration usually done with the help of config files? Do I have to compile a new containerssh-testauthconfigserver each time I would like to change something in the configuration?

Please describe your use case

I would like to test and deploy a containerssh-honeypot with asciinema logging enabled. Got the example running with the 0.4.0-PR3 versions of containerssh/containerssh and containerssh/containerssh-test-authconfig, but due to only superfical knowledge of the go-lang I'm having a hard time setting up a logging pipe.

Kerberos/GSS-API authentication

Licenses

Add an option to display third party licenses for binary & container builds

Unsupported MAC and Kex configuration causes crash

Supplying unsupported MAC or Kex configuration causes a crash due to golang/go#39397 .

Implement Kubernetes backend

Implement a Kubernetes backend that launches (and destroys) pods.

Release management

Provide binary releases

PAM authentication

Authenticate against Linux PAM.

Implement SFTP

SFTP subsystem calls are not implemented. Depends on #3

Containerized release

Provide a containerized release for easy access

Rename "user" to "username" in authentication requests

Currently the post request contains:

{
    "**user**": "username",
    "remoteAddress": "127.0.0.1:1234",
    "sessionId": "A base64 SSH session ID",
    "passwordBase64": "Base 64 password"
}

{
  "**username**":"ssh username",
  "sessionId": "ssh session ID"
}

I would suggest to either use username or user, to avoid confusion.

Web client

This feature will create a web interface that will allow authentication via username and password, and offer a TTY functionality in the browser using websockets.

Internally, this feature will not use SSH, instead it will talk to the container backend directly.

Direct shell backend

We may want to consider creating a direct-shell backend that creates a shell on the host machine directly.

missing permission in entrypoint

To Reproduce

If you can please provide the steps to reproduce the issue.

1. Clone containerssh git repo
2. Navigate to examples/quick-start
3. Follow the instructions
4. When performing docker-compose up -d the error occurs
   -->

Creating network "example_default" with the default driver
Creating example_authconfig_1   ... done
Creating example_containerssh_1 ... error

ERROR: for example_containerssh_1  Cannot start service containerssh: OCI runtime create failed: container_linux.go:349: starting container process caused "exec: \"/containerssh\": permission denied": unknown

ERROR: for containerssh  Cannot start service containerssh: OCI runtime create failed: container_linux.go:349: starting container process caused "exec: \"/containerssh\": permission denied": unknown
ERROR: Encountered errors while bringing up the project.

Expected behavior

containerssh container is getting created and is able to start

Fix

inside the image, the "containerssh" file which is the entrypoint does not have execution permission. Fix: add a RUN command in dockerfile to set the permission: chmod +x containerssh

Monitoring

Expose Prometheus metrics:

• Currently connected users
• Total connections since start
• Successful authentications since start
• Failed authentications since start
• Successful/failed authentications by country (GeoIP lookup?) since start
• Authentication backend failures
• Configuration backend failures
• Dockerrun backend failures
• Kuberun backend failures

Raise error on invalid configuration

Currently if you provide an invalid config (but valid json) the service just accepts that config and ignores it.

It would be great to have some feedback if you specify non existing keys, for example if you miss a certain config hierarchy (like "kuberun":) the whole config is ignored.