ovh/the-bastion
1
1
Fork 0
mirror of https://github.com/ovh/the-bastion.git synced 2025-09-27 23:34:25 +08:00
Code Issues Projects Releases Packages Wiki Activity

doc: update

Browse source
This commit is contained in:
Stéphane Lesimple 2021-02-15 13:34:22 +00:00 • committed by Stéphane Lesimple
parent 488ec6382e
commit 5eb5135d26
9 changed files with 171 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
bin/plugin/group-owner/groupGenerateEgressKey
View file

@ -19,9 +19,31 @@ my $remainingOptions = OVH::Bastion::Plugin::begin(
"size=i" => \my $size,
"encrypted" => \my $encrypted,
},
help => \&OVH::Bastion::Plugin::generateEgressKey::help,
help => \&help,
);
sub help {
print <<"EOF";
Create a new public + private key pair for a group
Usage: --osh $scriptName --group GROUP --algo ALGO --size SIZE [--encrypted]
--group GROUP Group name to generate a new egress key for.
--algo ALGO Specifies the algo of the key, either rsa, ecdsa or ed25519.
--size SIZE Specifies the size of the key to be generated.
For RSA, choose between 2048 and 8192 (4096 is good).
For ECDSA, choose either 256, 384 or 521.
For ED25519, size is always 256.
--encrypted If specified, a passphrase will be prompted for the new key
EOF
OVH::Bastion::Plugin::generateEgressKey::help_algos();
return 0;
}
#
# code
#

24
bin/plugin/open/selfGenerateEgressKey
View file

@ -18,9 +18,29 @@ my $remainingOptions = OVH::Bastion::Plugin::begin(
"size=i" => \my $size,
"encrypted" => \my $encrypted,
},
help => \&OVH::Bastion::Plugin::generateEgressKey::help,
help => \&help,
);
sub help {
print <<"EOF";
Create a new public + private key pair on your bastion account
Usage: --osh $scriptName --algo ALGO --size SIZE [--encrypted]
--algo ALGO Specifies the algo of the key, either rsa, ecdsa or ed25519.
--size SIZE Specifies the size of the key to be generated.
For RSA, choose between 2048 and 8192 (4096 is good).
For ECDSA, choose either 256, 384 or 521.
For ED25519, size is always 256.
--encrypted if specified, a passphrase will be prompted for the new key
EOF
OVH::Bastion::Plugin::generateEgressKey::help_algos();
return 1;
}
#
# code
#
@ -33,7 +53,7 @@ $fnret = OVH::Bastion::Plugin::generateEgressKey::preconditions(
size => $size
);
if ($fnret->err eq 'ERR_MISSING_PARAMETER') {
OVH::Bastion::Plugin::generateEgressKey::help();
help();
osh_exit(R('ERR_MISSING_PARAMETER', msg => "Missing the 'algo' or 'size' parameter'"));
}
$fnret or osh_exit $fnret;

16
doc/sphinx/administration/logs.rst
View file

