Skip to main content

Configuration and Setup

tiCrypt Audit requires three configuration files:

  • /etc/tiaudit/tiaudit.toml for the tiaudit service

  • /etc/tiaudit/log-streamer.toml for the tiaudit-logger service

  • /etc/tiaudit/log-uploader.toml for the tiaudit-log-uploader program

The configuration files are very similar. Some of the information has to be repeated in each configuration file.

The types of values used in the description of parameters are:

TypeExampleDescription
String"an example"String value
Booltrue, falseBoolean value
Int42Whole number value
Port22Number between 0 and 65535
Size16 MiB, 3 GBFile size with unit of measure
ArrString["a", "b", "c"]List/Array of string values

tiAudit Service Configuration

/etc/tiaudit/tiaudit.toml

This is the configuration file for the tiaudit service.

ParameterTypeRequiredDescription
hostnameStringThe hostname for the server
portPortPort for the server
baseURLStringThe URL as seen from outside
geoipStringSee geo
managemeng-dbStringPath to user management file
[sessions]SectionSee below
[clickhouse]SectionSee clickhouse
[smtp]SectionSee smtp
info

If you deploy using Nginx, you should set hostname = "localhost" and make sure baseURL points to the external URI set in Nginx and that port has the same value as in the configuration file /etc/nginx/conf.d/audit.ticrypt.conf

By setting management-db="/var/log/tiaudit/management.db", you make use of the preparations in the rest of this document.

Session Management Secrets

[sessions] sub-section

This is a critical subsection that specifies secrets for session management.

caution

If you do not set or change these values, the old COOKIES will be invalid and you will have to ask users to delete the existing cookies manually — an unpleasant process.

ParameterTypeRequiredDescription
authKeyString64 byte Base64 secret
encryptionKeyString32 byte Base64 secret

Generate authKey using:

openssl rand -base64 64

and encryptionKey with:

openssl rand -base64 32
note

If the authKey and encryptionKey have the wrong size, tiaudit cannot use them.

tiAudit Logger Configuration

/etc/tiaudit/log-streamer.toml

This is the configuration file for tiaudit-logger service.

ParameterTypeRequiredDescription
hostnameStringThe hostname to listen on
portPortPort to listen on
geoipStringSee geo
ipFallbackStringIP to use if geo-location fails.
[clickhouse]SectionSee clickhouse
[smtp]SectionSee smtp
[drivers]SectionSee drivers

tiAudit Log-Uploader Configuration

/etc/tiaudit/log-uploader.toml

This is the configuration file for tiaudit-log-uploader executable.

ParameterTypeRequiredDescription
batchIntBatch size
geoipStringSee geo
ipFallbackStringIP to use if geo-location fails.
[clickhouse]SectionSee clickhouse
[smtp]SectionSee smtp
[drivers]SectionSee drivers
info

The batch parameter tells the uploader how "aggressive" to be. Writes into Clickhouse are much faster if larger batches are used. This should be at least 10,000.

Common Configuration Options

note

Some configurations are common to all three configuration files.

Geolocation

ParameterTypeRequiredDescription
geoipStringLocation of GeoIP2 .mmdb file
note

If geoip is not set, geo-location is not available.

Clickhouse Database

section [clickhouse]

The [clickhouse] section specifies how to access the Clickhouse database. There are two options:

  1. Specify the uri parameter with complete information

  2. Specify some of the other parameters

caution

This information needs to be identical in all 3 configuration files.

ParameterTypeRequiredDescription
uriStringThe Clickhouse URI
schemetcp,udpType of communication, default TCP
usernameStringThe Clickhouse user name
passwordStringThe corresponding password
hostStringFormat host:port, default localhost:9000
databaseStringThe Clickhouse database

If the Clickhouse database is installed on the same server as tiCrypt Audit and the firewall blocks access to port 9000, and the server only allows access to admins, you do not need to set up any parameter except database.

Email Sending

section [smtp]

The alert subsystem finds important events in the tiCrypt event log. When such alerts are raised, one possible action is to send emails to interested parties. This section configures email sending through an SMTP server.

If the email driver is used, this section has to be present, otherwise, no emails can be sent.

ParameterTypeRequiredDescription
serverStringThe SMTP server
portPortThe SMTP port
usernameStringThe SMTP user name
passwordStringThe SMTP user password
fromStringFrom email address
toArrStringList of emails to sent to
ccArrStringSame but CCed
bccArrStringSame but BCCed

We recommend that you set up a special account for tiCrypt Audit rather than use an existing account.

Use the to, cc and bcc parameters to determine who is getting emails and in what form.

Drivers

section [drivers]

The drivers allow tiCrypt Audit to push alerts outside the system. Three types of drivers are supported as of version 1.4.0: print, email and Splunk.

All the drivers have to be in a section [drivers.name_of_driver] where name_of_driver has to be unique across all the drivers.

Provide meaningful names for the drivers.

An easy way to disable a driver is to set disabled = true rather than remove it from the configuration file.

The print driver displays alerts on the screen. This is not useful for tiaudit-logger service but it is useful for the tiaudit-log-uploader program.

ParameterTypeRequiredDescription
typeprintType of driver
disabledBoolIs the driver disabled?
encodingStringEncoding (e.g. text/plain)
destStringDestination: stderr or stdout

Email driver

The email driver assumes that tiCrypt Audit can send emails, i.e. that [smtp] section is set up correctly.

