Configuration and Setup
tiCrypt Audit requires three configuration files:
/etc/tiaudit/tiaudit.toml
for thetiaudit
service/etc/tiaudit/log-streamer.toml
for thetiaudit-logger
service/etc/tiaudit/log-uploader.toml
for thetiaudit-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 |
tiAudit Service Configuration
/etc/tiaudit/tiaudit.toml
This is the configuration file for the tiaudit
service.
Parameter | Type | Required | Description |
---|---|---|---|
hostname | String | ✅ | The hostname for the server |
port | Port | ✅ | Port for the server |
baseURL | String | ✅ | The URL as seen from outside |
geoip | String | See geo | |
managemeng-db | String | ✅ | Path to user management file |
[sessions] | Section | ✅ | See below |
[clickhouse] | Section | ✅ | See clickhouse |
[smtp] | Section | 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.
Session Management Secrets
[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 | ✅ | 64 byte Base64 secret |
encryptionKey | String | ✅ | 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.
tiAudit Logger Configuration
/etc/tiaudit/log-streamer.toml
This is the configuration file for tiaudit-logger
service.
Parameter | Type | Required | Description |
---|---|---|---|
hostname | String | ✅ | The hostname to listen on |
port | Port | ✅ | Port to listen on |
geoip | String | See geo | |
ipFallback | String | IP to use if geo-location fails. | |
[clickhouse] | Section | ✅ | See clickhouse |
[smtp] | Section | See smtp | |
[drivers] | Section | ✅ | See drivers |
tiAudit Log-Uploader Configuration
/etc/tiaudit/log-uploader.toml
This is the configuration file for tiaudit-log-uploader
executable.
Parameter | Type | Required | Description |
---|---|---|---|
batch | Int | Batch size | |
geoip | String | See geo | |
ipFallback | String | IP to use if geo-location fails. | |
[clickhouse] | Section | ✅ | See clickhouse |
[smtp] | Section | See smtp | |
[drivers] | Section | ✅ | See drivers |
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
Some configurations are common to all three configuration files.
Geolocation
Parameter | Type | Required | Description |
---|---|---|---|
geoip | String | Location of GeoIP2 .mmdb file |
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:
Specify the
uri
parameter with complete informationSpecify some of the other parameters
This information needs to be identical in all 3 configuration files.
Parameter | Type | Required | Description |
---|---|---|---|
uri | String | The Clickhouse URI | |
scheme | tcp,udp | Type of communication, default TCP | |
username | String | The Clickhouse user name | |
password | String | The corresponding password | |
host | String | Format host:port, default localhost:9000 | |
database | String | The 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.
Parameter | Type | Required | Description |
---|---|---|---|
server | String | The SMTP server | |
port | Port | The SMTP port | |
username | String | The SMTP user name | |
password | String | The SMTP user password | |
from | String | From email address | |
to | ArrString | List of emails to sent to | |
cc | ArrString | Same but CCed | |
bcc | ArrString | 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 | ✅ | Type of driver | |
disabled | Bool | ✅ | Is the driver disabled? |
encoding | String | Encoding (e.g. text/plain) | |
dest | String | Destination: stderr or stdout |
Email driver
The email driver assumes that tiCrypt Audit can send emails, i.e. that [smtp]
section is set up correctly.
Parameter | Type | Required | Description |
---|---|---|---|
type | smtp | ✅ | Type of driver |
disabled | Bool | ✅ | Is the driver disabled? |
encoding | String | Encoding (e.g. text/plain) | |
from | String | From field. E.g. server@example.com | |
to | ArrString | ✅ | E.g. [ "monitoring@example.com" ] |
server | String | ✅ | E.g smtp.example.com |
port | Port | Default: 587 | |
username | String | ✅ | SMTP user name |
password | String | ✅ | SMTP password |
max-retries | Int | How many times to retry |
Splunk driver
The splunk
driver allows integration with Splunk.
Parameter | Type | Required | Description |
---|---|---|---|
type | smtp | ✅ | Type of driver |
disabled | Bool | ✅ | Is the driver disabled? |
url | String | ✅ | The Splunk collection point |
token | String | ✅ | The Splunk token |
certified | Bool | Set to false to disable TLS certificate check | |
source | String | ✅ | Splunk source, e.g. tiCrypt |
sourceType | String | ✅ | Splunk source type, e.g. tiCryptAlert |
index | String | 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 port8081
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.