Below are the main sections within DefectDojo. Each is designed to allow for ease of use and simple organization of Products and their Tests. The :doc:`models` page will help you understand the terminology we use below, so we recommend taking a look at that first.

The following attributes describe a Product:

Name

A short name for the product, used for easy identification. This field can hold up to 300 characters.

Description

Used to fully describe the product. This field can hold up to 2000 characters.

Product Manager

Provides the ability to store who manages the product lifecycle. Useful for contacting team members. This field can hold up to 200 characters.

Technical Contact

Provides the ability to store who should be contacted in case of technical questions and/or difficulties.models. This field can hold up to 200 characters.

Manager

Provides the ability to store who manages the technical resources for the product. This field can hold up to 200 characters.

Date Created

Stores when the Product was fist added to DefectDojo.

Product Type

Used to group products together.

Authorized Users

List of users who are allowed to view and interact with the product.

Products are listed on the /product page and can be filtered by their attributes as well as sorted by their name and product type.

Visual representation of a product:

Product with metrics drop down displayed:

The following attributes describe an Engagement:

Name

Helps distinguish one Engagement from another on the same product. This field can hold up to 300 characters.

Target Start Date

The projected start date for this engagement.

Target End Date

The projected end date for this engagment.

Lead

The DefectDojo user who is considered the lead for this group of tests.

Product

The Product being tested as part of this group of tests.

Active

Denotes if the Engagement is currently active or not.

Test Strategy

The URL of the testing strategy defined for this Engagement.

Threat Model

The document generated by a threat modeling session discussing the risks associated with this product at this moment in time.

Status

Describes the current state of the Engagement. Values include In Progress, On Hold and Completed.

Engagements are listed in the /engagement page and can be filtered by their attributes as well as sorted by the product or product type.

Visual representation of an engagement:

Endpoints represent testable systems defined by IP address or Fully Qualified Domain Name.

The following attributes describe an Endpoint:

Protocol

The communication protocol such as 'http', 'https', 'ftp', etc.

Host

The host name or IP address, you can also include the port number. For example '127.0.0.1', '127.0.0.1:8080', 'localhost', 'yourdomain.com'.

Path

The location of the resource, it should start with a '/'. For example "/endpoint/420/edit"

Query

The query string, the question mark should be omitted. "For example 'group=4&team=8'

Fragment

The fragment identifier which follows the hash mark. The hash mark should be omitted. For example 'section-13', 'paragraph-2'.

Product

The Product that this endpoint should be associated with.

Endpoints are listed in the /engagement page and can be filtered by their attributes as well as sorted by the product or host.

Visual representation of an endpoint:

Visual representation of an endpoint with metrics displayed:

Findings represent a flaw within the product being tested. The following attributes help define a Finding:

Title

A short description of the flaw (Up to 100 characters)

Description

Longer more descriptive information about the flaw.

Date

The date the flaw was discovered.

CWE

The CWE nubmer associated with this flaw.

Severity

The severity level of this flaw (Critical, High, Medium, Low, Informational)

Numerical Severity

The numerical representation of the severity (S0, S1, S2, S3, S4)

Mitigation

Text describing how to best fix the flaw.

Impact

Text describing the impact this flaw has on systems, products, enterprise, etc.

Endpoints

The hosts within the product that are susceptible to this flaw.

References

The external documentation available for this flaw.

Test

The test that is associated with this flaw. The flaw belong to the test.

Is Template

Denotes of this finding is a template and can be reused.

Active

Denotes if this flaw is active or not.

Verified

Denotes if this flaw has been manually verified by tester.

False Positive

Denotes if this flaw has been deemed a false positive by the tester.

Duplicate

Denotes if this flaw is a duplicate of other flaws reported.

Out Of Scope

Denotes if this flaw falls outside the scope of the test and/or engagement.

Mitigated

Denotes if this flaw has been fixed, by storing the date it was fixed.

Mitigated By

Documents who has deemed this flaw as fixed.

Reporter

Documents who reported the flaw.

Last Reviewed

Provides the date the flaw was last "touched" by a tester.

Last Reviewed By

Provides the person who last reviewed the flaw.

Notes

Stores information pertinent to the flaw or the mitigation.

Images

Finding images can now be uploaded to help with documentation and proof of vulnerability.

If you are upgrading from an older version of DefectDojo, you will have to complete the following and make sure MEDIA_ROOT and MEDIA_URL are properly configured:

Add imagekit to INSTALLED_APPS:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'polymorphic',  # provides admin templates
    'overextends',
    'django.contrib.admin',
    'django.contrib.humanize',
    'gunicorn',
    'tastypie',
    'djangobower',
    'auditlog',
    'dojo',
    'tastypie_swagger',
    'watson',
    'tagging',
    'custom_field',
    'imagekit',
)

Add r'^media/' to LOGIN_EXEMPT_URLS:

