Contribute

From Digital Forensics Framework

Jump to: navigation, search

Contents

First of all

Any contribution is always welcome, even this page is about technical contributions, on the source code. For any other contribution please read our community page and/or the features request section.

For developers : it is mandatory to map your user-name please see Mapping your user section.

Source code read access

Digital Forensics Framework use GIT as source code manager. Access is freely available to everyone using address :

git://git.digital-forensic.org/dff.git

Keep in mind that you'll can only read on this address. Read + write access is available using a different service ; see below.

Source code write access

In order to contribute, you have to send us your ssh public key. If you already have a ssh public key, go to step Send us your ssh public key.

Generate your own ssh public key

Unix

Use ssh-keygen command to generate your 2048bits RSA private and public keys. Here is an example for user cma:

cma@chichodrome ~ $ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/cma/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/cma/.ssh/id_rsa.
Your public key has been saved in /home/cma/.ssh/id_rsa.pub.
The key fingerprint is:
e8:f6:62:c8:f6:37:ea:6a:d0:b4:f0:18:82:53:e2:dd cma@chichodrome
The key's randomart image is:
+--[ RSA 2048]----+
[...]
+-----------------+
cma@chichodrome ~ $ ls -la ~/.ssh
[...]
-rw-------  1 cma users 1675 Jan 11 15:57 id_rsa
-rw-r--r--  1 cma users  401 Jan 11 15:57 id_rsa.pub
[...]

The ssh-keygen asks you where to store keys, it also asks you for a pass-phrase, it is not mandatory to submit a pass-phrase although it is advised.

Once completed, you public keys is usually in ~/.ssh/id_rsa.pub path.

Windows

Use PuTTYgen, from Simon Tatham.

Double-click on puttygen.exe, first step : click on Generate:

Puttygen1.png

Move your mouse to generate entropy:

Puttygen2.png

Wait before completion of the generation process:

Puttygen3.png

Optionally, but advised, add a pass-phrase to protect your key:

Puttygen5.png

Final step : save both public and private keys in a safe location:

Puttygen6.png

Send us your ssh public key

Depending on the generation method ;

  • on Unix you have to send us ~/.ssh/id_rsa.pub
  • on Windows where you save it at the final step

Send the text contained in this public key, or the entire file, to cma@digital-forensic.org also add the user-name you own on DFF wiki/bug-tracker or the user-name you wish to use.

Use your key with GIT

The URL to use to clone our repository is not the same as the public version, you have to prepend the git user and use SSH instead of GIT what is done with this URL :

git@git.digital-forensic.org:dff.git

With this URL, we use SSH protocol ; everybody use the git user, and authentication is made with your public key ; added to this user.

Unix

On Linux / BSD ; your id_rsa and id_rsa.pub just have to sit in ~/.ssh/ to be used. Once your key have been validated just run this command to clone the repository in contributor mode:

git clone git@git.digital-forensic.org:dff.git

This will create a new dff directory under the path you run the command. To clone in a different directory use this command:

git clone git@git.digital-forensic.org:dff.git dff-repository

This will clone the repository in a directory named dff-repository.

Windows

On Windows we recommend usage of TortoiseGIT + MSysGIT. With it you can easily add your .pub and .ppk generated with PuTTYgen. In fact we will only add the .ppk key because this .ppk is made of both public and private key.

First step, right click in the blank area in the directory where you want to add DFF and select Git clone...:

Gitclone1.png

Second step, add the URL git@git.digital-forensic.org:dff.git, check Load Putty Key and add the path where your private key .ppk is and click OK:

Gitclone2.png

The fetching process starts:

Gitclone3.png

First time you connect to our repository, you will be warned this is a new repository, click Yes to add our repository to your trusted pool:

Gitclone4.png

Final step : Fetching process done, click Close:

Gitclone5.png

Mapping your user

Because user-name on your computer generally differs from the one used on DFF wiki/tracker/GIT, you have to set your user-name and e-mail up. If you don't do this, activity and statistics will not be mapped to your user-name. What is very annoying.

Unix

On Unix this can be achieved by adding this three lines in the file ~/.gitconfig, here is an example for the user cma:

[user]
        name = cma
        email = cma@digital-forensic.org

Windows

Right click in a blank area, under ToitoiseGit select Settings:

Toirtoisegit1.png

On the left select Git, Config and add your User Info according to your account on DFF wiki/tracker, here is an example for the user cma:

Toirtoisegit2.png

Working with GIT

Many documentation exists on GIT usage.

Here are several things you must do :

  • Create one master ticket, and several others if relevant, on the tracker
  • Work and push your work in a dedicated branch (named with the feature you work on)
  • Referencing ticket in your commit messages
  • If previous framework files have been modified by your commit it is also advised to explicitly lists those files (except only yours impacted).
  • Mastering GIT, for example guide of our VLC friends is very usefull !

Submission guidelines

Submit a bug

If you have encountered a bug during DFF run, don't hesitate to give feedback by registering on the tracker. Your registration will be validated and you will be able to report bugs.

Although it is advised to register on the tracker, you can also :

  • send an email to the user mailing-list dff@digital-forensic.org
  • or to the developer mailing list dff-devel@digital-forensic.org
  • finally you can use the contact form to contact the core-team of DFF.

What to provide

In order to let the team react rapidly, you will have to provide some information:

  • Architecture (x86 / amd64, ...)
  • Operating System (Windows, Linux, Unix, ...), its version and finally if 32 or 64 bits
  • The complete traceback
Category of bugs
  • If DFF provides the traceback through the python interpreter, then copy and paste it.
  • If DFF segfaults (yes, it could be possible...), you have several ways to give us some useful details
Segfault tracking under Linux / Unix

If it segfaults at start

user@dff > ulimit -c 2000000
user@dff > ./dff.py
user@dff > gdb -c core

If it segfault during usage

  • run dff.py
  • type the following command in another terminal
user@dff > pgrep dff
user@dff > 3442
user@dff > gdb
(gdb) attach 3442
[...]
(gdb) c

3) Try to generate the encountered segfault and then go back to gdb and type:

(gdb) bt
[...]

In the bug request, provide results provided by gdb.

Segfault tracking under Windows

In order to track segfaults under Windows, you will need to run the project through Visual Studio. It will provide some details concerning the segfault.

Features requests

If you need or want some specific features, either you can post your request via the tracker by tagging with Features.

Same as for the bug reporting :

  • it is advised to register on the tracker
  • you can also send an email to the user mailing-list dff@digital-forensic.org
  • or to the developer mailing list dff-devel@digital-forensic.org
  • finally you can use the contact form to contact the core-team of DFF.

Translation

A dedicated page exists, please see Translate DFF.

Ideas list

This ideas list has for goal to give some subject of development for student who work on DFF.