DefectDojo Documentation Release 1.3.1 Greg Anderson (@_GRRegg), Charles Neill (@ccneill), Jay Paz (@ May 16, 2018
DefectDojo DocumentationRelease 1.3.1
Greg Anderson (@_GRRegg), Charles Neill (@ccneill), Jay Paz (@jjpaz)
May 16, 2018
Contents
1 User Documentation 31.1 About DefectDojo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.4 Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.5 Usage Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.6 Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.7 Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.8 Running in Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2 Feature Documentation 332.1 DefectDojo Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3 API Documentation 553.1 DefectDojo API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
i
ii
DefectDojo Documentation, Release 1.3.1
About DefectDojo
What is DefectDojo?
DefectDojo is a security tool that automates application security vulnerability management. DefectDojo streamlinesthe application security testing process by offering features such as importing third party security findings, mergingand de-duping, integration with Jira, templating, report generation and security metrics.
What does DefectDojo do?
While traceability and metrics are the ultimate end goal, DefectDojo is a bug tracker at its core. Taking advantage ofDefectDojos Product:Engagement model, enables traceability among multiple projects and test cycles, and allows forfine-grained reporting.
How does DefectDojo work?
DefectDojo is based on a model that allows the ultimate flexibility in your test tracking needs.
Working in DefectDojo starts with a Product Type.
Each Product Type can have one of more Products.
Each Product can have one or more Engagements.
Each Engagement can have one more Tests.
Each Test can have one or more Findings.
Contents 1
DefectDojo Documentation, Release 1.3.1
The code is open source, and available on github.
A demo installation can be found over at PythonAnywhere.
Our documentation is organized in the following sections:
User Documentation
Feature Documentation
API Documentation
2 Contents
https://github.com/rackerlabs/django-DefectDojohttps://defectdojo.pythonanywhere.com
CHAPTER 1
User Documentation
1.1 About DefectDojo
1.1.1 DefectDojo Basics
Terms
There are several terms that will be helpful to understand as you work with DefectDojo
Products
This is the name of any project, program, team, or company that you are currently testing.
Examples
OpenStack Neutron
Internal wiki
Hipchat
Product types
These can be business unit divisions, different offices or locations, or any other logical way of distinguishing typesof products.
Examples
Internal / 3rd party
Main company / Acquisition
San Francisco / New York offices
3
DefectDojo Documentation, Release 1.3.1
Engagements
Engagements are moments in time when testing is taking place. They are associated with a name for easy reference, atime line, a lead (the user account of the main person conducting the testing), a test strategy, and a status.
Examples
Beta
Quarterly PCI Scan
Release Version X
Test Types
These can be any sort of distinguishing characteristic about the type of testing that was done during an Engagement.
Examples
Functional
Security
Nessus Scan
API test
Development Environments
These describe the environment that was tested during a particular Engagement.
Examples
Production
Staging
Stable
Projects that extend DefectDojo
In an effort to keep the main Defectdojo functionality as separate from our own needs as possible, the RackspaceSecurity Engineering team have made it possible to extend DefectDojo without the need to hack it or look under thehood. Some of the projects that extend DefectDojo as Django apps are as follows:
DefectDojo Engagement Survey_.
This project extends django-DefectDojo by incorporating survey(s) associated with each engagement to help developa test strategy. The questions within these surveys have been created by the Rackspace Security Engineering teamto help identify the attack vectors and risks associated with the product being assessed. .. _DefectDojo EngagementSurvey: https://github.com/grendel513/defectDojo-engagement-survey
1.2 Getting Started
Demo If youd like to check out a demo of DefectDojo before installing it, you can check out on our PythonAnywheredemo site.
You can log in as an administrator like so:
4 Chapter 1. User Documentation
https://github.com/grendel513/defectDojo-engagement-surveyhttps://defectdojo.pythonanywhere.comhttps://defectdojo.pythonanywhere.com
DefectDojo Documentation, Release 1.3.1
You can also log in as a product owner or non-staff user:
Installation
Change into the newly created `django-DefectDojo` directory:
cd django-DefectDojo/
There is a script in the main folder called setup.bash that will allow you to interactively install DefectDojo on anyLinux based systems. We do not recommend running DefectDojo as root, but you may do so if you choose.
You will need: * MySQL * pip
Recommended * virtualenv
1. If you havent already, run mysql_secure_install to set a password for your root MySQL user.
2. Create a MySQL user with CREATE priviledges, or use root.
Run the setup.bash script This script will:
1. Install all the operating system packages needed
2. Prompt for database connection information and create the necessary table
3. Install all python packages needed
4. Either makemigrations and migrate or syncdb depending on Django version installed.
5. Provide you with the commands needed to complete the installation
1.2.1 Install Script
Run the script:
./setup.bash
During the execution you will be prompted for a few items:
MySQL user (should already exist):
Enter the user you created or root if you used `mysql_secure_installation`
Password for user:
Enter the password for the MySQL user you selected.
Database name (should NOT exist):
Select a name for the DefectDojo database.
All the packages It may take some time for all the OS and python packages to be installed. As of this writing thepackages for this OS are:
gcc
libssl-dev
1.2. Getting Started 5
DefectDojo Documentation, Release 1.3.1
python-dev
libmysqlclient-dev
python-pip
mysql-server
nodejs-legacy
npm
And the python packages are (listed in setup.py as well):
Django==1.8,
MySQL-python==1.2.3,
Pillow==5.0.0,
django-tastypie==0.12.1,
django-tastypie-swagger,
gunicorn==19.1.1,
python-nmap==0.3.4,
pytz==2013.9,
requests==2.2.1,
wsgiref==0.1.2,
django-filter,
supervisor,
humanize
After all the components have been installed, the makemigrations process will prompt you to create a superuser
You have installed Djangos auth system, and dont have any superusers defined. Would you liketo create one now? (yes/no):
Answer yes and follow the prompts, this will be the user you will use to login to DefectDojo. #. (OPTIONAL) If youhavent already, run mysql_secure_install to set a password for your root MySQL user. #. Edit the settings.py file tomodify any other settings that you want to
change, such as your SMTP server information, which we leave off by default.
1. When you are ready to run DefectDojo, run the server with ./run_dojo.bash
1.2.2 Vagrant Install
You will need:
Vagrant
VirtualBox
Ansible
Instructions:
1. Modify the variables in ansible/vars.yml to fit your desired configuration
2. Type vagrant up in the repos root directory
6 Chapter 1. User Documentation
DefectDojo Documentation, Release 1.3.1
3. If you have any problems during setup, run vagrant provision once youve fixed them to continue provi-sioning the server
4. If you need to restart the server, you can simply run vagrant provision again
By default, the server will run on port 9999, but you can configure this in the vars.yaml file.
1.2.3 Docker Install
There are three versions of Docker Dojo. The first version is a development / testing version, the second is a dockercompose file with Nginx, MySQL and DefectDojo and the third is a Docker Cloud file for Docker Cloud.
Docker Local Install
You will need:
Latest version of Docker
Instructions:
1. Run the docker command to pull the latest version of DefectDojo. docker run -it -p8000:8000 appsecpipeline/django-defectdojo bash -c "exportLOAD_SAMPLE_DATA=True && bash /opt/django-DefectDojo/docker/docker-startup.bash"
2. Navigate to: http://localhost:8000 and login with the credentials shown in the terminal.
Docker Compose Install
You will need:
Latest version