LOGIN_EXEMPT_URLS = (
    r'^static/',
    r'^metrics/all$',
    r'^metrics$',
    r'^metrics/product/type/(?P<mtype>\d+)$',
    r'^metrics/simple$',
    r'^api/v1/',
    r'^ajax/v1/',
    r'^reports/cover$',
    r'^finding/image/(?P<token>[^/]+)$'
)

Then run the following commands (make sure your virtual environment is activated):

pip install django-imagekit
pip install pillow --upgrade
./manage.py makemigrations dojo
./manage.py makemigrations
./manage.py migrate

New installations will already have finding images configured.

Findings are listed on the /finding/open, /finding/closed, and /finding/accepted pages. They can be filtered by their attributes as well as sorted by their Name, Date, Reviewed Date, Severity and Product.

Visual representation of a Finding:

Automatically Removing Duplicate Findings

'Deduplication' is a feature that when enabled will compare findings to automatically identify duplicates. To enable deduplcation change 'ENABLE_DEDUPLICATION = False' to 'ENABLE_DEDUPLICATION = True' in your settings.py file. If you are upgrading from an older version of Dojo simply add 'ENABLE_DEDUPLICATION = True'.

Dojo deduplicates findings by comparing endpoints, cwe fields, and titles. If a two findings share a URL and have the same CWE or title, Dojo marks the less recent finding as a duplicate. When deduplication is enabled, a list of deduplicated findings is added to the engagement view.

DefectDojo provides a number of metrics visualization in order to help with reporting, awareness and to be able to quickly communicate a products/product type's security stance.

The following metric views are provided:

Product Type Metrics

This view provides graphs displaying Open Bug Count by Month, Accepted Bug Count by Month, Open Bug Count by Week, Accepted Bug Count by Week as well as tabular data on Top 10 Products by bug severity, Detail Breakdown of all reported findings, Opened Findings, Accepted Findings, Closed Findings, Trending Open Bug Count, Trending Accepted Bug Count, and Age of Issues.

Product Type Counts

This view provides tabular data of Total Current Security Bug Count, Total Security Bugs Opened In Period, Total Security Bugs Closed In Period, Trending Total Bug Count By Month, Top 10 By Bug Severity, and Open Findings. This view works great for communication with stakeholders as it is a snapshot in time of the product.

Simple Metrics

Provides tabular data for all Product Types. The data displayed in this view is the total number of S0, S1, S2, S3, S4, Opened This Month, and Closed This Month.

Engineer Metrics

Provides graphs displaying information about an testers activity.

Metrics Dashboard

Provides a full screen, auto scroll view with many metrics in graph format. This view is great for large displays or "Dashboards."

DefectDojo users inherit from django.contrib.auth.models.User.

A username, first name, last name, and email address can be associated with each. Additionally the following describe the type of use they are:

Active

Designates whether this user should be treated as active. Unselect this instead of deleting accounts.

Staff status

Designates whether the user can log into this site.

Superuser status

Designates that this user has all permissions without explicitly assigning them.

The calendar view provides a look at all the engagements occurring during the month displayed. Each entry is a direct link to the Engagement view page.

DefectDojo has the ability to import reports from other security tools. Currently importers exist for:

1. Burp XML
2. Nessus (CSV, XML)
3. Nexpose XML 2.0
4. ZAP XML
5. Veracode Detailed XML Report
6. Checkmarx Detailed XML Report
7. AppSpider Vulnerabilities Summary XML Report (VulnerabilitiesSummary.xml)
8. Arachni Scanner JSON Report
9. Visual Code Grepper XML or CSV
10. OWASP Dependency Check XML
11. Generic Findings in CSV format

The importers analyze each report and create new Findings for each item reported. DefectDojo collapses duplicate Findings by capturing the individual hosts vulnerable.

Additionally, DefectDojo allows for re-imports of previously uploaded reports. DefectDojo will attempt to capture the deltas between the original and new import and automatically add or mitigate findings as appropriate.

Bulk import of findings can be done using a CSV file with the following column headers:

Date: ::

Date of the finding in mm/dd/yyyy format.

Title: ::

Title of the finding

CweId: ::

Cwe identifier, must be an integer value.

Url: ::

Url associated with the finding.

Severity: ::

Severity of the finding. Must be one of Info, Low, Medium, High, or Critical.

Description: ::

Description of the finding. Can be multiple lines if enclosed in double quotes.

Mitigation: ::

Possible Mitigations for the finding. Can be multiple lines if enclosed in double quotes.

Impact: ::

Detailed impact of the finding. Can be multiple lines if enclosed in double quotes.

References: ::

References associated with the finding. Can be multiple lines if enclosed in double quotes.

Active: ::

Indicator if the finding is active. Must be empty, True or False

Verified: ::

Indicator if the finding has been verified. Must be empty, True, or False

FalsePositive: ::

Indicator if the finding is a false positive. Must be empty, True, or False

Duplicate: ::

Indicator if the finding is a duplicate. Must be empty, True, or False

DefectDojo has the ability to run a port scan using nmap. Scan can be configured for TCP or UDP ports as well as for a Weekly, Monthly or Quarterly frequency.

