Getting Started

Live Demo

If you’d like to check out a demo of DefectDojo before installing it, you can check out on our Heroku demo site.

You can log in as an administrator like so:

You can also log in as a product owner or non-staff user:

Docker Compose Install

Setup.bash Install

Installation - Setup.bash is temporarily depricated. It is recommended you use the docker-compose install

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 any Linux 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 haven’t already, run mysql_secure_install to set a password for your root MySQL user.
  2. Create a MySQL user with CREATE privileges, 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

Install Script

Run the script:


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 the packages for this OS are:

  • gcc
  • libssl-dev
  • python-dev
  • libmysqlclient-dev
  • python-pip
  • mysql-server
  • nodejs-legacy
  • npm

The python packages are listed in requirements.txt.

After all the components have been installed, the makemigrations process will prompt you to create a superuser

You have installed Django's auth system, and don't have any superusers defined.
Would you like to create one now? (yes/no):

Answer yes and follow the prompts, this will be the user you will use to login to DefectDojo.

  1. (OPTIONAL) If you haven’t already, run mysql_secure_install to set a password for your root MySQL user.
  2. Edit the file to modify any other settings that you want to change, such as your SMTP server information, which we leave off by default.
  3. When you are ready to run DefectDojo, run the server with ./run_dojo.bash

Environment Variables

All the DefectDojo settings and Django configurations in can be customized through the use of environment variables or a .env file.

DefectDojo currently uses django-environ, which allows you to use the Twelve-factor methodology, to configure your Django application with environment variables.

Environment variables can be set from the os environment by setting the variable as follows: export DD_DEBUG=on or environment settings can be specified in a file in the dojo/settings/ folder or specify a different environment by setting DD_ENV_PATH with the name of the env file you wish to use, dev.env for example.

DefectDojo Environment Variables

Required Variables

The following variables, at a minimum, must be set in order to start DefectDojo.

A secret key for a particular Django installation. This is used to provide cryptographic signing, and should be set to a unique, unpredictable value.
AES 256 key for encrypting sensitive data such as passwords in DefectDojo. Set to at least a 256-bit key and should be set to a unique, unpredictable value.

DefectDojo by default has debug set to off. If testing locally then set DD_DEBUG=on.

If debug is false then assets such as images will not served. If you want assets to be viewed then set DD_WHITENOISE=on.

WhiteNoise allows your web app to serve its own static files, making it a self-contained unit that can be deployed anywhere without relying on nginx, Amazon S3 or any other external service. (Especially useful on Heroku, OpenShift and other PaaS providers.)

Hosts/domain names that are valid for this site; If DEBUG is False, default is localhost/

Database connections are expressed as URL’s conforming to the 12factor approach

  • MySQL: mysql://user:password@host:port/database
  • MySQL example: export DD_DATABASE_URL=mysql://root:password@
  • PostgreSQL: postgres://, pgsql://, psql:// or postgresql://
  • SQLITE: sqlite://

Sample env file

prod.env in dojo/settings/prod.env:


Complete DefectDojo Variables List

If not in os.environ, to enable set DD_DEBUG=on Default: False
Raises Django’s ImproperlyConfigured exception if SECRET_KEY not in os.environ Default: None, must be set by the user
Local time zone for this installation. Choices can be found here: Default: UTC
Language code for this installation. All choices can be found here: Default: en-us
The ID, as an integer, of the current site in the django_site database table. This is used so that application data can hook into specific sites and a single database can manage content for multiple sites. Default: 1
If you set this to False, Django will make some optimizations so as not to load the internationalization machinery. Default: True
If you set this to False, Django will not format dates, numbers and calendars according to the current locale. Default: True
If you set this to False, Django will not use timezone-aware datetimes. Default: True
The name of the class to use for starting the test suite. Default: django.test.runner.DiscoverRunner
Database string expressed as a URL, refer to the documentation above for formatting. Default: Must be set by the user
Track database migrations through source control rather than managing migrations locally. Default: False
Absolute filesystem path to the directory that will hold user-uploaded files. Default: media
URL that handles the media served from MEDIA_ROOT. Make sure to use a trailing slash. Default: /media/
Absolute path to the directory static files should be collected to. Default: static
URL prefix for static files. Default: /static/
URL prefix to append, for example DefectDojo is installed in a subdirectory on the server Default: None
If True, the SecurityMiddleware redirects all non-HTTPS requests to HTTPS Default: False
If True, the SecurityMiddleware sets the X-XSS-Protection: 1; Default: False
Whether to use HTTPOnly flag on the session cookie. Default: False
Whether to use HttpOnly flag on the CSRF cookie. Default: True
Whether to use a secure cookie for the CSRF cookie. Default: False
Adds an HTTP_X_FORWARDED_PROTO Default: False
Path to WKHTMLTOPDF Default: /usr/local/bin/wkhtmltopdf
Used in a few places to prefix page headings and in email salutations Default: None
Tags that are used in for product, findings etc. and should the ability to force as lowercase. Default: True
The maximum length of a tag Default: 25
DefectDojo admins Default: DefectDojo:dojo@localhost,Admin:admin@localhost
Django has a build in admin module (/admin), setting enables or disables this built in Django feature. Default: False
WhiteNoise allows your web app to serve its own static files Default: False
Celery broker Default: sqla+sqlite:///dojo.celerydb.sqlite
Ignore celery result Default: True
Default: db+sqlite:///dojo.celeryresults.sqlite
Seconds to expiration Default:86400
Beat filename Default: /dojo.celery.beat.db
Options: ‘pickle’, ‘json’, ‘msgpack’ or ‘yaml’ Default: pickle