ovh/the-bastion
1
1
Fork 0
mirror of https://github.com/ovh/the-bastion.git synced 2025-09-28 15:54:30 +08:00
Code Issues Projects Releases Packages Wiki Activity

documentation: add a lot of new documentation topics

Browse source
This commit is contained in:
Stéphane Lesimple 2021-06-25 15:43:00 +00:00 • committed by Stéphane Lesimple
parent b942131092
commit 458c50eff1
19 changed files with 921 additions and 291 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/sphinx/Makefile
View file

@ -31,7 +31,8 @@ plugins:
@bash build-plugins-help.sh
bastion_conf:
@perl build-bastion-conf-help.pl < ../../etc/bastion/bastion.conf.dist > administration/bastion_conf.rst
@env BASTION_CONF=1 perl build-bastion-conf-help.pl < ../../etc/bastion/bastion.conf.dist > administration/configuration/bastion_conf.rst
@env OSH_HTTP_PROXY_CONF=1 perl build-bastion-conf-help.pl < ../../etc/bastion/osh-http-proxy.conf.dist > administration/configuration/osh-http-proxy_conf.rst
.PHONY: help Makefile plugins all autogenerated default bastion_conf

0
doc/sphinx/administration/bastion_conf.rst → doc/sphinx/administration/configuration/bastion_conf.rst
View file

9
doc/sphinx/administration/configuration/index.rst Normal file
View file

@ -0,0 +1,9 @@
===================
Configuration files
===================
.. toctree::
:maxdepth: 3
bastion_conf
osh-http-proxy_conf

184
doc/sphinx/administration/configuration/osh-http-proxy_conf.rst Normal file
View file

@ -0,0 +1,184 @@
=============================
osh-http-proxy.conf reference
=============================
.. note::
This module is optional, and disabled by default. To know more about the HTTP Proxy feature
of The Bastion, please check :doc:`/using/http_proxy`
Option List
===========
HTTP Proxy configuration
------------------------
These options modify the behavior of the HTTP Proxy, an optional module of The Bastion
- :ref:`enabled`
- :ref:`port`
- :ref:`ssl_certificate`
- :ref:`ssl_key`
- :ref:`ciphers`
- :ref:`insecure`
- :ref:`min_servers`
- :ref:`max_servers`
- :ref:`min_spare_servers`
- :ref:`max_spare_servers`
- :ref:`timeout`
- :ref:`log_request_response`
- :ref:`log_request_response_max_size`
Option Reference
================
HTTP Proxy configuration
------------------------
.. _enabled:
enabled
*******
:Type: ``bool``
:Default: ``false``
Whether the HTTP proxy daemon daemon is enabled or not. If it's not enabled, it'll exit when started. Of course, if you want to enable this daemon, you should **also** configure your init system to start it for you. Both sysV-style scripts and systemd unit files are provided. For systemd, using `systemctl enable osh-http-proxy.service` should be enough. For sysV-style inits, it depends on the scripts provided for your distro, but usually `update-rc.d osh-http-proxy defaults` then `update-rc.d osh-http-proxy enable` should do the trick.
.. _port:
port
****
:Type: ``int, 1 to 65535``
:Default: ``8443``
The port to listen to. You can use ports < 1024, in which case privileges will be dropped after binding, but please ensure your systemd unit file starts the daemon as root in that case.
.. _ssl_certificate:
ssl_certificate
***************
:Type: ``string``
:Default: ``/etc/ssl/certs/ssl-cert-snakeoil.pem``
The file that contains the server SSL certificate in PEM format. For tests, install the ``ssl-cert`` package and point this configuration item to the snakeoil certs (which is the default).
.. _ssl_key:
ssl_key
*******
:Type: ``string``
:Default: ``/etc/ssl/private/ssl-cert-snakeoil.key``
The file that contains the server SSL key in PEM format. For tests, install the ``ssl-cert`` package and point this configuration item to the snakeoil certs (which is the default).
.. _ciphers:
ciphers
*******
:Type: ``string``
:Default: ``""``
:Example: ``"ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"``
The ordered list the TLS server ciphers, in ``openssl`` classic format. Use ``openssl ciphers`' to see what your system supports,
an empty list leaves the choice to your openssl libraries default values (system-dependent)
.. _insecure:
insecure
********
:Type: ``bool``
:Default: ``false``
Whether to ignore SSL certificate verification for the connection between the bastion and the devices
.. _min_servers:
min_servers
***********
:Type: ``int, 1 to 512``
:Default: ``8``
Number of child processes to start at launch
.. _max_servers:
max_servers
***********
:Type: ``int, 1 to 512``
:Default: ``32``
Hard maximum number of child processes that can be active at any given time no matter what
.. _min_spare_servers:
min_spare_servers
*****************
:Type: ``int, 1 to 512``
:Default: ``8``
The daemon will ensure that there is at least this number of children idle & ready to accept new connections (as long as max_servers is not reached)
.. _max_spare_servers:
max_spare_servers
*****************
:Type: ``int, 1 to 512``
:Default: ``16``
The daemon will kill *idle* children to keep their number below this maximum when traffic is low
.. _timeout:
timeout
*******
:Type: ``int, 1 to 3600``
:Default: ``120``
Timeout delay (in seconds) for the connection between the bastion and the devices
.. _log_request_response:
log_request_response
********************
:Type: ``bool``
:Default: ``true``
When enabled, the complete response of the device to the request we forwarded will be logged, otherwise we'll only log the response headers
.. _log_request_response_max_size:
log_request_response_max_size
*****************************
:Type: ``int, 0 to 2^30 (1 GiB)``
:Default: ``65536``
This option only applies when `log_request_response` is true (see above). When set to zero, the complete response will be logged in the account's home log directory, including the body, regardless of its size. If set to a positive integer, the query response will only be partially logged, with full status and headers but the body only up to the specified size. This is a way to avoid turning off request response logging completely on very busy bastions, by ensuring logs growth don't get out of hand, as some responses to queries can take megabytes, with possibly limited added value to traceability.

4
doc/sphinx/administration/index.rst
View file

@ -9,7 +9,7 @@ Here we make the assumption that you've already installed The Bastion, and would
are not yet documented here, but directly in the configuration files themselves.
.. toctree::
:maxdepth: 3
:maxdepth: 2
bastion_conf
configuration/index
logs

20
doc/sphinx/build-bastion-conf-help.pl
View file

@ -72,7 +72,8 @@ while (<STDIN>) {
}
dumpdoc();
print <<'EOF';
if ($ENV{BASTION_CONF}) {
print <<'EOF';
======================
bastion.conf reference
======================
@ -88,6 +89,23 @@ Option List
===========
EOF
}
elsif ($ENV{OSH_HTTP_PROXY_CONF}) {
print <<'EOF';
=============================
osh-http-proxy.conf reference
=============================
.. note::
This module is optional, and disabled by default. To know more about the HTTP Proxy feature
of The Bastion, please check :doc:`/using/http_proxy`
Option List
===========
EOF
}
foreach my $section (@orderedsections) {
die "no description for section $section" if !$sectiondesc{$section};

BIN
doc/sphinx/img/group_roles.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 153 KiB

BIN
doc/sphinx/img/groups.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 175 KiB

6
doc/sphinx/index.rst
View file

@ -33,6 +33,12 @@ The second section explains how to :doc:`get the bastion running<installation/in
The third section focuses on :doc:`how to use<using/index>` the bastion, from the perspective of the different roles, such as bastion users, group owners, bastion admins, etc.
The fourth section is about the proper :doc:`administration<administration/index>` of the bastion itself. If you're about to be the person in charge of managing the bastion for your company, you want to read that one carefully!
The fifth section is the complete reference of all the :doc:`plugins<plugins/index>`, that are the commands used to interact with the bastion accounts, groups, accesses, credentials, and more.
The last section is the unavoidable and iconic :doc:`Frequently Asked Questions<faq>`.
.. toctree::
:maxdepth: 2
:caption: Table of contents