In order for the scans to kick off the dojo.management.commands.run_scan.py must run. It is easy to set up a cron job in order to kick these off at the appropriate frequency. Below is an example cron entry:

0 0 * * 0 /root/.virtualenvs/dojo/bin/python /root/defect-dojo/manage.py run_scan Weekly
0 0 1 * * /root/.virtualenvs/dojo/bin/python /root/defect-dojo/manage.py run_scan Monthly
0 0 1 3,6,9,12 * /root/.virtualenvs/dojo/bin/python /root/defect-dojo/manage.py run_scan Quarterly

The scan process will emal the configured recipients with the results.

These scans call also be kicked off on demand by selecting the Launch Scan Now option in the view scan screen.

DefectDojo's reports can be generated in AsciiDoc and PDF. AsciiDoc is recommended for reports with a large number of findings.

The PDF report is generated using wkhtmltopdf via Celery and sane defaults are included in the settings.py file. This allows report generation to be asynchronous and improves the user experience.

If you are updating from an older version of DefectDojo, you will need to install wkhtmltopdf on your own. Please follow the directions for your specific OS in the wkhtmltopdf documentation.

Some operating systems are capable of installing wkhtmltopdf from their package managers:

Mac:

brew install Caskroom/cask/wkhtmltopdf

Debian/Ubuntu:

sudo apt-get install wkhtmltopdf

Fedora/Centos:

sudo yum install wkhtmltopdf

Additionally, DefectDojo takes advantage of python-PDFKit to interact with the wkhtmltopdf commandline interface. It is easily installed by running:

pip install pdfkit

It will also be necessary to add the path of wkhtmltopdf to your settings.py file. By default the following entry ships with DefectDojp:

WKHTMLTOPDF_PATH = '/usr/local/bin/wkhtmltopdf'

However you make have to update that entry to suite your installation.

Celery is included with DefectDojo and needs to be kicked off in order for reports to generate/work. In development you can run the celery process like:

celery -A dojo worker -l info --concurrency 3

In production it is recommended that the celery process be daemonized. Supervisor is also included with DefectDojo and can be set up by following the Celery documentation. A sample celeryd.conf can be found at.

Celery beat should also be running, this will allow for celery to clean up after itself and keep your task database from getting too large. In development you can run the process like:

celery beat -A dojo -l info

In production it is recommended that the celery beat process also be daemonized. A sample celerybeatd.conf can be found here.

If you are upgrading from an older version of DefectDojo, you will have to install Celery on your own. To do this you you can run:

pip install celery

You will also need to install sqlalchemy:

pip install sqlalchemy

If you are using virtual environments make sure your environment is activated. You can also follow the installation instructions from the Celery documentation.

Reports can be generated for:

1. Groups of Products
2. Individual Products
3. Endpoints
4. Product Types
5. Custom Reports

Filtering is available on all Report Generation views to aid in focusing the report for the appropriate need.

Custom reports allow you to select specific components to be added to the report. These include:

1. Cover Page
2. Table of Contents
3. WYSIWYG Content
4. Findings List
5. Endpoint List
6. Page Breaks

The custom report workflow takes advantage of the same asynchronous process described above.

DefectDojo's JIRA integration is bidirectional. You may push findings to JIRA and share comments. If an issue is closed in JIRA it will automatically be closed in Dojo.

Preparing Jira, Enabling the Webhook

1. Visit https://<YOUR JIRA URL>/plugins/servlet/webhooks
2. Click 'Create a Webhook'
3. For the field labeled 'URL' enter: https://<YOUR DOJO DOMAIN>/webhook
4. Under 'Comments' enable 'Created'. Under Issue enable 'Updated'.

Configurations in Dojo

1. In dojo/settings.py set ENABLE_JIRA = True.

Adding JIRA to Dojo

1. Click 'JIRA' from the left hand menu.
2. Select 'Add Configuration' from the drop-down.
3. To obtain the 'open status key' and 'closed status key' visit https://<YOUR JIRA URL>/rest/api/latest/issue/<ANY VALID ISSUE KEY>/transitions?expand=transitions.fields
4. The 'id' for 'Todo' should be filled in as the 'open status key'
5. The 'id' for 'Done' should be filled in as the 'closed status key'
6. To obtain 'epic name id' visit: https://<YOUR JIRA URL>/secure/admin/ViewCustomFields.jspa
7. Click on the cog next to 'Epic Name' and select view.
8. The numeric value for 'epic name id' will be displayed in the URL
9. Note: dojojira uses the same celery functionality as reports. Make sure the celery runner is setup correclty as described: http://defectdojo.readthedocs.io/en/latest/features.html#reports

DefectDojo allows users to automatically consolidate issues from multiple scanners to remove duplicates.

To enable this feature, change the following in dojo/settings.py:

ENABLE_DEDUPLICATION = True

When deduplication is enabled, Dojo will compare CWE, title, and endpoint details for all findings in a given product. If an issue is added with either the CWE or title being the same while the endpoint is also the same, Dojo marks the old issue as a duplicate.