Installation¶

To install Audit you need to follow the next steps:

1. Add MongoDB repository.
2. Install MongoDB.
3. Configure authentication for MongoDB.
4. Install Django Audit Tools package.

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10

echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | sudo tee /etc/apt/sources.list.d/mongodb.list

sudo apt-get update

sudo apt-get install mongodb-org=2.6.3 mongodb-org-server=2.6.3 mongodb-org-shell=2.6.3 mongodb-org-mongos=2.6.3 mongodb-org-tools=2.6.3

echo "mongodb-org hold" | sudo dpkg --set-selections
echo "mongodb-org-server hold" | sudo dpkg --set-selections
echo "mongodb-org-shell hold" | sudo dpkg --set-selections
echo "mongodb-org-mongos hold" | sudo dpkg --set-selections
echo "mongodb-org-tools hold" | sudo dpkg --set-selections

sudo service mongod start

mongo

use admin

db.createUser({
    user: "<USER_ADMIN>",
    pwd: "<PASSWORD_ADMIN>",
    roles:
        [
            { role: "userAdminAnyDatabase", db: "admin" }
        ]
    }
)

# auth = True

sudo service mongod restart

mongo admin -u <USER_ADMIN> -p <PASSWORD_ADMIN>

use <DATABASE>

db.createUser({
    user: "<USER>",
    pwd: "<PASSWORD>",
    roles:
        [
            { role: "readWrite", db: "<DATABASE>" }
        ]
    }
)

export DB_AUDIT_USER=<USER>
export DB_AUDIT_PASSWORD=<PASSWORD>

pip install django-audit-tools.tar.gz

pip install django-audit-tools

Configuration¶

To configure Audit Tools you need to follow the next steps:

1. Add audit_tools to your INSTALLED_APPS settings like this:

   INSTALLED_APPS = (
       ...
       'audit_tools',
   )
   

2. Add audit.middleware.AuditMiddleware to your MIDDLEWARE_CLASSES settings like this:

   MIDDLEWARE_CLASSES = (
       ...
       'audit_tools.audit.middleware.AuditMiddleware',
   )
   

3. Configure blacklisted URLs in AUDIT_BLACKLIST settings.

4. Register models that will be logged in AUDIT_LOGGED_MODELS settings.

5. Execute the next django command:

   python manage.py prepare_audit
   

AUDIT_ACTIVATE = True

AUDIT_DB_ALIAS = 'audit'

AUDIT_DB_CONNECTION = {
    'HOST': 'localhost',
    'PORT': 27017,
    'NAME': 'audit',
    'USER': '',
    'PASSWORD': '',
}

AUDIT_RUN_ASYNC = False

AUDIT_CELERY_QUEUE = 'audit'

AUDIT_LOGGED_MODELS = (
    'audit_tools.audit.models.Access',
)

AUDIT_LOGGED_MODELS = ()

AUDIT_BLACKLIST = {
    'api': (
        r'^/api/.*',
        r'^/API/.*',
    )
}

AUDIT_BLACKLIST = {}

AUDIT_ACCESS_INDEXES = [
    'custom.pools.names',
    'custom.pools.num_polls',
    ('custom.pools.names', 'custom.pools.num_polls'),
]

AUDIT_CUSTOM_PROVIDER = {
    'audit_tools': 'audit_tools.audit.middleware.custom_provider',
}

AUDIT_TRANSLATE_URLS = False

Signals¶

audit_tools.audit.signals.register(model)[source]¶

Register a model to the audit code.

Parameters:	model (object) – Model to register.

audit_tools.audit.signals.register_models()[source]¶

Register all models listed in settings.LOGGED_MODELS.

audit_tools.audit.signals.unregister(model)[source]¶

Unregister a model to the audit code.

Parameters:	model (object) – Model to unregister.

audit_tools.audit.signals.unregister_models()[source]¶

Unregister all models listed in settings.LOGGED_MODELS.

Models¶

Ebury Audit models

class audit_tools.audit.models.Access(*args, **values)[source]¶

Information gathered from a request and response objects. Contains the following structure:

Variables:	interlink_id – Interlink id. request – Request. response – Response content, type and status code. exception – Exception raised. time – Request and response time. view – View full_name, app, name, args and kwargs. user – User id and name. custom – Custom providers field. process – Reference to Process object.

get_user()[source]¶

Obtains User object that corresponds to this Access instance.

Returns:	User object.
Return type:	django.contrib.auth.models.User

get_view()[source]¶

Obtains view object that corresponds to this Access instance.

Returns:	View.
Return type:	object

