gatoshell

installation

To actually use the shell – you need to run as root (default) or as a user which has access to the local socket. This application is not provided as a Docker container since it needs local socket access, but it can be wrapped in one of the slim Ubuntu or CentOS containers if needed. Alpine Linux will not work since the glib does not contain the needed encryption support.

By default, only root-level accounts can run the application locally. To allow other users – create a log reader group and give access to the /opt/gatoserverd/gatoserverd.sock file to it.

In some installations – it may be a good idea to create a unique user for reading logs and switch the login shell to the gatoshell. Doing this allows logs to be read without using the default root or admin account. This will require creating a group for log readers and granting access to /opt/gatoserverd/gatoserverd.sock.

You can also run gatoshell remotely by provisioning a certificate in your home directory. This is covered in a separate section below.

Ubuntu and other Debian-based Distributions

curl -1sLf 'https://dl.cloudsmith.io/public/caprica-llc/gatodebian/setup.deb.sh' | sudo -E bash

apt-get install gatoshell

CentOS and other RPM-based distributions

curl -1sLf 'https://dl.cloudsmith.io/public/caprica-llc/gatorpm/setup.rpm.sh' | sudo -E bash

rpm -ivh gatoshell

client provisioning quickstart

Each system will require a certificate exchange with the server process. You can perform this following the interactive shell steps detailed in the documentation, or through the shell.

Each gatod system and remote client will need a copy of the server certificate. You can generate a copy of this from the shell with

gatoshell -e rootca > rootca.crt

Copy this file to the /etc/gatod/ directory for gatod, or to your ~/.gatoshell directory as the name prompted during setup. Clients also need a countersigned certificate from the server – for this it’s simplest to copy and paste the request from the client into the application. Copy the text by selecting with your mouse, and put into the clipboard of your system by clicking the left mouse button on Linux systems, and the right button on Microsoft Windows operating systems.

Run the licensing operation:

gatoshell -e license

It will prompt for a license request – paste it and a signed certificate will be printed. Save that text as /etc/gatod/gatod.crt for gatod, or for gatoshell remote access save as the prompted name.

running gatoshell

The packages land the binary in /usr/sbin since it is not for general use. As an authorized user – just run gatoshell from the terminal. Gatoshell is an interactive terminal that uses GatoScript as an interface. Shell commands can also be passed at the command line with the -e option.

commands

help

Dumps out a list of supported commands and a brief help text on the current version

help

exit         exit the program
help         display help
info         Get server status  
license      create key to allow a client to access the main server  
lock         lock the server  
unlock       unlock the server
ping         ping server process  
q            query the log  
redact       Redact (overwrite securely) a single log item  
rootca       Get root CA certificate (save as gatoserverd.crt)  
mkpem        Generate a public/private key pair for encrypting data  
setpem       Load an encryption key just for this session (not persistent)  
shred        Shred the log - must be done interactively

clear

Resets the current terminal (if possible). Some pseudoterminals do not correctly implement these control codes (often freeware ssh clients for operating systems other than Linux).

exit

Immediately exits the program with return code 0.

info

Queries the server for version and licensing info and prints on the screen. Blocked if log is locked.

Current Clients: 0
License Expires: 2022-09-23 10:31:47.750537451 +0000 UTC
Version: gatod copyright © 2021 caprica llc tx - all right reserved - 1.9999

license

Uploads a license file from https://shop.loggingato.com to unlock more seats. The server has two free non-production seats included for free. Cut and paste the ASCII text to upload to the server.

lock

This command will ‘freeze’ the system until rebooted or the prompted password is entered. This provides a method to lock a VPS from prying while you are disconnected, if the same password is active no one else has connected.

To lock the server:

Lock String: 
Again: 
Locked server.

Any other queries without an unlock will fail.

gatoshell copyright © 2021 caprica llc tx - all right reserved - 1.9999
>>> q
locked

unlock

Will prompt for an unlock password – if successfully entered the system is enabled.

gatoshell copyright © 2021 caprica llc tx - all right reserved - 1.9999
>>> q
locked
>>> unlock
Unlock String: 
ok
>>> info
Max clients: 59
Current Clients: 0
License Expires: 2022-09-23 10:31:47.750537451 +0000 UTC

ping

Ping will perform a connectivity check on the server (done implicit by login). Will return copyright string.

query/q

This command will query the log. There are several optional parameters you can add – by default it just shows the latest (tail) of the log.

live/i – will give a live stream of updates (tail -f)
limit=n – will limit the number of results, defaults 20
app=s – searches only for entries from this app
keyword=s – searches for this string or string fragments in the messages. Note that for records encrypted with public key locks, the server cannot search for keywords since it’s not able to read the records once written.
start=date – searches from this date/time
end=date – searches to this date time

RNO                                 TS        Node       X         IP          App                              Message   
1763 2021-09-23 19:21:35 -0500 CDT  00000     127.0.0.1  0         gatoserverd  admin has unlocked the console. 
1764 2021-09-23 19:21:37 -0500 CDT  00000     127.0.0.1  0         gatoserverd  admin `info`                    
>>>

redact

Redacts allows you to do controlled redactions of the log – for instance when a password or other critical information has leaked into the logging data. Request the record number, and it will be wiped and the change logged to the main log.

RNO   TS        Node       X         IP                                 App            Message   
13238 2021-09-23 19:30:52 -0500 CDT  00000     127.0.0.1  1         /usr/lib/gdm3/gdm-x-session[3169]:  **encrypted** 
13239 2021-09-23 19:30:52 -0500 CDT  00000     127.0.0.1  1         nginx  GET /v2/login?uid=tacocat&password=tacocat 
>>> redact 13239
ok
>>> q limit=3
13238 2021-09-23 19:30:52 -0500 CDT  00000     127.0.0.1  1         /usr/lib/gdm3/gdm-x-session[3169]:  **encrypted** 
13239 2021-09-23 19:30:52 -0500 CDT  00000     127.0.0.1  0         nginx  redacted by admin @ 2021-09-23 19:37:55.201491154 -0500 CDT m=+21.176939703 
13240 2021-09-23 19:34:17 -0500 CDT  00000     127.0.0.1  0         gatoserverd                         admin redact `13239`

shred

This command will perform an seven pass overwrite of the logging database by writing random data to the records, deleting the database as well as losing all record of the original encryption keys before regenerating new ones. This may take an extremely long time depending on your database size and no logging can occur.

Generally – this is something you would want to do only when decommissioning a system.

rootca

This will print to the screen the certificate of the logging server, which is needed by the data collector services to connect.

setpem

This command loads the private key needed to decode shrouded data in the logs. The software allows you to encrypt or shroud some sensitive records to prevent some users from seeing them. Shrouded records appear as placeholder text if the correct key is not loaded. The key must be in the current directory and is not sent to the server.

Generally – you will want to use the password lock on the key, and in some cases you may want to delete the key and store offline until needed. If the key is encrypted – you will be prompted for the password to open it.

mkpem

Will generate a key for encrypting some or all records in your logging table. Optionally you make add a password to this key (just hit enter for an empty password). After generating – the console will display a block that must be added to your server configuration file to encrypt the records. The shell cannot modify the server settings – only the system root user can change them.

Note: The key is encrypted with a custom algorithm and will not be readable. Regular PEM encryption is vulnerable to padding oracle attacks (RFC1423) and is not used.