Welcome to Django-Dingos’s documentation!¶

Read up on techniques and styles used in DINGOS¶

Django DINGOS profitted a lot from the advice provided in Two Scoops of Django.

Unless you are an absolute Django expert (and maybe even then), please read Daniel Greenfield’s and Audrey Roy’s excellent Two Scoops of Django. Even though it provides best practices for Django 1.5, most of its advice is also valid for Django 1.6, and likely to be very relevant for quite a few minor revisions to come.

Make sure that DINGOS is the right place to modify / add to¶

Although DINGOS is likely to be used mainly in the context of the Django MANTIS Cyber Threat Intelligence Management application, DINGOS shold stay a /generic/ application for managing structured information. So whenever you find yourself adding/modifying stuff in DINGOS that is specific to cyber threat intelligence management, the STIX, CybOX standards, etc., DINGOS is the wrong place to modify/add to. The same goes for customizations that are particular to your instance of running MANTIS.

Please consider the following places for development instead:

• If you want to add Python code that is particular to cyber threat management, consider adding this in django-mantis-core
• If you want to add Python code that is particular to a certain standard, consider adding it to the respective importer module, e.g., django-mantis-stix-importer or similar
• If you want to make modifications to a DINGOS template that is required for your local instance of MANTIS (or whatever framework is using DINGOS), the right way is probably to override one of the DINGOS base templates. Have a look at how django-mantis overrides the templates/dingos/grappelli/base.html template; see also the Django documentation on overriding templates.
• If you want to change the url paths of DINGOS views, do this in the url.py of your instance rather than dingos/url.py.

Overview of the directory layout¶

The layout of the DINGOS Django application is as follows:

.
├── dingos
│   ├── core
│   │   ├── datastructures.py
│   │   └── ...
│   ├── management
│   │   └── commands
│   │       └── dingos_generic_xml_import.py
│   │
│   ├── migrations
│   │   ├── 0001_initial.py
│   │   └── ...
│   ├── templates
│   │   └── dingos
│   │       └── grappelli
│   │           ├── base.html
│   │           ├── details
│   │           │   └── ...
│   │           ├── includes
│   │           │   └── ...
│   │           ├── lists
│   │           │   └── ...
│   │           └── searches
│   │               └── ...
│   ├── templatetags
│   │   └── dingos_tags.py
│   ├── admin.py
│   ├── filter.py
│   ├── import_handling.py
│   ├── importer.py
│   ├── models.py
│   ├── __init__.py
│   ├── read_settings.py
│   ├── urls.py
│   ├── view_classes.py
│   └── views.py

core: internal DINGOS libraries¶

Internal libraries with helper functions are placed in the core folder. The most important library probably is core/datastructures.py, which contains DingosObjDict, the dictionary structure into which imported data is written. DingosObjDict preserves the order in which keys have been added and knows how to /flatten/ itself into a list of facts.

management/commands¶

This folder contains code for the command-line scripts that can be executed via Django’s django-admin or manage.py interface. Refer to Django documentation on custom django-admin commands for a description of how commands can be added.

templates\dingos\grappelli¶

DINGOS uses Django templates (see Django documentation on the template language) for rendering HTML pages. These are located in the template\dingos\grappelli folder. The reason for this nesting is the following:

• by having dingos in the file path, also other apps are able to refer to templates defined in DINGOS
• by having grappelli in the file path, we are open to supporting different CSS frameworks at a later point of time: for supporting, e.g., bootstrap, a folder templates\bootstrap would have to be added and would then contain the bootstrap-based templates.

In order to learn how to use the Django Grappelli CSS, make sure to include (r'^grappelli/', include('grappelli.urls')) in your url patterns in url.py. You can then view the Grappelli CSS documentation under <your Django server url>/grappelli/grp-doc/.

templatetags\dingos_tags.py¶

