Account Locking

For security reasons you may want to introduce account locking, where after a set number of incorrect passwords users cannot log into their accounts even when they have the correct password. This can prevent brute force password attacks. Foreman allows admins to pick the account lock number from 1 to 5, or none (default). This is available in the “User & Account Options” Tab in “Administration”:

This is what a user would see when they are locked out:

Admins can unlock users in the “Validate, Reset, & Deactivate Users” tab in “Administration”. Note that the number of locked users is highlighted in the tab title in red:

If there are users locked out, and the admin changes the account lock setting from X attempts to No lockout, they are all automatically unlocked.

Process Flow

I’ve created a process for Foreman. This shows a typical flow of a case through all the different users. Click to enlarge.

User Journey: Authorisers

Authorisers have the least amount of permissions on Foreman. They are allowed to authorise/reject cases and to view those cases. The administrative panel also has an option to allow authorisers to see tasks and evidence associated with those cases. When a requester selects an authoriser from their department when adding a new case, an email is sent to the authoriser for them to review the case details and approve/reject. If the authoriser rejects the case, the requester is able to edit the case and resubmit for authorisation. Case work cannot start until the case has been authorised.

1. The requester has created a new case. The status is “Awaiting authorisation” and Frank has been sent an email.
2. Frank logs in and sees all the cases he must authorise. By clicking on the case name, he will see the case details.
3. Frank can now click on authorise/reject this case after reviewing the details
4. The case history appears at the top of the page. In this instance, Frank rejects the case
5. The requester Rafael will receive an email with Frank’s reason for rejection. Rafael can edit the case, and this automatically changes the status from Rejected to Pending, and sends another email to Frank to authorise. Below, Frank accesses the authorise page again. The case history shows the changes Rafael has made to the justification, and this time, Frank approves the case. 

Here is a summary of the permissions a case authoriser has:

Cases	add new case	N
	authorise case	Y
	view cases associated with	Y
	view other cases	N
	update case status	N
	close & archive case	N
	edit case details	N
	link with other cases	N
	add/edit case managers	N
	move tasks to other cases	N
	upload file	N
	generate report	N
Task	add new task	N
	view task associated with	Y*
	view other tasks	N
	edit task details	N
	assign someone as investigator/QA	N
	assign self as investigator/QA	N
	update task status	N
	upload task file	N
	update task notes	N
	complete task investigation	N
	complete task QA	N
Evidence	add evidence	N
	view evidence associated with	Y*
	view evidence	N
	check in / out evidence	N
	add evidence photo	N
	edit evidence details	N
	add evidence QR code	N
	move evidence to other case	N

* – denotes this is an admin option to allow/disallow this. Authorisers cannot see cases (and associated tasks & evidence) that they have not authorised.

How to deploy to a web server

Foreman comes with the default Python server, which when run will run Foreman in the localhost on port 5000. This is fine when it’s just one person using Foreman or its being used on a shared machine, bet it’s likely you’ll want to deploy Foreman onto a webserver so it can be accessed by lots of people. Below is a guide if you are using Apache on Linux.

1. Download mod_wsgi. On Debian this can be done via:

apt-get install libapache2-mod-wsgi

2. Create a foreman.wsgi file with the following contents inside the foreman folder:

#!/usr/bin/env python
import sys, site
from os import path

sys.path.append(path.dirname(__file__))

site.addsitedir('[Path to Foreman package]')
config = '[Path to Foreman config file]'

sys.path.append(path.dirname(__file__))

def make_app():
from foreman.utils.utils import setup
setup(config)

from foreman.application import make_app
return make_app()

application = make_app()

3. Finally, Apache needs configuring. An example is below:

<VirtualHost *>
    ServerName example.com

    WSGIDaemonProcess foreman user=user1 group=group1 processes=2 threads=5
    WSGIScriptAlias / [Path to WSGI file]/foreman.wsgi

    <Directory [Path to Foreman]>
        WSGIProcessGroup foreman
        WSGIApplicationGroup %{GLOBAL}
        Order deny,allow
        Allow from all
    

Documentation on mod_wsgi can be found here.

Evidence Retention Policy Reminders

If your are part of a large organisation, then it is likely that you will have an evidence retention policy which states how long you should keep evidence (both physical and logical) after the case has been completed. Foreman now has an admin section where this policy can be applied:

When an ‘archived’ piece of evidence reaches the retention period (i.e. x number of months after the archival date), an email will be sent to the user who added the evidence initially into Foreman and all the current administrators (just in case that user is no longer in the team) so that they can destroy the evidence according to their policy. They can then update the evidence status in Foreman to ‘destroyed’ [More on Evidence statuses here]. To set up the emails, an automated daily task is required, for example using CRON (Linux) or Task Scheduler (Windows). The following script should be run once daily:

python run_foreman.py scheduled_tasks

When run, this checks all the currently archived pieces of evidence and sees if retention period has been set. If so, all those which are due destruction generate emails. A flag is set so that the email is only send once and not repeatedly. Please remember that the config file should point to the correct Foreman database and have an email server set up.

There are two options if a retention period is changed / no longer needed:

1. Existing retention emails still required, and only evidence archived from this point should not have retention periods: Administrator should select “No” for Evidence Retention Reminders
2. All retention emails should be stopped: Administrator should select “No” for Evidence Retention Reminders and tick Remove existing reminders

New Feature: Custom Text on Pages

Administrators in the administration panel are now able to add some custom text to the top of all add/edit pages for cases, tasks and evidence. This may be useful to add specific instructions to users, links to URLs (internal procedures & policies, or external links such as the ACPO guidelines) or other information; so that Foreman can smoothly integrate with your team practices.

The screenshot below shows the ability to add custom text to the task add & edit pages:

The screenshot below shows the output of the custom text added to the ‘add task’ page. This will be the same text for the ‘edit task’ page, but the administrator can choose different text for cases and evidence.

Debugging Foreman

Occasionally I will have missed a bug, and you might see the following page when you click a link:

Please raise a ticket and I’ll try and fix it – add a screenshot of the command line error you see and also what you did to create the error. However, if you’d like to try and debug this yourself, I suggest you turn on debug mode. The default config file has debug turned off but you can easily turn this on by changing debug = true. The config files are located at <foreman root>\foreman\config, and should have an entry like this:

[debugging]
# Debugging options. Set to true if Foreman errors and you would like an interactive debugger.
debug = true

Restart the Foreman server with the edited config file, and now, instead of the page above, you will get an interactive Python debugger!

If you hover over one of the light blue lines, a little black command line icon in the right-hand corner will appear. Click on that and you can now type in Python to interact with Foreman. The best starting point is to type dump() which will show all the variables currently in use:

This should help in working out what is wrong. Usually Foreman is expecting a value and the variable is actually null (None in Python).

Happy bug hunting!

Foreman Forensics Blog

This will be a place for me to add some detailed posts on any Foreman features, common setup issues and how Foreman does the case management process. Hopefully a helpful blog to those using Foreman or those interested in what it looks like and what it can do.