Last month we hosted a training webinar with our CTO and Co-Founder, Matt Tesauro, covering one of the key decisions you'll make when standing up the platform: how to structure your Asset Hierarchy.

This post distills that session into a practical getting-started guide. If you're new to DefectDojo or just moved to v3, this is the foundation everything else sits on.

The DefectDojo data model, in one line

At its heart, DefectDojo organizes security work like this:

Organization → Asset → Engagement → Test → Finding → Location

Organizations have Assets. Assets have Engagements, which represent testing activity like a scan or a manual pen test. Engagements contain Tests, and Tests produce Findings. New in DefectDojo v3, Locations record where a Finding was found.

If you've used DefectDojo for a while, this is a relabeling of the model you already know. The original structure was Product Type → Product → Engagement → Test → Finding, with Findings connected to Endpoints. Users kept telling us the same thing: "We don't have products, we have repos." At the end of the day, everything you test is an asset, so we’ve updated the naming convention to reflect that. Product Types are Organizations, Products are Assets, and Endpoints have been rebuilt as Locations, a broader concept that can represent the many different places a finding can live rather than forcing everything into a URL-shaped box.

Less cognitive load, same flexible engine underneath.

Why a hierarchy at all?

Software has not gotten simpler. The single monolith that did everything is mostly gone, replaced by microservices, monorepos that bundle five or six things into one repository, multiple environments, and shared infrastructure that four different application stacks depend on.

In order to get the most out of DefectDojo, it's important to understand the functionality and metadata associated with each level. The Asset Hierarchy, available in DefectDojo Pro, lets you establish parent and child relationships between Assets with a graphical view of the structure. You can nest arbitrarily deep (with sensible guardrails), and the structure was performance-tested against hierarchies thousands of levels deep, far beyond anything you'd build in practice.

The key design principle: every Asset in a hierarchy behaves exactly like a standalone Asset. Deduplication, role-based access control (RBAC), engagements, and findings all work the same at every level. The hierarchy simply adds relationships on top, and those relationships unlock better reporting, cleaner access control, and a structure that matches how your business actually thinks.

Bridging the marketing reality and the engineering reality

Every tech company has two vocabularies. The business talks about the product it sells: "the robot." Engineering talks about the cogs and gears: repos, containers, services. As an AppSec team, you have to secure all of it and, just as importantly, report on all of it.

A hierarchy reconciles the two. The parent Asset is the thing the business talks about. The children are the repos, containers, and services engineering ships. Now you can tell your leadership the robot looks good from a security perspective, and tell your engineers that one specific cog needs attention, from the same data.

Using the hierarchy for teams, organizations, and RBAC

The configuration of teams and organizations in DefectDojo is where the hierarchy earns its keep. Some patterns we see most often with customers:

Team-based structure. Create an Organization per team (payments, platform, and so on), then Assets for what each team owns. If the auth gateway has both a repo and a container, make the container a child Asset of the auth gateway. RBAC boundaries practically write themselves: give a VP read-only access to their team's Organization and they can see everything their charges are doing, and nothing else.

Tech-domain structure. Some organizations group by technology stream instead: an Organization for the web app group, another for infrastructure, mobile, or the data platform, with Assets underneath for each repo or service that group produces. Reporting and RBAC flow just as naturally.

Third-party pen testers. This one is a favorite. Create a child Asset that represents the pen tester's engagement, and grant the tester access to only that Asset. They can upload results but can't see anything else in your vulnerability management system. When it's time to report, you combine the parent and the pen test child into one reporting unit.

Because RBAC in DefectDojo works through groups, you can grant access to a parent and all of its children, or to a single child Asset, and global roles like global reader still apply across the whole tree. The hierarchy effectively gives you an additional security boundary to work with.

Design decisions to make before you build

Matt's biggest piece of advice: plan before you start. DefectDojo is famously flexible, and you can restructure a hierarchy at any time (move an Asset to a new parent, remove a relationship, even move it to a different Organization). But a little forethought avoids painting yourself into corners. Four things to think through:

