# Tampering detection

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 (opens new window) are shipped with auditor capabilities.

# Running an Auditor with immuclient

immuclient can act as Auditor by running the following command:

$ ./immuclient audit-mode
1m0s
immuclientd 2022/05/22 12:34:11 INFO: starting auditor with a 1m0s interval ...
immuclientd 2022/05/22 12:34:11 INFO: auditor monitoring HTTP server starting on 0.0.0.0:9477 ...
immuclientd 2022/05/22 12:34:11 INFO: audit #1 started @ 2022-05-22 12:34:11.543823286 +0200 CEST m=+0.153679785
immuclientd 2022/05/22 12:34:11 INFO: audit #1 - list of databases to audit has been (re)loaded - 2 database(s) found: [defaultdb mydatabase]
immuclientd 2022/05/22 12:34:11 INFO: audit #1 - auditing database defaultdb
immuclientd 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:

# HELP immuclient_audit_curr_root_per_server Current root index used for the latest audit.
# TYPE immuclient_audit_curr_root_per_server gauge
immuclient_audit_curr_root_per_server{server_address="127.0.0.1:3322",server_id="br8eugq036tfln0ct6o0"} 2
# HELP immuclient_audit_prev_root_per_server Previous root index used for the latest audit.
# TYPE immuclient_audit_prev_root_per_server gauge
immuclient_audit_prev_root_per_server{server_address="127.0.0.1:3322",server_id="br8eugq036tfln0ct6o0"} -1
# HELP immuclient_audit_result_per_server Latest audit result (1 = ok, 0 = tampered).
# TYPE immuclient_audit_result_per_server gauge
immuclient_audit_result_per_server{server_address="127.0.0.1:3322",server_id="br8eugq036tfln0ct6o0"} -1
# HELP immuclient_audit_run_at_per_server Timestamp in unix seconds at which latest audit run.
# TYPE immuclient_audit_run_at_per_server gauge
immuclient_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:

immuclient audit-mode            -  Run a foreground auditor
immuclient audit-mode install    -  Install and runs daemon
immuclient audit-mode stop       -  Stops the daemon
immuclient audit-mode start      -  Starts initialized daemon
immuclient audit-mode restart    -  Restarts daemon
immuclient audit-mode uninstall  -  Removes daemon and its setup

Flags:
  -h, --help   help for audit-mode

Global Flags:
      --audit-databases string               Optional comma-separated list of databases (names) to be audited. Can be full name(s) or just name prefix(es).
      --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")
      --audit-monitoring-port int            Port for the monitoring HTTP server when running in audit mode (serves endpoints like metrics, health and version). (default 9477)
      --audit-notification-password string   Password used to authenticate when publishing audit result to 'audit-notification-url'.
      --audit-notification-url string        If set, auditor will send a POST request at this URL with audit result details.
      --audit-notification-username string   Username used to authenticate when publishing audit result to 'audit-notification-url'.
      --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)
      --audit-username string                immudb username used to login during audit
      --certificate string                   server certificate file path (default "./tools/mtls/4_client/certs/localhost.cert.pem")
      --clientcas string                     clients certificates list. Aka certificate authority (default "./tools/mtls/2_intermediate/certs/ca-chain.cert.pem")
      --config string                        config file (default path are configs or $HOME. Default filename is immuclient.toml)
      --database string                      immudb database to be used
      --dir string                           Main directory for audit process tool to initialize (default "/var/folders/0z/wk6v4sjd31qbvt7l75t_z_v00000gn/T/")
  -a, --immudb-address string                immudb host address (default "127.0.0.1")
  -p, --immudb-port int                      immudb port number (default 3322)
      --max-recv-msg-size int                max message size in bytes the client can receive (default 4194304)
  -m, --mtls                                 enable mutual tls
      --password string                      immudb password used to login; can be plain-text or base64 encoded (must be prefixed with 'enc:' if it is encoded)
      --pkey string                          server private key path (default "./tools/mtls/4_client/private/localhost.key.pem")
      --roots-filepath string                Filepath for storing root hashes after every successful audit loop. Default is tempdir of every OS. (default "/tmp/")
      --server-signing-pub-key string        Path to the public key to verify signatures when presents
      --servername string                    used to verify the hostname on the returned certificates (default "localhost")
      --tokenfile string                     authentication token file (default path is $HOME or binary location; default filename is )
      --username string                      immudb username used to login
      --value-only                           returning only values for get operations

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

immuclient 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:

immuclient 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:

{
  "current_state": {
    "hash": "string",
    "signature": {
      "public_key": "string",
      "signature": "string"
    },
    "tx": 0
  },
  "db": "string",
  "password": "string",
  "previous_state": {
    "hash": "string",
    "signature": {
      "public_key": "string",
      "signature": "string"
    },
    "tx": 0
  },
  "run_at": "2020-11-13T00:53:42+01:00",
  "tampered": true,
  "username": "string"
}

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.