is_exception()[source]¶

Check if this Access contains a exception.

Returns:	True if contains exception.
Return type:	bool

is_response()[source]¶

Check if this Access contains a response.

Returns:	True if contains response.
Return type:	bool

items()[source]¶

List items in form (key, value).

Returns:	list(tuple())

url¶

Property that gives access to request__path field.

Type:	str

verbose_str()[source]¶

Verbose string representation.

Returns:	Verbose string representation.
Return type:	str

class audit_tools.audit.models.Process(*args, **values)[source]¶

Represents a process that launch a django management command. Contains the following structure:

Variables:	name – Process name. args – Process args. machine – Machine that launched this process. user – User that launched this process. pid – Process pid. creation_time – Time when process was launched.

items()[source]¶

List items in form (key, value).

Returns:	list(tuple())

verbose_str()[source]¶

Verbose string representation.

Returns:	Verbose string representation.
Return type:	str

class audit_tools.audit.models.ModelAction(*args, **values)[source]¶

Information from create, update or delete operations over a model. Contains the following structure:

Variables:	model – Model full_name, app and name. action – Create, update or delete action. content – Old and new values and changes. instance – Instance object id and description. timestamp – Time when action occurs. access – Reference to Access object. process – Reference to Process object.

changes¶

Property that gives access to content__changes field.

Type:	dict

get_instance()[source]¶

Obtains instance object that corresponds to this ModelAction instance.

Returns:	Instance object.
Return type:	object

get_model()[source]¶

Obtains Model class that corresponds to this ModelAction instance.

Returns:	Model class.
Return type:	object

items()[source]¶

List items in form (key, value).

Returns:	list(tuple())

verbose_str()[source]¶

Verbose string representation.

Returns:	Verbose string representation.
Return type:	str

Middleware¶

class audit_tools.audit.middleware.AuditMiddleware(*args, **kwargs)[source]¶

Middleware for audit logging

process_view(self, request, view_func, view_args, view_kwargs)[source]¶

Preprocess request.

Parameters:	request (django.http.HttpRequest) – Http request. view_func (callable) – View. view_args (list) – View arguments. view_kwargs (dict) – View keyword arguments.
Returns:	None

process_response(self, request, response)[source]¶

Postprocess response.

Parameters:	request (django.http.HttpRequest) – Http request. response (django.http.HttpResponse) – Response.
Returns:	None

process_exception(self, request, exception)[source]¶

Postprocess exception.

Parameters:	request (django.http.HttpRequest) – Http request. exception (Exception) – Response.
Returns:	None

Managers¶

# URL /
Access.objects.filter_by_url(url='/')
# Filter URLs using regular expression
Access.objects.filter_by_url(url=r'^/polls/\w*$')
# Accesses to /polls/ done by user with id 23
Access.objects.filter_by_url(url='/polls/', user__id=23)

# Accesses to poll's index
from polls.views import index
Access.objects.filter_by_view(fview=index)

# Accesses that raises an AttributeError exception
Access.objects.filter_by_exception(exc=AttributeError)

# Actions done over all polls
from polls.models import Poll
ModelAction.objects.filter_by_model(klass=Poll)

# Actions done over a single poll
poll = Poll.objects.get(id=1)
ModelAction.objects.filter_by_instance(obj=poll)

# Actions done over all polls and users
from django.contrib.auth.models import User
ModelAction.objects.filter_by_model_list(klass=[Poll, User])

Commands¶

Django commands for Audit application.

python manage.py drop_audit [init_date] [end_date]

python manage.py drop_audit
python manage.py drop_audit 01/01/2000
python manage.py drop_audit 01/01/2000 01/02/2000

python manage.py prepare_audit

python manage.py remove_audit

Custom providers¶

Custom provider is a mechanism that permits an application to add custom data to Access logs. A single provider can be specified for each app.

The next example define a provider that returns polls associated to current user:

def poll_provider(request):
    user = User.objects.get(pk=request.user.id)
    polls = Poll.objects.filter(user=user)
    polls_names = [p.name for p in polls]

    res = {
        'names': poll_names,
        'num_polls': len(poll_names),
    }

    return res

If this provider is defined inside polls.utils then must be set in settings.AUDIT_CUSTOM_PROVIDER:

AUDIT_CUSTOM_PROVIDER = {
    'polls': 'polls.utils.poll_provider',
}

This provider will result in an additional field inside Access named ‘polls’:

{
    ...
    custom = {
        polls = {
            names = [ "poll_1", "poll_2" ],
            num_polls = 2
        }
    }
}