1. Reporting granularity. If you know a VP is going to ask you about a specific slice of the portfolio, make sure that slice is easy to report on. A hierarchy designed around your reporting needs turns those requests into a couple of clicks.

2. Deduplication scope. Deduplication in DefectDojo applies within a single Asset. That makes Asset boundaries a deliberate choice. One customer wanted a single representation of each finding across all branches of a repo, so they used one Asset with an Engagement per branch. Another wanted to know that main, feature one, and feature two each independently contained a finding, so they made each branch its own Asset. Both are correct. It depends entirely on where you want deduplication to happen.

3. RBAC requirements. Who logs into Dojo? What do they need to see, and what should they never see? If the AppSec team are the only users, RBAC matters less. If dev teams and VPs log in, it becomes crucial, and your hierarchy should reflect those access boundaries.

4. Future-proofing without over-engineering. You can build a hierarchy so elaborate that you can report on anything, and in doing so make everyday reporting painful. If summing up "what does this repo look like" requires aggregating a dozen micro-Assets, you've gone too far. Keep it as simple as your real questions allow.

One more pattern worth knowing: short-lived Assets are completely fine. Some customers create an Asset per feature branch, then delete it once the branch merges. Dojo doesn't mind. If you need history for auditing, keep it. That's your policy call, not a platform constraint.

Let an LLM draft your hierarchy

Because everything in DefectDojo is API-driven, you can bring AI into the setup process. The approach Matt described, which the team has tested with consistent results across Claude and Gemini:

Write a markdown file describing your application environment, team structure, scanning tools, reporting stakeholders, SLA requirements, and how you handle branches.
Feed it to your LLM of choice and ask it to lay out a DefectDojo Asset Hierarchy.
Validate the output against reality. Does the deduplication scope make sense? Can you build the RBAC you need? Can you produce that VP report in a couple of clicks? Is it maintainable?

LLMs can make mistakes or miss context you didn't give them, so treat the output as a strong first draft, not a final answer. But for large or complicated environments, this removes a lot of drudgery. We've written more on this approach and included a sample prompt in our post on using AI tools to map your asset hierarchy.

When you're ready to implement: create your Organizations first, then parent Assets, then children. Set up RBAC groups for the pieces of the hierarchy people need access to, create Engagements for importing, wire up your CI/CD, and start rolling.

Using Community Edition? Tags get you there

The Asset Hierarchy is a DefectDojo Pro feature, but the underlying idea works in Community Edition too, using tags. Matt used this approach himself for years before the hierarchy existed.

Create a tagging convention with multiple values separated by colons, like BA:service:location. Then use the "tag contains" filter to slice your flat Asset list any way you need: BA: returns everything in Big App, BA:service: returns just the services. You lose the graphical view and the formal parent-child relationships, but the organizational logic, and the reporting slices it enables, are absolutely achievable. The main cost is discipline: your whole team has to follow the convention.

Seeing it pay off in reporting

Once your hierarchy exists, DefectDojo Pro's Insights dashboards and Pro Reporting understand it natively. Filter any dashboard by a parent Asset and include its children, and you get an automatic roll-up of the entire subtree. Want to compare versions of a product against each other, or check how one repo is trending against the other four that make up the same application? Select just those Assets and apply filters. You can cut and slice any section of the hierarchy, which turns stakeholder questions from an afternoon of spreadsheet work into a filter change.

Key takeaways

The data model matters. It drives reporting, RBAC, and deduplication behavior.
Plan before you start. Dojo is flexible enough to fix mistakes later, but a little pre-planning avoids rework.
Decide where you care about deduplication. That decision defines your Asset boundaries.
The hierarchy is a security boundary. Use it to give every stakeholder exactly the access they need and nothing more.
There is no single right answer. No two AppSec teams are structured the same, and DefectDojo is deliberately flexible for that reason.

The full documentation on the Asset Hierarchy covers every configuration option in detail. And if you'd like to see the hierarchy in action or talk through how to model your environment, reach out to us in the community slack.

Categories

By Author

Getting Started with Setting U...