30
doc/sphinx/plugins/group-owner/groupDestroy.rst Normal file
View file

@ -0,0 +1,30 @@
=============
groupDestroy
=============
Delete a group
==============
.. admonition:: usage
:class: cmdusage
--osh groupDestroy --group GROUP
.. program:: groupDestroy
.. option:: --group GROUP
Group name to delete
.. option:: --no-confirm
Skip group name confirmation, but blame yourself if you deleted the wrong group!
This command is able to delete any group you're an owner of.
Granted users to the sibling restricted command `groupDelete` can delete any group.

246
doc/sphinx/using/basics.rst
View file

@ -2,248 +2,14 @@
The basics
==========
This section explains the basics you need to know to work with the bastion. It's advised to go through all the subsections.
We make the assumption here that you already have a bastion account:
- either you're one of the admins who just :doc:`installed<../installation/basic>` it, or
- either you're one of the admins who just :doc:`installed<../../installation/basic>` it, or
- one of the admins created an account for you, using :doc:`/plugins/restricted/accountCreate`
First steps
===========
.. toctree::
Bastion alias
*************
You should setup a *bastion alias* to make it easy to connect to the bastion. An example of the proper alias to use for your account is given to the bastion administrator when s/he creates your account, and is usually something along the lines of:
.. code-block:: shell
alias bssh='ssh -t myname@the-bastion.example.org --'
Of course, you can modify it as you see fit, for example adding the ``-i`` argument to specify the private SSH key to use to connect to the bastion. You can use any name as the alias, but it's advised to keep it short, as you'll use it quite often.
For the remaining of this documentation, we'll assume your bastion alias is `bssh`.
You can do to categories of things on the bastion:
- Connect to infrastructures through it
- Interact with the bastion itself, for example to manage your account, and/or groups, through so-called :doc:`/plugins/index` aka *osh commands*
Plugins
*******
We'll start by using the ``info`` plugin, to verify that your bastion access works correctly:
.. code-block:: shell
:emphasize-lines: 1
$ bssh --osh info
*------------------------------------------------------------------------------*
|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. |
*------------------------------------------------------------------------------*
Enter PIN for 'PIV Card Holder pin (PIV_II)':
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> information
--------------------------------------------------------------------------------
~ You are johndoe
~ You are a bastion auditor!
~ Look at you, you are a bastion superowner!
~ Woosh, you are even a bastion admin!
~
~ Your alias to connect to this bastion is:
~ alias bssh='ssh johndoe@the-bastion.example.org -p 22 -t -- '
~ Your alias to connect to this bastion with MOSH is:
~ alias bsshm='mosh --ssh="ssh -p 22 -t" johndoe@the-bastion.example.org -- '
~
~ [...]
~
~ Here is your excuse for anything not working today:
~ BOFH excuse #46:
~ waste water tank overflowed onto computer
----------------------------------------------------------------------</info>---
Connection to the-bastion.example.org closed.
Congratulations, you've just used your first command on the bastion!
You can get a list of all the plugins you can use by saying:
.. code-block:: shell
$ bssh --osh help
The list will depend on your access level on the bastion, as some commands are restricted. You can have more information about any command by using ``--help`` with it:
.. code-block:: shell
$ bssh --osh selfAddIngressKey --help
See :doc:`/plugins/index` for more information about the plugins.
Instead of using ``--osh`` to call plugins, you can enter the special *interactive mode*, by saying:
.. code-block:: shell
$ bssh -i
In this mode, you can directly enter commands, and also use auto-completion features with the ``<TAB>`` key. You can start by just typing ``help``, which is the equivalent of saying ``bssh --osh help``. For security reasons, the interactive mode will disconnect you after a given amount of idle-time.
Setting up access to a server
*****************************
This section assumes that you have a server you want to secure access to, using the bastion. We'll call it *server42.example.org*, with IP 198.51.100.42. To do this, we'll use the **selfAddAccess** command.
Let's use the interactive mode to get the auto-completion features:
.. code-block:: shell
:emphasize-lines: 1
$ bssh -i
Enter PIN for 'PIV Card Holder pin (PIV_II)':
Welcome to bssh interactive mode, type `help' for available commands.
You can use <tab> and <tab><tab> for autocompletion.
You'll be disconnected after 60 seconds of inactivity.
Loading... 88 commands and 341 autocompletion rules loaded.
bssh(master)>
You can enter the first few characters of the command, then use ``<TAB>`` to help you complete it, then use ``<TAB>`` again to show you the required arguments. The complete command would be as follows:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfAddPersonalAccess --host 198.51.100.42 --port 22 --user root
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> adding private access to a server on your account
--------------------------------------------------------------------------------
~ Testing connection to root@198.51.100.42, please wait...
Warning: Permanently added '198.51.100.42' (ECDSA) to the list of known hosts.
root@198.51.100.42: Permission denied (publickey).
~ Note: if you still want to add this access even if it doesn't work, use --force
~ Couldn't connect to root@198.51.100.42 (ssh returned error 255). Hint: did you add the proper public key to the remote's authorized_keys?
-----------------------------------------------------</selfAddPersonalAccess>---
bssh(master)>
You'll notice that it didn't work. This is because first, you need to add your *personal egress key* to the remote machine's *authorized_keys* file. If this seems strange, here is :doc:`how it works <../presentation/principles>`. To get your *personal egress key*, you can use this command:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfListEgressKeys
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> the public part of your personal bastion key
--------------------------------------------------------------------------------
~ You can copy one of those keys to a remote machine to get access to it through your account
~ on this bastion, if it is listed in your private access list (check selfListAccesses)
~
~ Always include the from="198.51.100.1/32" part when copying the key to a server!
~
~ fingerprint: SHA256:rMpoCaYPSfRqmOBFOJvEr5uLqxYjqYtRDgUoqUwH2nA (ED25519-256) [2019/07/11]
~ keyline follows, please copy the *whole* line:
from="198.51.100.1/32" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILnY2NQTKsTDxgcaTE6vHVm9FIbud1rJcYQ/4xUyr+DK johndoe@bssh:1562861572
--------------------------------------------------------</selfListEgressKeys>---
Now that you have it, you can push this public key (the line starting with the *from=*) to the remote server's root authorized_keys, i.e. ``/root/.ssh/authorized_keys``. Now, you can add your access properly:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfAddPersonalAccess --host 198.51.100.42 --port 22 --user root
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> adding private access to a server on your account
--------------------------------------------------------------------------------
~ Testing connection to root@198.51.100.42, please wait...
Warning: Permanently added '198.51.100.42' (ECDSA) to the list of known hosts.
~ Access to root@198.51.100.42:22 successfully added
-----------------------------------------------------</selfAddPersonalAccess>---
bssh(master)>
All seems in order! Can we see this access we just created?
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfListAccesses
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> your access list
--------------------------------------------------------------------------------
~ Dear johndoe, you have access to the following servers:
~ IP PORT USER ACCESS-BY ADDED-BY ADDED-AT
~ 198.51.100.42 22 root personal johndoe 2020-05-01
-----------------------------------------------------</selfListAccesses>---
bssh(master)>
Connecting to a server and reviewing the session
************************************************
Good! Let's try to connect now!
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> ssh root@198.51.100.42
~ Welcome to the-bastion, johndoe, your last login was 00:13:37 ago (Fri 2020-08-28 13:07:43 UTC) from 192.0.2.11(proxy-11.example.org)
proxy-11.example.org:40610 => johndoe@the-bastion.example.org:22 => root@server42.example.org:22 ...
allowed ... log on(/home/johndoe/ttyrec/198.51.100.42/2020-08-28.13-07-45.497020.fb00e1957b22.johndoe.root.198.51.100.42.22.ttyrec)
will try the following accesses you have:
- personal access with ED25519-256 key SHA256:rMpoCaYPSfRqmOBFOJvEr5uLqxYjqYtRDgUoqUwH2nA [2019/07/11]
Connecting...
root@server42:~# id
uid=0(root) gid=0(root) groups=0(root),2(bin)
root@server42:~#
We're now connected to server42, and can do our work as usual. Note that to connect to server42, one can directly use:
.. code-block:: shell
$ bssh root@198.51.100.42
Where `bssh` is the bastion alias we've just set up above, no need to enter interactive mode first of course.
When we've done with server42, let's see if everything was correctly recorded:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfListSessions --type ssh --detailed
---the-bastion.example.org---------------------the-bastion-2.99.99-rc9.2-ovh1---
=> your past sessions list
--------------------------------------------------------------------------------
~ The list of your 100 past sessions follows:
~
f4cca44a848e [2020/08/26@09:28:57 - 2020/08/26@09:29:57 ( 60.0)] type ssh from 192.0.2.11:33450(proxy-11.example.org) via johndoe@198.51.100.1:22 to root@198.51.100.42:22(server42.example.org) returned 0
----------------------------------------------------------</selfListSessions>---
The first column is the unique identifier of the connection (or osh command).
Let's see what we did exactly during this session:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfPlaySession --id f4cca44a848e
---the-bastion.example.org---------------------the-bastion-2.99.99-rc9.2-ovh1---
=> replay a past session
--------------------------------------------------------------------------------
~ ID: f4cca44a848e
~ Started: 2020/08/26 09:28:57
~ Ended: 2020/08/26 09:29:57
~ Duration: 0d+00:01:00.382820
~ Type: ssh
~ From: 192.0.2.11:33450 (proxy-11.example.org)
~ Via: johndoe@198.51.100.1:22
~ To: root@198.51.100.42:22 (server42.example.org)
~ RetCode: 0
~
~ Press '+' to play faster
~ Press '-' to play slower
~ Press '1' to restore normal playing speed
~
~ When you're ready to replay session 9f352fd4b85c, press ENTER.
~ Starting from the next line, the Total Recall begins. Press CTRL+C to jolt awake.
Now that you've connected to your first server, using a personal access, you may want to check out the groups access management, or directly dive into the :doc:`/plugins/index`.
first_steps
access_management

86
doc/sphinx/using/basics/access_management.rst Normal file
View file

@ -0,0 +1,86 @@
=================
Access management
=================
There are two ways of managing authorizations on The Bastion, it is extremely important to understand those two ways because they're complementary.
.. note::
This section is largely inspired from the `blog post about the subject <https://www.ovh.com/blog/the-ovhcloud-ssh-bastion-part-2-delegation-dizziness/>`_
The main idea is that delegation is at the core of the system: everybody has their own set of responsibilities, and potential actions, without having to ask the bastion admin.
.. _accessManagementPersonalAccesses:
Personal Accesses
=================
On the bastion, each account has (at least) one set of **personal egress keys**. These beasts are generated when the account is first created. The personal egress **private key** sits in the bastion account home. The account user has no way to see it, or export it out of the bastion, but they can use it through the bastion's code logic. The user can retrieve the corresponding **public key** at any time, using the :doc:`/plugins/open/selfListEgressKeys` command, and install it – or get it installed – on the remote servers they needs to access. Depending on your use case – and the level of autonomy you want to give to the teams – there are two ways of managing these personal accesses.
Decentralized (help yourself)
*****************************
The first way mimics how you would manage accesses if you weren't using an SSH bastion at all. This is a perfectly valid way to handle accesses on a simple level, without too many users and a limited number of machines. This allows anyone to grant themselves personal accesses on the bastion, without having to ask anyone else to do it. It sounds like a security hole, but it's not. If someone adds themself a personal access to the remote server, it will only work if their personal egress public key has already been installed on the remote server. In other words, they either already had access to the remote server to do this – using means other than the bastion – or somebody who had access to the remote server accepted the addition of their key. Either way, they cannot magically grant themselves personal access without the admins of the remote server first permitting their key.
Centralized (ask the IT crowd)
******************************
Another way to handle this can be to grant a limited number of people, such as security teams, the right to add personal accesses to others. This way people are less autonomous, but it might be useful if adding accesses has to be enacted via normalized processes. It also has some nice effects: as a sysadmin, one of the pros is that you can create 3 separate accounts on the remote machine, and map them to each bastion account you're adding. This is a good method for achieving **end-to-end traceability**; including on the remote server; where you might want to install **auditd** or similar tools. It's also doable in the help yourself mode, but it may be harder to enforce.
To be clear, this access model doesn't scale so efficiently when we're dealing with whole teams, or big infrastructures – this is where group-based access comes handy.
.. _accessManagementGroupAccesses:
Group Accesses
==============
.. image:: /img/groups.png
:width: 400px
A group has three components:
- A list of members (accounts, representing individual people)
- At least one set of group egress keys
- A list of servers (or more precisely IPs)
Servers list
************
The servers list is actually a list of IPs, or IP blocks. They map to your servers, network devices, or anything else with SSH capability that has an IP (on which the egress group key has been installed). Technically, this list is actually composed of 3-tuple items: remote user, remote IP (or IP block), remote port. That which applies to the personal accesses, also applies here: adding a server to the list doesn't magically give access to it, it is first necessary to install the **egress group public key**. Of course, managing the installation of these keys manually quickly becomes impractical, but you can consider these part of the configuration of the servers, hence they should be managed with whichever centralized configuration system you already use (Puppet, Chef, Ansible, /bin/cp… wait, no, strike this last one).
Members list
************
The members are people who can connect to any server listed in the group server list. They'll be using the **private egress group key** they have access to, as members of said group. Of course, they have no way to extract this private key for their own use outside of the bastion, they can only use it through the bastion's code logic.
Got a new team member? Just add them as a member of your group, and they instantly get access to all the group servers. Somebody leaves the company? Just delete their account on the bastion, and all the accesses are instantly gone. This is the case because all your servers should have incoming SSH sessions limited to your bastions. This way, any rogue SSH key that would have been added, is no longer of any use.
.. _accessManagementGroupRoles:
And some more
*************
We've covered the basics of the group-based approach, but as we need a lot of flexibility and delegation, there is a little more to cover. Remember when I said a group had 3 components? Well, I lied. A group has more than just members. Additional group roles include:
- Guests
- Gatekeepers
- Aclkeepers
- Owners
All of these are lists of accounts that have a specific role in the group.
.. image:: /img/group_roles.png
First, **guests**. These are a bit like members, but with less privileges: they can connect to remote machines using the group key, but not to all the machines of the group, only to a subset. This is useful when somebody outside of the team needs a specific access to a specific server, potentially for a limited amount of time (as such accesses can be set to expire).
Then, **gatekeepers**. Those guys manage the list of members and guests of the group. In other terms, they have the right to give the right to get access. Nothing too complicated here. Then, there are the **aclkeepers**. As you may have guessed, they manage the list of servers that are part of the group. If you happen to have some automation managing the provisioning of servers of your infrastructure, this role could be granted to a robot account whose sole purpose would be to update the servers list on the bastion, in a completely integrated way with your provisioning. You can even tag such accounts so that they'll never be able to use SSH through the bastion, even if somebody grants them by mistake!
Last but not least, the **owners** have the highest privilege level on the group, which means they can manage the gatekeepers, aclkeepers and owners lists. They are permitted to give the right to give the right to get access. Moreover, users can accumulate these roles, which means some accounts may be a member and a gatekeeper at the same time, for example.
Global roles
============
Beyond the roles we have just described – which are all scoped to a group – there are two additional roles, which are scoped to the whole bastion: the **superowner** and the **bastion admin**.
In a nutshell, a **superowner** is the implicit owner of all groups present on the bastion. This comes in handy if the group becomes ownerless, as superowners are able to nominate a brand new owner.
The most powerful role is the **bastion admin**. This role should only be given to a few individuals, as they can impersonate anyone, and in practice should not be given to somebody who is not already root on the bastion's operating system itself. Among other things, they manage the configuration of the bastion, where the superowners are declared.

