DefectDojo Features

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 Models page will help you understand the terminology we use below, so we recommend taking a look at that first.

Products

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.

Product Listing Page

Visual representation of a product:

View Product Page

Product with metrics drop down displayed:

View Product Page With Metrics Displayed

Engagements

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.

Engagement Listing Page

Visual representation of an engagement:

View Engagement Page

Endpoints

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.

Endpoint Listing Page

Visual representation of an endpoint:

View Endpoint Page

Visual representation of an endpoint with metrics displayed:

View Endpoint Page with metrics

Findings

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.

Finding Listing Page

Finding Listing Page

Finding Listing Page

Visual representation of a Finding:

Finding View Finding View Finding View
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.

Metrics

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 Metrics
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.

Product Type Counts
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.

Simple Metrics
Engineer Metrics

Provides graphs displaying information about an testers activity.

Simple Metrics
Metrics Dashboard

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

Metrics Dashboard

Users

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.

Calendar

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.

Imports

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

  1. Burp XML
  2. Nessus (CSV, XML)
  3. Nmap (XML)
  4. Nexpose XML 2.0
  5. ZAP XML
  6. Veracode Detailed XML Report
  7. Checkmarx Detailed XML Report
  8. AppSpider Vulnerabilities Summary XML Report (VulnerabilitiesSummary.xml)
  9. Arachni Scanner JSON Report
  10. Visual Code Grepper XML or CSV
  11. OWASP Dependency Check XML
  12. Retire.js JavaScript Scan JSON
  13. Node Security Platform JSON
  14. Qualys XML
  15. OpenVAS CSV
  16. Snyk JSON
  17. 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.

Import Form

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.

Re-Import Form

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

Port Scans

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.

Port Scan Form

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
Port Scan Form

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.

Port Scan Form

Notifications

Notification settings

DefectDojo can inform you of different events in a variety of ways. You can be notified about things like an upcoming engagement, when someone mentions you in a comment, a scheduled report has finished generating, and more.

The following notification methods currently exist: - Email - Slack - HipChat - Alerts within DefectDojo

You can set these notifications on a global scope (if you have administrator rights) or on a personal scope. For instance, an administrator might want notifications of all upcoming engagements sent to a certain Slack channel, whereas an individual user wants email notifications to be sent to the user’s specified email address when a report has finished generating.

In order to identify and notify you about things like upcoming engagements, DefectDojo runs scheduled tasks for this purpose. These tasks are scheduled and run using Celery beat, so this needs to run for those notifications to work. Instructions on how to run Celery beat are available in the Reports section.

Reports

Report Listing

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:

Note

To get report email notifications, make sure you have a working email configuration in the system settings, and enable notifications for generated reports in the notification settings.

Mac:

brew install Caskroom/cask/wkhtmltopdf

Debian/Ubuntu:

sudo apt-get install wkhtmltopdf

Fedora/Centos:

sudo yum install wkhtmltopdf

Warning

Version in debian/ubuntu repos have reduced functionality (because it compiled without the wkhtmltopdf QT patches), such as adding outlines, headers, footers, TOC etc. To use this options you should install static binary from wkhtmltopdf site or you can use this script.

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 enable defectDojo to perform periodic checks of things like upcoming and stale engagements as well as allowing 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
Report Generation

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.

JIRA Integration

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

Issue Consolidation

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.

False Positive Removal

DefectDojo allows users to tune out false positives by enabling False Positive History. This will track what engineers have labeled as false positive for a specific product and for a specific scanner. While enabled, when a tool reports the same issue that has been flagged as a false positive previously, it will automatically mark the finding as a false positive, helping to tune overly verbose security tools.