configure

title: "Configuration and Setup" description: "Introduction to tiCrypt audit server" lead: "This section provides information on how to configure tiCrypt Adudit" date: 2021-01-08 11:30:57 lastmod: 2021-01-08 11:31:01 draft: false images: [] menu: docs: parent: "s-audit" identifier: "sa-config" weight: 30 toc: true ---

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:

Type	Example	Description
*String*	"an example"	String value
*Bool*	true, false	Boolean value
*Int*	42	Whole number value
*Port*	22	Number between 0 and 65535
*Size*	16 MiB, 3 GB	File size with unit of measure
*ArrString*	["a", "b", "c"]	List/Array of string values

`/etc/tiaudit/tiaudit.toml`

This is the configuration file for the tiaudit service.

Parameter	Type	Required	Description
`hostname`	*String*	Required	The hostname for the server
`port`	*Port*	Required	Port for the server
`baseURL`	*String*	Required	The URL as seen from outside
`geoip`	*String*	Optional	See [geo]
`managemeng-db`	*String*	Required	Path to user management file
`[sessions]`	*Section*	Required	See below
`[clickhouse]`	*Section*	Required	See [clickhouse]
`[smtp]`	*Section*	Optional	See [smtp]

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.

`[sessions]` sub-section

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

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.

Parameter	Type	Required	Description
`authKey`	*String*	Required	64 byte Base64 secret
`encryptionKey`	*String*	Required	32 byte Base64 secret

Generate authKey using:

openssl rand -base64 64

and encryptionKey with:

openssl rand -base64 32

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

`/etc/tiaudit/log-streamer.toml`

This is the configuration file for tiaudit-logger service.

Parameter	Type	Required	Description
`hostname`	*String*	Required	The hostname to listen on
`port`	*Port*	Required	Port to listen on
`geoip`	*String*	Optional	See [geo]
`ipFallback`	*String*	Optional	IP to use if geo-location fails.
`[clickhouse]`	*Section*	Required	See [clickhouse]
`[smtp]`	*Section*	Optional	See [smtp]
`[drivers]`	*Section*	Required	See [drivers]

`/etc/tiaudit/log-uploader.toml`

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

Parameter	Type	Required	Description
`batch`	*Int*	Optional	Batch size
`geoip`	*String*	Optional	See [geo]
`ipFallback`	*String*	Optional	IP to use if geo-location fails.
`[clickhouse]`	*Section*	Required	See [clickhouse]
`[smtp]`	*Section*	Optional	See [smtp]
`[drivers]`	*Section*	Required	See [drivers]

The batch parameter tells the uploadder 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

Some configurations are common to all three configuration files.

Geolocation

Parameter	Type	Required	Description
`geoip`	*String*	Optional	Location of GeoIP2 `.mmdb` file

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

Clickhouse: section `[clickhouse]`

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

specify the uri parameter with complete information
specify some of the other parameters

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

Parameter	Type	Required	Description
`uri`	*String*	Optional	The Clickhouse URI
`scheme`	tcp, udp	Optional	Type of communication, default TCP
`username`	*String*	Optional	The Clickhouse user name
`password`	*String*	Optional	The corresponding password
`host`	*String*	Optional	Format `host:port`, default `localhost:9000`
`database`	*String*	Optional	The Clickhouse database.

If the Clickhouse database is installed on the same server as tiCrypt Audit and 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 find 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.

Parameter	Type	Required	Description
`server`	*String*	Optional	The SMTP server
`port`	*Port*	Optional	The SMTP port
`username`	*String*	Optional	The SMTP user name
`password`	*String*	Optional	The SMTP user password
`from`	*String*	Optional	From email address
`to`	*ArrString*	Optional	List of emails to sent to
`cc`	*ArrString*	Optional	Same but CCed
`bcc`	*ArrString*	Optional	Same 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.

Print driver

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.

Parameter	Type	Required	Description
`type`	`print`	Required	Type of driver
`disabled`	*Bool*	Required	Is the driver disabled?
`encoding`	*String*	Optional	Encoding (e.g. `text/plain`)
`dest`	*String*	Optional	Destination: `stderr` or `stdout`

Email driver

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

Parameter	Type	Required	Description
`type`	`smtp`	Required	Type of driver
`disabled`	*Bool*	Required	Is the driver disabled?
`encoding`	*String*	Optional	Encoding (e.g. `text/plain`)
`from`	*String*	Optional	From field. E.g. `server@example.com`
`to`	*ArrString*	Required	E.g. `[ "monitoring@example.com" ]`
`server`	*String*	Required	E.g `smtp.example.com`
`port`	*Port*	Optional	Default: `587`
`username`	*String*	Required	SMTP user name
`password`	*String*	Requred	SMTP password
`max-retries`	*Int*	Optional	How many times to retry

Splunk driver

The splunk driver allows integration with Splunk.

Parameter	Type	Required	Description
`type`	`smtp`	Required	Type of driver
`disabled`	*Bool*	Required	Is the driver disabled?
`url`	*String*	Required	The Splunk collection point
`token`	*String*	Required	The Splunk `token`
`certified`	*Bool*	Optional	Set to `false` to disable TLS certificate check.
`source`	*String*	Required	Splunk source, e.g. `tiCrypt`
`sourceType`	*String*	Required	Splunk source type, e.g. `tiCryptAlert`
`index`	*String*	Optional	Splunk 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 un-compressed 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 in 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 loose 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.

/etc/tiaudit/tiaudit.toml

[sessions] sub-section​

/etc/tiaudit/log-streamer.toml

/etc/tiaudit/log-uploader.toml