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.
The following attributes describe a Product:
- A short name for the product, used for easy identification. This field can hold up to 300 characters.
- 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.
- 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
Visual representation of a product:
Product with metrics drop down displayed:
The following attributes describe an Engagement:
- 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.
- The DefectDojo user who is considered the lead for this group of tests.
- The Product being tested as part of this group of tests.
- 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.
- 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:
- The communication protocol such as ‘http’, ‘https’, ‘ftp’, etc.
- 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’.
- The location of the resource, it should start with a ‘/’. For example “/endpoint/420/edit”
- The query string, the question mark should be omitted. “For example ‘group=4&team=8’
- The fragment identifier which follows the hash mark. The hash mark should be omitted. For example ‘section-13’, ‘paragraph-2’.
- 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:
- A short description of the flaw (Up to 100 characters)
- Longer more descriptive information about the flaw.
- The date the flaw was discovered.
- The CWE nubmer associated with this flaw.
- The severity level of this flaw (Critical, High, Medium, Low, Informational)
- Numerical Severity
- The numerical representation of the severity (S0, S1, S2, S3, S4)
- Text describing how to best fix the flaw.
- Text describing the impact this flaw has on systems, products, enterprise, etc.
- The hosts within the product that are susceptible to this flaw.
- The external documentation available for this flaw.
- 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.
- Denotes if this flaw is active or not.
- 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.
- 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.
- Denotes if this flaw has been fixed, by storing the date it was fixed.
- Mitigated By
- Documents who has deemed this flaw as fixed.
- 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.
- Stores information pertinent to the flaw or the mitigation.
- 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/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:
- 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:
- Burp XML
- Nessus (CSV, XML)
- Nmap (XML)
- Nexpose XML 2.0
- ZAP XML
- Veracode Detailed XML Report
- Checkmarx Detailed XML Report
- AppSpider Vulnerabilities Summary XML Report (VulnerabilitiesSummary.xml)
- Arachni Scanner JSON Report
- Visual Code Grepper XML or CSV
- OWASP Dependency Check XML
- Node Security Platform JSON
- Qualys XML
- OpenVAS CSV
- Snyk JSON
- 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 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.
DefectDojo’s reports can be generated in AsciiDoc and PDF. AsciiDoc is recommended for reports with a large number of findings.
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:
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.
brew install Caskroom/cask/wkhtmltopdf
sudo apt-get install wkhtmltopdf
sudo yum install wkhtmltopdf
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
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:
- Groups of Products
- Individual Products
- Product Types
- 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:
- Cover Page
- Table of Contents
- WYSIWYG Content
- Findings List
- Endpoint List
- 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
- Configurations in Dojo
- In dojo/settings.py set ENABLE_JIRA = True.
- Adding JIRA to Dojo
- Click ‘JIRA’ from the left hand menu.
- Select ‘Add Configuration’ from the drop-down.
- 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
- The ‘id’ for ‘Todo’ should be filled in as the ‘open status key’
- The ‘id’ for ‘Done’ should be filled in as the ‘closed status key’
- To obtain ‘epic name id’ visit: https://<YOUR JIRA URL>/secure/admin/ViewCustomFields.jspa
- Click on the cog next to ‘Epic Name’ and select view.
- The numeric value for ‘epic name id’ will be displayed in the URL
- 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.
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.