Home

Awesome

ssh-hardening (Chef cookbook)

Supermarket Build Status Code Coverage Gitter Chat

Description

This cookbook provides secure ssh-client and ssh-server configurations. This cookbook does not provide capabilities for management of users and/or ssh keys, please use other cookbooks for that.

Requirements

Platform

Attributes

Below you can find the attribute documentation and their default values.

Notice: Some of attribute defaults of this cookbook are set in the recipes. You should use a higher attribute precedence level for overriding of such attributes. Such attributes are flagged with #override attribute# in the list below. Example for overriding a such attribute:

override['ssh-hardening']['ssh']['server']['listen_to'] = node['ipaddress']

Usage

Add the recipes to the run_list:

"recipe[ssh-hardening]"

This will install ssh-server and ssh-client. You can alternatively choose only one via:

"recipe[ssh-hardening::server]"
"recipe[ssh-hardening::client]"

Configure attributes:

"ssh-hardening": {
  "ssh" : {
    "server" : {
      "listen_to" : "10.2.3.4"
    }
  }
}

The default value for listen_to is 0.0.0.0. It is highly recommended to change the value.

SFTP

To enable the SFTP configuration add one of the following recipes to the run_list:

"recipe[ssh-hardening]"
or
"recipe[ssh-hardening::server]"

Configure attributes:

"ssh-hardening": {
  "ssh" : {
    "server": {
      "sftp" : {
      "enable" : true,
      "chroot" : "/home/sftp/%u",
      "group"  : "sftusers"
    }
    }
  }
}

This will enable the SFTP Server and chroot every user in the sftpusers group to the /home/sftp/%u directory.

Extra Configuration Options

Extra configuration options can be appended to the client or server configuration files. This can be used to override statically set values, or add configuration options not otherwise available via attributes.

The syntax is as follows:

# => Extra Server Configuration
default['ssh-hardening']['ssh']['server']['extras'].tap do |extra|
  extra['#Some Comment'] = 'Heres the Comment'
  extra['AuthenticationMethods'] =  'publickey,keyboard-interactive'
end

# => Extra Client Configuration
default['ssh-hardening']['ssh']['client']['extras'].tap do |extra|
  extra['PermitLocalCommand'] = 'no'
  extra['Tunnel'] =  'no'
end

Match Configuration Options for sshd

Match blocks have to be placed by the end of sshd_config. This can be achieved by using the match_blocks attribute tree:

default['ssh-hardening']['ssh']['server']['match_blocks'].tap do |match|
  match['User root'] = <<~ROOT
    AuthorizedKeysFile .ssh/authorized_keys
  ROOT
  match['User git'] = <<~GIT
    Banner none
    AuthorizedKeysCommand /bin/false
    AuthorizedKeysFile .ssh/authorized_keys
    GSSAPIAuthentication no
    PasswordAuthentication no
  GIT
end

Local Testing

Please install chef-dk, VirtualBox or VMware Workstation and Vagrant.

Linting is checked with rubocop and foodcritic:

$ chef exec rake lint
.....

Unit/spec tests are done with chefspec:

$ chef exec rake spec
.....

Integration tests are done with test-kitchen and inspec:

$ chef exec rake kitchen
.....
# or you can use the kitchen directly
$ kitchen test

FAQ / Pitfalls

I can't log into my account. I have registered the client key, but it still doesn't let me it.

If you have exhausted all typical issues (firewall, network, key missing, wrong key, account disabled etc.), it may be that your account is locked. The quickest way to find out is to look at the password hash for your user:

sudo grep myuser /etc/shadow

If the hash includes an !, your account is locked:

myuser:!:16280:7:60:7:::

The proper way to solve this is to unlock the account (passwd -u myuser). If the user doesn't have a password, you should can unlock it via:

usermod -p "*" myuser

Alternatively, if you intend to use PAM, you enabled it via ['ssh-hardening']['ssh']['use_pam'] = true. PAM will allow locked users to get in with keys.

Why doesn't my application connect via SSH anymore?

Always look into log files first and if possible look at the negotiation between client and server that is completed when connecting.

We have seen some issues in applications (based on python and ruby) that are due to their use of an outdated crypto set. This collides with this hardening module, which reduced the list of ciphers, message authentication codes (MACs) and key exchange (KEX) algorithms to a more secure selection.

If you find this isn't enough, feel free to activate the attributes cbc_requires for ciphers, weak_hmac for MACs and weak_kexfor KEX in the namespaces ['ssh-hardening']['ssh']['client'] or ['ssh-hardening']['ssh']['server'] based on where you want to support them.

Why can't I log to the SFTP server after I added a user to my SFTP group?

This is a ChrootDirectory ownership problem. sshd will reject SFTP connections to accounts that are set to chroot into any directory that has ownership/permissions that sshd considers insecure. sshd's strict ownership/permissions requirements dictate that every directory in the chroot path must be owned by root and only writable by the owner. So, for example, if the chroot environment is /home must be owned by root.

See https://wiki.archlinux.org/index.php/SFTP_chroot

Contributors + Kudos

This cookbook is mostly based on guides by:

Thanks to all of you!!

Contributing

See contributor guideline.

License and Author

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.