Quick-start guide

Django Conntrackt provides a very simple interface for reading the information

about network connections across projects, as well as for obtaining *iptables*

rules.

The Conntrackt content is currently being added through Django's administration

interface.

Conntrackt key concepts

-----------------------

There is a couple of key concepts to be aware of throughout the documentation:

Project

    A project is used to group the related entities. Project usually maps to

    business projects being worked on by the organisation members.

Location

    Location is used to group the related entities within a project. Locations

    can be abstract, like *primary site*, *secondary site*, or *disaster

    site*. They can also be more specific, like *Belgrade*, or *Stockholm*. The

    layout of locations that you choose is completely up ot you.

Entity

    Entity is an origin or destination of network communication. An entity can

    represent a single physical or virtual device (server, router, or some other

    network-capable device), or it can represent a subnet (therefore being

    mapped to multiple physical or virtual devices).

    Every entity must have an assigned project and location.

Interface

    Interface is used for representing a specific network interface on an

    entity. In regular case, where the entity is a physical or virtual device,

    an interface will map to a single IP address.

    An interface is also used to provide subnet information for entities that

    represent subnets.

    Multiple interfaces can be assigned to an entity as well.

Communication

    Communication is used to specify the planned connections between

    entities. This information is useful for keeping track which entity is

    talking to which entity (and using which interfaces), allowing easier

    tracking of what's happening in the project.

    In addition, this information can be used to generate the iptables rules for

    servers to restrict the access.

Navigating through Conntrackt

-----------------------------

Conntrackt tries to employ a simple and lean web interface for all of its

tasks. Every Conntrackt page has a navigation bar at the top, that lets you

access the most common pages in the application.

The *Main Page* links will take you to the homepage of Conntrackt. If you want

to add data to conntrackt, click on the *Administration* link, which will take

you to Django's built-in administration interface.

If you are not logged-in, you can click on the *Log-in* link that will take you

to the log-in page where you can provide your credentials (username and

password). In case you are already- logged-in, you will instead see your

*username* and *log-out* link.

Homepage

~~~~~~~~

This page provides an overview of projects and entities belonging to the

projects. No information will be shown if there are no projects defined.

Each project's information is shown in a small frame on the page, with project

name at the top, and listing of entities belonging to the project under it.

Clickin on the project name will take you to project details page, while

clicking on an entity name will take you to entity details page.

In addition, small clickable icons are show next to the project and

entities. Clicking on the book-like icon next to a project will trigger download

of ZIP archive that contains *iptables* rules for all of the project's entities

in separate files. This is a convenient way to obtain all of the *iptables* for

a project.

If you click on the icon next to an entity, you will be instead offered to

download *iptables* rules for that specific entity in plain-text format.

Project details page

~~~~~~~~~~~~~~~~~~~~

The project details page provides an overview of project's locations, with

entities listed under the location to which they belong to.

Each location is contained inside of a small frame, with location name at the

top, and listing of entities in the location below it.

Clicking on an entity name will take you to entity details page.

In addition, small clickable icons are show next to the location and

entities. Clicking on the book-like icon next to a location will trigger download

of ZIP archive that contains *iptables* rules for all of the location's entities

in separate files. This is a convenient way to obtain all of the *iptables* for

a specific location in a project.

If you click on the icon next to an entity, you will be instead offered to

download *iptables* rules for that specific entity in plain-text format.

Entity details page

~~~~~~~~~~~~~~~~~~~

This page provides more details about an entity in a project. You will be

presented with the following information on this page:

* Entity's project name.

* Entity's location name.

* Informationg about incoming and outgoing communications.

* Inline iptables rules.

The project name is clickable, and it will take you to project details page.

The information about incoming communications shows all communications that have

one of this entity's interfaces as destination. The listing will show an IP

address/subnet of the source, protocol used in communication, and port number

(if applicable).

Similarly, the outgoing communications listing will display communications where

the entity is the source (starting point), and includes information about

destination IP address/subnet, protocol user in communication, and port number

(if applicable).

The iptables listing can be obtained either by copy/pasting it from the page, or

by clicking on the *Download* button below it (which will generate a plaintext

file containing the same iptables rules as listed in the *iptables rules*

frame).

Managing data

-------------

Data for Conntrackt can be added and modified using Django's built-in

administration GUI. You can easily access the administration GUI from

Conntrackt's pages, by clicking on the *Administration* link in the navigation

