Skip to content
immudb docker run -d --net host -it --name immudb codenotary/immudb:latest

Auditor

The Auditor is a component for checking if immudb was tampered, it’s a good practice to run the auditor as a separate and independent component.

immuclient and immugw are shipped with auditor capabilities.

Running an Auditor with immuclient#

immuclient can act as Auditor by running the following command:

1$ ./immuclient audit-mode
21m0s
3immuclientd 2022/05/22 12:34:11 INFO: starting auditor with a 1m0s interval ...
4immuclientd 2022/05/22 12:34:11 INFO: auditor monitoring HTTP server starting on 0.0.0.0:9477 ...
5immuclientd 2022/05/22 12:34:11 INFO: audit #1 started @ 2022-05-22 12:34:11.543823286 +0200 CEST m=+0.153679785
6immuclientd 2022/05/22 12:34:11 INFO: audit #1 - list of databases to audit has been (re)loaded - 2 database(s) found: [defaultdb mydatabase]
7immuclientd 2022/05/22 12:34:11 INFO: audit #1 - auditing database defaultdb
8immuclientd 2022/05/22 12:34:11 INFO: audit #1 finished in 55.295777ms @ 2022-05-22T12:34:11.599119184+02:00

immuclient is now running on the following address: 0.0.0.0:9477/metrics

example output:

 1# HELP immuclient_audit_curr_root_per_server Current root index used for the latest audit.
 2# TYPE immuclient_audit_curr_root_per_server gauge
 3immuclient_audit_curr_root_per_server{server_address="127.0.0.1:3322",server_id="br8eugq036tfln0ct6o0"} 2
 4# HELP immuclient_audit_prev_root_per_server Previous root index used for the latest audit.
 5# TYPE immuclient_audit_prev_root_per_server gauge
 6immuclient_audit_prev_root_per_server{server_address="127.0.0.1:3322",server_id="br8eugq036tfln0ct6o0"} -1
 7# HELP immuclient_audit_result_per_server Latest audit result (1 = ok, 0 = tampered).
 8# TYPE immuclient_audit_result_per_server gauge
 9immuclient_audit_result_per_server{server_address="127.0.0.1:3322",server_id="br8eugq036tfln0ct6o0"} -1
10# HELP immuclient_audit_run_at_per_server Timestamp in unix seconds at which latest audit run.
11# TYPE immuclient_audit_run_at_per_server gauge
12immuclient_audit_run_at_per_server{server_address="127.0.0.1:3322",server_id="br8eugq036tfln0ct6o0"} 1.5907565337454605e+09

immuclient looks for immudb at 127.0.0.1:3322 by default with the default username and password. Nevertheless a number of parameters can be defined:

 1immuclient audit-mode            -  Run a foreground auditor
 2immuclient audit-mode install    -  Install and runs daemon
 3immuclient audit-mode stop       -  Stops the daemon
 4immuclient audit-mode start      -  Starts initialized daemon
 5immuclient audit-mode restart    -  Restarts daemon
 6immuclient audit-mode uninstall  -  Removes daemon and its setup
 7
 8Flags:
 9  -h, --help   help for audit-mode
10
11Global Flags:
12      --audit-databases string               Optional comma-separated list of databases (names) to be audited. Can be full name(s) or just name prefix(es).
13      --audit-monitoring-host string         Host for the monitoring HTTP server when running in audit mode (serves endpoints like metrics, health and version). (default "0.0.0.0")
14      --audit-monitoring-port int            Port for the monitoring HTTP server when running in audit mode (serves endpoints like metrics, health and version). (default 9477)
15      --audit-notification-password string   Password used to authenticate when publishing audit result to 'audit-notification-url'.
16      --audit-notification-url string        If set, auditor will send a POST request at this URL with audit result details.
17      --audit-notification-username string   Username used to authenticate when publishing audit result to 'audit-notification-url'.
18      --audit-password string                immudb password used to login during audit; can be plain-text or base64 encoded (must be prefixed with 'enc:' if it is encoded)
19      --audit-username string                immudb username used to login during audit
20      --certificate string                   server certificate file path (default "./tools/mtls/4_client/certs/localhost.cert.pem")
21      --clientcas string                     clients certificates list. Aka certificate authority (default "./tools/mtls/2_intermediate/certs/ca-chain.cert.pem")
22      --config string                        config file (default path are configs or $HOME. Default filename is immuclient.toml)
23      --database string                      immudb database to be used
24      --dir string                           Main directory for audit process tool to initialize (default "/var/folders/0z/wk6v4sjd31qbvt7l75t_z_v00000gn/T/")
25  -a, --immudb-address string                immudb host address (default "127.0.0.1")
26  -p, --immudb-port int                      immudb port number (default 3322)
27      --max-recv-msg-size int                max message size in bytes the client can receive (default 4194304)
28  -m, --mtls                                 enable mutual tls
29      --password string                      immudb password used to login; can be plain-text or base64 encoded (must be prefixed with 'enc:' if it is encoded)
30      --pkey string                          server private key path (default "./tools/mtls/4_client/private/localhost.key.pem")
31      --roots-filepath string                Filepath for storing root hashes after every successful audit loop. Default is tempdir of every OS. (default "/tmp/")
32      --server-signing-pub-key string        Path to the public key to verify signatures when presents
33      --servername string                    used to verify the hostname on the returned certificates (default "localhost")
34      --tokenfile string                     authentication token file (default path is $HOME or binary location; default filename is )
35      --username string                      immudb username used to login
36      --value-only                           returning only values for get operations

To get the (signed) state in combination with the immuclient with auditor capabilities:

1immuclient audit-mode --audit-username {immudb-username} --audit-password {immudb-pw} --server-signing-pub-key {state-public-key}

Running immuclient Auditor as a service#

immuclient as Auditor can be installed in the system with the following command:

Install service:

1immuclient audit-mode install

In this case, all parameters are written into the immuclient configuration file:

  • Linux: /etc/immudb/immuclient.toml
  • Windows: C:\ProgramData\ImmuClient\config\immuclient.toml

Auditor best practices#

How can I be notified if my immudb instance was tampered?#

It’s possible to provide an external url that will be triggered in case a tamper is detected. By configuring IMMUCLIENT_AUDIT_NOTIFICATION_URL, a POST request will be sent with the following body:

 1{
 2  "current_state": {
 3    "hash": "string",
 4    "signature": {
 5      "public_key": "string",
 6      "signature": "string"
 7    },
 8    "tx": 0
 9  },
10  "db": "string",
11  "password": "string",
12  "previous_state": {
13    "hash": "string",
14    "signature": {
15      "public_key": "string",
16      "signature": "string"
17    },
18    "tx": 0
19  },
20  "run_at": "2020-11-13T00:53:42+01:00",
21  "tampered": true,
22  "username": "string"
23}

NOTE: it’s not possible to know at which transaction the database was tampered. The Auditor checks every second if the data was tampered - so it’s only possible to know at which time frame the tampering was detected.

How many Auditors should I run to secure my immudb instance?#

A proper setup of one immuclient instance can fit most of cases, but there are ways to increase the security on detecting tampering. A single instance can go offline for any reason: network problems, hardware failures or attacks. Therefore a good practice can be to have multiple Auditor instances running in different zones.

Edit this page on GitHub Last updated