Asset Hierarchy: Overview | DefectDojo Documentation

Asset Hierarchy: Overview (Open Source)

DefectDojo uses five main data classes to organize your work: Organizations, Assets, Engagements, Tests, and Findings.

DefectDojo is made to be flexible to conform to your team, rather than making your team conform to the tool. You’ll be able to design a robust, adaptable workspace once you understand how these data classes can be used to organize your work.

Asset Hierarchy Diagram

Organizations

The first category of data you’ll need to set up in DefectDojo is an Organization. Organizations are intended to categorize Assets in a specific way. This could be:

Assets are grouped and nested underneath their Organization.

Organizations can have Role-Based Access Control rules applied, which limit team members’ ability to view and interact with their data (including any underlying Assets with Engagement, Test and Finding data). For more information on user roles, see our Introduction To Roles article.

What can an Organization represent?

Assets

An Asset in DefectDojo is intended to represent any project, program, or application that you are currently testing. The Asset hosts all of the security work and testing history related to the underlying goal.

Assets can be as broad or as specific in scope as you wish. By default, Assets are completely separate objects in the hierarchy, but they can be grouped together by Organization.

Assets are ‘walled-off’ and do not interact with other Assets. DefectDojo’s Smart Features, such as Deduplication, only apply within the context of a single Asset.

Like Organizations, Assets can have Role-Based Access Control rules applied, which limit team members’ ability to view and interact with them (as well as any underlying Engagement, Test and Finding data). For more information on user roles, see our Introduction To Roles article.

What can an Asset represent?

DefectDojo’s concept of an ‘Asset’ will not necessarily correspond 1:1 to what your organization would refer to as a ‘Product’. Software development is complex, and security needs can vary greatly even within the scope of a single piece of software.

The following scenarios are good reasons to consider creating a separate DefectDojo Asset:

These variations within a single Asset can also be handled at the Engagement level. Note that Engagements don’t have access control in the way Assets and Organizations do.

Engagements

Once an Asset is set up, you can begin creating and scheduling Engagements. Engagements are meant to represent moments in time when testing is taking place, and contain one or more Tests.

Engagements always have:

There are two types of Engagement: Interactive and CI/CD.

Engagements can be tracked using DefectDojo’s Calendar view.

What can an Engagement represent?

Engagements are meant to represent groups of related testing efforts. How you wish to group your testing efforts depends on your approach.

If you have a planned testing effort scheduled, an Engagement offers you a place to store all of the related results. Here’s an example of this kind of Engagement:

Engagement: ExampleSoftware 1.5.2 - Interactive Testing Effort

In this example, a security team runs multiple tests on the same day as part of a software release.

You can also organize CI/CD Test results within an Engagement. These kinds of Engagements are ‘Open-Ended’ meaning that they don’t have a date, and will instead add additional data each time the associated CI/CD actions are run.

Engagement: ExampleSoftware CI/CD Testing

In this example, multiple CI/CD scans are automatically imported as Tests every time a new software release is created.

Engagements can be organized however works best for your team. All Engagements nested under an Asset can be viewed by the team assigned to work on the Asset.

Tests

Tests are a grouping of activities conducted by engineers to attempt to discover flaws in an Asset.

Tests always have:

Tests can be created in different ways. Tests can be automatically created when scan data is imported directly into an Engagement, resulting in a new Test containing the scan data. Tests can also be created in anticipation of planning future engagements, or for manually entered security findings requiring tracking and remediation.

Test Types

DefectDojo supports two categories of Test Types:

  1. Parser-based Test Types: These correspond to specific security scanners that produce output in formats like XML, JSON, or CSV. When importing scan results, DefectDojo uses specialized parsers to convert the scanner output into Findings.
  2. Non-parser Test Types: These are used for manually created Findings not imported from scan files. These Test Types use the Generic Findings Import method to render Findings and metadata.

The following Test Types appear in the “Scan Type” dropdown when creating a new test.

Non-parser Test Types should be used when you need to manually create findings that require remediation but don’t originate from automated scanner output.

Parser-based Test Types

Parser-based test types can be categorized by how their test type name is determined:

Examples include:

Report-Defined Test Type Naming Rules:

Important Considerations:

How do Tests interact with each other?

Tests take your testing data and group it into Findings. Generally, security teams will be running the same testing effort repeatedly, and Tests in DefectDojo allow you to handle this process in an elegant way.

Previously imported tests can be reimported - If you’re running the same type of test within the same Engagement context, you can Reimport the test results after each completed scan. DefectDojo will compare the Reimported data to the existing result, and will not create new Findings if duplicates exist in the scan data.

Tests can be imported separately - If you run the same test on an Asset within separate Engagements, DefectDojo will still compare the data with previous Tests to find duplicate Findings. This allows you to keep track of previously mitigated or risk-accepted Findings.

If a Test is added directly to an Asset without an Engagement, a generic Engagement will be created automatically to contain the Test. This allows for ad-hoc data imports.

Examples of Tests:

Findings

Once data has been added uploaded to a Test, the results of that data will be listed in the Test as individual Findings for review.

A finding represents a specific flaw discovered while testing.

Findings always have:

Findings can be added through a data import, but they can also be added manually to a Test.

Examples of Findings:

Endpoints

Scan data generally will contain references to the hosts or endpoints affected by a given Finding. DefectDojo automatically aggregates Findings per-endpoint, so you can use the Endpoint view to look at all Findings that affect a given Endpoint or Hostname.

Examples: