Pryv.io audit configuration

This document describes how to configure the Audit feature for your Pryv.io platform.

Audit is only available in the entreprise version of Pryv.io.

Table of contents

1. Outputs
2. Filtering
3. Rules
   1. You must specify at least one of them
   2. You can aggregate per resource
4. Examples
   1. log everything
   2. log nothing
   3. log a few API methods
   4. log everything, but a few
   5. log all events methods, but get
5. Syslog
   1. Templating
6. Support
7. Performance
8. Previous version

Outputs

Audit data can be written to any or both of the following:

• in a dedicated storage where it will be indexed for querying through the Events API
• in the host machine’s syslog to which you can setup your own listeners

Filtering

for both of these outputs, you can define which API method you log by filtering per method-id.

You can find these settings in the platform configuration under the Audit settings tab, in the AUDIT_STORAGE_FILTER and AUDIT_SYSLOG_FILTER variables:

In the Admin panel:

{
  "methods": {
    "include": ["access.create", "events.all"],
    "exclude": ["events.get"]
  }
}

In the platform.yml file:

methods:
  include: ["accesses.create", "events.all"]
  exclude: ["events.get"]

Rules

You must specify at least one of them

At least one of the arrays must contain a valid value.

You can aggregate per resource

The Pryv.io API method ids are built in the format {resource}.{verb}, for example: events.get.
Audit filters accept aggregation of all methods for a particular resource using all for the verb, for example: events.all

Examples

log everything

{
  "methods": {
    "include": ["all"],
    "exclude": []
  }
}

log nothing

{
  "methods": {
    "include": [],
    "exclude": ["all"]
  }
}

log a few API methods

{
  "methods": {
    "include": ["access.create", "accesses.delete"],
    "exclude": []
  }
}

log everything, but a few

{
  "methods": {
    "include": [],
    "exclude": ["events.get"]
  }
}

log all events methods, but get

{
  "methods": {
    "include": ["events.all"],
    "exclude": ["events.get"]
  }
}

Syslog

Introductory notes about syslog:

The syslog protocol is using a socket in order to transmit messages. For Linux, this socket is a SOCK_STREAM unix socket, which is identified by the name /dev/log. The syslog deamon for Ubuntu is rsyslogd, its configuration files are located in /etc/rsyslog.conf and /etc/rsyslog.d/. In particular, the default logging rules can be found in /etc/rsyslog.d/50-default.conf. These rules typically tell to which actual log files the socket messages will be pipped to (e.g. /var/log/syslog), according to the message type (see the Syslog wiki for more details about Facility and Security levels).*

If activated, the Pryv.io service will write to the host machines syslog. This is useful if you wish to enable security logging, for actions such as blocking an IP address after it has performed too many forbidden requests using tools such as fail2ban.

A Pryv.io audit log will look like this in the syslog:

Oct 26 14:58:46 co1-pryv-li pryv-audit[57]: ck6j759f000011ps2octzo1ds audit-log/pryv-api createdBy:system ["access-ck6j78uj600011ss2neygkpub","action-events.get"] {"source":{"name":"http","ip":"85.5.192.175"},"action":"events.get","query":{"toTime":"9900000000","fromTime":"-9900000000","limit":"1","sortAscending":"true","state":"all"}}

Templating

You can edit its template using the AUDIT_SYSLOG_FORMAT platform parameter:

{
  "template": "{userid} {type} createdBy:{createdBy} {streamIds} {content}",
  "level": "notice"
}

Support

You can get in touch with Pryv’s support at Open Pryv - Issues and question

Performance

As both syslog and storage logging require additionnal processing, we recommend to activate logging only for the methods that require it.

Previous version

For audit configuration previous to Pryv.io 1.7, please see the PDF.