@ -93,8 +93,8 @@ plugin
accountsql
This field will contain either:
- ok: when :ref:`bastion_conf_enableAccountSqlLog` is enabled, and we successfully inserted a new row for the log
- no: when :ref:`bastion_conf_enableAccountSqlLog` is disabled
- ok: when :ref:`enableAccountSqlLog` is enabled, and we successfully inserted a new row for the log
- no: when :ref:`enableAccountSqlLog` is disabled
- error: when we couldn't insert a new row, **error** followed by a detailed error message, for example "error SQL error [global] err 8 while doing [inserting data (execute)]: attempt to write a readonly database".
globalsql
@ -364,7 +364,7 @@ Syslog
======
Files location
--------------
**************
If you use ``syslog-ng`` and installed the provided templates (which is the default if you used the ``--new-install`` option to the install script), you'll have 4 files in your system log directory:
@ -381,7 +381,7 @@ If you use ``syslog-ng`` and installed the provided templates (which is the defa
This is where all the satellite scripts (mostly found in the ``bin/cron/`` directory) will log their output.
Log format
----------
**********
A syslog message will always match the following generic format::
@ -406,7 +406,7 @@ If you don't or can't use :ref:`syslog`, the bastion can create and use access l
These access logs will only contain :ref:`log_open` and :ref:`log_close` log types, which can be seen as "access logs". All the other log types, such as :ref:`log_warn`, :ref:`log_membership`, etc. are only logged through syslog.
These logs are enabled through the :ref:`bastion_conf_enableGlobalAccessLog` and :ref:`bastion_conf_enableAccountAccessLog` options.
These logs are enabled through the :ref:`enableGlobalAccessLog` and :ref:`enableAccountAccessLog` options.
enableGlobalAccessLog
When enabled, a single log file will be used, located in :file:`/home/logkeeper/global-log-YYYYMM.log`. There will be one file per month. Note that it can grow quite large if you have a busy bastion.
@ -419,19 +419,19 @@ If both options are enabled, it means that every access log will be logged twice
SQLite logs
===========
If you want to store access logs into local sqlite databases, you can enable either :ref:`bastion_conf_enableGlobalSqlLog`, :ref:`bastion_conf_enableAccountSqlLog`, or both.
If you want to store access logs into local sqlite databases, you can enable either :ref:`enableGlobalSqlLog`, :ref:`enableAccountSqlLog`, or both.
enableGlobalSqlLog
When enabled, a global sqlite database will be created in :file:`/home/logkeeper/global-log-YYYYMM.sqlite`. It'll contain one row per access (created at the same time the :ref:`log_open` log is emitted). The following columns exist: id, timestamp, account, cmdtype, allowed, ipfrom, ipto, portto, user, plugin, uniqid. Refer to the :ref:`log_open` log description to get the meaning of each column.
enableAccountSqlLog
When enabled, an sqlite database per account will be created in :file:`/home/USER/USER-log-YYYYMM.sqlite`. It'll contain one row per access (created at the same time the :ref:`log_open` log is emitted), and the same row will be updated by the :ref:`log_close` event when it is emitted. The following columns exist: id, timestamp, timestampusec, account, cmdtype, allowed, hostfrom, ipfrom, bastionip, bastionport, hostto, ipto, portto, user, plugin, ttyrecfilee, params, timestampend, timestampendusec, returnvalue, comment, uniqid. Refer to the :ref:`log_open` log and :ref:`log_close` log descriptions to get the meaning of each column. Note that the :ref:`bastion_conf_enableAccountSqlLog` option is required if you want the :doc:`/plugins/open/selfListSessions` and :doc:`/plugins/open/selfPlaySession` plugins to work, as they use this database.
When enabled, an sqlite database per account will be created in :file:`/home/USER/USER-log-YYYYMM.sqlite`. It'll contain one row per access (created at the same time the :ref:`log_open` log is emitted), and the same row will be updated by the :ref:`log_close` event when it is emitted. The following columns exist: id, timestamp, timestampusec, account, cmdtype, allowed, hostfrom, ipfrom, bastionip, bastionport, hostto, ipto, portto, user, plugin, ttyrecfilee, params, timestampend, timestampendusec, returnvalue, comment, uniqid. Refer to the :ref:`log_open` log and :ref:`log_close` log descriptions to get the meaning of each column. Note that the :ref:`enableAccountSqlLog` option is required if you want the :doc:`/plugins/open/selfListSessions` and :doc:`/plugins/open/selfPlaySession` plugins to work, as they use this database.
Note that enabling these on a very busy bastion (several new connections per second) can create lock contention, especially on the global log: ensure you have a fast storage. In any case, if a connection can't get the lock after a few seconds, it'll proceed anyway, and skip writing the sql log. In that case, if you enabled syslog or local access logs, the **globalsql** and/or the **accountsql** field will contain the error detail.
Terminal recordings (*ttyrec*)
==============================
Every egress connection is started under ``ttyrec``, which means that everything appearing on the console is recorded. If a password is asked by some program, for example, and typing the password prints '*' or doesn't print anything at all, this won't be recorded. This is by design. In other words, the keystrokes are not recorded, except if they produce something on the screen. The ttyrec files location is always :file:`/home/USER/ttyrec/REMOTEIP/file.ttyrec`, where the actual `file.ttyrec` name can be configured by the :ref:`bastion_conf_ttyrecFilenameFormat` option. By default, it'll contain the date, time, account, remote ip, port and user used to start the egress connection, as well as the uniqid, for easier correlation between all the logs produced by the same connection. Note that for long connections, or connections producing a lot of output, ttyrec files will be transparently rotated, without interrupting the connection. This is to avoid ending up with ttyrec files of several gigabytes that would still be opened, written to, hence impossible to compress, encrypt, and push to an escrow filer. The uniqid will be the same for all the ttyrec files corresponding to the same connection.
Every egress connection is started under ``ttyrec``, which means that everything appearing on the console is recorded. If a password is asked by some program, for example, and typing the password prints '*' or doesn't print anything at all, this won't be recorded. This is by design. In other words, the keystrokes are not recorded, except if they produce something on the screen. The ttyrec files location is always :file:`/home/USER/ttyrec/REMOTEIP/file.ttyrec`, where the actual `file.ttyrec` name can be configured by the :ref:`ttyrecFilenameFormat` option. By default, it'll contain the date, time, account, remote ip, port and user used to start the egress connection, as well as the uniqid, for easier correlation between all the logs produced by the same connection. Note that for long connections, or connections producing a lot of output, ttyrec files will be transparently rotated, without interrupting the connection. This is to avoid ending up with ttyrec files of several gigabytes that would still be opened, written to, hence impossible to compress, encrypt, and push to an escrow filer. The uniqid will be the same for all the ttyrec files corresponding to the same connection.
To play ttyrec files, you can either use :doc:`/plugins/open/selfPlaySession` for yourself, or, for admins having local access to the bastion machine, the ``ttyplay`` program can be used. Another software, perhaps more powerful than ttyplay, can also be used: `IPBT <https://www.chiark.greenend.org.uk/~sgtatham/ipbt/>`_ (`wiki <https://nethackwiki.com/wiki/IPBT>`_), aka "It's PlayBack Time", by the PuTTY author. It can do more advanced things such as look for words appearing on any frame recorded in the ttyrec file, play files using a logarithmic speed, or display an OSD with the exact time output you're seeing has appeared. As ttyrec is a well-known format that has been around for a while, there are a bunch of other programs you can use to read or convert these files.

2
doc/sphinx/build-plugins-help.sh
View file

@ -26,6 +26,8 @@ mkdir doc/sphinx/plugins
export PLUGIN_QUIET=1
export PLUGIN_HELP=1
export PLUGIN_DOCGEN=1
export ANSI_COLORS_DISABLED=1
for pluginfile in $(find bin/plugin -executable -type f -print)
do

2
doc/sphinx/installation/basic.rst
View file

@ -47,7 +47,7 @@ Other BSD variants partially work but are unsupported and discouraged as they ha
- OpenBSD 5.4+
- NetBSD 7+
In any case, you are expected to install this on a properly secured machine (including, but not limited to: ``iptables``/``pf``, reduced-set of installed software and daemons, general system hardening, etc.). If you use Debian, following the `CIS Hardening guidelines <https://www.cisecurity.org/benchmark/debian_linux/>`_ is a good start. We have a `tool <https://github.com/ovh/debian-cis`_ to check for compliance against these guidelines. If you use Debian and don't yet have your own hardened template, this script should help you getting up to speed, and ensuring your hardened host stays hardened over time, through a daily audit you might want to setup through cron.
In any case, you are expected to install this on a properly secured machine (including, but not limited to: ``iptables``/``pf``, reduced-set of installed software and daemons, general system hardening, etc.). If you use Debian, following the `CIS Hardening guidelines <https://www.cisecurity.org/benchmark/debian_linux/>`_ is a good start. We have `a tool <https://github.com/ovh/debian-cis>`_ to check for compliance against these guidelines. If you use Debian and don't yet have your own hardened template, this script should help you getting up to speed, and ensuring your hardened host stays hardened over time, through a daily audit you might want to setup through cron.
Great care has been taken to write secure, tested code, but of course this is worthless if your machine is a hacker highway. Ensuring that all the layers below the bastion code (the operating system and the hardware it's running on) is your job.

26
doc/sphinx/plugins/group-owner/groupDelEgressKey.rst Normal file
View file

@ -0,0 +1,26 @@
==================
groupDelEgressKey
==================
Remove a bastion group egress key
=================================
.. admonition:: usage
:class: cmdusage
--osh groupDelEgressKey <--group GROUP> <--id ID>
.. program:: groupDelEgressKey
.. option:: --group GROUP
Name of the group to delete the egress key from
.. option:: --id ID
Specify the key ID to delete, you can get it with groupInfo

58
doc/sphinx/plugins/group-owner/groupGenerateEgressKey.rst Normal file
View file

@ -0,0 +1,58 @@
=======================
groupGenerateEgressKey
=======================
Create a new public + private key pair for a group
==================================================
.. admonition:: usage
:class: cmdusage
--osh groupGenerateEgressKey --group GROUP --algo ALGO --size SIZE [--encrypted]
.. program:: groupGenerateEgressKey
.. option:: --group GROUP
Group name to generate a new egress key for.
.. option:: --algo ALGO
Specifies the algo of the key, either rsa, ecdsa or ed25519.
.. option:: --size SIZE
Specifies the size of the key to be generated.
For RSA, choose between 2048 and 8192 (4096 is good).
For ECDSA, choose either 256, 384 or 521.
For ED25519, size is always 256.
.. option:: --encrypted
If specified, a passphrase will be prompted for the new key
Note that the actually available algorithms on a bastion depend on the underlying OS and the configured policy.
A quick overview of the different algorithms::
+---------+------+----------+-------+-----------------------------------------+
| algo | size | strength | speed | compatibility |
+=========+======+==========+=======+=========================================+
| DSA | any | 0 | n/a | obsolete, do not use |
| RSA | 2048 | ** | ** | works everywhere |
| RSA | 4096 | *** | * | works almost everywhere |
| ECDSA | 521 | **** | ***** | OpenSSH 5.7+ (Debian 7+, Ubuntu 12.04+) |
| Ed25519 | 256 | ***** | ***** | OpenSSH 6.5+ (Debian 8+, Ubuntu 14.04+) |
+---------+------+----------+-------+-----------------------------------------+
This table is meant as a quick cheat-sheet, you're warmly advised to do
your own research, as other constraints may apply to your environment.

2
doc/sphinx/plugins/group-owner/index.rst
View file

@ -8,8 +8,10 @@ group-owner plugins
groupAddGatekeeper
groupAddOwner
groupDelAclkeeper
groupDelEgressKey
groupDelGatekeeper
groupDelOwner
groupGenerateEgressKey
groupGeneratePassword
groupModify
groupTransmitOwnership

56
lib/perl/OVH/Bastion/Plugin/generateEgressKey.pm
View file

@ -9,40 +9,42 @@ use OVH::Result;
use OVH::Bastion;
use OVH::Bastion::Plugin qw{ :DEFAULT };
sub help {
sub help_algos {
require Term::ANSIColor;
my $fnret = OVH::Bastion::get_supported_ssh_algorithms_list(way => 'egress');
my @algoList = @{$fnret->value};
my $algos = Term::ANSIColor::colored(uc join(' ', @algoList), 'green');
my $helpAlgoSize = '--algo rsa --size 4096';
if (grep { $_ eq 'ecdsa' } @algoList) {
$helpAlgoSize = '--algo ecdsa --size 521';
# when generating documentation, don't talk about "this" bastion, be generic
if ($ENV{'PLUGIN_DOCGEN'}) {
osh_info <<"EOF";
Note that the actually available algorithms on a bastion depend on the underlying OS and the configured policy.
A quick overview of the different algorithms::
EOF
}
if (grep { $_ eq 'ed25519' } @algoList) {
$helpAlgoSize = '--algo ed25519';
}
osh_info <<"EOF";
Create a new public + private key pair. The private key will stay on this bastion.
Usage: --osh $scriptName $helpAlgoSize [--encrypted]
--algo ALGO Specifies the algo of the key, either rsa, ecdsa or ed25519.
--size SIZE Specifies the size of the key to be generated.
For RSA, choose between 2048 and 8192 (4096 is good).
For ECDSA, choose either 256, 384 or 521.
For ED25519, size is always 256.
--encrypted if specified, a passphrase will be prompted for the new key
else {
osh_info <<"EOF";
With the policy and SSH version on this bastion,
the following algorithms are supported: $algos
the following algorithms are supported: $algos.
algo size strength speed compatibility
------- ---- ---------- -------- -----------------------
RSA 4096 good slow works everywhere
ECDSA 521 strong fast debian7+ (OpenSSH 5.7+)
ED25519 256 verystrong veryfast debian8+ (OpenSSH 6.5+)
A quick overview of the different algorithms:
EOF
}
osh_info <<"EOF";
+---------+------+----------+-------+-----------------------------------------+
| algo | size | strength | speed | compatibility |
+=========+======+==========+=======+=========================================+
| DSA | any | 0 | n/a | obsolete, do not use |
| RSA | 2048 | ** | ** | works everywhere |
| RSA | 4096 | *** | * | works almost everywhere |
| ECDSA | 521 | **** | ***** | OpenSSH 5.7+ (Debian 7+, Ubuntu 12.04+) |
| Ed25519 | 256 | ***** | ***** | OpenSSH 6.5+ (Debian 8+, Ubuntu 14.04+) |
+---------+------+----------+-------+-----------------------------------------+
This table is meant as a quick cheat-sheet, you're warmly advised to do
your own research, as other constraints may apply to your environment.
EOF
return 0;
}