Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
docs: restore eight markdown links mangled into NUL bytes #15756
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: dev
Are you sure you want to change the base?
Uh oh!
There was an error while loading. Please reload this page.
docs: restore eight markdown links mangled into NUL bytes #15756
Changes from all commits
bdb5534d0bc247File filter
Filter by extension
Conversations
Uh oh!
There was an error while loading. Please reload this page.
Jump to
Uh oh!
There was an error while loading. Please reload this page.
There are no files selected for viewing
<div class="version-opensource">  </div> <div class="version-pro">  </div> <span style="background-color:rgba(242, 86, 29, 0.3)">DefectDojo, Inc. and open-source contributors maintain this documentation to support both the Community and Pro editions of DefectDojo.</span> ## What is DefectDojo? DefectDojo is a Developer Security Operations (DevSecOps) platform. DefectDojo streamlines DevSecOps by serving as an automatic aggregator for your suite of security tools, allowing you to easily organize your security work and report your organization’s security posture to other stakeholders. While security process automation and integrated development pipelines are the end goals of DefectDojo, at its core this software is a bug tracker for security vulnerabilities, which is meant to ingest, organize and standardize reports from many security tools. ### What does DefectDojo do? DefectDojo has smart features to enhance and tune the results from your security tools, including the ability to: - Track and report on security Findings in context - Enforce SLAs in context - Handle False Positives, Risk Acceptances and other triage decisions - Distill duplicates using DefectDojo's deduplication algorithm - Integrate with external Project Tracking software. - Provide metrics/reports across repositories and development branches using CI/CD integration. - Coordinate traditional Pen test management. - Set and enforce SLAs for vulnerability remediation procedures. - Create and track Risk Acceptances for security vulnerabilities. Ultimately, DefectDojo's Asset:Engagement model allows you to take inventory of your development environment and immediately place new security Findings in context. --- Here are some examples of ways DefectDojo can be implemented, with DefectDojo co-founder and CTO Matt Tesauro: <iframe width="560" height="315" src="DefectDojo, Inc. and open-source contributors maintain this documentation to support both the Community and Pro editions of DefectDojo.
What is DefectDojo?
DefectDojo is a Developer Security Operations (DevSecOps) platform. DefectDojo streamlines DevSecOps by serving as an automatic aggregator for your suite of security tools, allowing you to easily organize your security work and report your organization’s security posture to other stakeholders.
While security process automation and integrated development pipelines are the end goals of DefectDojo, at its core this software is a bug tracker for security vulnerabilities, which is meant to ingest, organize and standardize reports from many security tools.
What does DefectDojo do?
DefectDojo has smart features to enhance and tune the results from your security tools, including the ability to:
Ultimately, DefectDojo's Asset:Engagement model allows you to take inventory of your development environment and immediately place new security Findings in context.
Here are some examples of ways DefectDojo can be implemented, with DefectDojo co-founder and CTO Matt Tesauro:
<iframe width="560" height="315" src="" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> --- ## DefectDojo Open-Source DefectDojo's core functionality is available in DefectDojo Open-Source. This edition of DefectDojo includes: - Import/Reimport for all 500+ Supported Tools - REST API - Deduplication features - Limited UI, metrics and reporting features - Jira integration capability For teams managing a smaller volume of Findings, DefectDojo Open-Source is a great starting point. ### Installation Guides There are a few supported ways to install DefectDojo’s Open-Source edition ([available on Github](https://github.com/DefectDojo/django-DefectDojo)): [Docker Compose](https://github.com/DefectDojo/django-DefectDojo/blob/master/readme-docs/DOCKER.md) is the easiest method to install the core program and services required to run DefectDojo. Our [Architecture](/get_started/open_source/architecture/) guide gives you an overview of each service and component used by DefectDojo. [Running In Production](/get_started/open_source/running-in-production/) lists system requirements, performance tweaks and maintenance processes for running DefectDojo on a production server (with Docker Compose). Kubernetes is not fully supported at the Open-Source level, but this guide can be referenced and used as a starting point to integrate DefectDojo into Kubernetes architecture. If you run into trouble with an Open-Source install, we highly recommend asking questions on the [OWASP Slack](https://owasp.org/slack/invite). Our community members are active on the #defectdojo channel and can help you with issues you’re facing. ## 🟧 DefectDojo Pro Edition <iframe width="560" height="315" src="" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>DefectDojo Open-Source
DefectDojo's core functionality is available in DefectDojo Open-Source.
This edition of DefectDojo includes:
For teams managing a smaller volume of Findings, DefectDojo Open-Source is a great starting point.
Installation Guides
There are a few supported ways to install DefectDojo’s Open-Source edition (available on Github):
Docker Compose is the easiest method to install the core program and services required to run DefectDojo. Our Architecture guide gives you an overview of each service and component used by DefectDojo. Running In Production lists system requirements, performance tweaks and maintenance processes for running DefectDojo on a production server (with Docker Compose).
Kubernetes is not fully supported at the Open-Source level, but this guide can be referenced and used as a starting point to integrate DefectDojo into Kubernetes architecture.
If you run into trouble with an Open-Source install, we highly recommend asking questions on the OWASP Slack. Our community members are active on the #defectdojo channel and can help you with issues you’re facing.
🟧 DefectDojo Pro Edition
<iframe width="560" height="315" src="" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> DefectDojo, Inc. hosts a Pro edition of this software for commercial purposes. Along with a sleek, modern UI, DefectDojo Pro includes: * [Connectors](/connectors/upstream/about/): out-of-the-box API integrations with enterprise-level scanners (such as Checkmarx One, BurpSuite, Semgrep and more) * **Configurable Import Methods**: [Universal Parser](/supported_tools/parsers/universal_parser/), [Smart Upload](/import_data/pro/specialized_import/smart_upload/) * **[CLI Tools](/import_data/pro/specialized_import/external_tools/)** for rapid integration with your systems * **[Additional Project Tracking Integrations](/connectors/issue_tracking/)**: ServiceNow, Azure DevOps, GitHub and GitLab * **[Improved Metrics](/metrics_reports/pro_metrics/pro__overview/)** for executive reporting and high-level analysis * **[Priority And Risk](/asset_modelling/pro_hierarchy/priority_sla/)** to identify the Findings of highest urgency, system-wide * **Premium Support** and implementation guidance for your organization The Pro edition is available as a cloud-hosted SaaS offering, and is also available for installation on-premises. For more information on DefectDojo Pro, check out our [Pricing page](https://defectdojo.com/pricing). ## Online Demos Online demos for both Open-Source and Pro versions of DefectDojo are available. Both can be accessed using the following credentials: - Username: `admin` - Password: `1Defectdojo@demo#appsec` These demos come loaded with sample data, and are reset on a daily basis. ### Open-Source Demo A running example of DefectDojo (Open-Source Edition) is available at [https://demo.defectdojo.org/18. ### Pro Demo A running example of DefectDojo Pro is available at [https://pro.demo.defectdojo.com/19. ## Learning DefectDojo Whether you’re a Pro or an Open-Source user, we have many resources to help you get started with DefectDojo. * Review our supported [security tool integrations](/supported_tools/) to help fit DefectDojo in your DevSecOps program. * Our team maintains a [YouTube Channel](https://www.youtube.com/@defectdojo) which hosts tutorials, archived Office Hours events, and other content. ## Connect With Us To get in touch with the DefectDojo, Inc. team, you can always reach out to [hello@defectdojo.com](mailto:hello@defectdojo.com). We regularly on [LinkedIn](https://www.linkedin.com/company/33245534) and also host online presentations for AppSec professionals that can be accessed live or on demand. You can learn about upcoming events on our [Events page](https://defectdojo.com/events) or watch past presentations on our [YouTube Channel](https://www.youtube.com/@defectdojo). ### Stickers Looking for cool DefectDojo laptop stickers? As a thank you for being a part of the DefectDojo community, you can sign up to get some free DefectDojo stickers. For more information, check out [this link](https://defectdojo.com/defectdojo-sticker-request)." title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>DefectDojo, Inc. hosts a Pro edition of this software for commercial purposes. Along with a sleek, modern UI, DefectDojo Pro includes:
The Pro edition is available as a cloud-hosted SaaS offering, and is also available for installation on-premises.
For more information on DefectDojo Pro, check out our Pricing page.
Online Demos
Online demos for both Open-Source and Pro versions of DefectDojo are available. Both can be accessed using the following credentials:
admin1Defectdojo@demo#appsecThese demos come loaded with sample data, and are reset on a daily basis.
Open-Source Demo
A running example of DefectDojo (Open-Source Edition) is available at https://demo.defectdojo.org/.
Pro Demo
A running example of DefectDojo Pro is available at https://pro.demo.defectdojo.com/.
Learning DefectDojo
Whether you’re a Pro or an Open-Source user, we have many resources to help you get started with DefectDojo.
Connect With Us
To get in touch with the DefectDojo, Inc. team, you can always reach out to hello@defectdojo.com.
We regularly on LinkedIn and also host online presentations for AppSec professionals that can be accessed live or on demand. You can learn about upcoming events on our Events page or watch past presentations on our YouTube Channel.
Stickers
Looking for cool DefectDojo laptop stickers? As a thank you for being a part of the DefectDojo community, you can sign up to get some free DefectDojo stickers. For more information, check out this link.
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:131317. ## 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. CI runs two checks: the rendered docs site, and any `docs.defectdojo.com` URLs hardcoded into the Django app (templates and settings). Both use a `--remap` so absolute `docs.defectdojo.com` URLs resolve against the freshly built site. To run both locally from the root of the repo: ``` cd docs && rm -rf public/ && hugo --minify --gc --config config/production/hugo.toml && cd .. lychee --offline --no-progress \ --root-dir "$PWD/docs/public" \ --remap "https://docs.defectdojo.comfile://$PWD/docs/public" \ './docs/public/**/*.html' lychee --offline --no-progress \ --root-dir "$PWD/docs/public" \ --remap "https://docs.defectdojo.comfile://$PWD/docs/public" \ --exclude '%7[BD]' \ $(grep -rl 'docs\.defectdojo\.com' dojo/ --include='*.html' --include='*.py' --include='*.tpl') ``` ### Theme overrides We use significant CSS overrides which are detailed in `docs/layouts`.The documentation is built with Hugo and uses a variation of the Doks 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
cd docsand thennpm install.cd docsto switch to the docs folder, and start the Hugo development server by runningnpm run dev. Hot reloading is supported - pages will automatically update with changes while the server is running.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.
http://localhost:1313/sitemap.xml[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. CI runs two checks: the rendered docs site, and any
docs.defectdojo.comURLs hardcoded into the Django app (templates and settings). Both use a--remapso absolutedocs.defectdojo.comURLs resolve against the freshly built site. To run both locally from the root of the repo:Theme overrides
We use significant CSS overrides which are detailed in
docs/layouts.**Availability:** Messaging Connectors are a beta feature. Enable **Messaging Connectors** on the Feature Flags page. Because alerts are routed by rules, **Rules Engine 2.0** must be enabled as well. Messaging Connectors send alerts from DefectDojo to a chat service, to an email address, or to an Amazon SNS topic. They sit beside the ticketing and incident-management connectors on the same **Downstream Connectors** page, and they are configured the same way: create a connection once, then decide what should be sent to it. Ticketing connectors and messaging connectors answer different questions. A ticketing connector creates and updates a ticket that tracks one Finding over time. A messaging connector posts a message about something that just happened, such as an import that brought in new High and Critical Findings. A message has no status to transition and no ticket to keep in sync, so the two are configured separately and neither affects the other. ## What you can send Alerts are routed by Rules Engine 2.0. A rule decides **when** to send (a trigger), **which** Findings qualify (conditions), and **where** the message goes (a notify node addressing your connection and channel). This means the filters available to an alert are the same ones available to a rule: severity, scope, tags, status, and anything else a rule condition can express. Several different alerts going to several different channels are simply several rules. ## The four vendors | Vendor | What you provide | How many destinations per connection | | --- | --- | --- | | Slack | A bot token from a Slack app | Many. Each destination names a channel ID. | | Microsoft Teams | A Power Automate workflow URL | One. The URL decides the channel. | | Email | Nothing. The instance mail server is used. | Many. Each destination names recipients. | | Amazon SNS | An AWS access key allowed to publish | Many. Each destination names a topic ARN. | Each is set up the same way: add the connection under **Connect > Downstream**, then create an alert that addresses it. ## Set up a Slack connection You need a Slack app with a bot token. If your workspace already has one for DefectDojo you can reuse it. ### 1. Create a Slack app 1. Go to [https://api.slack.com/apps22and select **Create New App**, then **From scratch**. 2. Name the app (for example, DefectDojo) and pick the workspace it should post to. 3. Open **OAuth & Permissions** and add these **Bot Token Scopes**: - `chat:write` (required): lets the app post messages. - `chat:write.public` (optional): lets the app post to any public channel without being invited to it first. Without this scope you must invite the bot to each channel you want to use. 4. Select **Install to Workspace** and approve the app. 5. Copy the **Bot User OAuth Token**. It starts with `xoxb-`. ### 2. Add the connection in DefectDojo 1. Go to **Connect > Downstream**. 2. In the **Messaging** section, find the Slack tile and select **Add Configuration**. 3. Enter: - **Location**: your Slack workspace URL, for example `https://your-workspace.slack.com`. This is used for display and links only. - **Identifier**: a label that tells this connection apart from others, for example `Security workspace`. - **Bot Token**: the `xoxb-` token you copied. 4. Save. DefectDojo validates the token against Slack immediately, so an incorrect or revoked token is reported here rather than the first time an alert fires. You can add as many Slack connections as you need. Separate connections are how you reach more than one workspace. ### 3. Find the channel ID Slack destinations take a channel **ID**, not a channel name. 1. In Slack, open the channel and select its name at the top. 2. Scroll to the bottom of the **About** tab. 3. Copy the **Channel ID**. It looks like `C0123456789`. If the app does not have the `chat:write.public` scope, invite it to the channel as well: type `/invite @your-app-name` in the channel. ## Set up a Microsoft Teams connection Teams uses a **Power Automate workflow URL**. Classic Office 365 connectors are retired, and this route needs no app registration and no tenant admin consent: somebody with rights to the channel creates the flow and pastes the URL it returns. **One connection posts to one channel.** The workflow URL decides where the message goes, so a second channel means a second connection rather than a second destination. ### 1. Create the workflow 1. In Teams, open the channel you want to post to, select the **...** menu next to the channel name, then **Workflows**. 2. Choose the **Post to a channel when a webhook request is received** template. 3. Confirm the team and channel, then select **Add workflow**. 4. Copy the URL the workflow gives you. It is a long `https://` address on a Microsoft Power Automate host. Treat this URL as a password. Anyone holding it can post to that channel. ### 2. Add the connection in DefectDojo 1. Go to **Connect > Downstream**. 2. In the **Messaging** section, find the Microsoft Teams tile and select **Add Configuration**. 3. Enter: - **Location**: your Teams or Microsoft 365 URL. This is used for display and links only. - **Instance Label**: a label naming the channel this connection reaches, for example `Security / Alerts`. - **Workflow URL**: the URL you copied. 4. Save. DefectDojo checks the URL's shape on save (it must be `https://` and on a Microsoft workflow host) but does not post to it. A workflow URL has no way to be tested other than sending a message, and a surprise message in a channel on save is worse than finding out later. Use **Send test message** when you are ready. A Teams destination has one optional field, a channel label, which only labels the delivery record. The workflow URL already decides the destination. ## Set up an Email connection Email needs no credential. DefectDojo sends through the mail server this instance already uses for notifications, so there is nothing new to configure and no second place for SMTP to be wrong. 1. Go to **Connect > Downstream**. 2. In the **Messaging** section, find the Email tile and select **Add Configuration**. 3. Enter: - **Location**: the sender identity to display, for example `mailto:defectdojo@example.com`. - **Instance Label**: a label that tells this connection apart from others. 4. Save. Saving fails if this instance has no mail server or no sender address configured, because nothing sent over the connection would leave the building. Configure SMTP under **Settings > System Settings** first. Recipients are set on the alert, not on the connection, so one Email connection serves every alert. An email destination takes up to 50 addresses; past that, use a distribution address. ## Set up an Amazon SNS connection SNS is different in kind from the other three: DefectDojo publishes one message to a topic, and AWS fans it out to whatever is subscribed, which may be email addresses, SMS numbers, a Lambda function, an HTTPS endpoint, or an SQS queue. DefectDojo does not know or care which. ### 1. Create an access key that can publish 1. In the AWS console, create (or pick) an IAM user or role for DefectDojo. 2. Attach a policy allowing `sns:Publish` on the topics you intend to use. Naming the topic ARNs explicitly is better than allowing all of them. 3. Create an access key for it and copy both halves. AWS shows the secret access key once. If the topic is encrypted with a KMS key, the same principal also needs `kms:GenerateDataKey` and `kms:Decrypt` on that key, or every publish is refused. ### 2. Add the connection in DefectDojo 1. Go to **Connect > Downstream**. 2. In the **Messaging** section, find the Amazon SNS tile and select **Add Configuration**. 3. Enter: - **Location**: a URL for display and links only, for example your AWS console URL. - **Instance Label**: a label that tells this connection apart from others, for example `Production AWS account`. - **Access Key ID**: the key ID, which looks like `AKIAIOSFODNN7EXAMPLE`. - **Secret Access Key**: the secret half. 4. Save. DefectDojo checks the credential with AWS immediately, so a wrong or deleted key is reported here rather than the first time an alert fires. That check confirms only that the credential is valid; whether it may publish to a given topic is checked when you set the destination. **There is no region to enter.** The region is part of the topic ARN, so one connection can publish to topics in more than one region, and there is no second setting that can disagree with the ARN. ### 3. Find the topic ARN An SNS destination takes the topic's ARN. 1. In the SNS console, open the topic. 2. Copy the **ARN** from the top of the page. It looks like `arn:aws:sns:us-east-1:123456789012:security-alerts`. Unlike a Teams workflow URL, an ARN is not a secret: it names a topic, and publishing to it requires the credential on the connection. That is why one SNS connection can serve many topics. FIFO topics (an ARN ending in `.fifo`) are not supported. They require a message group and a deduplication ID, which are ordering rules an alert has nothing to supply. Use a standard topic. ## Send a test message Anywhere a messaging destination is configured, **Send test message** delivers a short message through exactly the same path a real alert uses, and reports what the vendor said. Use it to confirm the things that are easy to get wrong: for Slack, that the channel ID is right and the bot can post there; for Teams, that the workflow URL still works; for email, that the address is deliverable; for SNS, that the key may publish to that topic. The vendor's own answer is passed through, so a missing Slack invite reads as a message telling you to invite the bot rather than a generic failure. A successful test also clears a connection that has been automatically disabled (see [When a connection stops working](#when-a-connection-stops-working)). ## Create an alert There are two ways in. Both produce the same thing: a Rules Engine 2.0 rule. ### The alerts page The short route, for the common case of announcing new findings from an import. 1. Go to **Connect > Downstream** and select **Create Alert** on a messaging connection, or open **Messaging Alerts** directly. 2. Select **New Alert** and fill in: - **Name**: what this alert is for, for example `New highs to the security channel`. - **Alert**: what it is about. **New findings from an import** is currently the only option. - **Send over**: the messaging connection. - **Where it delivers**: the vendor's own destination field, so a Slack channel ID, an optional Teams channel label, a list of email addresses, or an SNS topic ARN. - **Severity**: the floor, from **Critical only** through **Every severity**. - **Mode**: **Simulate** records what would have been sent without sending it, **Live** actually sends. 3. Select **Create Alert**. The page lists the alerts it created, with the trigger, the severity floor, and a toggle to enable or disable each one. Start in **Simulate** if you want to see what an alert would have caught before anyone's channel hears about it. The rule runs, the deliveries are recorded, and nothing is sent. Alerts are rules, so they can also be opened in the rule editor from the same list. Once a rule has been edited into something the form cannot express, such as a second branch or a second message, the list offers the rule editor instead of the form, rather than a form that would quietly flatten the extra work. ### The rule editor The full route, for anything the form does not cover. 1. Go to **Automation > Rules Engine 2.0** and create a rule. 2. Add a trigger. For alerts about newly imported Findings, use the Finding event trigger on **created**. Imports are batched, so one import produces one alert rather than one per Finding. 3. Add conditions for what should qualify, for example a minimum severity of High. 4. Add a message node for the vendor you want (**Send a Slack Message**, **Send a Microsoft Teams Message**, **Send an Email**, or **Publish to an SNS Topic**) and set: - **Connection**: the messaging connection you created. - **Destination**: the vendor's destination, so a channel ID for Slack, an optional channel label for Teams, recipients for email, or a topic ARN for SNS. 5. Save the rule and enable it. Nothing is sent when no Findings match the conditions, so a rule filtered to High and above stays quiet on an import that only brought in Low Findings. ### Rules written before Messaging Connectors A message node sends over a connection, and only over a connection. The Slack, Teams, and email nodes previously fell back to the instance-wide settings under **Settings > Notifications** when no connection was chosen. They no longer do. A rule written that way keeps running, and its message node records a skipped delivery saying it names no connection. To fix it, open the rule, choose a connection and a destination on the node, and save. A delivery that was already recorded can be replayed from the deliveries list once the node names a connection. The connection is a required field on every message node, so the rule editor asks for one before the rule can be saved. ## When a connection stops working A revoked bot token, a deleted workflow, or a deleted AWS access key fails every alert it serves. Rather than recording the same failure for every event, DefectDojo counts consecutive credential failures per destination and stops sending after a few of them. The connection reports which destination was disabled and why. To recover: fix the credential (reinstall the Slack app and paste the new token, recreate the Teams workflow and paste the new URL, or create a new AWS access key), then either send a test message to that destination, which re-enables it on success, or use the re-enable action directly. Only credential failures cause this. A message rejected because a Slack channel ID is wrong, the bot is not invited, an email address does not exist, or an IAM policy does not allow publishing to one topic does not disable anything, because the credential is fine and correcting the destination or the policy should work immediately. ## Alerts and notifications together Messaging Connectors do not replace notifications. The instance-wide Slack, Teams, and email settings under **Settings > Notifications**, personal notifications, and the notification matrix all keep working exactly as configured. They are what announces DefectDojo's own events; a Messaging Connector is what a rule you wrote sends over. One thing to watch: if an alert posts to the same channel or address that the instance-wide setting already announces to, that destination receives both messages. Configure one or the other for a given destination. ## Limitations - Message wording is not customizable yet. Alerts use DefectDojo's built-in wording. - Messages are one-way. DefectDojo does not read replies, and there are no buttons or interactive elements in the message. - Threads, message editing, and direct messages to individual users are not supported. Personal notifications continue to use the existing notification system. - One Teams connection reaches one channel, because the workflow URL is what addresses the channel. - SNS messages are plain text. A topic can fan out to email, SMS, Lambda and HTTPS subscribers at once, so there is no single format that suits all of them, and no per-protocol variant is published. - SNS FIFO topics are not supported. - Reports and other attachments cannot be sent yet. Alerts are messages with links back to DefectDojo. - The alerts page covers new findings from an import. Anything else is built in the rule editor.Availability: Messaging Connectors are a beta feature. Enable Messaging Connectors on the Feature Flags page. Because alerts are routed by rules, Rules Engine 2.0 must be enabled as well.
Messaging Connectors send alerts from DefectDojo to a chat service, to an email address, or to an Amazon SNS topic. They sit beside the ticketing and incident-management connectors on the same Downstream Connectors page, and they are configured the same way: create a connection once, then decide what should be sent to it.
Ticketing connectors and messaging connectors answer different questions. A ticketing connector creates and updates a ticket that tracks one Finding over time. A messaging connector posts a message about something that just happened, such as an import that brought in new High and Critical Findings. A message has no status to transition and no ticket to keep in sync, so the two are configured separately and neither affects the other.
What you can send
Alerts are routed by Rules Engine 2.0. A rule decides when to send (a trigger), which Findings qualify (conditions), and where the message goes (a notify node addressing your connection and channel).
This means the filters available to an alert are the same ones available to a rule: severity, scope, tags, status, and anything else a rule condition can express. Several different alerts going to several different channels are simply several rules.
The four vendors
Each is set up the same way: add the connection under Connect > Downstream, then create an alert that addresses it.
Set up a Slack connection
You need a Slack app with a bot token. If your workspace already has one for DefectDojo you can reuse it.
1. Create a Slack app
chat:write(required): lets the app post messages.chat:write.public(optional): lets the app post to any public channel without being invited to it first. Without this scope you must invite the bot to each channel you want to use.xoxb-.2. Add the connection in DefectDojo
https://your-workspace.slack.com. This is used for display and links only.Security workspace.xoxb-token you copied.You can add as many Slack connections as you need. Separate connections are how you reach more than one workspace.
3. Find the channel ID
Slack destinations take a channel ID, not a channel name.
C0123456789.If the app does not have the
chat:write.publicscope, invite it to the channel as well: type/invite @your-app-namein the channel.Set up a Microsoft Teams connection
Teams uses a Power Automate workflow URL. Classic Office 365 connectors are retired, and this route needs no app registration and no tenant admin consent: somebody with rights to the channel creates the flow and pastes the URL it returns.
One connection posts to one channel. The workflow URL decides where the message goes, so a second channel means a second connection rather than a second destination.
1. Create the workflow
https://address on a Microsoft Power Automate host.Treat this URL as a password. Anyone holding it can post to that channel.
2. Add the connection in DefectDojo
Security / Alerts.DefectDojo checks the URL's shape on save (it must be
https://and on a Microsoft workflow host) but does not post to it. A workflow URL has no way to be tested other than sending a message, and a surprise message in a channel on save is worse than finding out later. Use Send test message when you are ready.A Teams destination has one optional field, a channel label, which only labels the delivery record. The workflow URL already decides the destination.
Set up an Email connection
Email needs no credential. DefectDojo sends through the mail server this instance already uses for notifications, so there is nothing new to configure and no second place for SMTP to be wrong.
mailto:defectdojo@example.com.Saving fails if this instance has no mail server or no sender address configured, because nothing sent over the connection would leave the building. Configure SMTP under Settings > System Settings first.
Recipients are set on the alert, not on the connection, so one Email connection serves every alert. An email destination takes up to 50 addresses; past that, use a distribution address.
Set up an Amazon SNS connection
SNS is different in kind from the other three: DefectDojo publishes one message to a topic, and AWS fans it out to whatever is subscribed, which may be email addresses, SMS numbers, a Lambda function, an HTTPS endpoint, or an SQS queue. DefectDojo does not know or care which.
1. Create an access key that can publish
sns:Publishon the topics you intend to use. Naming the topic ARNs explicitly is better than allowing all of them.If the topic is encrypted with a KMS key, the same principal also needs
kms:GenerateDataKeyandkms:Decrypton that key, or every publish is refused.2. Add the connection in DefectDojo
Production AWS account.AKIAIOSFODNN7EXAMPLE.DefectDojo checks the credential with AWS immediately, so a wrong or deleted key is reported here rather than the first time an alert fires. That check confirms only that the credential is valid; whether it may publish to a given topic is checked when you set the destination.
There is no region to enter. The region is part of the topic ARN, so one connection can publish to topics in more than one region, and there is no second setting that can disagree with the ARN.
3. Find the topic ARN
An SNS destination takes the topic's ARN.
arn:aws:sns:us-east-1:123456789012:security-alerts.Unlike a Teams workflow URL, an ARN is not a secret: it names a topic, and publishing to it requires the credential on the connection. That is why one SNS connection can serve many topics.
FIFO topics (an ARN ending in
.fifo) are not supported. They require a message group and a deduplication ID, which are ordering rules an alert has nothing to supply. Use a standard topic.Send a test message
Anywhere a messaging destination is configured, Send test message delivers a short message through exactly the same path a real alert uses, and reports what the vendor said.
Use it to confirm the things that are easy to get wrong: for Slack, that the channel ID is right and the bot can post there; for Teams, that the workflow URL still works; for email, that the address is deliverable; for SNS, that the key may publish to that topic. The vendor's own answer is passed through, so a missing Slack invite reads as a message telling you to invite the bot rather than a generic failure.
A successful test also clears a connection that has been automatically disabled (see When a connection stops working).
Create an alert
There are two ways in. Both produce the same thing: a Rules Engine 2.0 rule.
The alerts page
The short route, for the common case of announcing new findings from an import.
New highs to the security channel.The page lists the alerts it created, with the trigger, the severity floor, and a toggle to enable or disable each one.
Start in Simulate if you want to see what an alert would have caught before anyone's channel hears about it. The rule runs, the deliveries are recorded, and nothing is sent.
Alerts are rules, so they can also be opened in the rule editor from the same list. Once a rule has been edited into something the form cannot express, such as a second branch or a second message, the list offers the rule editor instead of the form, rather than a form that would quietly flatten the extra work.
The rule editor
The full route, for anything the form does not cover.
Nothing is sent when no Findings match the conditions, so a rule filtered to High and above stays quiet on an import that only brought in Low Findings.
Rules written before Messaging Connectors
A message node sends over a connection, and only over a connection. The Slack, Teams, and email nodes previously fell back to the instance-wide settings under Settings > Notifications when no connection was chosen. They no longer do.
A rule written that way keeps running, and its message node records a skipped delivery saying it names no connection. To fix it, open the rule, choose a connection and a destination on the node, and save. A delivery that was already recorded can be replayed from the deliveries list once the node names a connection.
The connection is a required field on every message node, so the rule editor asks for one before the rule can be saved.
When a connection stops working
A revoked bot token, a deleted workflow, or a deleted AWS access key fails every alert it serves. Rather than recording the same failure for every event, DefectDojo counts consecutive credential failures per destination and stops sending after a few of them. The connection reports which destination was disabled and why.
To recover: fix the credential (reinstall the Slack app and paste the new token, recreate the Teams workflow and paste the new URL, or create a new AWS access key), then either send a test message to that destination, which re-enables it on success, or use the re-enable action directly.
Only credential failures cause this. A message rejected because a Slack channel ID is wrong, the bot is not invited, an email address does not exist, or an IAM policy does not allow publishing to one topic does not disable anything, because the credential is fine and correcting the destination or the policy should work immediately.
Alerts and notifications together
Messaging Connectors do not replace notifications. The instance-wide Slack, Teams, and email settings under Settings > Notifications, personal notifications, and the notification matrix all keep working exactly as configured. They are what announces DefectDojo's own events; a Messaging Connector is what a rule you wrote sends over.
One thing to watch: if an alert posts to the same channel or address that the instance-wide setting already announces to, that destination receives both messages. Configure one or the other for a given destination.
Limitations
Uh oh!
There was an error while loading. Please reload this page.