bar.

From there you can add new projects, locations, interfaces, entities, and

communications. You can also click on links towards them to get a full listing

from where you can modify existing entries.

The admin interface for Conntrackt behaves the same as for every Django

application, except for some convenience functionality that helps speed-up

adding or modification of some data.

The interfaces, entities, and communications pages allow editing most of the

data inline, which can speed-up the process quite a bit. In addition, all three

pages provide filters that allow you to easily view data specific to a

particular project and/or location. The filters are available on the right

side.

Although interfaces can be managed separately, you may find it much easier to

manage them from within the entity pages. When adding or modifying an entity,

you will have some inline forms for specifying entity's interfaces. This is the

recommended way to add and modify the interfaces for entities.

Projects

~~~~~~~~

For every project you can provide the following information:

* *Name* of a project.

* *Description* of a project.

Locations

~~~~~~~~~

For every location you can provide the following information:

* *Name* of a location.

* *Description* of a location.

Entities

~~~~~~~~

For every entity you can provide the following information:

* *Name* of an entity.

* *Description* of an entity.

* *Project* to which the entity belongs.

* *Location* at which the entity is available.

In addtion, you can easily add and modify the interfaces of an entity through an

inline form.

On an entity listing page you can also reassign the entities easily to different

locations and/or projects using the inline fields.

Managing interfaces data

~~~~~~~~~~~~~~~~~~~~~~~~

For every interface you can provide the following information:

* *Name* of an interface. This should usually by system-specific name, for example *eth0*.

* *Description* of an interface.

* *Entity* to which an interface belongs.

* *Address* of an interface. This is usually an IP address.

* *Netmask* of an interface. When specifying a single specific IP address, this

  should be set to 255.255.255.255 (the default).

When an interface is representing a single IP address, the *address* should be

set to interface's IP address, and *netmask* should be set to

*255.255.255.255*. If specifying the subnet, the *address* and *netmask* will be

used to denote the subnet of format *address*/*netmask*. Conntrackt

distinguishes between these two types of *address* and *netmask* combination,

and produces appropriate iptables rules in both cases.

In addition to specifying an interface from the dedicated interface pages, a

more convenient way to add them is when adding or modifying the end

entities. Each end entity will have inline forms where you can provide the

information about its interfaces.

Another useful way to modify the interface information is using the inline

fields on the interface listing page (especially when making changes to a large

number of entities due to subnet changes for the in the project).

Managing communications data

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For every communication you can provide the following information:

* *Source* of communication, which denotes a specific interface (of a specific

  entity) **from** which the communication is established.

* *Destination* of communication, which denotes a specific interface (of a

  specific entity) **to** which the communication is established.

* *Protocol* used for the communication. Supported protocols currently include

  *TCP*, *UDP*, and *ICMP*.

* *Port* used for the communication. In case of *TCP* and *UDP*, this value

  denotes the actual port, while in case of *ICMP* protocol, this value will

  denote the **ICMP package type** - specified as **numeric** value.

When editing communications you may find it particularly useful to add them

through the communications list page by first specifying a filter (by project

and/or location), and then clicking on the *Add communication* link. This way

the filter will be applied to *source* and *destination* fields.

For example, if you choose project **Test**, and location **Main site**, and then click

on the *Add communication* button, the *source* and *destination* fields will be

limited to entity interfaces that specificaly belong to the **Test** project and

location **Main site**.

You can also easily modify existing communications using the communication

listing page. From there you can easily modify source, destination, protocol,

and port. Similarly to adding a new communication, you can apply a filter that

will narrow-down the selection for source and destination. It is highly

recommended to apply the filter in this way.

Iptables generation

-------------------

In addition to tracking the communications across a project, one of the main

features of Conntrackt is its ability to generate the *iptables* rules for all

entities in project based on provided communications data.

These *iptables* rules can then be easily applied to *GNU/Linux* entities. The

rules are generated with the following rules in mind:

* Default target for *INPUT* chain is *DROP*.

* Default target for *FORWARD* chain is *DROP*.

* Default target for *OUTPUT* chain is *ALLOW*.

* No limits are imposed on the *OUTPUT* chain.

* Rules for the *INPUT* chain are applied using a whitelist basis. Only

  explicitly defined communications in the iptables will be used to generate the

  *ACCEPT* rules. The matching is performed based on *source*, *protocol*, and

  destination *port*.