ParameterTypeRequiredDescription
typesmtpType of driver
disabledBoolIs the driver disabled?
encodingStringEncoding (e.g. text/plain)
fromStringFrom field. E.g. server@example.com
toArrStringE.g. [ "monitoring@example.com" ]
serverStringE.g smtp.example.com
portPortDefault: 587
usernameStringSMTP user name
passwordStringSMTP password
max-retriesIntHow many times to retry

Splunk driver

The splunk driver allows integration with Splunk.

ParameterTypeRequiredDescription
typesmtpType of driver
disabledBoolIs the driver disabled?
urlStringThe Splunk collection point
tokenStringThe Splunk token
certifiedBoolSet to false to disable TLS certificate check
sourceStringSplunk source, e.g. tiCrypt
sourceTypeStringSplunk source type, e.g. tiCryptAlert
indexStringSplunk index, default main

tiCrypt Audit pushes JSON alerts to Splunk. They have an easy-to-understand structure.

Nginx integration

In order for tiCrypt Audit application to be delivered, Nginx needs to be configured to send the traffic to the tiaudit service.

The following configuration file is based on Mozilla’s SSL Configuration Generator.

We assume that:

  • The tiCrypt server is abailable at tiaudit.example.com

  • The tiaudit service runs on port 8081

  • The TLS/SSL combined certificate and chain is stored in /etc/pki/tls/certs/example-stacked.crt

  • The TLS/SSL trust chain is stored in /etc/pki/tls/certs/example-chain.crt

  • The TLS/SSL key is stored in: /etc/pki/tls/private/example.key

Create the file /etc/nginx/conf.d/audit.ticrypt.conf with content similar to:

map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}

upstream audit-backend {
server 127.0.0.1:8081;
}

server {
listen 443 ssl;
server_name audit.example.com;
root /var/www/ticrypt-audit;

ssl_certificate /etc/pki/tls/certs/example-stacked.crt;
ssl_certificate_key /etc/pki/tls/private/example.pem;

ssl_session_timeout 1d;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_dhparam /etc/pki/tls/dhparam.pem;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;

#add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Content-Security-Policy "script-src 'unsafe-inline' 'unsafe-eval' 'self' https://code.getmdl.io; frame-ancestors 'self' http://127.0.0.1:*";

ssl_session_tickets off;
location / {
try_files $uri @proxy;
}

location @proxy {
proxy_pass http://audit-backend;
proxy_redirect off;
proxy_buffering off;
proxy_cache off;
proxy_http_version 1.1;
proxy_read_timeout 900s;
proxy_connect_timeout 360s;
proxy_send_timeout 360s;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Ssl on;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}

You need to customize the values for your situation.

The above config file assumes that the TLS/SSL certificate is stacked. A stacked/bundled certificate is the concatenation of the actual certificate and the local certificate authority chain of certificates. ow, we just just have few more steps:

# Create the static directory for tiCrypt REST
mkdir -p /var/www/ticrypt-rest
# Verify the TLS certificate
openssl x509 -in /etc/pki/tls/certs/example-stacked.crt -text -noout
# Verify the TLS private key
openssl rsa -in /etc/pki/tls/private/example.pem -check

If your certificate or the private key is not correct, Nginx will not start. Check the validity before restarting Nginx

Some critical things that remain are:

# Create or download non-standard Diffie-Hellman parameters.
# Alternatively generate new ones yourself:
openssl dhparam -outform pem -out /etc/pki/tls/dhparam.pem 2048
# Or download from Mozilla:
curl https://ssl-config.mozilla.org/ffdhe2048.txt > /etc/pki/tls/dhparam.pem

# Tell SELinux that Nginx can connect
setsebool -P httpd_can_network_connect=true

Now we can restart Nginx:

systemctl restart nginx

Loading the logs

Everything should now be ready for loading the history and starting the live log loading.

We assume that the tiCrypt log files are in /var/log/ticrypt. If you imported the logs from another server just place the files, unchanged, somewhere.

Do not unpack existing archived log files. The log uploader is capable of understanding compressed and uncompressed files.

As long as you have access to the log files, you do not need to be root to run the loading command

# Load the tiCrypt history
tiaudit-log-uploader -c /etc/tiaudit/log-uploader.toml /var/log/ticrypt

The process will take anywhere from few seconds to several minutes depending on the log size. Statistics will be printed at the end on the number of events of each type processed and the number of errors. Make sure no errors are reported.

Now, we can start the logger service

systemctl start tiaudit
systemctl start tiaudit-logger

Verify that everything is fine:

systemctl status tiaudit
systemctl status tiaudit-logger

Create the first user/admin

Initially, there is no user in tiCrypt Audit application. None of the functionality except registration is available without user accounts.

User registration can be be performed based on invitations. To create the first invitation for user me@example.com (upon registration, this account becomes an admin account) do:

sudo -u tiaudit tiaudit -c /etc/tiaudit/tiaudit.toml -i me@example.com

It is important not to run tiaudit as root since it will set the wrong permissions on the database file and the tiaudit service will not be able to write data.

One of the last lines displayed looks like:

2020/05/25 16:27:55 URL: https://tiaudit.example.com/?email=me@example.com&invite=JWL8-3y2XCX_rg7LGpBG8gJdaTdeTMJGOS5bLrhdrdkK

Ignore the error about binding.

Cut-and-paste the URL into a web browser. Now that the tiaudit service is running, it should take you to the registration page with the "Email" field already filled in. Fill in the information and verify that you can log in and that you are an admin.

If you lose your password, follow the same process to get a valid invitation. You can then change the password. This process will not make you an admin if you are not already.