250
doc/sphinx/using/basics/first_steps.rst Normal file
View file

@ -0,0 +1,250 @@
===========
First steps
===========
Bastion alias
*************
You should setup a *bastion alias* to make it easy to connect to the bastion. An example of the proper alias to use for your account is given to the bastion administrator when they creates your account, and is usually something along the lines of:
.. code-block:: shell
:emphasize-lines: 1
alias bssh='ssh -t myname@the-bastion.example.org --'
Of course, you can modify it as you see fit, for example adding the ``-i`` argument to specify the private SSH key to use to connect to the bastion. You can use any name as the alias, but it's advised to keep it short, as you'll use it quite often.
For the remaining of this documentation, we'll assume your bastion alias is ``bssh``.
You can do two categories of things on the bastion:
- Connect to infrastructures through it
- Interact with the bastion itself, for example to manage your account, and/or groups, through so-called :doc:`/plugins/index` aka *osh commands*
Plugins
*******
We'll start by using the ``info`` plugin, to verify that your bastion access works correctly:
.. code-block:: shell
:emphasize-lines: 1
bssh --osh info
*------------------------------------------------------------------------------*
|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. |
*------------------------------------------------------------------------------*
Enter PIN for 'PIV Card Holder pin (PIV_II)':
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> information
--------------------------------------------------------------------------------
~ You are johndoe
~ You are a bastion auditor!
~ Look at you, you are a bastion superowner!
~ Woosh, you are even a bastion admin!
~
~ Your alias to connect to this bastion is:
~ alias bssh='ssh johndoe@the-bastion.example.org -p 22 -t -- '
~ Your alias to connect to this bastion with MOSH is:
~ alias bsshm='mosh --ssh="ssh -p 22 -t" johndoe@the-bastion.example.org -- '
~
~ [...]
~
~ Here is your excuse for anything not working today:
~ BOFH excuse #46:
~ waste water tank overflowed onto computer
----------------------------------------------------------------------</info>---
Connection to the-bastion.example.org closed.
Congratulations, you've just used your first command on the bastion!
You can get a list of all the plugins you can use by saying:
.. code-block:: shell
:emphasize-lines: 1
bssh --osh help
The list will depend on your access level on the bastion, as some commands are restricted. You can have more information about any command by using ``--help`` with it:
.. code-block:: shell
:emphasize-lines: 1
bssh --osh selfAddIngressKey --help
See :doc:`/plugins/index` for more information about the plugins.
Instead of using ``--osh`` to call plugins, you can enter the special *interactive mode*, by saying:
.. code-block:: shell
:emphasize-lines: 1
bssh -i
In this mode, you can directly enter commands, and also use auto-completion features with the ``<TAB>`` key. You can start by just typing ``help``, which is the equivalent of saying ``bssh --osh help``. For security reasons, the interactive mode will disconnect you after a given amount of idle-time.
Setting up access to a server
*****************************
.. note::
This section assumes that you've just set up your bastion and your account is the one that has been created on installation, with all the super-powers included, especially access to the restricted :doc:`/plugins/restricted/selfAddPersonalAccess` command that we'll use below. If this is not the case, you'll need first to have a bastion admin grant you this command through :doc:`/plugins/restricted/accountGrantCommand`
Let's say that you have a server you want to secure access to, using the bastion. We'll call it *server42.example.org*, with IP 198.51.100.42. To do this, we'll use the :doc:`/plugins/restricted/selfAddPersonalAccess` command.
We can use the interactive mode to get the auto-completion features:
.. code-block:: shell
:emphasize-lines: 1
bssh -i
Enter PIN for 'PIV Card Holder pin (PIV_II)':
Welcome to bssh interactive mode, type `help' for available commands.
You can use <tab> and <tab><tab> for autocompletion.
You'll be disconnected after 60 seconds of inactivity.
Loading... 88 commands and 341 autocompletion rules loaded.
bssh(master)>
You can enter the first few characters of the command, then use ``<TAB>`` to help you complete it, then use ``<TAB>`` again to show you the required arguments. The complete command would be as follows:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfAddPersonalAccess --host 198.51.100.42 --port 22 --user root
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> adding private access to a server on your account
--------------------------------------------------------------------------------
~ Testing connection to root@198.51.100.42, please wait...
Warning: Permanently added '198.51.100.42' (ECDSA) to the list of known hosts.
root@198.51.100.42: Permission denied (publickey).
~ Note: if you still want to add this access even if it doesn't work, use --force
~ Couldn't connect to root@198.51.100.42 (ssh returned error 255). Hint: did you add the proper public key to the remote's authorized_keys?
-----------------------------------------------------</selfAddPersonalAccess>---
bssh(master)>
You'll notice that it didn't work. This is because first, you need to add your *personal egress key* to the remote machine's *authorized_keys* file. If this seems strange, here is :doc:`how it works <../presentation/principles>`. To get your *personal egress key*, you can use this command:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfListEgressKeys
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> the public part of your personal bastion key
--------------------------------------------------------------------------------
~ You can copy one of those keys to a remote machine to get access to it through your account
~ on this bastion, if it is listed in your private access list (check selfListAccesses)
~
~ Always include the from="198.51.100.1/32" part when copying the key to a server!
~
~ fingerprint: SHA256:rMpoCaYPSfRqmOBFOJvEr5uLqxYjqYtRDgUoqUwH2nA (ED25519-256) [2019/07/11]
~ keyline follows, please copy the *whole* line:
from="198.51.100.1/32" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILnY2NQTKsTDxgcaTE6vHVm9FIbud1rJcYQ/4xUyr+DK johndoe@bssh:1562861572
--------------------------------------------------------</selfListEgressKeys>---
Now that you have it, you can push this public key (the line starting with the *from=*) to the remote server's root authorized_keys, i.e. ``/root/.ssh/authorized_keys``. Now, you can add your access properly:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfAddPersonalAccess --host 198.51.100.42 --port 22 --user root
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> adding private access to a server on your account
--------------------------------------------------------------------------------
~ Testing connection to root@198.51.100.42, please wait...
Warning: Permanently added '198.51.100.42' (ECDSA) to the list of known hosts.
~ Access to root@198.51.100.42:22 successfully added
-----------------------------------------------------</selfAddPersonalAccess>---
bssh(master)>
All seems in order! Can we see this access we just created?
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfListAccesses
---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
=> your access list
--------------------------------------------------------------------------------
~ Dear johndoe, you have access to the following servers:
~ IP PORT USER ACCESS-BY ADDED-BY ADDED-AT
~ 198.51.100.42 22 root personal johndoe 2020-05-01
-----------------------------------------------------</selfListAccesses>---
bssh(master)>
Connecting to a server and reviewing the session
************************************************
Good! Let's try to connect now!
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> ssh root@198.51.100.42
~ Welcome to the-bastion, johndoe, your last login was 00:13:37 ago (Fri 2020-08-28 13:07:43 UTC) from 192.0.2.11(proxy-11.example.org)
proxy-11.example.org:40610 => johndoe@the-bastion.example.org:22 => root@server42.example.org:22 ...
allowed ... log on(/home/johndoe/ttyrec/198.51.100.42/2020-08-28.13-07-45.497020.fb00e1957b22.johndoe.root.198.51.100.42.22.ttyrec)
will try the following accesses you have:
- personal access with ED25519-256 key SHA256:rMpoCaYPSfRqmOBFOJvEr5uLqxYjqYtRDgUoqUwH2nA [2019/07/11]
Connecting...
root@server42:~# id
uid=0(root) gid=0(root) groups=0(root),2(bin)
root@server42:~#
We're now connected to server42, and can do our work as usual. Note that to connect to server42, one can directly use:
.. code-block:: shell
:emphasize-lines: 1
bssh root@198.51.100.42
Where ``bssh`` is the bastion alias we've just set up above, no need to enter interactive mode first of course.
When we're done with server42, let's see if everything was correctly recorded:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfListSessions --type ssh --detailed
---the-bastion.example.org---------------------the-bastion-2.99.99-rc9.2-ovh1---
=> your past sessions list
--------------------------------------------------------------------------------
~ The list of your 100 past sessions follows:
~
f4cca44a848e [2020/08/26@09:28:57 - 2020/08/26@09:29:57 ( 60.0)] type ssh from 192.0.2.11:33450(proxy-11.example.org) via johndoe@198.51.100.1:22 to root@198.51.100.42:22(server42.example.org) returned 0
----------------------------------------------------------</selfListSessions>---
The first column is the unique identifier of the connection (or osh command).
Let's see what we did exactly during this session:
.. code-block:: shell
:emphasize-lines: 1
bssh(master)> selfPlaySession --id f4cca44a848e
---the-bastion.example.org---------------------the-bastion-2.99.99-rc9.2-ovh1---
=> replay a past session
--------------------------------------------------------------------------------
~ ID: f4cca44a848e
~ Started: 2020/08/26 09:28:57
~ Ended: 2020/08/26 09:29:57
~ Duration: 0d+00:01:00.382820
~ Type: ssh
~ From: 192.0.2.11:33450 (proxy-11.example.org)
~ Via: johndoe@198.51.100.1:22
~ To: root@198.51.100.42:22 (server42.example.org)
~ RetCode: 0
~
~ Press '+' to play faster
~ Press '-' to play slower
~ Press '1' to restore normal playing speed
~
~ When you're ready to replay session 9f352fd4b85c, press ENTER.
~ Starting from the next line, the Total Recall begins. Press CTRL+C to jolt awake.
Now that you've connected to your first server, using a personal access, you may want to learn more about the :doc:`<access_management>`, or directly dive into the :doc:`/plugins/index`.

15
doc/sphinx/using/basics/index.rst Normal file
View file

@ -0,0 +1,15 @@
==========
The basics
==========
This section explains the basics you need to know to work with the bastion. It's advised to go through all the subsections.
We make the assumption here that you already have a bastion account:
- either you're one of the admins who just :doc:`installed<../../installation/basic>` it, or
- one of the admins created an account for you, using :doc:`/plugins/restricted/accountCreate`
.. toctree::
first_steps
access_management

194
doc/sphinx/using/http_proxy.rst Normal file
View file

@ -0,0 +1,194 @@
===========
HTTPS Proxy
===========
.. contents::
Introduction
============
In addition to securing your SSH accesses, by splitting the authentication part (ingress connection) and the authorization part (egress connection), The Bastion can do a similar job for HTTPS connections.
Note that there is an overhead (depending on your hardware setup) of several hundreds of milliseconds for each query-response trip, due to the fact that multiple processes are spawned for each query, to ensure proper security containment to the calling account's system user. It's probably a bad idea to use on a multi-million queries/day workload, or if each added millisecond to the query-response trip impacts the QoS of your service.
The primary use is for network devices, that happen to have more and more HTTPS APIs in addition to the usual ``conf terminal`` available through SSH. As the same commands are usually available from HTTPS and SSH on these devices, it would be too bad to secure the access to SSH through the bastion, but leave direct access to their HTTPS API!
Query workflow
==============
The workflow is similar to the one used by SSH, e.g. two distinct connections (ingress and egress), with the egress connection using credentials stored on the bastion:
- A client makes an HTTP request to the proxy, with the following information embedded in:
- The type of request (GET or POST)
- The complete URI, including the host of the remote HTTPS server it would like to send the request to
- Potential body data for POST requests
- Credentials to authenticate to the proxy on the ingress connection, namely the bastion account name and its proxy password (set by ``selfGenerateProxyPassword``)
- User name to use to authenticate on the remote HTTPS server (for the egress connection)
- The bastion checks the provided credentials to authenticate the request against a known account (authentication part)
- The bastion verifies whether the just-authenticated account has access rights to connect to the remote server as the specified remote user (authorization part)
- The bastion uses the (group or personal) credentials stored on the bastion, to passthrough the HTTP request to the remote server, as the specified remote user
- The bastion forwards the response to the client
Setting up the HTTPS Proxy
==========================
You should enable the HTTPS Proxy daemon, and configure it. Please check the :doc:`/administration/configuration/osh-http-proxy_conf` for more information.
Running a query through the proxy
=================================
First try
---------
Once the proxy is running, we can try to query it:
.. code-block:: none
:emphasize-lines: 1
curl https://bastion1.example.org:8443/
No authentication provided, and authentication is mandatory
Of course, the proxy only accepts to work when one is properly authenticated to it. To do this, one should have an account on the bastion, and use the :doc:`/plugins/open/selfGenerateProxyPassword` command so that a new ingress password is set for their account. They'll then be able to authenticate to the proxy using the HTTP basic-auth method, and try to send a request to a remote server. To keep a high compatibility with HTTP clients and libraries that can be used on the ingress side, all the additional data required by the bastion to properly authenticate, authorize and passthrough the request is encoded in the *user* part of the widely supported HTTP Authorize header (basic-auth). The *password* part corresponds to the password we've generated just above.
The format of the *user* part is as follows:
.. code-block:: none
BASTION_ACCOUNT@REMOTE_USER@REMOTE_HOST%REMOTE_PORT
The **%REMOTE_PORT** part is optional, and defaults to **443** if omitted.
For example, to send a **GET /info** request to the remote network device named **router12.example.org** on the default port **443**, using the remote account **monitoring**, through the **bastion1.example.org** bastion, having the HTTPS Proxy listening on its port **8443** and a bastion account **robot-mon**, one can use **curl**:
.. code-block:: none
:emphasize-lines: 1
curl -u robot-mon@monitoring@router12.example.org https://bastion1.example.org:8443/info
Enter host password for user 'robot-mon@monitoring@router12.example.org':
This account doesn't have access to this user@host tuple (Access denied for robot-mon to monitoring@router12.example.org:443)
A password will be prompted: the password generated by ``selfGenerateProxyPassword`` should be entered. Remember: this is to authenticate yourself to the bastion (ingress connection), then the bastion will authenticate itself to the remote machine (egress connection), using credentials stored on the bastion, that your account must have access to.
In the above case, we entered the password correctly, but our account doesn't have access to the requested host `monitoring@router12.example.org`. This is what we need to do now.
Access declaration
------------------
The access check is the same than the one done for SSH accesses, which means that oneself can have access to a remote host either through a :ref:`personal access <accessManagementPersonalAccesses>` or a :ref:`group access <accessManagementGroupAccesses>`.
To get granted access to a remote device, through a personal access, either the :doc:`/plugins/restricted/selfAddPersonalAccess` or the :doc:`/plugins/restricted/accountAddPersonalAccess` shall be used (both are restricted commands) such as:
.. code-block:: none
:emphasize-lines: 1
bssh --osh accountAddPersonalAccess --host router12.example.org --port 443 --user monitoring --force
Note the use of ``--force`` to skip the SSH connection test, which is useless in our case.
To use a group access instead, one of the :ref:`aclkeepers <accessManagementGroupRoles>` of the group should use :doc:`/plugins/group-aclkeeper/groupAddServer`, such as:
.. code-block:: none
:emphasize-lines: 1
bssh --osh groupAddServer --group netdevices --host router12.example.org --port 443 --user monitoring --force
Egress password
---------------
For personal accesses
*********************
If access to a remote device is granted to you through a personal access (using either the ``selfAddPersonalAccess`` or ``accountAddPersonalAccess`` commands), you must first generate a new set of credentials that will be stored on your bastion account, for egress connections. This is the equivalent of your personal egress keys for SSH, but in that case it's a password that will be used to authenticate using basic-auth to the remote server. You can generate this password using the ``selfGeneratePassword`` command:
.. code-block:: none
:emphasize-lines: 1
bssh --osh selfGeneratePassword --do-it
*------------------------------------------------------------------------------*
|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. |
*------------------------------------------------------------------------------*
╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1───
│ ▶ generating a new egress password for your account
├───────────────────────────────────────────────────────────────────────────────
│ Generated a new password of length 16 for your account, robot-mon, hashes follow:
│ md5crypt: $1$G0fo$2DH2OJQJ9bMgo5fUUuPeK.
│ sha256crypt: $5$2xd1aGuD$ze7px3olXdjWthSrdnzelm6avzT2kszx/voXms8/V00
│ sha512crypt: $6$udw2UNLs$tQ1p7ZYraOT4Woh1ZCGJNf.UAIh09nXPBf4ejpRurOY/fJUs6Dgh1WdkpY4pdCvKMQrPeetB42bNTSzIwJyGi1
│ This new password will now be used by default.
╰─────────────────────────────────────────────────────</selfGeneratePassword>───
As you can see, the password is stored on your bastion account, and is not printed: only its hashes are. With this information, the corresponding remote account can be provisioned on the device (usually, a network device).
In our above example, an account named **monitoring** would have to be created on the remote device, using one of these hashes. Prefer to use the most secure hashing algorithm supported by the remote device.
To get your password (hash) list, you can use ``selfListPasswords``:
.. code-block:: none
:emphasize-lines: 1
bssh --osh selfListPasswords
*------------------------------------------------------------------------------*
|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. |
*------------------------------------------------------------------------------*
╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1───
│ ▶ list your egress passwords
├───────────────────────────────────────────────────────────────────────────────
│ Current password created at Tue Jun 22 15:42:10 2021 by robot-mon
│ ... md5crypt: $1$G0fo$2DH2OJQJ9bMgo5fUUuPeK.
│ ... sha256crypt: $5$2xd1aGuD$ze7px3olXdjWthSrdnzelm6avzT2kszx/voXms8/V00
│ ... sha512crypt: $6$udw2UNLs$tQ1p7ZYraOT4Woh1ZCGJNf.UAIh09nXPBf4ejpRurOY/fJUs6Dgh1WdkpY4pdCvKMQrPeetB42bNTSzIwJyGi1
│
│ Fallback password 1 created at Wed Jun 2 08:00:01 2021 by robot-mon
│ ... md5crypt: $1$qF0M$2.rbRRGs66aPiEpc/SqGv/
│ ... sha256crypt: $5$E9qkC7D6$SG8BB.nXvwU0dB0Bq9S/sF5pDidLwSIDKCv95qNWhX0
│ ... sha512crypt: $6$druGNgSk$bzVHSvux/OOE2ZhDpabFekQU3GTsiKS7Yl/lLmb9gIAmjnFfR6gj7GzOniK2jdLtEcB/hQlhcx9TDgj5zHhVd.
│
╰────────────────────────────────────────────────────────</selfListPasswords>───
If the ``selfGeneratePassword`` command is used several times, the newly generated password will always override the previous one. Still, all the previous passwords are kept (archived) for good measure, and can be restored manually by a bastion admin. These passwords are named *Fallback passwords* in the output of ``selfListPasswords``.
For group accesses
******************
If the access to the remote device is given through a group, then the group's own credentials will be used. To this effect, one of the group owners should use the :doc:`/plugins/group-owner/groupGeneratePassword` command:
.. code-block:: none
:emphasize-lines: 1
bssh --osh groupGeneratePassword --group netdevices --do-it
╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1───
│ ▶ generating a new egress password for the group
├───────────────────────────────────────────────────────────────────────────────
│ Generated a new password of length 16 for group netdevices, hashes follow:
│ md5crypt: $1$9sb2$X8/pPBSLfQ0ddBGR/bzsT1
│ sha256crypt: $5$o6Jr8w0X$yQfLuX17tUwE1jfhhAX//vsn6KpXU5jUd7SCNbkYNH.
│ sha512crypt: $6$gyxMyjao$YNhZJPXZa4r838XKg2tfvvoV/Dtm5HKsyKt18BnvFfT.y.hZuSXRX9GhM4mA0hUsO9f0UBisO/WiK3vF/9qsL1
│ This new password will now be used by default.
╰────────────────────────────────────────────────────</groupGeneratePassword>───
As with the personal egress passwords, the password is stored on the bastion only, and is not printed: only its hashes are. With this information, the corresponding remote account can be provisioned on the device (usually, a network device).
In our above example, an account named **monitoring** would have to be created on the remote device, using one of these hashes. Prefer to use the most secure hashing algorithm supported by the remote device.
To get the group's password (hash) list, one can use the :doc:`/plugins/open/groupListPasswords` command:
.. code-block:: none
:emphasize-lines: 1
bssh --osh groupListPasswords --group netdevices
*------------------------------------------------------------------------------*
|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. |
*------------------------------------------------------------------------------*
╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1───
│ ▶ list the egress passwords of the group
├───────────────────────────────────────────────────────────────────────────────
│ Current password created at Tue Jun 29 10:21:38 2021 by slesimpl
│ ... md5crypt: $1$9sb2$X8/pPBSLfQ0ddBGR/bzsT1
│ ... sha256crypt: $5$o6Jr8w0X$yQfLuX17tUwE1jfhhAX//vsn6KpXU5jUd7SCNbkYNH.
│ ... sha512crypt: $6$gyxMyjao$YNhZJPXZa4r838XKg2tfvvoV/Dtm5HKsyKt18BnvFfT.y.hZuSXRX9GhM4mA0hUsO9f0UBisO/WiK3vF/9qsL1
╰───────────────────────────────────────────────────────</groupListPasswords>───
If the ``groupGeneratePassword`` command is used several times, the newly generated password will always override the previous one. Still, all the previous passwords are kept (archived) for good measure, and can be restored manually by a bastion admin. These passwords are named *Fallback passwords* in the output of ``groupListPasswords``.

4
doc/sphinx/using/index.rst
View file

@ -4,5 +4,7 @@ Using the bastion
.. toctree::
basics
basics/index
piv
scp
http_proxy

14
doc/sphinx/using/piv.rst
View file

@ -1,6 +1,6 @@
========
PIV keys
========
================
PIV keys support
================
.. contents::
@ -18,12 +18,14 @@ If you want to support PIV keys without making those mandatory, you don't have a
In that case, after having properly configured your hardware token with a key in slot 9a, you can just use :doc:`/plugins/open/selfAddIngressKey` to add the key to your bastion account, and call it a day. As a quick guidance, on a Yubikey you can usually generate a key in the proper slot this way, after you've setup a management key:
.. code:: shell
:emphasize-lines: 1
yubico-piv-tool --key=YOUR_MGMT_KEY --action generate --pin-policy always --touch-policy never --slot 9a -o -
Now, if you want the bastion to be aware that this key is from a hardware token, you shall use the ``--piv`` option to :doc:`/plugins/open/selfAddIngressKey`. This won't do anything special per-se, except storing the certificates information, and showing the details of the PIV key in command outputs such as :doc:`/plugins/open/selfListIngressKeys`. Note however that if in the future you enable the PIV enforcing policy either on your account or globally, this key will be considered valid, contrary to all the keys added without the ``--piv`` option, even if these keys happen to be PIV ones. To add a key with the ``--piv`` option, you'll need the SSH public key as usual, but also the attestation certificate and the key certificate. Step by step details on how to get those are out of the scope of this document, but again as a quick guidance, on a Yubikey you can usually get those this way:
.. code:: shell
:emphasize-lines: 1,2,3
yubico-piv-tool --action=read-certificate --slot=9a --key-format=SSH
yubico-piv-tool --action=attest --slot=9a
@ -32,8 +34,9 @@ Now, if you want the bastion to be aware that this key is from a hardware token,
When you'll have added your key, you'll see a few more details than usual:
.. code:: shell
:emphasize-lines: 1
$ bssh --osh selfAddIngressKey --piv
bssh --osh selfAddIngressKey --piv
Enter PIN for 'PIV Card Holder pin (PIV_II)':
---the-bastion.example.org--------------------------------the-bastion-3.01.03---
=> add a new public key to your account
@ -120,8 +123,9 @@ Temporary grace period
If you enable the PIV policy globally or on several accounts, you'll soon find out that sometimes people forget or lose their PIV-enabled hardware tokens, effectively locking them out of the bastion. There is a *temporary grace period* feature you can use to handle such cases nicely:
.. code:: shell
:emphasize-lines: 1
$ bssh --osh accountPIV --account lechuck --policy grace --ttl 48h
bssh --osh accountPIV --account lechuck --policy grace --ttl 48h
---the-bastion.example.org--------------------------------the-bastion-3.01.03---
=> modify the PIV policy of an account
--------------------------------------------------------------------------------

76
doc/sphinx/using/scp.rst Normal file
View file

@ -0,0 +1,76 @@
===========
SCP support
===========
.. contents::
Introduction
============
The Bastion's main goal is to secure ``ssh`` connections. However, one might also want to use ``scp`` through it.
Its use is supported through the :doc:`/plugins/open/scp` bastion plugin, and documented as part of all the plugins. This additional documentation section gives some examples and outlines some common configuration errors.
Prerequisites
=============
The use of SCP through the bastion requires an SCP program than supports the **-S** option, and a shell to run the wrapper. This is the case on all operating systems using OpenSSH such as Linux or \*BSD.
If you're running under Microsoft Windows, you might want to setup either a Linux VM, or a WSL (Windows Subsystem for Linux) environment, to have the OpenSSH version of **scp** and a working POSIX-style shell.
Note that it won't work with Windows GUI apps, because there's no way to specify a wrapper (through **-S**), and no shell. For example, it won't work under WinSCP.
Also note that only SCP is supported, *not SFTP*.
Basic usage
===========
Please check the :doc:`/plugins/open/scp` documentation to see how to use it.
Access model
============
.. note::
Currently, to be able to use SCP with a remote server, you first need to have a declared SSH access to it. This might change in a future version.
Error message 1
---------------
This is briefly explained in the :doc:`/plugins/open/scp` documentation, but having access rights to SSH to a machine is not enough to have the right to SCP to or from it. If you have the following error, then this is your problem:
::
Sorry, you seem to have access through ssh and through scp but by different and distinct means (distinct keys).
The intersection between your rights for ssh and for scp needs to be at least one.
When this happens, it means that you have at least one declared SSH access to this machine (through one or several groups, or through personal accesses). You also have at least one declared SCP access to it. However **both accesses are declared through different means**, and more precisely different SSH keys. For example:
- You are a member of a group having this machine on one hand, and you have a declared SCP access to this machine using a personal access on the other hand. For SSH, the group key would be used, but for SCP, your personal key would be used. However, for technical reasons (that might be lifted in a future version), your SSH and SCP access must be declared with the same key, so in other words, using the same access mean (same group, or personal access).
- You are a member of group **A** having this machine, but SCP access is declared in group **B**. In that case, as previously, as two different keys are used, this won't work.
To declare an SCP access, in addition to a preexisting SSH access, you should use either:
- :doc:`/plugins/group-aclkeeper/groupAddServer`, if the SSH access is part of a group
- :doc:`/plugins/restricted/selfAddPersonalAccess` or :doc:`/plugins/restricted/accountAddPersonalAccess`, if the SSH access is personal (tied to an account)
In both cases, where you would use the ``--user`` option to the command, to specify the remote user to use for the SSH access being declared, you should replace it by either ``--scp-down`` or ``--scp-up``, to specify that you're about to add an SCP access (not an SSH one), and which direction you want to allow. You can allow both directions by using the command first with ``--scp-down``, then with ``--scp-up``.
For example, this is a valid command to add SCP access to a machine which is part of a group:
::
bssh --osh groupAddServer --group mygroup --host scpserver.example.org --port 22 --scp-up
Error message 2
---------------
If you have the following message:
::
Sorry, but you don't seem to have access to HOST:IP
Then it means that you don't even have SSH access to this machine. In that case, somebody should grant you access, either by adding you to a group having this machine (:doc:`/plugins/group-gatekeeper/groupAddMember`) or by adding this machine to your personal accesses (:doc:`/plugins/restricted/accountAddPersonalAccess` or :doc:`/plugins/restricted/selfAddPersonalAccess`).

71
etc/bastion/osh-http-proxy.conf.dist
View file

@ -1,90 +1,79 @@
############################################################################################
# Config for the HTTP Proxy of The Bastion.
# This is a JSON file, its syntax must be valid at all times. To verify:
# => grep -v ^# /etc/bastion/osh-http-proxy.conf|python -mjson.tool>/dev/null && echo OK
#
# If you're on a production bastion you can verify it can properly load its configuration:
# => perl -I/opt/bastion/lib/perl -MOVH::Bastion -e 'die OVH::Bastion::load_configuration_file(file => "/etc/bastion/osh-http-proxy.conf")'
## Config for the HTTP Proxy of The Bastion.
## This is a JSON file, its syntax must be valid at all times. To verify:
## => grep -v ^# /etc/bastion/osh-http-proxy.conf|python -mjson.tool>/dev/null && echo OK
##
## If you're on a production bastion you can verify it can properly load its configuration:
## => perl -I/opt/bastion/lib/perl -MOVH::Bastion -e 'die OVH::Bastion::load_configuration_file(file => "/etc/bastion/osh-http-proxy.conf")'
############################################################################################
{
# > HTTP Proxy configuration
# >> These options modify the behavior of the HTTP Proxy, an optional module of The Bastion
#
# enabled (bool)
# VALUE: true or false
# DESC: whether the http proxy daemon is enabled or not (if not, it'll exit when launched)
# DESC: Whether the HTTP proxy daemon daemon is enabled or not. If it's not enabled, it'll exit when started. Of course, if you want to enable this daemon, you should **also** configure your init system to start it for you. Both sysV-style scripts and systemd unit files are provided. For systemd, using `systemctl enable osh-http-proxy.service` should be enough. For sysV-style inits, it depends on the scripts provided for your distro, but usually `update-rc.d osh-http-proxy defaults` then `update-rc.d osh-http-proxy enable` should do the trick.
# DEFAULT: false
"enabled": false,
#
# port (int)
# VALUE: 1 to 65535
# DESC: port to listen to. you can set < 1024, in which case privileges will be dropped after binding,
# but please ensure your systemd unit file starts the daemon as root in that case
# port (int, 1 to 65535)
# DESC: The port to listen to. You can use ports < 1024, in which case privileges will be dropped after binding, but please ensure your systemd unit file starts the daemon as root in that case.
# DEFAULT: 8443
"port": 8443,
#
# ssl_certificate (string)
# VALUE: a full path to a file
# DESC: file that contains the server SSL certificate in PEM format. For tests, install the ssl-cert package and point to snakeoil (which is the default).
# DEFAULT: /etc/ssl/private/ssl-cert-snakeoil.key
# DESC: The file that contains the server SSL certificate in PEM format. For tests, install the ``ssl-cert`` package and point this configuration item to the snakeoil certs (which is the default).
# DEFAULT: /etc/ssl/certs/ssl-cert-snakeoil.pem
"ssl_certificate": "/etc/ssl/certs/ssl-cert-snakeoil.pem",
#
# ssl_key (string)
# VALUE: a full path to a file
# DESC: file that contains the server SSL key in PEM format. For tests, install the ssl-cert package and point to snakeoil (which is the default).
# DESC: The file that contains the server SSL key in PEM format. For tests, install the ``ssl-cert`` package and point this configuration item to the snakeoil certs (which is the default).
# DEFAULT: /etc/ssl/private/ssl-cert-snakeoil.key
"ssl_key": "/etc/ssl/private/ssl-cert-snakeoil.key",
#
# ciphers (string)
# VALUE: openssl-compatible colon-separated (':') ciphersuites
# DESC: the ordered list the TLS server ciphers, in openssl classic format. Use `openssl ciphers' to see what your system supports,
# DESC: The ordered list the TLS server ciphers, in ``openssl`` classic format. Use ``openssl ciphers`' to see what your system supports,
# an empty list leaves the choice to your openssl libraries default values (system-dependent)
# EXAMPLE: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
# DEFAULT: ""
"ciphers": "",
#
# insecure (bool)
# VALUE: true or false
# DESC: whether to ignore SSL certificate verification for the connection between the bastion and the devices
# DESC: Whether to ignore SSL certificate verification for the connection between the bastion and the devices
# DEFAULT: false
"insecure": false,
#
# min_servers (int)
# VALUE: 1 to 512
# DESC: number of child processes to start at launch
# min_servers (int, 1 to 512)
# DESC: Number of child processes to start at launch
# DEFAULT: 8
"min_servers": 8,
#
# max_servers (int)
# VALUE: 1 to 512
# DESC: hard maximum number of child processes that can be active at any given time no matter what
# max_servers (int, 1 to 512)
# DESC: Hard maximum number of child processes that can be active at any given time no matter what
# DEFAULT: 32
"max_servers": 32,
#
# min_spare_servers (int)
# VALUE: 1 to 512
# DESC: the daemon will ensure that there is at least this number of children idle & ready to accept new connections (as long as max_servers is not reached)
# min_spare_servers (int, 1 to 512)
# DESC: The daemon will ensure that there is at least this number of children idle & ready to accept new connections (as long as max_servers is not reached)
# DEFAULT: 8
"min_spare_servers": 8,
#
# max_spare_servers (int)
# VALUE: 1 to 512
# DESC: the daemon will kill *idle* children to keep their number below this maximum when traffic is low
# max_spare_servers (int, 1 to 512)
# DESC: The daemon will kill *idle* children to keep their number below this maximum when traffic is low
# DEFAULT: 16
"max_spare_servers": 16,
#
# timeout (int)
# VALUE: 1 to 3600
# DESC: timeout delay (in seconds) for the connection between the bastion and the devices
# timeout (int, 1 to 3600)
# DESC: Timeout delay (in seconds) for the connection between the bastion and the devices
# DEFAULT: 120
"timeout": 120,
#
# log_request_response (bool)
# VALUE: true or false
# DESC: when enabled, the complete response of the device to the request we forwarded will be logged, otherwise we'll only log the response headers
# DESC: When enabled, the complete response of the device to the request we forwarded will be logged, otherwise we'll only log the response headers
# DEFAULT: true
"log_request_response": true,
#
# log_request_response_max_size (int)
# VALUE: 0 to 2^30 (1 GiB)
# DESC: this option only applies when `log_request_response` is true (see above). When set to zero, the complete response will be logged in the account's home log directory, including the body, regardless of its size. If set to a positive integer, the query response will only be partially logged, with full status and headers but the body only up to the specified size. This is a way to avoid turning off request response logging completely on very busy bastions, by ensuring logs growth don't get out of hand, as some responses to queries can take megabytes, with possibly limited added value to traceability.
# log_request_response_max_size (int, 0 to 2^30 (1 GiB))
# DESC: This option only applies when `log_request_response` is true (see above). When set to zero, the complete response will be logged in the account's home log directory, including the body, regardless of its size. If set to a positive integer, the query response will only be partially logged, with full status and headers but the body only up to the specified size. This is a way to avoid turning off request response logging completely on very busy bastions, by ensuring logs growth don't get out of hand, as some responses to queries can take megabytes, with possibly limited added value to traceability.
# DEFAULT: 65536
"log_request_response_max_size": 65536
}