When you deploy a vanilla docker-compose, it will create a persistent volume for your MySQL database. As long as your volume is there, you should not lose any data.
latest
, then you need to pre pull the latest
from
DockerHub to update.The generic upgrade method for docker-compose are as follows:
Pull the latest version
docker pull defectdojo/defectdojo-django:latest
docker pull defectdojo/defectdojo-nginx:latest
If you would like to use a version other than the latest, specify the version (tag) you want to upgrade to:
docker pull defectdojo/defectdojo-django:1.10.2
docker pull defectdojo/defectdojo-nginx:1.10.2
If you would like to use alpine based images, you specify the version (tag) you want to upgrade to:
docker pull defectdojo/defectdojo-django:1.10.2-alpine
docker pull defectdojo/defectdojo-nginx:1.10.2-alpine
Go to the directory where your docker-compose.yml file lives
Stop DefectDojo: ./dc-stop.sh
Re-start DefectDojo, allowing for container recreation:
./dc-up-d.sh
Database migrations will be run automatically by the initializer.
Check the output via docker-compose logs initializer
or relevant k8s command
If you have the initializer disabled (or if you want to be on the
safe side), run the migration command:
docker-compose exec uwsgi /bin/bash -c "python manage.py migrate"
If you build your images locally and do not use the ones from DockerHub, the instructions are the same, with the caveat that you must build your images first.
Pull the latest DefectDojo changes
git fetch
git pull
git merge origin/master
Then replace the first step of the above generic upgrade method for docker-compose with: docker-compose build
If you have installed DefectDojo on “iron” and wish to upgrade the installation, please see the instructions in the repo.
There are no special instruction for upgrading to 2.26.0. Check the Release Notes for the contents of the release.
There are no special instruction for upgrading to 2.25.0. Check the Release Notes for the contents of the release.
A few query parameters related to filtering object via API related to a products tags have been renamed to be more consistent with the other “related object tags”:
Breaking Change
product__tags__name
-> product__tags
not_product__tags__name
-> not_product__tags
engagement__product__tags__name
-> engagement__product__tags
not_engagement__product__tags__name
-> not_engagement__product__tags
test__engagement__product__tags__name
-> test__engagement__product__tags
not_test__engagement__product__tags__name
-> not_test__engagement__product__tags
Deprecation
The OpenAPI 2.0 Swagger API documentation is being deprecated in favor of the existing OpenAPI 3.0 API documentation page. The OpenAPI 2.0 Swagger API documentation page is slated for removal in version 2.30.0
Note: The API has not changed in any way and behaves the same between OAPI2 and OAPI3
For all other changes, check the Release Notes for the contents of the release.
There are no special instruction for upgrading to 2.24.0. Check the Release Notes for the contents of the release.
There is a migration from the legacy Nessus and Nessus WAS parsers to a single Tenable parser. The updated Tenable parser simply merges existing support for Nessus and Nessus WAS without introducing new functionality that could create instability
There is a migration process built into the upgrade that will automatically convert exiting Nessus and Nessus WAS findings and tests into Tenable findings and tests
Breaking Change
scan-type
parameter needs to be updated to Tenable Scan
./dc-up.sh mysql-rabbitmq
or ./dc-up.sh mysql-redis
./dc-up-d.sh mysql-rabbitmq
or ./dc-up-d.sh mysql-redis
docker-compose --profile mysql-rabbitmq --env-file ./docker/environments/mysql-rabbitmq.env up
or docker-compose --profile mysql-redis --env-file ./docker/environments/mysql-redis.env up
For all other changes, check the Release Notes for the contents of the release.
There are no special instruction for upgrading to 2.22.0. Check the Release Notes for the contents of the release.
There are no special instruction for upgrading to 2.21.0. Check the Release Notes for the contents of the release.
There are no special instruction for upgrading to 2.20.0. Check the Release Notes for the contents of the release.
There are new docker images based on alpine with fewer third party dependencies. Related to the new images the current docker files had to be renamed and have a “-debian” or the new images a “-alpine” at the end. Furthermore there are new docker tags [DefectdojoVersion]-[OS]. For example 2.19.0-alpine or 2.19.0-debian. The currend tags (latest and [DefectdojoVersion]) are still based on the “old” images. Be aware that the new alpine images are not heavily tested and may contain bugs.
Breaking Change
In version 2.19.3, the GitHub OAuth integration has been removed to prevent configurations that may allow more access than intended.
DefectDojo Security Advisory: Severity Medium | Potential GitHub Authentication Misconfiguration
Upgrade instructions for helm chart with rabbitMQ enabled: The rabbitMQ uses a statefulset by default. Before upgrading the helm chart we have to ensure that all queues are empty:
kubectl exec -i <name_of_the_rabbitmq_pod> -- rabbitmqctl list_queues
Next step is to delete rabbitMQ pvc:
kubectl delete pvc -l app.kubernetes.io/name=rabbitmq
Last step is to perform the upgrade.
For more information: https://artifacthub.io/packages/helm/bitnami/rabbitmq/11.2.0
There are no special instruction for upgrading to 2.17.0. Check the Release Notes for the contents of the release.
There are no special instruction for upgrading to 2.16.0. Check the Release Notes for the contents of the release.
There are no special instruction for upgrading to 2.15.0. Check the Release Notes for the contents of the release.
The last release implemented the search for vulnerability ids, but the search database was not initialized. To populate the database table of the vulnerability ids, execute this django command from the defect dojo installation directory or from a shell of the Docker container or Kubernetes pod:
./manage.py migrate_cve
Additionally this requires a one-time rebuild of the Django-Watson search index. Execute this django command from the defect dojo installation directory or from a shell of the Docker container or Kubernetes pod:
./manage.py buildwatson
Upgrade instructions for helm chart with postgres enabled: The postgres database uses a statefulset by default. Before upgrading the helm chart we have to delete the statefullset and ensure that the pvc is reused, to keep the data. For more information: https://docs.bitnami.com/kubernetes/infrastructure/postgresql/administration/upgrade/ .
helm repo update
helm dependency update ./helm/defectdojo
# obtain name oft the postgres pvc
export POSTGRESQL_PVC=$(kubectl get pvc -l app.kubernetes.io/instance=defectdojo,role=primary -o jsonpath="{.items[0].metadata.name}")
# delete postgres statefulset
kubectl delete statefulsets.apps defectdojo-postgresql --namespace default --cascade=orphan
# upgrade
helm upgrade \
defectdojo \
./helm/defectdojo/ \
--set primary.persistence.existingClaim=$POSTGRESQL_PVC \
... # add your custom settings
Further changes:
Legacy authorization for changing configurations based on staff users has been removed.
Breaking change for search: The field cve
has been removed from the search index for Findings and the Vulnerability Ids have been added to the search index. With this the syntax to search explicitly for vulnerability ids have been changed from cve:
to vulnerability_id:
, e.g. vulnerability_id:CVE-2020-27619
.
Breaking change for Findings: The field cve
will be replaced by a list of Vulnerability Ids, which can store references to security advisories associated with this finding. These can be Common Vulnerabilities and Exposures (CVE) or from other sources, eg. GitHub Security Advisories. Although the field does still exist in the code, the API and the UI have already been changed to use the list of Vulnerability Ids. Other areas like hash code calculation, search and parsers will be migrated step by step in later stages.
This change also causes an API change for the endpoint /engagements/{id}/accept_risks/
.
Breaking change for APIv2: configuration_url
was removed from API endpoint /api/v2/tool_configurations/
due to redundancy.
Breaking change for Docker Compose: Starting DefectDojo with Docker Compose now supports 2 databases (MySQL and PostgreSQL) and 2 celery brokers (RabbitMQ and Redis). To make this possible, docker-compose needs to be started with the parameters --profile
and --env-file
. You can get more information in Setup via Docker Compose - Profiles. The profile mysql-rabbitmq
provides the same configuration as in previous releases. With this the prerequisites have changed as well: Docker requires at least version 19.03.0 and Docker Compose 1.28.0.
Breaking change for Helm Chart: In one of the last releases we upgraded the redis dependency in our helm chart without renaming keys in our helm chart. We fixed this bug with this release, but you may want to check if all redis values are correct (Pull Request).
The flexible permissions for the configuration of DefectDojo are now active by default. With this, the flag Staff for users is not relevant and not visible anymore. The old behaviour can still be activated by setting the parameter FEATURE_CONFIGURATION_AUTHORIZATION
to False
. If you haven’t done so with the previous release, you can still run a migration script with ./manage.py migrate_staff_users
. This script:
AUTHORIZATION_STAFF_OVERRIDE
is set to True
.This release is a breaking change regarding the Choctaw Hog parser. As the maintainers of this project unified multiple parsers under the RustyHog parser, we now support the parsing of Choctaw Hog JSON output files through the Rusty Hog parser. Furthermore, we also support Gottingen Hog and Essex Hog JSON output files with the RustyHog parser.
There is another breaking change regarding the import of SSLyze scans. The parser has been renamed from SSLyze 3 Scan (JSON)
to SSLyze Scan (JSON)
. The data in the database is fixed by the initializer, but it may break scripted API calls.
Release 2.7.0 contains a beta functionality to make permissions for the configuration of DefectDojo more flexible. When the settings parameter FEATURE_CONFIGURATION_AUTHORIZATION
is set to True
, many configuration dialogues and API endpoints can be enabled for users or groups of users, regardless of their Superuser or Staff status, see Configuration Permissions.
The functionality using the flag AUTHORIZATION_STAFF_OVERRIDE
has been removed. The same result can be achieved with giving the staff users a global Owner role.
To support the transition for these 2 changes, you can run a migration script with ./manage.py migrate_staff_users
. This script:
AUTHORIZATION_STAFF_OVERRIDE
is set to True
.There are no special instruction for upgrading to 2.6.0. Check the Release Notes for the contents of the release.
Please consult the security advisories GHSA-f82x-m585-gj24 (moderate) and GHSA-v7fv-g69g-x7p2 (high) to see what security issues were fixed in this release. These will be published and become visible at January 18th, 2022.
Legacy authorization has been completely removed with version 2.5.0. This includes removal of the migration of users
to the new authorization as described in https://documentation.defectdojo.com/getting_started/upgrading/#authorization.
If you are still using the legacy authorization, you should run the migration with ./manage.py migrate_authorization_v2
before upgrading to version 2.5.0
This release introduces the “Forgot password” functionality (DD_FORGOT_PASSWORD
: default True
). The function
allows sending an e-mail with the reset password link. Missing configuration or misconfiguration of SMTP
(DD_EMAIL_URL
) could raise an error (HTTP-500). Check and test (for example by resetting your own password) if you
configured SMTP correctly. If you want to avoid HTTP-500 and you don’t want to set up SMTP, you can just simply switch
off the “Forgot password” functionality (DD_FORGOT_PASSWORD=False
).
Release renamed system setting mail_notifications_from
to email_from
. This value will not be used only for sending
notifications but also for sending the reset password emails. It is highly recommended to check the content of this
value if you are satisfied. If you installed DefectDojo earlier, you can expect "from@example.com"
there. A fresh
installation will use "no-reply@example.com"
This release updates our helm dependencies. There is a breaking change if you are using the mysql database from the helm chart because we replaced the deprecated chart from the stable repo with a chart from bitnami. If you have persistance enabled, ensure to backup your data before upgrading. All data get lost when replacing the mysql chart during the upgrade. For data migration take a look at the mysql backup and restore process.
Furthermore we updated our kubernetes version. Current tests run on 1.18.16 and 1.22.0.
This releases fixes a High severity vulnerability for which the details will be disclosed on November 16th in GHSA-fwg9-752c-qh8w
There is a breaking change in the API for importing and re-importings scans with SonarQube API and Cobalt.io API. The scan configurations
have been unified and are set now with the attribute api_scan_configuration
.
The existing configurations for SonarQube API and Cobalt.io API have been migrated.
At the request of pyup.io, we had to remove the parser for Safety scans.
There are no special instruction for upgrading to 2.3.0. In 2.3.0 we changed the default password hashing algorithm to Argon2 (from PBKDF2). When logging in, exising hashes get replaced by an Argon2 hash. If you want to rehash password without users having to login, please see the Django password management docs. The previous password hashing algorithm (PBKDF2) was not unsafe, but we wanted to follow the OWASP guidelines.
Upgrade to 2.0.0 contained migration of endpoints. Some parts of migration haven’t been done properly. This deficiency
may manifest as a doubled slash in endpoint URLs (like http://foo.bar:8080//test
) or as a problem with deduplication
of the same endpoints. The mentioned bug was fixed in 2.2.0 and if you have seen these kinds of problems, just rerun
“Endpoint migration” as it is written in Upgrading to DefectDojo Version 2.0.x..
Follow the usual steps to upgrade as described above.
BEFORE UPGRADING
AFTER UPGRADING
python manage.py migrate
) try to migrate all endpoints to new format and merge duplicates.docker-compose exec uwsgi ./manage.py endpoint_migration --dry-run
docker-compose exec uwsgi ./manage.py endpoint_migration
We decided to name this version 2.0.0 because we did some big cleanups in this release:
Remove API v1 (#4413)
Remove setup.bash installation method (#4417)
Rename Finding.is_Mitigated field to Finding.is_mitigated (#3854)
Remove everything related to the old tagging library (#4419)
Remove S0/S1/S2../S5 severity display option (#4415)
Refactor EndPoint handling/formatting (#4473)
Upgrade to Django 3.x (#3632)
PDF Reports removed (#4418)
Hashcode calculation logic has changed. To update existing findings run:
./manage.py dedupe --hash_code_only
.
If you’re using docker:
docker-compose exec uwsgi ./manage.py dedupe --hash_code_only
.
This can take a while depending on your instance size.
python manage.py migrate
) tries to migrate all endpoints to new format and merge duplicates.docker-compose exec uwsgi ./manage.py endpoint_migration --dry-run
docker-compose exec uwsgi ./manage.py endpoint_migration
The new authorization system for Products and Product Types based on roles is the default now. The fields for authorized users are not available anymore, but you can assign roles as described in Permissions. Users are migrated automatically, so that their permissions are as close as possible to the previous authorization:
AUTHORIZED_USERS_ALLOW_STAFF
is True
, the user will get the Owner role for the respective Product or Product Type.AUTHORIZED_USERS_ALLOW_CHANGE
or AUTHORIZED_USERS_ALLOW_DELETE
is True
, the user will get the Writer role for the respective Product or Product Type.The new authorization is active for both UI and API. Permissions set via authorized users or via the Django Admin interface are no longer taken into account.
Please review the roles for your users after the upgrade to avoid an unintended permissions creep.
See release notes: https://github.com/DefectDojo/django-DefectDojo/releases/tag/1.15.0
If you have made changes to JIRA templates or the template config in the JIRA Project config for instances/products/engagements:
The jira template settings introduced in 1.13 have been changed. You now have to select a subfolder instead of a sinlge template file. If you have chosen a non-default template here, you have to reapply that to all products / engagements. Also you have to move your custom templates into the correct subfolder in dojo/templates/issue-trackers/
.
Hashcode calculation logic has changed in #4134, #4308 and #4310 to update existing findings run:
./manage.py dedupe --hash_code_only
If you’re using docker:
docker-compose exec uwsgi ./manage.py dedupe --hash_code_only
This can take a while depending on your instance size.
Note that the below fields are now optional without default value. They will not be filled anymore with values such as “No references given” when found empty while saving the findings
See release notes: https://github.com/DefectDojo/django-DefectDojo/releases/tag/1.13.0
Hashcode settings affecting deduplication have changed, to update existing findings run:
./manage.py dedupe
If you’re using docker:
docker-compose exec uwsgi ./manage.py dedupe
This can take a while depeneding on your instance size. It might possible that new duplicates are detected among existing findings, so make a backup before running!
1.10.4 is a security release
What's New:
settings.py
file
out-of-the-box. Custom settings need to go into
local\_settings.py
. See
https://github.com/DefectDojo/django-DefectDojo/blob/master/dojo/settings/settings.py
and
https://github.com/DefectDojo/django-DefectDojo/blob/master/docker/extra_settings/README.mdsettings.py
or settings.dist.py
to
local\_settings.py
. Details of that PR:
https://github.com/DefectDojo/django-DefectDojo/pull/3136Breaking changes
Kubernetes/Helm users: we have moved away from the "stable" repository
to "bitnami" in this release. The bitnami postgresql chart required us
to add a new key to the postgresql secret, which will give you the error
postgresql-postgres-password is missing
if you have
createPostgresqlSecret: false
. In 1.10.1, a fix was also included to
allow your existing postgresqlPassword
to be reused properly.
Including in 1.10.1 were a couple fixes related to a rabbitMQ upgrade.
The path to access password
, erlangCookie
and
existingPasswordSecret
changed from rabbitmq
to auth
. Furthermore,
as rabbitMQ is deployed as a StatefulSet, an in-place upgrade is not
possible and an error will likely be thrown such as
Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', and 'updateStrategy' are forbidden
.
After ensuring your rabbitMQ celery queue is empty, you will then want
to delete your rabbitMQ StatefulSet and PVC to allow them to get
re-created, or fully delete and recreate defectdojo.
This is a security release
What's New:
NOTE:
When upgrading from before 1.9.2, a corrective script may need to be ran
./manage.py create\_endpoint\_status
If you're using docker:
docker-compose exec uwsgi ./manage.py create\_endpoint\_status
This can take a while depending on your hardware and the number of findings in your instance.
This requires a (one-time) rebuild of the Django-Watson search index. Execute the django command from the defect dojo installation directory:
./manage.py buildwatson]
If you're using docker:
docker-compose exec uwsgi ./manage.py buildwatson
This can take a while depending on your hardware and the number of findings in your instance.
What's New:
This requires a (one-time) rebuild of the Django-Watson search index. Execute the django command from the defect dojo installation directory:
./manage.py buildwatson
If you're using docker:
docker-compose exec uwsgi ./manage.py buildwatson
This can take a while depending on your hardware and the number of findings in your instance.
As a result of a breaking bug revolving around Endpoint_status objects, a corrective script will need to be ran after every dynamic scan imported through either API version.
The script can be found here
./manage.py create\_endpoint\_status
If you're using docker:
docker-compose exec uwsgi ./manage.py create\_endpoint\_status
This can take a while depending on your hardware and the number of findings in your instance.
What's New:
This requires a (one-time) rebuild of the Django-Watson search index. Execute the django command from the defect dojo installation directory:
./manage.py buildwatson dojo.Finding
If you're using docker:
docker-compose exec uwsgi ./manage.py buildwatson dojo.Finding
What's New:
Upgrading to 1.5.0 requirements:
Back up your database first, ideally take the backup from production and test the upgrade on a staging server.
Edit the settings.py file which can be found in
django-DefectDojo/dojo/settings/settings.py
. Copy in the rest
framework configuration after the CSRF_COOKIE_SECURE = True:
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework.authentication.TokenAuthentication',
'rest_framework.authentication.BasicAuthentication',
),
'DEFAULT_PERMISSION_CLASSES': (
'rest_framework.permissions.DjangoModelPermissions',
),
'DEFAULT_RENDERER_CLASSES': (
'rest_framework.renderers.JSONRenderer',
),
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
'PAGE_SIZE': 25
}
Navigate to: LOGIN_EXEMPT_URLS and add the following after r'^%sfinding/image/(?P<token>[^/]+)$' % URL_PREFIX:
r'^%sfinding/image/(?P<token>[^/]+)$' % URL_PREFIX,
r'^%sapi/v2/' % URL_PREFIX,
Navigate to: INSTALLED_APPS and add the following after: 'multiselectfield',:
'multiselectfield',
'rest_framework',
'rest_framework.authtoken',
'rest_framework_swagger',
'dbbackup',
Navigate to: CELERY_TASK_IGNORE_RESULT = True and add the following after CELERY_TASK_IGNORE_RESULT line:
CELERY_RESULT_BACKEND = 'db+sqlite:///dojo.celeryresults.sqlite'
Save your modified settings file. For reference the modified file should look like the new 1.5.0 [settings](https://github.com/DefectDojo/django-DefectDojo/blob/master/dojo/settings/settings.dist.py) file, minus the environmental configurations. As an alternative this file can be used and the enviromental configurations from you environment can be copied into this file.
pip install -r requirements.txt --upgrade
Upgrade the database:
./manage.py makemigrations
./manage.py migrate
Collect the static files (Javascript, Images, CSS):
./manage.py collectstatic --noinput
Complete
What's New:
Upgrading to 1.3.1 requires:
What's New: New feature: Benchmarks (OWASP ASVS)
Upgrading to 1.2.9 requires:
New feature: Product Grading (Overall Product Health) Upgrading to 1.2.8 requires:
Upgrading to 1.2.4 requires:
Upgrading to 1.2.3 requires:
Pull request #313 moves a number of system settings previously located in the application's settings.py to a model that can be used and changed within the web application under "Configuration -> System Settings".
If you're using a custom URL_PREFIX
you will need to set this in the
model after upgrading by editing dojo/fixtures/system_settings.json
and setting your URL prefix in the url_prefix
value there. Then issue
the command ./manage.py loaddata system_settings.json
to load your
settings into the database.
If you're not using a custom URL_PREFIX
, after upgrading simply go to
the System Settings page and review which values you want to set for
each setting, as they're not automatically migrated from settings.py.
If you like you can then remove the following settings from settings.py to avoid confusion:
ENABLE_DEDUPLICATION
ENABLE_JIRA
S_FINDING_SEVERITY_NAMING
URL_PREFIX
TIME_ZONE
TEAM_NAME
Upgrading to 1.2.2 requires:
If you are upgrading an existing version of DefectDojo, you will need to run the following commands manually:
First install Yarn. Follow the instructions based on your OS: https://yarnpkg.com/lang/en/docs/install/
The following must be removed/commented out from settings.py
: :
'djangobower.finders.BowerFinder',
From the line that contains:
# where should bower install components
...
To the end of the bower declarations
'justgage'
)
The following needs to be updated in settings.py
: :
STATICFILES_DIRS = (
# Put strings here, like "/home/html/static" or "C:/www/django/static".
# Always use forward slashes, even on Windows.
# Don't forget to use absolute paths, not relative paths.
os.path.dirname(DOJO_ROOT) + "/components/yarn_components",
)
Pull request #300 makes DefectDojo Django 1.11 ready. A fresh install of DefectDojo can be done with the setup.bash script included - no special steps are required.
If you are upgrading an existing installation of DefectDojo, you will need to run the following commands manually: :
pip install django-tastypie --upgrade
pip install django-tastypie-swagger --upgrade
pip install django-filter --upgrade
pip install django-watson --upgrade
pip install django-polymorphic --upgrade
pip install django --upgrade
pip install pillow --upgrade
./manage.py makemigrations
./manage.py migrate
The following must be removed/commented out from settings.py: :
TEMPLATE_DIRS
TEMPLATE_DEBUG
TEMPLATE_LOADERS
TEMPLATE_CONTEXT_PROCESSORS
The following needs to be added to settings.py: :
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
]
Once all these steps are completed your installation of DefectDojo will be running under Django 1.11