When you are viewing a template and find something like {% show_InfoObjectIDData object %} that seems to do something magical (in this case, rendering a box containg identifier data of an object), then you are looking at a Django /template tag/. Those are defined in templatetags\dingos_tags.py; the template snippets used by the tags are defined in ``templatesdingosgrappelliincludes`.

admin.py¶

Configuration for the Django admin interface: via the admin interface, you can access the DINGOS models. That is useful for viewing certain data (e.g., which namespaces do I have in my system?) and configuring data (e.g., managing naming schemas via the InfoObjectType objects). Refer to the Django documentation on the admin site for details about the contents of admin.py – you may also want to have a look at the documentation of Django Grappelli, since admin.py uses some extensions provided by Grappelli.

filter.py¶

DINGOS uses the django-filter app to generate filters for list views. The configuration for the filters is located in filter.py: for background on how to configure filters, please refer to the django-filter documentation.

import_handling.py¶

Next to models.py (see below), this is the heart of DINGOS: it defines the class DingoImportHandling that contains the xml_import function, a highly configurable function for turning XML into DINGOS dictionary objects, and create_iobject, the function used to write a DINGOS dictionary object to a InfoObject in the database.

importer.py¶

The most important content of this file is the generic class DingoImportCommand which provides the basis for easy implementation of import scripts to be carried out via the command-line (see above under management/commands and Django documentation on custom django-admin commands.

This file also contains a very simple generic XML importer, which is mostly for demonstration purposes.

models.py¶

The heart of DINGOS. The code is extensively documented; please refer to the DINGOS Developers' Overview of the DINGOS models for an overview.

__init__.py¶

DINGOS uses the __init__.py file to define a number of defaults used within the DINGOS code.

read_settings.py¶

Code for reading DINGOS-specific settings configured in the Django settings file(s). Some of the defaults defined in __init__.py can be overwritten here.

urls.py¶

The Django URL configuration. See the Django documentation on the URL dispatcher.

view_classes.py¶

DINGOS makes extensive use of Django’s class-based views (see the Django documentation on class-based views). In view_classes.py, we define mixins (see also the Django documentation on using mixins in class-based views) and base classes that are used for defining views in DINGOS.

views.py¶

The DINGOS views. Refert to the Django documentation on class-based views.

When writing and testing views, do not even start without the excellent Django Debug Toolbar: it shows you, for example, how many which SQL queries were executed (which will help you to find the right configuration for the prefetch_related and select_related

Relevant folders and files¶

Supporting Documentation¶

• For basics on templates, refer to the Django documentation on the template language.
• In order to learn how to use the Django Grappelli CSS, make sure to include (r'^grappelli/', include('grappelli.urls')) in your url patterns in url.py. You can then view the Grappelli CSS documentation under <your Django server url>/grappelli/grp-doc/.
• For information on class-based views see: - Django documentation on class-based views - Django documentation on using mixins in class-based views

Dingos-specific features¶

Tips and tricks¶

When writing and testing views, do not even start without the excellent Django Debug Toolbar: it shows you, for example, how many which SQL queries were executed (which will help you to find the right configuration for the prefetch_related and select_related

Defining user configurations¶

The default user configuration is defined in the constant DINGOS_DEFAULT_USER_PREFS. dingos/__init__.py but can be overwritten in the settings, e.g. as follows:

DINGOS = {
          (...)
          'DINGOS_DEFAULT_USER_PREFS' : {
              'dingos' : { 'widgets' :
                               {'embedded_in_objects' :
                                    {'lines' : {'@description': """Max. number of objects displayed in
                                                        widget listing the objects in which the
                                                        current object is embedded.""",
                                                '_value' : '5'}
                                    } ,
                                },
                           'view' :
                               {'pagination':
                                    {'lines' : {'@description': """Max. number of lines displayed in
                                                    paginated views.""",
                                                '_value' : '20'},
                                     },
                                'orientation' : {'@description': """Layout orientation. Possible values are 'vertical', 'horizontal', and 'auto'.""",
                                                 '_value' : 'horizontal'}
                               }

              }
          }

 (...)
}

When a user logs in for the first time, the standard user configuration is copied over to his personal user configuration. The user configuration can be viewed with the view named url.dingos.admin.view.userprefs – the standard URL for this view is ../Admin/ViewUserPrefs.

A logged in user can edit the settings under the ViewUserPrefs. Alternatively, for testing purposes, you can change the preferences via the command line interface:

python manage.py dingos_manage_user_settings --reset preferences <user_name1> <user_name2> --settings=...

After doing this, go to the above-mentioned view of the user preferences for a user to also refresh the user data that has been cached in the session.

Accessing user configurations in templates¶

In templates, user configurations are accessed as follows:

customization.<default_value>.<path>.<to>.<value>.<in>.<config>.<dictionary>

For example to access the orientation of the display defined as horizontal above, you would write:

customization.horizontal.dingos.view.orientation

Or, to access the number of lines to be shown on a list display (with a default value of 15), you would write:

customization.15.dingos.view.pagination.lines

Accessing user configuration in views¶

The Dingos standard views all include the mixin ViewMethodsMixin, which defines the function lookup_customization. In order to look up the number of lines to be shown on a list display (with a default value of 15), you would write:

self.lookup_customization('dingos','view','pagination','lines',default=15)