Intrusion detection

Let's take a few steps back to see the bigger picture: the client application generates requests and sends them through the chain of Acra's services to receive decrypted plaintext in the end.

What if the attackers compromise the app deeply and badly enough so they are able to alter its behaviour? From a simple SQL injection to remote/local code execution errors, there are threats, which make your application a source of risk once it's been compromised. Our idea is that since AcraServer is the only entity that decrypts sensitive data and sees all the requests addressed to it, it is AcraServer's responsibility to tell the good behaviour from bad and to take appropriate action.

Poison records

For a quick illustrated starter on poison records * , check out an article in our Medium blog and see our technical blog for a more detailed explanation.

Poison records are the records specifically designed and crafted in such a way that they wouldn't be queried by a user under normal circumstances. Yet poison records will be included in the outputs of SELECT * requests. Upon passing AcraServer, they will inform it of untypical behaviour. The goal of using poison records is simple — to detect adversaries trying to download full tables / full database from the application server or trying to run full scans in their injected queries.

Poison records are the first of many database self-defence features planned for Acra

The concept: In a regular environment, users never query all the records will full-scan requests and their select statements are filtered by certain WHERE clauses. If this is your case, you'll benefit from using poison records. In essence, a poison record is a flawed AcraStruct, encrypted with a special Zone key. This design ensures that matching happens in the cryptographic layer, but without significant computational expenses.

How does it work?

AcraServer's key storage contains a special key, which is used for recognition of poison records. This key is generated either after a query passes through AcraServer, or upon running poison record generation utility AcraPoisonRecordMaker (but you will have to move the keys into AcraServer's key directory manually).

Implementing poison records with Acra (the fast way)

  • The fastest way to try Acra and poison records is to launch Acra in a Docker image using the following instruction.
  • Poison records are generated by a special utility – AcraPoisonRecordMaker. It’s already installed in the AcraServer / AcraTranslator docker containers.

For example, you can run AcraServer with MySQL database:

$ docker-compose -f docker/docker-compose.mysql-nossl-server-ssession-connector.yml up

$ docker ps
CONTAINER ID        IMAGE                               COMMAND                  CREATED             STATUS              PORTS                              NAMES
fa5c8a717f82        cossacklabs/acra-webconfig:master   "/acra-webconfig -st…"   5 minutes ago       Up 5 minutes>8000/tcp             docker_acra-webconfig_1
74ab6172fa41        cossacklabs/acra-connector:master   "/acra-connector --a…"   5 minutes ago       Up 5 minutes        9191/tcp,>9494/tcp   docker_acra-connector_1
19e2160e7c2f        cossacklabs/acra-server:master      "/acra-server --mysq…"   6 minutes ago       Up 5 minutes                                           docker_acra-server_1
732610db0946        docker_mysql                        "docker-entrypoint.s…"   6 minutes ago       Up 6 minutes>3306/tcp             docker_mysql_1

Then run AcraPoisonRecordMaker:

$ docker exec -it docker_acra-server_1 /acra-poisonrecordmaker --keys_dir=/keys

The output is base64-encoded poison record that you should decode and insert into your data in the database as binary data.

There is one useful additional parameter that AcraPoisonRecordMaker has: --data_length. It will change the size of the generated random data in the poison record. This is useful for transforming the data inside the poison records to resemble your data in lengths.

For instance, if you store data that’s typically 2kb in size, use the following option:

docker exec -it docker_acra-server_1 /acra-poisonrecordmaker --keys_dir=/keys --data_length=2048    

Implementing poison records with Acra (the long non-Docker way)

Poison records are generated by a special utility – AcraPoisonRecordMaker. To install it, run:

go get

First, please make sure that you have ACRA_MASTER_KEY stored as an environmental variable (echo $ACRA_MASTER_KEY should display key). If you haven't generated keys before, read Key generation page. After generating ACRA_MASTER_KEY, assign it to a variable like this:

export ACRA_MASTER_KEY=$(echo -n "My_Very_Long_Key_Phrase_ge_32_chars" | base64)

Run AcraPoisonRecordMaker:


Your output will look something like this:


It's a base64-encoded poison record that you should decode and insert into your data in the database as binary data.

NOTE: For AcraPoisonRecordMaker to work, the key folder has to have proper permissions (as set originally by acra-keymaker):

  • folder 700,
  • private keys 600.

It is best to keep this utility and the corresponding keys on AcraServer.

Controlling AcraServer's behaviour with poison records

Poison records are useful signals for controlling the system's behaviour. With their help you can either:

  • Perform a shut-down if a poison record is detected:
$GOPATH/bin/acra-server --db_host= --poison_shutdown_enable
  • Run a script if a poison record is matched in the input stream:
$GOPATH/bin/acra-server --db_host= --poison_run_script_file=/path/to/file
  • Perform a shut-down and run a script:
$GOPATH/bin/acra-server --db_host= --poison_run_script_file=/path/to/file --poison_shutdown_enable

Additional notes

AcraPoisonRecordMaker has an additional parameter --data_length that will change the size of the generated random data in the poison record. You should use this option to transform the data inside the poison records to resemble your typical data. Ideally, a poison record should look like any other record in your database. And if you store 1k-2k data, you should use this option:

$GOPATH/bin/acra-poisonrecordmaker --data_length=100500

* When naming our special type of data containers (records) created scpecifically for raising an alarm within Acra-powered infrastructure on detection of suspicious behaviour, we were pretty sure we've seen the term "poison records" used elsewhere in the same context before. But as it turned out, we've pioneered this particular database protection tool. Here is a description of what poison records are, what they do, and how to create and use them.