diff --git a/.github/workflows/validate_docs_build.yml b/.github/workflows/validate_docs_build.yml index 7d57f74f2c6..2583be524f6 100644 --- a/.github/workflows/validate_docs_build.yml +++ b/.github/workflows/validate_docs_build.yml @@ -40,3 +40,10 @@ jobs: HUGO_ENVIRONMENT: production HUGO_ENV: production run: cd docs && npm ci && hugo --minify --gc --config config/production/hugo.toml + + - name: Check internal links + uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2 + with: + args: --offline --no-progress --root-dir docs/public './docs/public/**/*.html' + fail: true + diff --git a/docs/content/admin/sso/OS__auth0.md b/docs/content/admin/sso/OS__auth0.md index dbaf8f0c60a..e603a020cba 100644 --- a/docs/content/admin/sso/OS__auth0.md +++ b/docs/content/admin/sso/OS__auth0.md @@ -5,7 +5,7 @@ weight: 4 audience: opensource --- -Open-Source DefectDojo supports login via Auth0. DefectDojo Pro users should refer to the [Pro Auth0 guide](../PRO__auth0/). +Open-Source DefectDojo supports login via Auth0. DefectDojo Pro users should refer to the [Pro Auth0 guide](/admin/sso/pro__auth0/). ## Prerequisites diff --git a/docs/content/admin/sso/OS__azure_ad.md b/docs/content/admin/sso/OS__azure_ad.md index baea2b204ae..3af21e2a86c 100644 --- a/docs/content/admin/sso/OS__azure_ad.md +++ b/docs/content/admin/sso/OS__azure_ad.md @@ -5,7 +5,7 @@ weight: 6 audience: opensource --- -Open-Source DefectDojo supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. DefectDojo Pro users should refer to the [Pro Azure AD guide](../PRO__azure_ad/). +Open-Source DefectDojo supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. DefectDojo Pro users should refer to the [Pro Azure AD guide](/admin/sso/pro__azure_ad/). ## Prerequisites diff --git a/docs/content/admin/sso/OS__github_enterprise.md b/docs/content/admin/sso/OS__github_enterprise.md index 8427b58decc..8648403c888 100644 --- a/docs/content/admin/sso/OS__github_enterprise.md +++ b/docs/content/admin/sso/OS__github_enterprise.md @@ -5,7 +5,7 @@ weight: 8 audience: opensource --- -Open-Source DefectDojo supports login via GitHub Enterprise. DefectDojo Pro users should refer to the [Pro GitHub Enterprise guide](../PRO__github_enterprise/). +Open-Source DefectDojo supports login via GitHub Enterprise. DefectDojo Pro users should refer to the [Pro GitHub Enterprise guide](/admin/sso/pro__github_enterprise/). ## Prerequisites diff --git a/docs/content/admin/sso/OS__gitlab.md b/docs/content/admin/sso/OS__gitlab.md index f8ae2bcaa90..611e6ccef3f 100644 --- a/docs/content/admin/sso/OS__gitlab.md +++ b/docs/content/admin/sso/OS__gitlab.md @@ -5,7 +5,7 @@ weight: 10 audience: opensource --- -Open-Source DefectDojo supports login via GitLab. DefectDojo Pro users should refer to the [Pro GitLab guide](../PRO__gitlab/). +Open-Source DefectDojo supports login via GitLab. DefectDojo Pro users should refer to the [Pro GitLab guide](/admin/sso/pro__gitlab/). ## Prerequisites diff --git a/docs/content/admin/sso/OS__google.md b/docs/content/admin/sso/OS__google.md index e7e1d505438..fc9e4eedee0 100644 --- a/docs/content/admin/sso/OS__google.md +++ b/docs/content/admin/sso/OS__google.md @@ -5,7 +5,7 @@ weight: 12 audience: opensource --- -Open-Source DefectDojo supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). DefectDojo Pro users should refer to the [Pro Google guide](../PRO__google/). +Open-Source DefectDojo supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). DefectDojo Pro users should refer to the [Pro Google guide](/admin/sso/pro__google/). ## Prerequisites diff --git a/docs/content/admin/sso/OS__keycloak.md b/docs/content/admin/sso/OS__keycloak.md index e056f0da9fc..e1c3fd8ed85 100644 --- a/docs/content/admin/sso/OS__keycloak.md +++ b/docs/content/admin/sso/OS__keycloak.md @@ -5,7 +5,7 @@ weight: 14 audience: opensource --- -Open-Source DefectDojo supports login via KeyCloak. DefectDojo Pro users should refer to the [Pro KeyCloak guide](../PRO__keycloak/). +Open-Source DefectDojo supports login via KeyCloak. DefectDojo Pro users should refer to the [Pro KeyCloak guide](/admin/sso/pro__keycloak/). This guide assumes you already have a KeyCloak Realm configured. If not, see the [KeyCloak documentation](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html). diff --git a/docs/content/admin/sso/OS__ldap.md b/docs/content/admin/sso/OS__ldap.md new file mode 100644 index 00000000000..1fa929e23cb --- /dev/null +++ b/docs/content/admin/sso/OS__ldap.md @@ -0,0 +1,135 @@ +--- +title: "LDAP Authentication" +description: "Authenticate users via LDAP by building custom Docker images" +weight: 20 +audience: opensource +aliases: + - /en/open_source/ldap-authentication +--- + +**This feature is experimental, and is not implemented in DefectDojo Pro**. + +DefectDojo does not support LDAP authentication out of the box. However, since DefectDojo is built on Django, LDAP can be added by building your own Docker images and modifying a small number of configuration files. + +## Files to Modify + +- `Dockerfile.django-*` +- `Dockerfile.nginx-*` +- `requirements.txt` +- `local_settings.py` +- `docker-compose.yml` *(optional — for passing secrets via environment variables)* + +## Dockerfile Modifications + +In both `Dockerfile.django-alpine` and `Dockerfile.nginx-alpine`, add the following to the `apk add` layer: + +```bash +openldap-dev \ +cyrus-sasl-dev \ +``` + +In `Dockerfile.django-debian`, add the following to the `apt-get install` layer: + +```bash +libldap2-dev \ +libsasl2-dev \ +ldap-utils \ +``` + +## requirements.txt + +Check [pypi.org](https://pypi.org) for the latest versions at the time of implementation, then add: + +``` +python-ldap==3.4.5 +django-auth-ldap==5.2.0 +``` + +- [python-ldap](https://pypi.org/project/python-ldap/) +- [django-auth-ldap](https://pypi.org/project/django-auth-ldap/) + +## local_settings.py + +Find the settings file (see `/dojo/settings/settings.py` for instructions on using `local_settings.py`) and make the following additions. + +At the top of the file: + +```python +import ldap +from django_auth_ldap.config import LDAPSearch, GroupOfNamesType +import environ +``` + +Add LDAP variables to the `env` dict: + +```python +# LDAP +env = environ.FileAwareEnv( + DD_LDAP_SERVER_URI=(str, 'ldap://ldap.example.com'), + DD_LDAP_BIND_DN=(str, ''), + DD_LDAP_BIND_PASSWORD=(str, ''), +) +``` + +Then add the LDAP settings beneath the `env` dict: + +```python +AUTH_LDAP_SERVER_URI = env('DD_LDAP_SERVER_URI') +AUTH_LDAP_BIND_DN = env('DD_LDAP_BIND_DN') +AUTH_LDAP_BIND_PASSWORD = env('DD_LDAP_BIND_PASSWORD') + +AUTH_LDAP_USER_SEARCH = LDAPSearch( + "ou=Groups,dc=example,dc=com", ldap.SCOPE_SUBTREE, "(uid=%(user)s)" +) + +AUTH_LDAP_USER_ATTR_MAP = { + "first_name": "givenName", + "last_name": "sn", + "email": "mail", +} +``` + +Customise all search variables to match your organisation's LDAP configuration. + +### Optional: Group Controls + +```python +AUTH_LDAP_GROUP_SEARCH = LDAPSearch( + "dc=example,dc=com", + ldap.SCOPE_SUBTREE, + "(objectClass=groupOfNames)", +) +AUTH_LDAP_GROUP_TYPE = GroupOfNamesType(name_attr="cn") + +AUTH_LDAP_REQUIRE_GROUP = "cn=DD_USER_ACTIVE,ou=Groups,dc=example,dc=com" + +AUTH_LDAP_USER_FLAGS_BY_GROUP = { + "is_active": "cn=DD_USER_ACTIVE,ou=Groups,dc=example,dc=com", + "is_staff": "cn=DD_USER_STAFF,ou=Groups,dc=example,dc=com", + "is_superuser": "cn=DD_USER_ADMIN,ou=Groups,dc=example,dc=com", +} +``` + +Finally, add `django_auth_ldap.backend.LDAPBackend` to `AUTHENTICATION_BACKENDS`: + +```python +AUTHENTICATION_BACKENDS = ( + 'django_auth_ldap.backend.LDAPBackend', + 'django.contrib.auth.backends.RemoteUserBackend', + 'django.contrib.auth.backends.ModelBackend', +) +``` + +Full documentation: [Django Authentication with LDAP](https://django-auth-ldap.readthedocs.io/en/latest/) + +## docker-compose.yml + +To pass LDAP credentials to the container via environment variables, add these to the `uwsgi` service environment section: + +```yaml +DD_LDAP_SERVER_URI: "${DD_LDAP_SERVER_URI:-ldap://ldap.example.com}" +DD_LDAP_BIND_DN: "${DD_LDAP_BIND_DN:-}" +DD_LDAP_BIND_PASSWORD: "${DD_LDAP_BIND_PASSWORD:-}" +``` + +Alternatively, set these values directly in `local_settings.py`. diff --git a/docs/content/admin/sso/OS__oidc.md b/docs/content/admin/sso/OS__oidc.md index 9c195889923..b105931ea3b 100644 --- a/docs/content/admin/sso/OS__oidc.md +++ b/docs/content/admin/sso/OS__oidc.md @@ -5,7 +5,7 @@ weight: 18 audience: opensource --- -Open-Source DefectDojo supports login via a generic OpenID Connect (OIDC) provider. DefectDojo Pro users should refer to the [Pro OIDC guide](../PRO__oidc/). +Open-Source DefectDojo supports login via a generic OpenID Connect (OIDC) provider. DefectDojo Pro users should refer to the [Pro OIDC guide](/admin/sso/pro__oidc/). ## Configuration diff --git a/docs/content/admin/sso/OS__okta.md b/docs/content/admin/sso/OS__okta.md index 8348fdf2339..7f10b785c0a 100644 --- a/docs/content/admin/sso/OS__okta.md +++ b/docs/content/admin/sso/OS__okta.md @@ -5,7 +5,7 @@ weight: 16 audience: opensource --- -Open-Source DefectDojo supports login via Okta. DefectDojo Pro users should refer to the [Pro Okta guide](../PRO__okta/). +Open-Source DefectDojo supports login via Okta. DefectDojo Pro users should refer to the [Pro Okta guide](/admin/sso/pro__okta/). ## Prerequisites diff --git a/docs/content/admin/sso/OS__saml.md b/docs/content/admin/sso/OS__saml.md index 7ded9b13c26..f92a7725c7e 100644 --- a/docs/content/admin/sso/OS__saml.md +++ b/docs/content/admin/sso/OS__saml.md @@ -7,7 +7,7 @@ aliases: - /en/working_with_findings/sla_configuration --- -Open-Source DefectDojo supports SAML authentication via environment variables. DefectDojo Pro users should refer to the [Pro SAML guide](../PRO__saml/). +Open-Source DefectDojo supports SAML authentication via environment variables. DefectDojo Pro users should refer to the [Pro SAML guide](/admin/sso/pro__saml/). ## Setup diff --git a/docs/content/admin/sso/PRO__auth0.md b/docs/content/admin/sso/PRO__auth0.md index a755a31ee8c..201b76a5b1e 100644 --- a/docs/content/admin/sso/PRO__auth0.md +++ b/docs/content/admin/sso/PRO__auth0.md @@ -5,7 +5,7 @@ weight: 3 audience: pro --- -DefectDojo Pro supports login via Auth0. Open-Source users should refer to the [Open-Source Auth0 guide](../OS__auth0/). +DefectDojo Pro supports login via Auth0. Open-Source users should refer to the [Open-Source Auth0 guide](/admin/sso/os__auth0/). ## Prerequisites diff --git a/docs/content/admin/sso/PRO__azure_ad.md b/docs/content/admin/sso/PRO__azure_ad.md index 9682551e1aa..278423d92b9 100644 --- a/docs/content/admin/sso/PRO__azure_ad.md +++ b/docs/content/admin/sso/PRO__azure_ad.md @@ -5,7 +5,7 @@ weight: 5 audience: pro --- -DefectDojo Pro supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. Open-Source users should refer to the [Open-Source Azure AD guide](../OS__azure_ad/). +DefectDojo Pro supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. Open-Source users should refer to the [Open-Source Azure AD guide](/admin/sso/os__azure_ad/). ## Prerequisites diff --git a/docs/content/admin/sso/PRO__github_enterprise.md b/docs/content/admin/sso/PRO__github_enterprise.md index 6318baf32e5..6211f846002 100644 --- a/docs/content/admin/sso/PRO__github_enterprise.md +++ b/docs/content/admin/sso/PRO__github_enterprise.md @@ -5,7 +5,7 @@ weight: 7 audience: pro --- -DefectDojo Pro supports login via GitHub Enterprise. Open-Source users should refer to the [Open-Source GitHub Enterprise guide](../OS__github_enterprise/). +DefectDojo Pro supports login via GitHub Enterprise. Open-Source users should refer to the [Open-Source GitHub Enterprise guide](/admin/sso/os__github_enterprise/). ## Prerequisites diff --git a/docs/content/admin/sso/PRO__gitlab.md b/docs/content/admin/sso/PRO__gitlab.md index cb854902a6f..dc13511ca90 100644 --- a/docs/content/admin/sso/PRO__gitlab.md +++ b/docs/content/admin/sso/PRO__gitlab.md @@ -5,7 +5,7 @@ weight: 9 audience: pro --- -DefectDojo Pro supports login via GitLab. Open-Source users should refer to the [Open-Source GitLab guide](../OS__gitlab/). +DefectDojo Pro supports login via GitLab. Open-Source users should refer to the [Open-Source GitLab guide](/admin/sso/os__gitlab/). ## Prerequisites diff --git a/docs/content/admin/sso/PRO__google.md b/docs/content/admin/sso/PRO__google.md index b03a63a7da7..b59695aadb1 100644 --- a/docs/content/admin/sso/PRO__google.md +++ b/docs/content/admin/sso/PRO__google.md @@ -5,7 +5,7 @@ weight: 11 audience: pro --- -DefectDojo Pro supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). Open-Source users should refer to the [Open-Source Google guide](../OS__google/). +DefectDojo Pro supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). Open-Source users should refer to the [Open-Source Google guide](/admin/sso/os__google/). ## Prerequisites diff --git a/docs/content/admin/sso/PRO__keycloak.md b/docs/content/admin/sso/PRO__keycloak.md index e90d6909bbb..06d8fb11933 100644 --- a/docs/content/admin/sso/PRO__keycloak.md +++ b/docs/content/admin/sso/PRO__keycloak.md @@ -5,7 +5,7 @@ weight: 13 audience: pro --- -DefectDojo Pro supports login via KeyCloak. Open-Source users should refer to the [Open-Source KeyCloak guide](../OS__keycloak/). +DefectDojo Pro supports login via KeyCloak. Open-Source users should refer to the [Open-Source KeyCloak guide](/admin/sso/os__keycloak/). This guide assumes you already have a KeyCloak Realm configured. If not, see the [KeyCloak documentation](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html). diff --git a/docs/content/admin/sso/PRO__oidc.md b/docs/content/admin/sso/PRO__oidc.md index d68a0a4ad0e..a5d4b0f5c76 100644 --- a/docs/content/admin/sso/PRO__oidc.md +++ b/docs/content/admin/sso/PRO__oidc.md @@ -5,7 +5,7 @@ weight: 17 audience: pro --- -DefectDojo Pro supports login via a generic OpenID Connect (OIDC) provider. Open-Source users should refer to the [Open-Source OIDC guide](../OS__oidc/). +DefectDojo Pro supports login via a generic OpenID Connect (OIDC) provider. Open-Source users should refer to the [Open-Source OIDC guide](/admin/sso/os__oidc/). ## Configuration diff --git a/docs/content/admin/sso/PRO__okta.md b/docs/content/admin/sso/PRO__okta.md index 4863dcb773b..7cb8d7b3f16 100644 --- a/docs/content/admin/sso/PRO__okta.md +++ b/docs/content/admin/sso/PRO__okta.md @@ -5,7 +5,7 @@ weight: 15 audience: pro --- -DefectDojo Pro supports login via Okta. Open-Source users should refer to the [Open-Source Okta guide](../OS__okta/). +DefectDojo Pro supports login via Okta. Open-Source users should refer to the [Open-Source Okta guide](/admin/sso/os__okta/). ## Prerequisites diff --git a/docs/content/admin/sso/PRO__saml.md b/docs/content/admin/sso/PRO__saml.md index 7ca7b225e99..8c84a77f847 100644 --- a/docs/content/admin/sso/PRO__saml.md +++ b/docs/content/admin/sso/PRO__saml.md @@ -5,7 +5,7 @@ weight: 1 audience: pro --- -DefectDojo Pro supports SAML authentication via the **Enterprise Settings** UI. Open-Source users should refer to the [Open-Source SAML guide](../OS__saml/). +DefectDojo Pro supports SAML authentication via the **Enterprise Settings** UI. Open-Source users should refer to the [Open-Source SAML guide](/admin/sso/os__saml/). ## Setup diff --git a/docs/content/admin/sso/_index.md b/docs/content/admin/sso/_index.md index c48d92360ae..bcface4bac3 100644 --- a/docs/content/admin/sso/_index.md +++ b/docs/content/admin/sso/_index.md @@ -20,15 +20,15 @@ aliases: Users can connect to DefectDojo with a Username and Password, but you can also allow users to authenticate via Single Sign-On (SSO). DefectDojo supports SAML and a range of OAuth providers: -* **[Auth0](./PRO__auth0/)** -* **[Azure Active Directory](./PRO__azure_ad/)** -* **[GitHub Enterprise](./PRO__github_enterprise/)** -* **[GitLab](./PRO__gitlab/)** -* **[Google](./PRO__google/)** -* **[KeyCloak](./PRO__keycloak/)** -* **[Okta](./PRO__okta/)** -* **[OIDC (OpenID Connect)](./PRO__oidc/)** -* **[SAML](./PRO__saml/)** +* **[Auth0](/admin/sso/pro__auth0/)** +* **[Azure Active Directory](/admin/sso/pro__azure_ad/)** +* **[GitHub Enterprise](/admin/sso/pro__github_enterprise/)** +* **[GitLab](/admin/sso/pro__gitlab/)** +* **[Google](/admin/sso/pro__google/)** +* **[KeyCloak](/admin/sso/pro__keycloak/)** +* **[Okta](/admin/sso/pro__okta/)** +* **[OIDC (OpenID Connect)](/admin/sso/pro__oidc/)** +* **[SAML](/admin/sso/pro__saml/)** SSO configuration can only be performed by a **Superuser**. diff --git a/docs/content/open_source/archived_docs/_index.md b/docs/content/archived_docs/_index.md similarity index 100% rename from docs/content/open_source/archived_docs/_index.md rename to docs/content/archived_docs/_index.md diff --git a/docs/content/open_source/archived_docs/burp-plugin.md b/docs/content/archived_docs/burp-plugin.md similarity index 100% rename from docs/content/open_source/archived_docs/burp-plugin.md rename to docs/content/archived_docs/burp-plugin.md diff --git a/docs/content/open_source/archived_docs/google-sheets-sync.md b/docs/content/archived_docs/google-sheets-sync.md similarity index 100% rename from docs/content/open_source/archived_docs/google-sheets-sync.md rename to docs/content/archived_docs/google-sheets-sync.md diff --git a/docs/content/asset_modelling/hierarchy/OS__sla_configuration.md b/docs/content/asset_modelling/hierarchy/OS__sla_configuration.md index 87cf294abae..ef454a48b2e 100644 --- a/docs/content/asset_modelling/hierarchy/OS__sla_configuration.md +++ b/docs/content/asset_modelling/hierarchy/OS__sla_configuration.md @@ -73,6 +73,6 @@ Once a new SLA has been selected for a Product, all of the associated Findings' ## Notes on SLAs -* SLAs can be optionally restarted once a [Risk Accepted](/triage_findings/findings_workflows/risk_acceptances/) Finding reactivates. This is set when creating the Risk Acceptance by setting the **Restart SLA Expired** field. +* SLAs can be optionally restarted once a [Risk Accepted](/triage_findings/findings_workflows/os__risk_acceptance/) Finding reactivates. This is set when creating the Risk Acceptance by setting the **Restart SLA Expired** field. * Reimporting a Finding does not restart the SLA - SLAs are always calculated from when a Finding was first detected unless **Restart SLA on Finding Reactivation** is enabled. * Risk Acceptance expiry or reactivation of a Closed Finding are the only ways to reset or recalculate an SLA for a Finding once it is created (without changing the Product's SLA configuration). diff --git a/docs/content/asset_modelling/hierarchy/PRO__priority_sla.md b/docs/content/asset_modelling/hierarchy/PRO__priority_sla.md index 5baf8753d9a..1407232bb4e 100644 --- a/docs/content/asset_modelling/hierarchy/PRO__priority_sla.md +++ b/docs/content/asset_modelling/hierarchy/PRO__priority_sla.md @@ -262,6 +262,6 @@ Once a new SLA has been selected for a Product, all of the associated Findings' ## Notes on SLAs -* SLAs can be optionally restarted once a [Risk Accepted](/triage_findings/findings_workflows/risk_acceptances/) Finding reactivates. This is set when creating the Risk Acceptance by setting the **Restart SLA Expired** field. +* SLAs can be optionally restarted once a [Risk Accepted](/triage_findings/findings_workflows/pro__risk_acceptance/) Finding reactivates. This is set when creating the Risk Acceptance by setting the **Restart SLA Expired** field. * Reimporting a Finding does not restart the SLA - SLAs are always calculated from when a Finding was first detected unless **Restart SLA on Finding Reactivation** is enabled. * Risk Acceptance expiry or reactivation of a Closed Finding are the only ways to reset or recalculate an SLA for a Finding once it is created (without changing the Product's SLA configuration). diff --git a/docs/content/asset_modelling/hierarchy/benchmarks.md b/docs/content/asset_modelling/hierarchy/benchmarks.md new file mode 100644 index 00000000000..2f6ec981e49 --- /dev/null +++ b/docs/content/asset_modelling/hierarchy/benchmarks.md @@ -0,0 +1,38 @@ +--- +title: "OWASP ASVS Benchmarks" +description: "Benchmark a Product against the OWASP Application Security Verification Standard" +weight: 6 +audience: opensource +--- + +DefectDojo supports benchmarking Products against the [OWASP Application Security Verification Standard (ASVS)](https://owasp.org/www-project-application-security-verification-standard/), which provides a basis for testing web application technical security controls. + +Benchmarks allow you to measure how well a Product meets your organization's defined security requirements, and to publish a score on the Product page for visibility. + +## Accessing Benchmarks + +Benchmarks are available from the **Product** page. To open the Benchmarks view, select the dropdown menu in the upper-right area of the Product page and choose **OWASP ASVS v.3.1** near the bottom of the menu. + +## Benchmark Levels + +OWASP ASVS defines three levels of verification coverage: + +- **Level 1** – For all software. Covers the most critical security requirements with the lowest cost to verify. This is the default level in DefectDojo. +- **Level 2** – For applications that contain sensitive data. Appropriate for most applications. +- **Level 3** – For the most critical applications, such as those performing high-value transactions or storing sensitive medical, financial, or safety data. + +You can switch between levels using the dropdown in the upper-right of the Benchmarks view. + +## Benchmark Score + +The left side of the Benchmarks view displays the current score for your Product at the selected ASVS level: + +- The **desired score** your organization has set as a target +- The **percentage of benchmarks passed** toward achieving that score +- The **total number of enabled benchmarks** for the selected level + +Enabling the **Publish** checkbox will display the ASVS score directly on the Product page. + +## Managing Benchmark Entries + +Individual benchmark entries can be marked as passed or failed as your team works through the ASVS controls. Additional benchmark entries, beyond the default ASVS set, can be added or updated through the **Django admin site**. diff --git a/docs/content/automation/api/languages.md b/docs/content/automation/api/languages.md new file mode 100644 index 00000000000..707af50f03d --- /dev/null +++ b/docs/content/automation/api/languages.md @@ -0,0 +1,38 @@ +--- +title: "Languages and Lines of Code" +description: "Import language composition data for a Product using the cloc tool" +weight: 3 +audience: opensource +aliases: + - /en/open_source/languages +--- + +DefectDojo can display a breakdown of programming languages and lines of code for a Product, populated by importing a report from the [cloc](https://github.com/AlDanial/cloc) (Count Lines of Code) tool via the API. + +## Generating the cloc Report + +Run `cloc` against your codebase using the `--json` flag to produce a JSON file in the correct format: + +```bash +cloc --json /path/to/your/project > cloc-report.json +``` + +## Importing via the API + +Upload the JSON report to DefectDojo via the API. When importing, all existing language data for the Product is replaced with the contents of the new file. + +The import endpoint is documented in the [DefectDojo API v2 docs](./api-v2-docs). + +## Viewing Results + +After import, the language breakdown is displayed on the left side of the Product details page, showing each language and its line count. Colors for each language are defined by entries in the `Language_Type` table, pre-populated with data from GitHub. + +## Updating Language Colors + +GitHub periodically updates language colors as new languages emerge. To pull the latest color data, run the following management command: + +```bash +./manage.py import_github_languages +``` + +This reads from [ozh/github-colors](https://github.com/ozh/github-colors) and adds new languages or updates existing colors. diff --git a/docs/content/automation/api/notification_webhooks.md b/docs/content/automation/api/notification_webhooks.md new file mode 100644 index 00000000000..5e9c8f7236e --- /dev/null +++ b/docs/content/automation/api/notification_webhooks.md @@ -0,0 +1,346 @@ +--- +title: "Notification Webhooks" +description: "Send HTTP webhook notifications to an external server on DefectDojo events" +weight: 8 +audience: opensource +aliases: + - /en/open_source/notification_webhooks/how_to +--- + +**This is an experimental Open Source feature — behavior may change in future releases.** + +Webhooks are outbound HTTP requests sent from your DefectDojo instance to a user-defined server whenever specific events occur. + +## Setup + +Webhook endpoints are configured by admins. When a webhook is created, DefectDojo sends a [`ping`](#ping) event to verify the endpoint is reachable and returning the expected status code. + +## Endpoint State Transitions + +DefectDojo monitors delivery success and will temporarily or permanently disable an endpoint based on HTTP responses or network failures. Manual re-activation by an admin is also possible. + +- **Stadium-shaped states**: Active — webhooks can be sent +- **Rectangle states**: Inactive — webhook delivery will fail and is not retried +- **Transitions driven by**: HTTP responses from the target server, celery automation, or manual admin action + +## Request Headers + +Every webhook request includes the following headers: + +```yaml +User-Agent: DefectDojo- +X-DefectDojo-Event: +X-DefectDojo-Instance: +``` + +## Events + +### product_type_added + +Fired when a new Product Type is created. + +**Header:** +```yaml +X-DefectDojo-Event: product_type_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### product_added + +Fired when a new Product is created. + +**Header:** +```yaml +X-DefectDojo-Event: product_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### engagement_added + +Fired when a new Engagement is created. + +**Header:** +```yaml +X-DefectDojo-Event: engagement_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### test_added + +Fired when a new Test is created. + +**Header:** +```yaml +X-DefectDojo-Event: test_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "test": { + "id": 90, + "title": "notif test", + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90" + }, + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### scan_added / scan_added_empty + +Fired when a scan is imported or reimported. `scan_added_empty` fires when a reimport results in no changes (no findings created or closed). + +**Headers:** +```yaml +X-DefectDojo-Event: scan_added +``` +```yaml +X-DefectDojo-Event: scan_added_empty +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "finding_count": 4, + "findings": { + "mitigated": [ + { + "id": 233, + "severity": "Medium", + "title": "Mitigated Finding", + "url_api": "http://localhost:8080/api/v2/findings/233/", + "url_ui": "http://localhost:8080/finding/233" + } + ], + "new": [ + { + "id": 232, + "severity": "Critical", + "title": "New Finding", + "url_api": "http://localhost:8080/api/v2/findings/232/", + "url_ui": "http://localhost:8080/finding/232" + } + ], + "reactivated": [ + { + "id": 234, + "severity": "Low", + "title": "Reactivated Finding", + "url_api": "http://localhost:8080/api/v2/findings/234/", + "url_ui": "http://localhost:8080/finding/234" + } + ], + "untouched": [ + { + "id": 235, + "severity": "Info", + "title": "Untouched Finding", + "url_api": "http://localhost:8080/api/v2/findings/235/", + "url_ui": "http://localhost:8080/finding/235" + } + ] + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "test": { + "id": 90, + "title": "notif test", + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90" + }, + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### ping + +Sent during webhook setup to verify the endpoint is reachable. + +**Header:** +```yaml +X-DefectDojo-Event: ping +``` + +**Body:** +```json +{ + "description": "Test webhook notification", + "title": "", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +## Roadmap + +Known planned improvements: + +- SLA-related events (not yet supported) +- User-defined webhooks (currently admin-only) +- Improved UI with filtering and pagination for webhook endpoints diff --git a/docs/content/automation/api/rate_limiting.md b/docs/content/automation/api/rate_limiting.md new file mode 100644 index 00000000000..3aa5e5737cc --- /dev/null +++ b/docs/content/automation/api/rate_limiting.md @@ -0,0 +1,44 @@ +--- +title: "Rate Limiting" +description: "Configure rate limiting on the login page to mitigate brute force attacks" +weight: 4 +audience: opensource +aliases: + - /en/open_source/rate_limiting +--- + +DefectDojo includes login-page rate limiting to protect against brute force attacks, powered by [Django Ratelimit](https://django-ratelimit.readthedocs.io/en/stable/index.html). + +## Configuration + +Rate limiting is configured via the following settings (see [Configuration](../../get_started/open_source/configuration) for how to apply these): + +```python +DD_RATE_LIMITER_ENABLED=(bool, True), +DD_RATE_LIMITER_RATE=(str, '5/m'), +DD_RATE_LIMITER_BLOCK=(bool, True), +DD_RATE_LIMITER_ACCOUNT_LOCKOUT=(bool, True), +``` + +### Rate Limit (`DD_RATE_LIMITER_RATE`) + +Sets how frequently requests will be limited. Supported units: + +- Seconds: `1s` +- Minutes: `5m` +- Hours: `100h` +- Days: `2400d` + +See the [Django Ratelimit rates docs](https://django-ratelimit.readthedocs.io/en/stable/rates.html) for extended configuration options. + +### Block Requests (`DD_RATE_LIMITER_BLOCK`) + +By default, rate limiting records offenses but does not block requests. Setting `DD_RATE_LIMITER_BLOCK` to `True` will actively block all incoming requests once the configured rate is exceeded. + +### Account Lockout (`DD_RATE_LIMITER_ACCOUNT_LOCKOUT`) + +When enabled, a user whose login attempts trigger the rate limit will be required to reset their password before they can log in again. This reduces the risk of credential compromise during a brute force attack. + +## Multi-Process Behaviour + +When running with multiple `uwsgi` processes, the rate limiting package uses a memory-based cache that is local to each process. Rate limit counters are not shared across processes in this default configuration. diff --git a/docs/content/automation/rules_engine/_index.md b/docs/content/automation/rules_engine/_index.md index 25a5b4b104f..fa9f022e061 100644 --- a/docs/content/automation/rules_engine/_index.md +++ b/docs/content/automation/rules_engine/_index.md @@ -13,4 +13,5 @@ seo: canonical: "" # custom canonical URL (optional) robots: "" # custom robot tags (optional) exclude_search: true +audience: pro --- \ No newline at end of file diff --git a/docs/content/get_started/common_use_cases/common_use_cases.md b/docs/content/get_started/common_use_cases/common_use_cases.md index 14f68145752..6177924dda5 100644 --- a/docs/content/get_started/common_use_cases/common_use_cases.md +++ b/docs/content/get_started/common_use_cases/common_use_cases.md @@ -100,13 +100,13 @@ Key Concerns for Kate's Cloud Service: #### Tagging Shared Services -Because Kate's model contains many shared services that can impact other Products, the team [Tags](/asset_modelling/tags/tagging_objects/) their Products to indicate which cloud offerings rely on those services. This allows any issues with shared services to be filtered across Products and reported to the relevant teams. Each of these shared services are in a single Product Type that separates them from the main cloud offerings. +Because Kate's model contains many shared services that can impact other Products, the team [Tags](/asset_modelling/tags/os__tagging_objects/) their Products to indicate which cloud offerings rely on those services. This allows any issues with shared services to be filtered across Products and reported to the relevant teams. Each of these shared services are in a single Product Type that separates them from the main cloud offerings. ![image](images/example_product_hierarchy_microservices.png) Because the company is rapidly growing and tech leads are changing frequently, Kate can use Tags to track which tech lead is currently responsible for each cloud product, avoiding the need for constant manual updates to their DefectDojo system. These tech lead associations are tracked by a service that’s external to DefectDojo and can govern the import pipelines or call the DefectDojo API. -For more information on Tagging, see our guide to [Tags](/asset_modelling/tags/tagging_objects/). +For more information on Tagging, see our guide to [Tags](/asset_modelling/tags/os__tagging_objects/). #### RBAC Model diff --git a/docs/content/open_source/contributing/_index.md b/docs/content/get_started/contributing/_index.md similarity index 78% rename from docs/content/open_source/contributing/_index.md rename to docs/content/get_started/contributing/_index.md index 5b87571cfcb..bfa0542cf5d 100644 --- a/docs/content/open_source/contributing/_index.md +++ b/docs/content/get_started/contributing/_index.md @@ -1,8 +1,11 @@ --- title: "Contributing" description: "How you can help to make DefectDojo even better" -weight: 4 +weight: 5 chapter: true +audience: opensource +aliases: + - /en/open_source/contributing --- You can find further information in the [contributing guidelines](https://github.com/DefectDojo/django-DefectDojo/blob/master/readme-docs/CONTRIBUTING.md). diff --git a/docs/content/open_source/contributing/branching-model.md b/docs/content/get_started/contributing/branching-model.md similarity index 96% rename from docs/content/open_source/contributing/branching-model.md rename to docs/content/get_started/contributing/branching-model.md index 58dcf75a14c..b548d7b43fb 100644 --- a/docs/content/open_source/contributing/branching-model.md +++ b/docs/content/get_started/contributing/branching-model.md @@ -3,12 +3,13 @@ title: "Open-Source Branching & Releases" description: "How we create releases" draft: false weight: 3 +audience: opensource aliases: - /en/open_source/contributing/branching-model --- ## Regular releases -The DefectDojo team aims to maintain the following cadence: +The DefectDojo team aims to maintain the following cadence: - Minor releases: at least once a month on the first Monday of the month. - Patch/Bugfix: releases every week on Monday. @@ -25,7 +26,6 @@ GitHub Actions are the source of truth. The releases are semi-automated. The ste PRs that relate to security issues are done through [security advisories](https://github.com/DefectDojo/django-DefectDojo/security/advisories) which provide a way to work privately on code without prematurely disclosing vulnerabilities. ## Release and hotfix model -![Schemas](images/branching_model_v2.png) Diagrams created with [plantUML](https://plantuml.com). Find a web-based editor for PlantUML at https://www.planttext.com. diff --git a/docs/content/get_started/contributing/documentation.md b/docs/content/get_started/contributing/documentation.md new file mode 100644 index 00000000000..1e70b18dab5 --- /dev/null +++ b/docs/content/get_started/contributing/documentation.md @@ -0,0 +1,46 @@ +--- +title: "Amend Documentation" +description: "How to amend the documentation" +draft: false +weight: 4 +audience: opensource +aliases: + - /en/open_source/contributing/documentation +--- + +The documentation is built with [Hugo](https://gohugo.io/) and uses a variation of the [Doks](https://getdoks.org/) theme. + +Static files for the website are built with Github actions and are published in the gh-pages branch. + +## How to run a local preview + +1. [Install Hugo](https://gohugo.io/getting-started/installing/). Make sure you have installed the extended version with Sass/SCSS support. Please note there are various Linux packages available on [Hugo GitHub](https://github.com/gohugoio/hugo/releases) +2. Install required theme using Node.js: `cd docs` and then `npm install`. +3. To run the Docs local server, `cd docs` to switch to the docs folder, and start the Hugo development server by running `npm run dev`. Hot reloading is supported - pages will automatically update with changes while the server is running. +4. Visit [http://localhost:1313](http://localhost:1313). + +## Contribution guidelines + +At this stage, our documentation is largely maintained by the DefectDojo Pro team, but we still welcome contributions to docs from the community. + +* Note that our Search functionality uses an external index which points at **docs.defectdojo.com** - so you won't be able to use Search to find any pages that are in dev. Instead, consult your local sitemap.xml file to find any new URLs you've created: `http://localhost:1313/sitemap.xml` +* Our docs are currently written for two audiences: Open Source and Pro, so please include an appropriate label in your Hugo front matter, like so: + +``` +--- +title: "Your great article" +audience: opensource +--- +``` + +* Do not use relative link paths: `[link](../your_article/)`. Although technically 'legal' in Hugo, you will not pass our unit tests. + +## Unit tests for docs + +DefectDojo's docs use Lychee to check for 404s and other link errors. To run this test locally, you can run this command from the root of the repo. This will delete anything in Hugo's `/public/` folder and then rebuild. + +`cd docs && rm -rf public/ && hugo --minify --gc --config config/production/hugo.toml && lychee --offline --no-progress --root-dir public './public/**/*.html` + +### Theme overrides + +We use significant CSS overrides which are detailed in `docs/layouts`. diff --git a/docs/content/open_source/contributing/how-to-write-a-parser.md b/docs/content/get_started/contributing/how-to-write-a-parser.md similarity index 99% rename from docs/content/open_source/contributing/how-to-write-a-parser.md rename to docs/content/get_started/contributing/how-to-write-a-parser.md index c47e3cd8c41..aef9f904043 100644 --- a/docs/content/open_source/contributing/how-to-write-a-parser.md +++ b/docs/content/get_started/contributing/how-to-write-a-parser.md @@ -3,6 +3,7 @@ title: "Contribute to Parsers" description: "How to contribute to parsers" draft: false weight: 1 +audience: opensource aliases: - /en/open_source/contributing/how-to-write-a-parser --- diff --git a/docs/content/open_source/contributing/parser-documentation-template.md b/docs/content/get_started/contributing/parser-documentation-template.md similarity index 98% rename from docs/content/open_source/contributing/parser-documentation-template.md rename to docs/content/get_started/contributing/parser-documentation-template.md index ed3bfc0dce9..90e7b080671 100644 --- a/docs/content/open_source/contributing/parser-documentation-template.md +++ b/docs/content/get_started/contributing/parser-documentation-template.md @@ -1,7 +1,8 @@ --- title: "Parser Documentation Template" toc_hide: true -weight: 1 +weight: 2 +audience: opensource aliases: - /en/open_source/contributing/parser-documentation-template --- diff --git a/docs/content/get_started/pro/pro_features.md b/docs/content/get_started/pro/pro_features.md index 9d5d7600545..e9ad78bb9d8 100644 --- a/docs/content/get_started/pro/pro_features.md +++ b/docs/content/get_started/pro/pro_features.md @@ -16,7 +16,7 @@ Here is a list of DefectDojo Pro’s many additional features, along with links ### Pro UI DefectDojo's UI has been reworked in DefectDojo Pro to be faster, more functional, fully customizable, and better at navigating through enterprise-level data volume. It also includes a dark mode. -See our [Pro UI Guide](../ui_pro_vs_os) for more information. +See our [Pro UI Guide](/get_started/about/ui_pro_vs_os/) for more information. ![image](images/enabling_deduplication_within_an_engagement_2.png) @@ -41,7 +41,7 @@ See our [Rules Engine Guide](/automation/rules_engine/about) for more info. ### Pro Dashboards and Reporting -Generate [instant reports and metrics](../ui_pro_vs_os/#new-dashboards) to share the security posture of your apps and repos, evaluate your security tools and analyze your team's performance in addressing security issues. +Generate [instant reports and metrics](/get_started/about/ui_pro_vs_os/#new-dashboards) to share the security posture of your apps and repos, evaluate your security tools and analyze your team's performance in addressing security issues. The graphics on the landing page can be exported as SVG files, and the data used to create the graphics can also be exported as a table. diff --git a/docs/content/import_data/import_intro/reimport.md b/docs/content/import_data/import_intro/reimport.md index a00cf012e8d..ccfcbd112d0 100644 --- a/docs/content/import_data/import_intro/reimport.md +++ b/docs/content/import_data/import_intro/reimport.md @@ -41,10 +41,14 @@ If any incoming Findings match Findings that already exist, the incoming Finding If there are any Findings that already exist in the Test but which are not present in the incoming report, you can choose to automatically set those Findings to Inactive and Mitigated (on the assumption that those vulnerabilities have been resolved since the previous import). The Test page will show these Findings as **Closed**. -If you don’t want any Findings to be closed, you can disable this behavior on Reimport: +If you **don’t** want any old Findings to be closed, you can disable this behavior on Reimport: * Uncheck the **Close Old Findings** checkbox if using the UI -* Set **close\_old\_findings** to **False** if using the API +* Set `close_old_findings` to `False` if using the API (on this endpoint, `close_old_findings` is `True` by default) + +**Scope note:** Unlike with Import, Reimport can never look at other Tests in the Engagement when considering Findings to close. The scope of Finding closure is always limited to the target Test. + +The `close_old_findings` feature will also respect the `service` field: only Findings with an identical `service` value (or no `service` value, if none was specified) will be considered for closure. ### Reopen Findings diff --git a/docs/content/import_data/import_scan_files/PRO__import_scan_ui.md b/docs/content/import_data/import_scan_files/PRO__import_scan_ui.md index bf4058ecb17..bf879496495 100644 --- a/docs/content/import_data/import_scan_files/PRO__import_scan_ui.md +++ b/docs/content/import_data/import_scan_files/PRO__import_scan_ui.md @@ -62,6 +62,25 @@ To open Optional Fields, click the button labelled **"Optional Fields +"** above * **Source Code Management URI** can also be specified. This form option must be a valid URI. * **Group By:** if you want to create Finding Groups out of this File, you can specify the grouping method here. +### Close Old Findings + +When importing a scan, you can automatically close Findings from previous scans that are no longer present in the new report. Enable this by checking the **Close Old Findings** checkbox in the UI or setting `close_old_findings: true` in the API. + +#### Scope: Engagement vs. Product + +By default, `close_old_findings` closes Findings of the same scan type within the **same Engagement**. DefectDojo Pro adds a second option — **Close Old Findings Within This Product** — which widens the scope to all Findings of the same scan type across the **entire Product**, regardless of which Engagement they belong to. + +| Option | UI checkbox | API parameter | Scope | +|---|---|---|---| +| Close old findings (engagement scope) | **Close Old Findings** | `close_old_findings: true` | Same Engagement | +| Close old findings (product scope) | **Close Old Findings Within This Product** | `close_old_findings_product_scope: true` | Entire Product | + +`close_old_findings_product_scope` requires `close_old_findings` to also be enabled. Setting `close_old_findings_product_scope` without `close_old_findings` has no effect. + +> **Note:** `close_old_findings_product_scope` only applies to the Import (`/import-scan`) endpoint. It has no effect on the Reimport (`/reimport-scan`) endpoint, where the scope is always limited to the current Test. + +The `service` field is also respected: only Findings with an identical `service` value (or no `service` value, if none was specified at import time) will be considered for closure. + ### Triage-less scanners: Do Not Reactivate field Some scanners might not include triage information in their reports (e.g. tfsec). They simply scan code or dependencies, flag issues, and return everything, regardless of whether a vulnerability has already been triaged or not. diff --git a/docs/content/import_data/import_scan_files/endpoint_meta_importer.md b/docs/content/import_data/import_scan_files/endpoint_meta_importer.md new file mode 100644 index 00000000000..582ec7c6295 --- /dev/null +++ b/docs/content/import_data/import_scan_files/endpoint_meta_importer.md @@ -0,0 +1,39 @@ +--- +title: "Endpoint Meta Importer" +description: "Bulk-apply tags and custom fields to endpoints via CSV" +weight: 4 +audience: opensource +--- + +The **Endpoint Meta Importer** lets you apply tags and custom fields to large numbers of endpoints at once using a CSV file. This is particularly useful for organizations running heavy infrastructure scanning, where endpoints need flexible metadata for filtering, sorting, and reporting. + +## CSV Format + +The CSV file must have a `hostname` column (required), plus any number of additional columns representing the tags or custom fields you want to apply. Each additional column name becomes the tag/field key, and its row value becomes the tag/field value. + +**Example:** + +``` +hostname,team,public_facing +sheets.google.com,data analytics,yes +docs.google.com,language processing,yes +feedback.internal.google.com,human resources,no +``` + +This would apply the following metadata: + +| Endpoint | Tags / Custom Fields | +|---|---| +| `sheets.google.com` | `team:data analytics`, `public_facing:yes` | +| `docs.google.com` | `team:language processing`, `public_facing:yes` | +| `feedback.internal.google.com` | `team:human resources`, `public_facing:no` | + +## Requirements + +- The `hostname` column is **required**. It is used to find existing endpoints with a matching host, or to create new endpoints if no match is found. +- All other column names are treated as tag/custom field keys. +- Values are stored in `key:value` format. + +## Using the Endpoint Meta Importer + +The Endpoint Meta Importer is available from the **Endpoints** tab when viewing a Product. Upload your CSV file there to apply the metadata to your endpoints in bulk. diff --git a/docs/content/open_source/_index.md b/docs/content/open_source/_index.md deleted file mode 100644 index 2cc62b8933d..00000000000 --- a/docs/content/open_source/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Open Source DefectDojo" -description: "" -summary: "" -date: 2023-09-07T16:12:03+02:00 -lastmod: 2023-09-07T16:12:03+02:00 -draft: false -weight: 999 -toc: true -sidebar: - collapsed: true -seo: - title: "" # custom title (optional) - description: "" # custom description (recommended) - canonical: "" # custom canonical URL (optional) - robots: "" # custom robot tags (optional) ---- \ No newline at end of file diff --git a/docs/content/open_source/archived_docs/usage/_index.md b/docs/content/open_source/archived_docs/usage/_index.md deleted file mode 100644 index a07aee8157c..00000000000 --- a/docs/content/open_source/archived_docs/usage/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Usage" -description: "How to use DefectDojo to manage vulnerabilities" -weight: 2 -chapter: true -sidebar: - collapsed: true ---- diff --git a/docs/content/open_source/archived_docs/usage/features.md b/docs/content/open_source/archived_docs/usage/features.md deleted file mode 100644 index 0635177a8d3..00000000000 --- a/docs/content/open_source/archived_docs/usage/features.md +++ /dev/null @@ -1,687 +0,0 @@ ---- -title: "Features" -description: "Various features help manage vulnerabilities." -draft: false -weight: 2 -exclude_search: false -aliases: - - /en/open_source/archived_docs/usage/features ---- -## Tags - -In DefectDojo, tags are a first class citizen and are recognized as the facilitators -of organization within each level of the [data model](../models). Tags are -ideal for grouping objects in a manner that can be filtered out into smaller, more -digestible chunks. - -Here is an example with a product with two tags and four findings each with a single tag - -![High level example of usage with tags](images/tags-high-level-example.png) - -#### Format of tag - -Tags can be formatted in any of the following ways: -- StringWithNoSpaces -- string-with-hyphens -- string_with_underscores -- colons:acceptable -- "quoted string with spaces" - -### Adding and Removing - -Tags can be managed in the following ways - -1. Creating or Editing new objects - - When a new object is created or edited through the UI or API, there is a field for specifying - the tags to be set on a given object. This field is a multiselect field that also has - auto completion to make searching and adding existing tags a breeze. Here is what the field - looks like on the product from the screenshot in the previous section: - - ![Tag management on an object](images/tags-management-on-object.png) - -2. Import and Reimport - - Tags can also be applied to a given test at the time of import or reimport. This is a very - handy use case when importing via the API with automation as it provides an opportunity to - append automation run details and tool information that may not be captured in the test - or finding object directly. - - The field looks and behaves exactly as it does on a given object - -3. Bulk Edit Menu (Findings only) - - When needing to update many findings with the same set of tags, the bulk edit menu can be - used to ease the burden. - - In the following example, lets say I want to update the tags of the two findings with the tag "tag-group-alpha" to be a new tag list like this ["tag-group-charlie", "tag-group-delta"]. - First I would select the tags to be updated: - - ![Select findings for bulk edit tag update](images/tags-select-findings-for-bulk-edit.png) - - Once a finding is selected, a new button appears with the name "Bulk Edit". Clicking this button - produces a dropdown menu with many options, but the focus is just on tags for now. Update the - field to have the desired tag list as follows, and click submit - - ![Apply changes for bulk edit tag update](images/tags-bulk-edit-submit.png) - - The tags on the selected Findings will be updated to whatever was specified in the tags field - within the bulk edit menu - - ![Completed bulk edit tag update](images/tags-bulk-edit-complete.png) - -### Filtering - -Tags can be filtered in many ways through both the UI and the API. For example, here is a snippet -of the Finding filters: - -![Snippet of the finding filters](images/tags-finding-filter-snippet.png) - -There are ten fields related to tags: - - - Tags: filter on any tags that are attached to a given Finding - - Examples: - - Finding will be returned - - Finding Tags: ["A", "B", "C"] - - Filter Query: "B" - - Finding Will *not* be returned - - Finding Tags: ["A", "B", "C"] - - Filter Query: "F" - - Not Tags: filter on any tags that are *not* attached to a given Finding - - Examples: - - Finding will be returned - - Finding Tags: ["A", "B", "C"] - - Filter Query: "F" - - Finding Will *not* be returned - - Finding Tags: ["A", "B", "C"] - - Filter Query: "B" - - Tag Name Contains: filter on any tags that contain part or all of the query in the given Finding - - Examples: - - Finding will be returned - - Finding Tags: ["Alpha", "Beta", "Charlie"] - - Filter Query: "et" (part of "Beta") - - Finding Will *not* be returned - - Finding Tags: ["Alpha", "Beta", "Charlie"] - - Filter Query: "meg" (part of "Omega") - - Not Tags: filter on any tags that do *not* contain part or all of the query in the given Finding - - Examples: - - Finding will be returned - - Finding Tags: ["Alpha", "Beta", "Charlie"] - - Filter Query: "meg" (part of "Omega") - - Finding Will *not* be returned - - Finding Tags: ["Alpha", "Beta", "Charlie"] - - Filter Query: "et" (part of "Beta") - -For the other six tag filters, they follow the same rules as "Tags" and "Not Tags" as above, -but at different levels in the data model: - - - Tags (Test): filter on any tags that are attached to the Test of a given Finding is part of - - Not Tags (Test): filter on any tags that are *not* attached to the Test of a given Finding is part of - - Tags (Engagement): filter on any tags that are attached to the Engagement of a given Finding is part of - - Not Tags (Engagement): filter on any tags that are *not* attached to the Engagement of a given Finding is part of - - Tags (Product): filter on any tags that are attached to the Product of a given Finding is part of - - Not Tags (Product): filter on any tags that are *not* attached to the Product of a given Finding is part of - -### Tag Inheritance - -When enabled, tags applied to a given product will automatically be applied to all objects under Products in the [Product Hierarchy](/asset_modelling/hierarchy/product_hierarchy/). - -#### Configuration - -Tag Inheritance can be enabled at the following scope levels: -- Global Scope - - Every product system wide will begin applying tags to all children objects - - This is set within the System Settings -- Product Scope - - Only the selected product will begin applying tags to all children objects - - This is set at the product creation/edit page - -#### Behaviors - -Tags can be added and removed to other objects the same as when tag inheritance -is disabled. The only exception to that rule being inherited tags as they cannot -be removed from an object. See the following example of adding a tag "test_only_tag" -to the Test object and a tag "engagement_only_tag" to the Engagement. - -![Example of inherited tags](images/tags-inherit-exmaple.png) - -When updates are made to the tag list on a product, the same changes are made to all -objects within the product asynchronously. The duration of this task directly correlates -to the number the objects contained within a finding. If the results are not observed -within a reasonable time period, consult the celery worker logs to identify where any -problems might have arisen. - -## Risk Acceptance - -Findings cannot always be remediated or addressed for various reasons. A -finding \'status\' can be change to \'accepted\' by doing the following: Findings -are accepted in the engagement view. To locate the engagement from the -finding click the link to engagement as shown below. - -![Select an engagement](images/select_engagement.png) - -Then, in the engagement view click the plus icon in the \'Risk -Acceptance\' box and fill in the details to support the risk acceptance. - -![Creating a risk acceptance](images/risk_exception.png) - -The engagement view is now updated with the risk. - -![Risk Acceptance engagement view](images/engagement_risk_acceptance.png) - -The finding status changes to \'Accepted\' with a link to the risk -acceptance. - -![Risk acceptance on finding](images/finding_accepted.png) -## Deduplication - -Deduplication is a feature that when enabled will compare -findings to automatically identify duplicates. When -deduplication is enabled, a list of deduplicated findings is added -to the engagement view. The following image illustrates the option -deduplication on engagement and deduplication on product level: - -![Deduplication on product and engagement level](images/deduplication.png) - -Upon saving a finding, DefectDojo will look at the other findings in the -product or the engagement (depending on the configuration) to find -duplicates - -When a duplicate is found: - -- The newly imported finding takes status: inactive, duplicate -- An \"Original\" link is displayed after the finding status, leading - to the original finding - -There are two ways to use the deduplication: - -Deduplicate vulnerabilities in the same build/release. The vulnerabilities may be found by the same scanner (same scanner deduplication) or by different scanners (cross-scanner deduplication). -: this helps analysis and assessment of the technical debt, - especially if using many different scanners; although - detecting duplicates across scanners is not trivial as it - requires a certain standardization. - -Track unique vulnerabilities across builds/releases so that DefectDojo knows when it finds a vulnerability that has seen it before. - -: this allows you keep information attached to a given finding - in a unique place: all further duplicate findings will point - to the original one. - -### Deduplication configuration - -#### Global configuration - -The deduplication can be activated in \"System Settings\" by ticking -\"Deduplicate findings\". - -An option to delete duplicates can be found in the same menu, and the -maximum number of duplicates to keep for the same finding can be -configured. - -#### Engagement configuration - -When creating or editing an engagement, the -\"Deduplication within engagement only\" checkbox can be ticked. - -- If activated: Findings are only deduplicated within the same - engagement. Findings present in different engagements cannot be - duplicates -- Otherwise: Findings are deduplicated across the whole product - -Note that currently deduplication does not occur across different products. - -### Deduplication algorithms - -The behavior of the deduplication can be configured for each parser in -settings.dist.py (or settings.py after install) by configuring the -`DEDUPLICATION_ALGORITHM_PER_PARSER` variable, or via the env variable (useful for Kubernetes deployments) `DD_DEDUPLICATION_ALGORITHM_PER_PARSER` with a JSON string like -```json -{"ScannerName":"algorithm"} -``` -The environment variable will override the settings in `settings.dist.py`, replacing by matching the keys. - - -The available algorithms are: - -DEDUPE_ALGO_UNIQUE_ID_FROM_TOOL (value for `DD_DEDUPLICATION_ALGORITHM_PER_PARSER`: `unique_id_from_tool`) -: The deduplication occurs based on - finding.unique_id_from_tool which is a unique technical - id existing in the source tool. Few scanners populate this - field currently. If you want to use this algorithm, you may - need to update the scanner code beforehand. - - Advantages: - : - If your source tool has a reliable means of tracking - a unique vulnerability across scans, this - configuration will allow defectDojo to use this - ability. - - Drawbacks: - : - Using this algorithm will not allow cross-scanner - deduplication as other tools will have a different - technical id. - - When the tool evolves, it may change the way the - unique id is generated. In that case you won\'t be - able to recognise that findings found in previous - scans are actually the same as the new findings. - -DEDUPE_ALGO_HASH_CODE (value for `DD_DEDUPLICATION_ALGORITHM_PER_PARSER`: `hash_code`) -: The deduplication occurs based on finding.hash_code. The - hash_code itself is configurable for each scanner in - parameter `HASHCODE_FIELDS_PER_SCANNER`. - -DEDUPE_ALGO_UNIQUE_ID_FROM_TOOL_OR_HASH_CODE (value for `DD_DEDUPLICATION_ALGORITHM_PER_PARSER`: `unique_id_from_tool_or_hash_code`) -: A finding is a duplicate with another if they have the same - unique_id_from_tool OR the same hash_code. - - Allows to use both - : - a technical deduplication (based on - unique_id_from_tool) for a reliable same-parser - deduplication - - and a functional one (based on hash_code configured - on CWE+severity+file_path for example) for - cross-parser deduplication - - -DEDUPE_ALGO_LEGACY (value for `DD_DEDUPLICATION_ALGORITHM_PER_PARSER`: `legacy`) -: This is algorithm that was in place before the configuration - per parser was made possible, and also the default one for - backward compatibility reasons. - - Legacy algorithm basically deduplicates based on: - : - For static scanner: \[\'title\', \'cwe\', \'line\', - \'file_path\', \'description\'\] - - For dynamic scanner: \[\'title\', \'cwe\', \'line\', - \'file_path\', \'description\', \'endpoints\'\] - - Note that there are some subtleties that may give unexpected - results. Switch - `dojo.specific-loggers.deduplication` to debug - in `settings.py` to get more info in case of trouble. - -### Hash_code computation configuration - -The hash_code computation can be configured for each parser using the -parameter `HASHCODE_FIELDS_PER_SCANNER` in -`settings.dist.py`, or via the env variable (useful for Kubernetes deployments) `DD_HASHCODE_FIELDS_PER_SCANNER` with a JSON string like -```json -{"ScannerName":["field1", "field2"]} -``` -The environment variable will override the settings in `settings.dist.py`, replacing by matching the keys. - -The parameter `HASHCODE_ALLOWED_FIELDS` list the fields -from finding table that were tested and are known to be working when -used as a hash_code. Don\'t hesitate to enrich this list when required -(the code is generic and allows adding new fields by configuration only) - -Note that `endpoints` isn\'t a field from finding table but -rather a meta value that will trigger a computation based on all the -endpoints. - -When populating `HASHCODE_FIELDS_PER_SCANNER`, please -respect the order of declaration of the fields: use the same order as in -`HASHCODE_ALLOWED_FIELDS`: that will allow cross-scanner -deduplication to function because the hash_code is computed as a -sha-256 of concatenated values of the configured fields. - -Tips: - -- It\'s advised to use fields that are standardized for a reliable - deduplication, especially if aiming at cross-scanner deduplication. - For example `title` and `description` tend - to change when the tools evolve and don\'t allow cross-scanner - deduplication - - Good candidates are - : - `cwe` or `cve` - - Adding the severity will make sure the deduplication won\'t - be to aggressive (there are several families of XSS and sql - injection for example, with various severities but the same - cwe). - - Adding the file_path or endpoints is advised too. - -- The parameter `HASHCODE_ALLOWS_NULL_CWE` will allow - switching to legacy algorithm when a null cwe is found for a given - finding: this is to avoid getting many duplicates when the tool - fails to give a cwe while we are expecting it. - -### Hashcode generation / regeneration - -When you change the hashcode configuration, it is needed to regenerated the hashcodes for all findings, -or at least those findings found by scanners for which the configuration was updated. - -This is sometimes also needed after an upgrade to a new DefectDojo version, for example when we made changes -to the hashcode configuration or calculation logic. We will mention this in the upgrade notes. - -To regenerate the hashcodes, use the `dedupe` management command: - -{{< highlight bash >}} -docker compose exec uwsgi ./manage.py dedupe --hash_code_only -{{< / highlight >}} - -This will only regenerated the hashcodes, but will not run any deduplication logic on existing findings. -If you want to run deduplication again on existing findings to make sure any duplicates found by the new -hashcode config are marked as such, run: - -{{< highlight bash >}} -docker compose exec uwsgi ./manage.py dedupe -{{< / highlight >}} - -The deduplication part of this command will run the deduplication for each finding in a celery task. If you want to -run the deduplication in the foreground process, use: - -{{< highlight bash >}} -docker compose exec uwsgi ./manage.py dedupe --dedupe_sync -{{< / highlight >}} - -Please note the deduplication process is resource intensive and can take a long time to complete -(estimated ~7500 findings per minute when run in the foreground) - - -### Debugging deduplication - -There is a specific logger that can be activated in order to have -details about the deduplication process : switch -`dojo.specific-loggers.deduplication` to debug in -`settings.dist.py`. - -### Deduplication - APIv2 parameters - -| Parameter | Import behaviour | Reimport Behaviour | -|-----------|------------------|-------------------| -| `close_old_findings` | if `true`, findings that are not duplicates and that were in the previous scan of the same type (example ZAP) for the same **engagement** (or product in case of `close_old_findings_product_scope`) and that are not present in the new scan are closed (`Inactive`, `Verified`, `Mitigated`). | if `true`, findings that that are in the same **test** and that are not present in the new scan are closed (`Inactive`, `Verified`, `Mitigated`) | -| `close_old_findings_product_scope` | if true, `close_old_findings` applies to all findings of the same type in the whole **product**. Note that "Deduplication on engagement" is no longer used to determine the scope of `close_old_findings` | has no effect | - -The `close_old_findings` feature will respect the value of the `service` field to only close findings with an identical `service` value. - -### Deduplication / Similar findings - -Similar Findings Visualization: - -![Similar findings list](images/similar_finding_1.png) - -![Similar findings list with a duplicate](images/similar_finding_2.png) - -Similar Findings -: While viewing a finding, similar findings within the same product - are listed along with buttons to mark one finding a duplicate of the - other. Clicking the \"Use as original\" button on a similar finding - will mark that finding as the original while marking the viewed - finding as a duplicate. Clicking the \"Mark as duplicate\" button on - a similar finding will mark that finding as a duplicate of the - viewed finding. If a similar finding is already marked as a - duplicate, then a \"Reset duplicate status\" button is shown instead - which will remove the duplicate status on that finding along with - marking it active again. - -## Service Level Agreement (SLA) - -DefectDojo allows you to maintain your security SLAs and automatically -remind teams whenever a SLA is about to get breached, or is breached. - -To apply SLAs to Findings, open the `System Settings` page and check 'Enable Finding SLAs'. - -You will then need to create one or more SLA Configurations, from the SLA Configuration menu (your-defectdojo.com/sla_config). - -![SLA configuration screen](images/sla_settings.png) - -### SLA notification configuration - -There are 3 variables in the system settings that can be set for notifications of SLA breaches. -By default notifications are disabled. -You can either choose to notify about breaches for findings that are only in 'Active' or -for any findings across the instance that are in `Active, Verified`. -Furthermore, it is possible choose to only consider findings that have a JIRA issue linked to them. - -There are 2 variables in the settings.py file that you can configure, to -act on the global behavior. - -{{< highlight python >}} -SLA_NOTIFY_PRE_BREACH = 3 -SLA_NOTIFY_POST_BREACH = 7 -{{< / highlight >}} - -The `SLA_NOTIFY_PRE_BREACH` is expressed in days. Whenever a finding\'s -\"SLA countdown\" (time to remediate) drops to this number, a -notification would be sent everyday, as scheduled by the crontab in -`settings.py`, until the day it breaches. - -The `SLA_NOTIFY_POST_BREACH` lets you define in days how long you want -to be kept notified about findings that have breached the SLA. Passed -that number, notifications will cease. - -Be mindful of performance if you choose to have SLA notifications on -non-verified findings, especially if you import a lot of findings -through CI in \'active\' state. - - -### What notification channels for SLA notifications? - -You will notice that an extra `SLA breach` option is now present -on the `Notification` page and also in the `Product` view. - -![SLA notification checkbox](images/sla_notification_product_checkboxes.png) - -### SLA notification with JIRA - -You can choose to also send SLA notification as JIRA comments, if your -product is configured with JIRA. You can enable this at the Product level in the Product specific -JIRA settings. - -The Product level JIRA notification configuration takes precendence over -the global JIRA notification configuration. - -### When is the SLA notification job run? - -The default setup will trigger the SLA notification code at 7:30am on a -daily basis, as defined in the `settings.py` file. You can of course -modify this schedule to your context. - -{{< highlight python >}} -'compute-sla-age-and-notify': { - 'task': 'dojo.tasks.async_sla_compute_and_notify', - 'schedule': crontab(hour=7, minute=30), -} -{{< / highlight >}} - -The celery containers are the ones concerned with this configuration. If -you suspect things are not working as expected, make sure they have the -latest version of your settings.py file. - - -You can of course change this default by modifying that stanza. - -### Launching from the CLI - -You can also invoke the SLA notification function from the CLI. For -example, if run from docker compose: - -{{< highlight bash >}} -$ docker compose exec uwsgi /bin/bash -c 'python manage.py sla_notifications' -{{< / highlight >}} - -## Reports - -### Instant reports - -![Report Listing](images/report_1.png) - -Instant reports can be generated for: - -1. Product types -2. Products -3. Engagements -4. Tests -5. List of Findings -6. Endpoints - -Filtering is available on all report generation views to aid in focusing the report for the appropriate need. - -### Custom reports - -![Report Generation](images/report_2.png) - -Custom reports, generated with the Report Builder, 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 -5. Vulnerable Endpoints -6. Page Breaks - -DefectDojo's reports can be generated in HTML. - -## 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](images/met_1.png) - -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](images/met_2.png) - -Product Tag Counts -: Same as above, but for a group of products sharing a tag. - -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](images/met_3.png) - -Engineer Metrics -: Provides graphs displaying information about a tester\'s activity. - - ![Simple Metrics](images/met_4.png) - -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](images/met_5.png) - -## Users - -DefectDojo users inherit from -[django.contrib.auth.models.User](https://docs.djangoproject.com/en/3.1/topics/auth/default/#user-objects). - -A username, first name, last name, and email address can be associated -with each user. Additionally the following attributes describe the type of users: - -Active -: Designates whether this user should be treated as active and can login to DefectDojo. - Unselect this instead of deleting accounts. - -Superuser status -: Designates that this user can configure the system and has all permissions - for objects without explicitly assigning them. - -A superuser may force a password reset for any user at any given time. This -can be set when creating a new user, or when editing an existing one, requiring -the user to change their password upon their next login. - -DefectDojo enforces the following password rules for all users: -* Must meet a length requirement of 9 characters -* Must be unique (not commonly used) -* Must contain one of each of the following: a number (0-9), uppercase letter - (A-Z), lowercase letter (a-z), and symbol ()[]{}|\~!@#$%^&*_-+=;:`'",<>./? - -## Calendar - -The calendar view provides a look at all the engagements and tests occurring -during the month d, week or day displayed. Each entry is a direct link to the -respective engagement or test view page. - -## Benchmarks - -![OWASP ASVS Benchmarks](images/owasp_asvs.png) - -DefectDojo utilizes the OWASP ASVS Benchmarks to benchmark a product to -ensure the product meets your application technical security controls. -Benchmarks can be defined per the organizations policy for secure -development and multiple benchmarks can be applied to a product. - -Benchmarks are available from the Product view. To view the configured -benchmarks select the dropdown menu from the right hand drop down menu. -You will find the selection near the bottom of the menu entitled: -\'OWASP ASVS v.3.1\'. - -![OWASP ASVS Benchmarks Menu](images/owasp_asvs_menu.png) - -In the Benchmarks view for each product, the default level is ASVS Level -1. On the top right hand side the drop down can be changed to the -desired ASVS level (Level 1, Level 2 or Level 3). The publish checkbox -will display the ASVS score on the product page and in the future this -will be applied to reporting. - -![OWASP ASVS Score](images/owasp_asvs_score.png) - -On the left hand side the ASVS score is displayed with the desired -score, the % of benchmarks passed to achieve the score and the total -enabled benchmarks for that AVSV level. - -Additional benchmarks can be added/updated in the Django admin site. In -a future release this will be brought out to the UI. - -## Endpoint Meta Importer - -For heavy infrastructure scanning organizations, endpoints need to be as -flexible as possible to get the most of DefectDojo. This flexibility comes -in the form of Tags and custom fields. Tags allow users to filter, sort, and -report objects in ways the base object is not totally proficient in doing. - -Endpoint Meta Importer provides a means to apply arbitrary tags and custom fields to -endpoints in mass via a CSV file. Tags and customs fields are stored in the -format of column:row. - -Here is a very simple example with only two columns: - -``` -hostname | team | public_facing ------------------------------------------------------------------- -sheets.google.com | data analytics | yes -docs.google.com | language processing | yes -feedback.internal.google.com | human resources | no -``` - -The three endpoints hosts will be used to find existing endpoints with matching hosts, -or create new endpoints, and then apply meta as follows: - -``` -sheets.google.com (endpoint) -> [ team:data analytics, public_facing:yes ] (tags) -docs.google.com (endpoint) -> [ team:language processing, public_facing:yes ] (tags) -feedback.internal.google.com (endpoint) -> [ team:human resources, public_facing:no ] (tags) -``` - -Endpoint Meta Importer can be found in the Endpoint tab when viewing a Product - -**Note:** The field "hostname" is required as it is used to query/create endpoints. - -## Findings Image Upload - -You can add images (.png, .jpeg, .gif) to your findings. In order to achieve this, you have to click on "Manage Files" within the finding: -![Manage Files](images/findings_manage_files.png) -There, you can upload a png file to attach it to a finding: -![Upload PNG File](images/file_upload.png) -The following picture shows the result: -![Result PNG File in finding](images/uploaded_png_to_finding.png) diff --git a/docs/content/open_source/archived_docs/usage/questionnaires.md b/docs/content/open_source/archived_docs/usage/questionnaires.md deleted file mode 100644 index bf39e369aa7..00000000000 --- a/docs/content/open_source/archived_docs/usage/questionnaires.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: "Questionnaires" -description: "Collect information from people internal or external to DefectDojo." -weight: 3 -draft: false -aliases: - - /en/open_source/archived_docs/usage/questionnaires ---- -## Questionnaires - -Questionnaires provide a means for collecting information from developers and respective stakeholders. DefectDojo includes functionality to create new questionnaires with custom questions, open questionnaires to receive responses for certain time periods from insiders or outsiders, and connect questionnaires with new or existing engagements. - -## Creating a New Questionnaire - -To access, create, or modify new/existing questionnaires, navigate to the _All Questionnaires_ dashboard from the sidebar. - -![Questionnaires Location](images/questionnaires-sidebar.png) - -On the questionnaire dashboard, all existing questionnaires are displayed. To quickly find a questionnaire, the filters may be used to search for snippets within the questionnaire name and/or description, as well as by active/inactive status. - -When questionnaires are open for responses, they will be displayed in the _General Questionnaires_ block towards the bottom of the page. - -To begin the process of creating a new questionnaire, select the _Create Questionnaire_ button located in the top right of the questionnaire dashboard. - -![Questionnaires Home View](images/questionnaires-main-view.png) - -Questionnaires have a name and description, as well as an activity status, which are initially set on questionnaire creation, but can be modified in the future if necessary. Once these fields are filled in appropriately, the user can create the questionnaire without any questions (by selecting _Create Questionnaire_), or with questions (by selecting _Create Questionnaire and Add Questions_). - -![Create New Questionnaire](images/questionnaires-create-new.png) - -To add questions to a questionnaire, select the dropdown titled _Select as many Questions as applicable_, which will open all of the existing questions within DefectDojo. Once the desired questions are selected from the list, the dropdown can be closed, and the _Update Questionnaire Questions_ can be selected to save the newly created questionnaire. - -_Note_: New questions may also be added at the time of questionnaire creation by selecting the plus located next to the questions dropdown. - -![Select Questions](images/questionnaires-select-questions.png) - -## Creating New Questions - -The questions dashboard displays all of the questions that may exist as part of questionnaires within DefectDojo. Similar to questionnaires, to quickly find a question, the filters may be used to search for optional status, or snippets within the question name and/or description. Two types of questions exist within DefectDojo questionnaires: _Text Questions_ and _Multiple Choice Questions_. To add a new question, select the _Create Question_ button located in the top right of the questions dashboard. - -![Questionnaire Questions](images/questionnaires-questions.png) - -#### Adding Text Questions - -To add a text question (open-ended), fill out the add question form, where: - - **Type** - The type of question being created, in this case _Text_. - - **Order** - The order of a question describes its position in a questionnaire relative to other questions (e.g., an order of _1_ will put the question higher than a question with order _4_). - - **Optional** - When the optional box is checked, a question will not be required in a questionnaire. - - **Question Text** - The text that is displayed to prompt a user for their answer (e.g. What is your favorite color?). - -![Add Text Answer Question](images/questionnaires-open-ended.png) - -#### Adding Multiple Choice Questions - -Similar to the process of adding a text question, choice questions (non-open-ended) allow the user to pick from a given list of choices. To add a choice question, fill out the add question form, where: - - **Type** - The type of question being created, in this case _Choice_. - - **Order** - The order of a question describes its position in a questionnaire relative to other questions (e.g., an order of _1_ will put the question higher than a question with order _4_). - - **Optional** - When the optional box is checked, a question will not be required in a questionnaire. - - **Multichoice** - When the multichoice box is checked, multiple choices from the list of choices may be selected by the user. - - **Answer Choices** - The possible answer choices that may be selected by a user. - -![Add Multiple Choice Question](images/questionnaires-multiple-choice.png) - -## Publishing a Questionnaire - -Once a questionnaire has been successfully created, it can be published to accept responses. To publish a questionnaire, select the plus located to the right of _General Questionnaires_. - -![Add General Questionnaire](images/questionnaires-main-view.png) - -This will prompt for a specific questionnaire to be selected, as well as a date the questionnaire response window should close. The response window sets a due date for recipients. Once these two options have been selected, publish the questionnaire by selecting _Add Questionnaire_. - -![Publicize Questionnaire](images/questionnaires-publicize.png) - -Once a questionnaire is published, a link to share it can be retrieved by selecting the _Share Questionnaire_ action. To ensure the newly created questionnaire has been constructed as expected, open the share link and view the newly created questionnaire. - -![Share Questionnaire Link](images/questionnaires-share.png) - -![Responding to Questionnaires](images/questionnaires-respond.png) - -## Unassigned Questionnaires - -When a questionnaire's response window has closed, all of the responses will be saved, and the questionnaire will be listed as an _Unassigned Answered Engagement Questionnaire_ on the DefectDojo dashboard. - -There are three actions that may be taken when a questionnaire's response window has closed: _View Responses_, _Create Engagement_, and _Assign User_. - -![Unnasigned Questionnaires](images/questionnaires-unassigned.png) - -#### View Questionnaire Responses - -To view the questionnaire responses, select the _View Responses_ action. All of the responses from the questionnaire will be displayed. - -![View Questionnaire Responses](images/questionnaires-view-responses.png) - -#### Create an Engagement From a Questionnaire - -To link the questionnaire to a product via an engagement, select the _Create Engagement_ action. Once a product is selected from the dropdown, select _Create Engagement_. This will link the questionnaire results with a new engagement under the selected product, which can then be given specific details similar to other engagements in DefectDojo, such as _Description_, _Version_, _Status_, _Tags_, etc. - -![Link Questionnaire to Engagement](images/questionnaires-new-engagement.png) - -![New Engagement for Questionnaire](images/questionnaires-create-engagement.png) - -To view a questionnaire at the engagement level, navigate to the engagement linked with the desired questionnaire. Expand the _Additional Features_ menu to reveal a _Questionnaires_ dropdown, which will contain all of the linked questionnaires. - -![View Questionnaire from Engagement](images/questionnaires-view-questionnaire.png) - -#### Assign a Questionnaire to a User - -To assign a questionnaire to a user, select the _Assign User_ action. This will prompt for a user to be selected from the dropdown of available users. Once a user is selected, assign the questionnaire to the specified user by selecting _Assign Questionnaire_. - -![Assign Questionnaire to User](images/questionnaires-assign-user.png) - -## Creating Questionnaires From Engagements - -While questionnaires are commonly created from the questionnaire dashboard, they can also be created at the engagement level. To create a new questionnaire from within an engagement, expand the _Additional Features_ dropdown to reveal the _Questionnaires_ dropdown. In the right side header of the _Questionnaires_ dropdown, select the plus to link a new questionnaire. - -![New Questionnaire from Engagement](images/questionnaires-add-from-engagement.png) - -Once prompted, select a questionnaire from the available surveys list to link it with the engagement. If the user wishes to leave a response at the time of linking the questionnaire with the engagement, the _Add Questionnaire and Repond_ option may be selected. To simply link the questionnaire with the engagement, select _Add Questionnaire_. - -![Select Questionnaire from Engagement](images/questionnaires-select-survey.png) - -## Anonymous Questionnaires - -Questionnaires, by default, are only accessible by DefectDojo users. To allow outside responses to DefectDojo questionnaires, ensure the _Allow Anonymous Survey Reponses_ option within the _System Settings_ is selected. To share a questionnaire with anonymous users, use the questionnaire's _Share Link_. - -![Anonymous Survey Reponses](images/questionnaires-system-settings.png) diff --git a/docs/content/open_source/contributing/documentation.md b/docs/content/open_source/contributing/documentation.md deleted file mode 100644 index aa99d3c65e7..00000000000 --- a/docs/content/open_source/contributing/documentation.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Amend Documentation" -description: "How to amend the documentation" -draft: false -weight: 2 -aliases: - - /en/open_source/contributing/documentation ---- -The documentation is built with [Hugo](https://gohugo.io/) and uses the theme [Docsy](https://www.docsy.dev). -Static files for the webside are build with github actions and are publish in the gh-pages branch. - -## How to run a local preview - -1. [Install Hugo](https://gohugo.io/getting-started/installing/). Make sure you have installed the extended version with Sass/SCSS support. Please note there are various Linux packages available on [Hugo GitHub](https://github.com/gohugoio/hugo/releases) -2. Install required theme using Node.js: `cd docs` and then `npm install`. -3. To run the Docs local server, `cd docs` to switch to the docs folder, and start the hugo server by running `npm run dev`. Hot reloading is supported - pages will automatically update with changes while the server is running. -4. Visit [http://localhost:1313](http://localhost:1313). - -DefectDojo Docs are built using a variation of the [Doks](https://getdoks.org/) theme. \ No newline at end of file diff --git a/docs/content/open_source/exporting.md b/docs/content/open_source/exporting.md deleted file mode 100644 index c87163e0199..00000000000 --- a/docs/content/open_source/exporting.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Export Findings" -description: "DefectDojo has the ability to export findings." -draft: false -weight: 12 -aliases: - - /en/open_source/exporting ---- -## Export Findings - -Pages that show a list of findings or a list of engagements have a CSV and Excel Export functionality in the top right dropdown menu. - -![Export findings](images/export_1.png) - -The list of engagements can be exported as CSV/Excel. - -![Export engagements](images/export_2.png) \ No newline at end of file diff --git a/docs/content/open_source/languages.md b/docs/content/open_source/languages.md deleted file mode 100644 index c96f08a4381..00000000000 --- a/docs/content/open_source/languages.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Languages and lines of code (Open-Source)" -description: "You can import an analysis of languages used in a project, including lines of code." -draft: false -weight: 10 -aliases: - - /en/open_source/languages ---- -## Import of languages for a project - -You can import JSON reports generated by the [cloc tool](https://github.com/AlDanial/cloc) via the API: - -![Import of cloc JSON file](images/languages_api.png) - -When importing a file, all language information for the respective project will be deleted first and then populated with the content of the file. -Please make sure to use the `--json` parameter when invoking the `cloc` command, to get the correct file format. - -## Display - -The results of the import are shown on the left side of the product details page. - -![Display of languages](images/languages_ui.png) - -The colors are defined by entries in the table `Language_Type`, which has been prepopulated with data from GitHub. - -## Import of language types - -GitHub updates its language colors from time to time, when new languages emerge. The management command - -`./manage.py import_github_languages` - -reads data from a JSON file hosted in https://github.com/ozh/github-colors to add new languages and update colors. diff --git a/docs/content/open_source/ldap-authentication.md b/docs/content/open_source/ldap-authentication.md deleted file mode 100644 index d1d8f64a4cb..00000000000 --- a/docs/content/open_source/ldap-authentication.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: "Authentication via LDAP (Open-Source)" -description: "Authenticate users using LDAP" -draft: false -weight: 4 -aliases: - - /en/open_source/ldap-authentication ---- -## LDAP Authentication - -Out of the box DefectDojo does not support LDAP authentication. - -*However*, since DefectDojo is built using Django, it isn't too difficult to add support for LDAP. -So long as you don't mind building your own Docker images... - -We will need to modify a grand total of 4-5 files, depending on how you want to pass DefectDojo your LDAP secrets. - - - Dockerfile.django-* - - Dockerfile.nginx-* - - requirements.txt - - local_settings.py - - docker-compose.yml *(Optional)* - - -#### Dockerfile modifications - -In both `Dockerfile.django-alpine` and `Dockerfile.nginx-alpine`, you need to add the following lines to the `apk add` layers: - -```bash -openldap-dev \ -cyrus-sasl-dev \ -``` - -Also, in `Dockerfile.django-debian`, you need to add the following lines to the `apt-get install` layers: - -```bash -libldap2-dev \ -libsasl2-dev \ -ldap-utils \ -``` - - -#### requirements.txt - -Please check for the latest version of these requirements at the time of implementation on pypi.org and use those if you can. - -- [python-ldap](https://pypi.org/project/python-ldap/) -- [django-auth-ldap](https://pypi.org/project/django-auth-ldap/) - -Otherwise add the following to requirements.txt: - -```python -python-ldap==3.4.5 -django-auth-ldap==5.2.0 -``` - - -#### local_settings.py - -Find the settings file (hint: check in `/dojo/settings/settings.py` for instructions for how to use `/dojo/settings/local_settings.py`, if the file does not already exist) and add the following: - -At the top of the file: -```python -import ldap -from django_auth_ldap.config import LDAPSearch, GroupOfNamesType -import environ -``` - -Then further down add LDAP settings to the env dict: -```python -# LDAP -env = environ.FileAwareEnv( - DD_LDAP_SERVER_URI=(str, 'ldap://ldap.example.com'), - DD_LDAP_BIND_DN=(str, ''), - DD_LDAP_BIND_PASSWORD=(str, ''), -) -``` - -Then under the env dict add: -```python -AUTH_LDAP_SERVER_URI = env('DD_LDAP_SERVER_URI') -AUTH_LDAP_BIND_DN = env('DD_LDAP_BIND_DN') -AUTH_LDAP_BIND_PASSWORD = env('DD_LDAP_BIND_PASSWORD') - -AUTH_LDAP_USER_SEARCH = LDAPSearch( - "ou=Groups,dc=example,dc=com", ldap.SCOPE_SUBTREE, "(uid=%(user)s)" -) - -AUTH_LDAP_USER_ATTR_MAP = { - "first_name": "givenName", - "last_name": "sn", - "email": "mail", -} -``` -Please make sure to customise all of the LDAP search variables to match your company's configuration. - - -For additional group controls you can add: -```python -# Set up the basic group parameters. -AUTH_LDAP_GROUP_SEARCH = LDAPSearch( - "dc=example,dc=com", - ldap.SCOPE_SUBTREE, - "(objectClass=groupOfNames)", -) -AUTH_LDAP_GROUP_TYPE = GroupOfNamesType(name_attr="cn") - -# Simple group restrictions -AUTH_LDAP_REQUIRE_GROUP = "cn=DD_USER_ACTIVE,ou=Groups,dc=example,dc=com" - -AUTH_LDAP_USER_FLAGS_BY_GROUP = { - "is_active": "cn=DD_USER_ACTIVE,ou=Groups,dc=example,dc=com", - "is_staff": "cn=DD_USER_STAFF,ou=Groups,dc=example,dc=com", - "is_superuser": "cn=DD_USER_ADMIN,ou=Groups,dc=example,dc=com", -} -``` - -Then also add `'django_auth_ldap.backend.LDAPBackend'` to the `AUTHENTICATION_BACKENDS` variable, for example: -```python -AUTHENTICATION_BACKENDS = ( - 'django_auth_ldap.backend.LDAPBackend', - 'django.contrib.auth.backends.RemoteUserBackend', - 'django.contrib.auth.backends.ModelBackend', -) -``` - -Read the docs for Django Authentication with LDAP here: https://django-auth-ldap.readthedocs.io/en/latest/ - -#### docker-compose.yml - -In order to pass the variables to the `local_settings.py` file via docker, it's a good idea to add these to the `docker-compose.yml` file. - -You can do this by adding the following variables to the environment section for the uwsgi image: -```yaml -DD_LDAP_SERVER_URI: "${DD_LDAP_SERVER_URI:-ldap://ldap.example.com}" -DD_LDAP_BIND_DN: "${DD_LDAP_BIND_DN:-}" -DD_LDAP_BIND_PASSWORD: "${DD_LDAP_BIND_PASSWORD:-}" -``` - -Alternatively you can set these values in a `local_settings.py` file. diff --git a/docs/content/open_source/notification_webhooks/_index.md b/docs/content/open_source/notification_webhooks/_index.md deleted file mode 100644 index a2afb003ae3..00000000000 --- a/docs/content/open_source/notification_webhooks/_index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Notification Webhooks (experimental)" -weight: 7 -chapter: true -sidebar: - collapsed: true -exclude_search: true ---- - -Note: This is an experimental Open-Source feature - results may vary. - -Functionality might generate breaking changes in following DefectDojo releases and might not be considered final. - -Webhooks are HTTP requests coming from the DefectDojo instance towards a user-defined webserver which expects this kind of incoming traffic. - -## Events - -- [`product_type_added`](./product_type_added) -- [`product_added`](./product_added) -- [`engagement_added`](./engagement_added) -- [`test_added`](./test_added) -- [`scan_added` and `scan_added_empty`](./scan_added) -- [`ping`](./ping) \ No newline at end of file diff --git a/docs/content/open_source/notification_webhooks/engagement_added.md b/docs/content/open_source/notification_webhooks/engagement_added.md deleted file mode 100644 index ab9cce6e8e2..00000000000 --- a/docs/content/open_source/notification_webhooks/engagement_added.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Event: engagement_added" -weight: 4 -exclude_search: true -aliases: - - /en/open_source/notification_webhooks/engagement_added ---- -## Event HTTP header -```yaml -X-DefectDojo-Event: engagement_added -``` - -## Event HTTP body -```json -{ - "description": "", - "title": "", - "engagement": { - "id": 7, - "name": "notif eng", - "url_api": "http://localhost:8080/api/v2/engagements/7/", - "url_ui": "http://localhost:8080/engagement/7" - }, - "product": { - "id": 4, - "name": "notif prod", - "url_api": "http://localhost:8080/api/v2/products/4/", - "url_ui": "http://localhost:8080/product/4" - }, - "product_type": { - "id": 4, - "name": "notif prod type", - "url_api": "http://localhost:8080/api/v2/product_types/4/", - "url_ui": "http://localhost:8080/product/type/4" - }, - "url_api": "http://localhost:8080/api/v2/engagements/7/", - "url_ui": "http://localhost:8080/engagement/7", - "user": { - "id": 1, - "email": "admin@defectdojo.local", - "first_name": "Admin", - "last_name": "User", - "username": "admin", - "url_api": "http://localhost:8080/api/v2/users/1/", - "url_ui": "http://localhost:8080/user/1" - } -} -``` diff --git a/docs/content/open_source/notification_webhooks/how_to.md b/docs/content/open_source/notification_webhooks/how_to.md deleted file mode 100644 index 5a1309d9330..00000000000 --- a/docs/content/open_source/notification_webhooks/how_to.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "Notification Webhooks Setup" -weight: 1 -chapter: true -aliases: - - /en/open_source/notification_webhooks/how_to ---- -Webhooks are HTTP requests coming from the DefectDojo instance towards a user-defined webserver which expects this kind of incoming traffic. - -## Transition graph: - -It is not unusual that in some cases a webhook can not be delivered. It is usually connected to network issues, server misconfiguration, or running upgrades on the server. DefectDojo needs to react to these outages. It might temporarily or permanently disable related endpoints. The following graph shows how it might change the status of the webhook definition based on HTTP responses (or manual user interaction). - - - - -![image](images/webhook-state-transition-flow.png) - -Notes: - -1. Transitions: - - bold: manual changes by user - - dotted: automated by celery - - others: based on responses on webhooks -1. Nodes: - - Stadium-shaped: Active - following webhook can be sent - - Rectangles: Inactive - performing of webhook will fail (and not retried) - - Hexagonal: Initial and final states - - Rhombus: All states (meta node to make the graph more readable) - -## Body and Headers - -The body of each request is JSON which contains data about related events like names and IDs of affected elements. -Examples of bodies are on pages related to each event (see below). - -Each request contains the following headers. They might be useful for better handling of events by the server receiving them. - -```yaml -User-Agent: DefectDojo- -X-DefectDojo-Event: -X-DefectDojo-Instance: -``` -## Disclaimer - -This functionality is new and in experimental mode. This means functionality might generate breaking changes in following DefectDojo releases and might not be considered final. - -However, the community is open to feedback to make this functionality better and get it stable as soon as possible. - -## Roadmap - -There are a couple of known issues that are expected to be resolved as soon as core functionality is considered ready. - -- Support events - Not only adding products, product types, engagements, tests, or upload of new scans but also events around SLA -- User webhook - right now only admins can define webhooks; in the future, users will also be able to define their own -- Improvement in UI - add filtering and pagination of webhook endpoints - -## Events - -- [`product_type_added`](../product_type_added) -- [`product_added`](../product_added) -- [`engagement_added`](../engagement_added) -- [`test_added`](../test_added) -- [`scan_added` and `scan_added_empty`](../scan_added) -- [`ping`](../ping) diff --git a/docs/content/open_source/notification_webhooks/ping.md b/docs/content/open_source/notification_webhooks/ping.md deleted file mode 100644 index 9d2233bee04..00000000000 --- a/docs/content/open_source/notification_webhooks/ping.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Event: ping" -weight: 7 -chapter: true -exclude_search: true -aliases: - - /en/open_source/notification_webhooks/ping ---- -An event `ping` is sent during Webhook setup to test whether the endpoint is up and responding with the expected status code. - -## Event HTTP header -```yaml -X-DefectDojo-Event: ping -``` - -## Event HTTP body -```json -{ - "description": "Test webhook notification", - "title": "", - "user": { - "id": 1, - "email": "admin@defectdojo.local", - "first_name": "Admin", - "last_name": "User", - "username": "admin", - "url_api": "http://localhost:8080/api/v2/users/1/", - "url_ui": "http://localhost:8080/user/1" - }, -} -``` diff --git a/docs/content/open_source/notification_webhooks/product_added.md b/docs/content/open_source/notification_webhooks/product_added.md deleted file mode 100644 index b14fce04571..00000000000 --- a/docs/content/open_source/notification_webhooks/product_added.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Event: product_added" -weight: 3 -chapter: true -exclude_search: true -aliases: - - /en/open_source/notification_webhooks/product_added ---- -## Event HTTP header -```yaml -X-DefectDojo-Event: product_added -``` - -## Event HTTP body -```json -{ - "description": "", - "title": "", - "product": { - "id": 4, - "name": "notif prod", - "url_api": "http://localhost:8080/api/v2/products/4/", - "url_ui": "http://localhost:8080/product/4" - }, - "product_type": { - "id": 4, - "name": "notif prod type", - "url_api": "http://localhost:8080/api/v2/product_types/4/", - "url_ui": "http://localhost:8080/product/type/4" - }, - "url_api": "http://localhost:8080/api/v2/products/4/", - "url_ui": "http://localhost:8080/product/4", - "user": { - "id": 1, - "email": "admin@defectdojo.local", - "first_name": "Admin", - "last_name": "User", - "username": "admin", - "url_api": "http://localhost:8080/api/v2/users/1/", - "url_ui": "http://localhost:8080/user/1" - } -} -``` diff --git a/docs/content/open_source/notification_webhooks/product_type_added.md b/docs/content/open_source/notification_webhooks/product_type_added.md deleted file mode 100644 index 223888e5f75..00000000000 --- a/docs/content/open_source/notification_webhooks/product_type_added.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "Event: product_type_added" -weight: 2 -chapter: true -exclude_search: true -aliases: - - /en/open_source/notification_webhooks/product_type_added ---- -## Event HTTP header -```yaml -X-DefectDojo-Event: product_type_added -``` - -## Event HTTP body -```json -{ - "description": "", - "title": "", - "product_type": { - "id": 4, - "name": "notif prod type", - "url_api": "http://localhost:8080/api/v2/product_types/4/", - "url_ui": "http://localhost:8080/product/type/4" - }, - "url_api": "http://localhost:8080/api/v2/product_types/4/", - "url_ui": "http://localhost:8080/product/type/4", - "user": { - "id": 1, - "email": "admin@defectdojo.local", - "first_name": "Admin", - "last_name": "User", - "username": "admin", - "url_api": "http://localhost:8080/api/v2/users/1/", - "url_ui": "http://localhost:8080/user/1" - } -} -``` diff --git a/docs/content/open_source/notification_webhooks/scan_added.md b/docs/content/open_source/notification_webhooks/scan_added.md deleted file mode 100644 index e1950ac6312..00000000000 --- a/docs/content/open_source/notification_webhooks/scan_added.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Event: scan_added and scan_added_empty" -weight: 6 -chapter: true -exclude_search: true -aliases: - - /en/open_source/notification_webhooks/scan_added ---- -Event `scan_added_empty` describes a situation when reimport did not affect the existing test (no finding has been created or closed). - -## Event HTTP header for scan_added -```yaml -X-DefectDojo-Event: scan_added -``` - -## Event HTTP header for scan_added_empty -```yaml -X-DefectDojo-Event: scan_added_empty -``` - -## Event HTTP body -```json -{ - "description": "", - "title": "", - "engagement": { - "id": 7, - "name": "notif eng", - "url_api": "http://localhost:8080/api/v2/engagements/7/", - "url_ui": "http://localhost:8080/engagement/7" - }, - "finding_count": 4, - "findings": { - "mitigated": [ - { - "id": 233, - "severity": "Medium", - "title": "Mitigated Finding", - "url_api": "http://localhost:8080/api/v2/findings/233/", - "url_ui": "http://localhost:8080/finding/233" - } - ], - "new": [ - { - "id": 232, - "severity": "Critical", - "title": "New Finding", - "url_api": "http://localhost:8080/api/v2/findings/232/", - "url_ui": "http://localhost:8080/finding/232" - } - ], - "reactivated": [ - { - "id": 234, - "severity": "Low", - "title": "Reactivated Finding", - "url_api": "http://localhost:8080/api/v2/findings/234/", - "url_ui": "http://localhost:8080/finding/234" - } - ], - "untouched": [ - { - "id": 235, - "severity": "Info", - "title": "Untouched Finding", - "url_api": "http://localhost:8080/api/v2/findings/235/", - "url_ui": "http://localhost:8080/finding/235" - } - ] - }, - "product": { - "id": 4, - "name": "notif prod", - "url_api": "http://localhost:8080/api/v2/products/4/", - "url_ui": "http://localhost:8080/product/4" - }, - "product_type": { - "id": 4, - "name": "notif prod type", - "url_api": "http://localhost:8080/api/v2/product_types/4/", - "url_ui": "http://localhost:8080/product/type/4" - }, - "test": { - "id": 90, - "title": "notif test", - "url_api": "http://localhost:8080/api/v2/tests/90/", - "url_ui": "http://localhost:8080/test/90" - }, - "url_api": "http://localhost:8080/api/v2/tests/90/", - "url_ui": "http://localhost:8080/test/90", - "user": { - "id": 1, - "email": "admin@defectdojo.local", - "first_name": "Admin", - "last_name": "User", - "username": "admin", - "url_api": "http://localhost:8080/api/v2/users/1/", - "url_ui": "http://localhost:8080/user/1" - } -} -``` diff --git a/docs/content/open_source/notification_webhooks/test_added.md b/docs/content/open_source/notification_webhooks/test_added.md deleted file mode 100644 index dba53ff5cda..00000000000 --- a/docs/content/open_source/notification_webhooks/test_added.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Event: test_added" -weight: 5 -chapter: true -exclude_search: true -aliases: - - /en/open_source/notification_webhooks/test_added ---- -## Event HTTP header -```yaml -X-DefectDojo-Event: test_added -``` - -## Event HTTP body -```json -{ - "description": "", - "title": "", - "engagement": { - "id": 7, - "name": "notif eng", - "url_api": "http://localhost:8080/api/v2/engagements/7/", - "url_ui": "http://localhost:8080/engagement/7" - }, - "product": { - "id": 4, - "name": "notif prod", - "url_api": "http://localhost:8080/api/v2/products/4/", - "url_ui": "http://localhost:8080/product/4" - }, - "product_type": { - "id": 4, - "name": "notif prod type", - "url_api": "http://localhost:8080/api/v2/product_types/4/", - "url_ui": "http://localhost:8080/product/type/4" - }, - "test": { - "id": 90, - "title": "notif test", - "url_api": "http://localhost:8080/api/v2/tests/90/", - "url_ui": "http://localhost:8080/test/90" - }, - "url_api": "http://localhost:8080/api/v2/tests/90/", - "url_ui": "http://localhost:8080/test/90", - "user": { - "id": 1, - "email": "admin@defectdojo.local", - "first_name": "Admin", - "last_name": "User", - "username": "admin", - "url_api": "http://localhost:8080/api/v2/users/1/", - "url_ui": "http://localhost:8080/user/1" - } -} -``` diff --git a/docs/content/open_source/notification_webhooks/transition-state b/docs/content/open_source/notification_webhooks/transition-state deleted file mode 100644 index 2d27360bbf6..00000000000 --- a/docs/content/open_source/notification_webhooks/transition-state +++ /dev/null @@ -1,24 +0,0 @@ -```kroki {type=mermaid} -flowchart TD - - START{{Endpoint created}} - ALL{All states} - STATUS_ACTIVE([STATUS_ACTIVE]) - STATUS_INACTIVE_TMP - STATUS_INACTIVE_PERMANENT - STATUS_ACTIVE_TMP([STATUS_ACTIVE_TMP]) - END{{Endpoint removed}} - - START ==> STATUS_ACTIVE - STATUS_ACTIVE --HTTP 200 or 201 --> STATUS_ACTIVE - STATUS_ACTIVE --HTTP 5xx
or HTTP 429
or Timeout--> STATUS_INACTIVE_TMP - STATUS_ACTIVE --Any HTTP 4xx response
or any other HTTP response
or non-HTTP error--> STATUS_INACTIVE_PERMANENT - STATUS_INACTIVE_TMP -.After 60s.-> STATUS_ACTIVE_TMP - STATUS_ACTIVE_TMP --HTTP 5xx
or HTTP 429
or Timeout
within 24h
from the first error-->STATUS_INACTIVE_TMP - STATUS_ACTIVE_TMP -.After 24h.-> STATUS_ACTIVE - STATUS_ACTIVE_TMP --HTTP 200 or 201 --> STATUS_ACTIVE_TMP - STATUS_ACTIVE_TMP --HTTP 5xx
or HTTP 429
or Timeout
within 24h from the first error
or any other HTTP response or error--> STATUS_INACTIVE_PERMANENT - ALL ==Activation by user==> STATUS_ACTIVE - ALL ==Deactivation by user==> STATUS_INACTIVE_PERMANENT - ALL ==Removal of endpoint by user==> END -``` \ No newline at end of file diff --git a/docs/content/open_source/rate_limiting.md b/docs/content/open_source/rate_limiting.md deleted file mode 100644 index bbd9285a9ec..00000000000 --- a/docs/content/open_source/rate_limiting.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Rate Limiting (Open-Source)" -description: "Configurable rate limiting on the login page to mitigate brute force attacks" -draft: false -weight: 11 -aliases: - - /en/open_source/rate_limiting ---- -DefectDojo has protection against brute force attacks through rate limiting. - -## Configuration - -For further information, please visit the package documentation [Django Ratelimit](https://django-ratelimit.readthedocs.io/en/stable/index.html) - -#### Enable Rate Limiting - -To enable and configure rate limiting, edit the settings (see [Configuration](../../get_started/open_source/configuration) and edit/replace the following information: - -{{< highlight python >}} -DD_RATE_LIMITER_ENABLED=(bool, True), -DD_RATE_LIMITER_RATE=(str, '5/m'), -DD_RATE_LIMITER_BLOCK=(bool, True), -DD_RATE_LIMITER_ACCOUNT_LOCKOUT=(bool, True), -{{< /highlight >}} - -#### Rate Limit - -The frequency at which the request will be limited can be set to - -* seconds - `1s` -* minutes - `5m` -* hours - `100h` -* days - `2400d` - -Extended configuration can be found [here](https://django-ratelimit.readthedocs.io/en/stable/rates.html) - -#### Block Requests - -By default, rate limiting is set to record offenses, but does not actually block requests and enforce the limit. - -Setting `DD_RATE_LIMITER_BLOCK` will block all incoming requests at the configured frequncy once that frequency has been exceeded. - -#### Account Lockout - -In the event of a brute force attack, a users credentials could potentially be comprimised. - -In an attempt to circumvent that event, setting `DD_RATE_LIMITER_ACCOUNT_LOCKOUT` will force a user to reset their password upon the next attempted login. - -#### Multi-Process Behavior - -When using configurations with multiple uwsgi processes, the rate limiting package uses the default cache that is memory based and local to a process. - -#### Extra Configuation - -For further information, please visit the package documentation [Django Ratelimit](https://django-ratelimit.readthedocs.io/en/stable/index.html) diff --git a/docs/content/releases/os_upgrading/2.2.md b/docs/content/releases/os_upgrading/2.2.md index f7b1a9ea3c8..04125b04b5a 100644 --- a/docs/content/releases/os_upgrading/2.2.md +++ b/docs/content/releases/os_upgrading/2.2.md @@ -8,5 +8,5 @@ exclude_search: true 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.](/open_source/upgrading/2.0/#endpoints). +"Endpoint migration" as it is written in [Upgrading to DefectDojo Version 2.0.x.](/releases/os_upgrading/2.0/#endpoints). diff --git a/docs/content/releases/os_upgrading/2.52.md b/docs/content/releases/os_upgrading/2.52.md index 18aa85e15be..8ed5e6f3c9e 100644 --- a/docs/content/releases/os_upgrading/2.52.md +++ b/docs/content/releases/os_upgrading/2.52.md @@ -48,7 +48,7 @@ If you want to be 110% sure no tasks will be lost you could perform the upgrade `docker compose down` -4) Continue the upgrade as normal per the [upgrade guide](upgrading_guide) +4) Continue the upgrade as normal per the [upgrade guide](/releases/os_upgrading/upgrading_guide/) `docker compose pull` `docker compose up -d` diff --git a/docs/content/releases/pro/changelog.md b/docs/content/releases/pro/changelog.md index 65b23a303ab..7345d2eace2 100644 --- a/docs/content/releases/pro/changelog.md +++ b/docs/content/releases/pro/changelog.md @@ -8,7 +8,7 @@ aliases: Here are the release notes for **DefectDojo Pro (Cloud Version)**. These release notes are focused on UX, so will not include all code changes. -For Open Source release notes, please see the [Releases page on GitHub](https://github.com/DefectDojo/django-DefectDojo/releases), or alternatively consult the Open Source [upgrade notes](/changelog/os_upgrading/upgrading_guide/). +For Open Source release notes, please see the [Releases page on GitHub](https://github.com/DefectDojo/django-DefectDojo/releases), or alternatively consult the Open Source [upgrade notes](/releases/os_upgrading/upgrading_guide/). ## Feb 2026: v2.55 @@ -633,7 +633,7 @@ configuration fields. - **(API)** It is now possible to prefetch a Finding with attached files via API. - **(Login)** A new "Forgot Username" link has been added to the login form. The link will navigate to a page which requests the user's email address. The username will be sent to that address if it exists. - **Risk Acceptances** Notes are now added to Findings when they are removed from Risk Acceptances. -- **(Risk Acceptance)** Risk Acceptance overhaul. Feature has been extended with new functions. See [Risk Acceptance documentation](/triage_findings/findings_workflows/risk_acceptances/) for more details. +- **(Risk Acceptance)** Risk Acceptance overhaul. Feature has been extended with new functions. See [Risk Acceptance documentation](/triage_findings/findings_workflows/pro__risk_acceptance/) for more details. - **Tools** Qualys HackerGuardian parser added. - **Tools** Semgrep Parser updated with new severity mappings. HackerOne parser updated and now supports bug bounty reports. - **Tools** fixed an issue where certain tools would not process asyncronously: Whitehat_Sentinel, SSLyze, SSLscan, Qualys_Webapp, Mend, Intsights, H1, and Blackduck. diff --git a/docs/content/triage_findings/findings_workflows/add_files.md b/docs/content/triage_findings/findings_workflows/add_files.md new file mode 100644 index 00000000000..dd39e38e2c1 --- /dev/null +++ b/docs/content/triage_findings/findings_workflows/add_files.md @@ -0,0 +1,24 @@ +--- +title: "Attaching Files to Findings" +audience: opensource +description: "Upload images or other files to a Finding for additional context" +weight: 3 +--- + +You can attach image files to any Finding to provide visual context — for example, a screenshot of a vulnerability in action or a proof-of-concept image. + +## Supported File Types + +The following image formats are supported: + +- `.png` +- `.jpeg` / `.jpg` +- `.gif` + +## How to Attach a File + +1. Open the Finding you want to attach a file to. +2. Click **Manage Files** within the Finding detail view. +3. In the file management view, select the file you want to upload and confirm. + +The attached image will then be visible within the Finding. diff --git a/docs/content/triage_findings/findings_workflows/exporting.md b/docs/content/triage_findings/findings_workflows/exporting.md new file mode 100644 index 00000000000..dabd779d940 --- /dev/null +++ b/docs/content/triage_findings/findings_workflows/exporting.md @@ -0,0 +1,18 @@ +--- +title: "Export Findings" +description: "Export findings and engagements as CSV or Excel" +weight: 4 +audience: opensource +aliases: + - /en/open_source/exporting +--- + +Pages that show a list of findings or a list of engagements have a CSV and Excel export option in the top-right dropdown menu. + +## Exporting Findings + +From any findings list page, open the dropdown menu in the top-right corner to export the visible findings as a CSV or Excel file. + +## Exporting Engagements + +The list of engagements can also be exported as CSV or Excel using the same dropdown menu on the engagements list page. diff --git a/docs/content/triage_findings/findings_workflows/finding_status_definitions.md b/docs/content/triage_findings/findings_workflows/finding_status_definitions.md index bd05a5b645d..ffe86b3ff62 100644 --- a/docs/content/triage_findings/findings_workflows/finding_status_definitions.md +++ b/docs/content/triage_findings/findings_workflows/finding_status_definitions.md @@ -72,7 +72,7 @@ Findings cannot always be remediated or addressed for various reasons. You can a Risk Acceptances have expiry dates, at which time you can reevaluate the impact of the Finding and decide what to do next. -For more information on Risk Acceptances, see our [Guide](../risk_acceptances). +For more information on Risk Acceptances, see our [Guide](/triage_findings/findings_workflows/os__risk_acceptance/). ### **Out Of Scope**