django-audit-logger 1.1.0

A logger to be used internally

Django Audit Logger

A django package that allows you to log user logins and changes to instances of the models within your project.

Install

Pip

pip install django-audit-logger

Dependencies:

• Django
• Boto3
• Celery
• Redis

Works with both python 2.7 and all versions of python that support Django 1.11 (>= 3.4)

Update Settings

Add the following settings to your settings.py file and give them the correct values.

AUDIT_LOGGER_REGION = ''
AUDIT_LOGGER_KEY_ID = ''
AUDIT_LOGGER_SECRET_ACCESS_KEY = ''
AUDIT_LOGGER_GROUP_NAME = ''
AUDIT_LOGGER_STREAM_NAME = ''
AUDIT_LOGGER_EXCLUDE = []
AUDIT_LOGGER_USER_ORGANISATION_FIELD = []
LOG_INTERVAL = ''

Add auditlogger to your INSTALLED_APPS.

Optional: Add your models to the logger:

By default, only User logins are logged. You can start logging additional models by using the @auditlogger_update_delete decorator.

from auditlogger.signals import auditlogger_update_delete

@auditlogger_update_delete
class ModelToLog(models.Model):
    name = models.CharField(max_length=100)
    (...)

Both create, update and delete actions will be logged.

Settings

AWS settings

AUDIT_LOG_REGION
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY

These settings manage the connection to AWS.

CloudWatch settings

AUDIT_LOG_GROUP_NAME

The name of the LogGroup within CloudWatch to sent the logs to.

AUDIT_LOG_STREAM_NAME

The name of the log stream.

Audit-logger settings:

AUDIT_LOG_EXCLUDE

Just as you can include models to be logged, you can also exclude them. This is useful for models that will be logged by default. For example, one can exclude the django Session object like so: AUDIT_LOG_EXCLUDE = ['Session']

AUDIT_LOGGER_USER_ORGANISATION_FIELD

If the project that you wish to collect the audit-logger to uses tenants, academies or an equivalent that users are members of, you can add them to the logs through this setting. The organisation will be displayed as the value of the organisation field in the logs.

The organisation may be linked to the user as a direct relation, or through an intermediary object like a profile model. To support both scenarios the value should be provided as a list.

For example in the following scenarios:

user -> organisation the value should be: ['organisation']

user -> profile -> organisation the value should be: ['profile', 'organisation']

LOG_INTERVAL

The logs are pushed to cloudwatch in batches, with all logged events being held in redis until the log interval expires. The interval value represents the time in minutes, with 5 as the default.

Custom log events

You can also link other signals used in your app to the logger like so:

from auditlogger.signals import send_log
from django.dispatch import receiver, Signal
from myapp.models import Organisation

organisation_login_signal = Signal(providing_args=['date', 'instance'])


@receiver(organisation_login_signal, sender=Organisation)
def organisation_login(**kwargs):
    """detect organisation logins"""
    send_log('ORGANISATION_LOGIN', **kwargs)

Test

The app comes with included tests that you can run with the following command from the django-audit-logger directory (requires the python manage.py migrate command to have been run):

python auditlogger/run_tests.py