Research Reports

Analyzing DefectDojo

7 min read

Analyzing DefectDojo

Source: DefectDojo/django-DefectDojo (SHA: 8a99ad6, full: 8a99ad6ae9a3e3027074958fd5859921ca5d0412)

How It Works

DefectDojo is an OWASP Flagship project that functions as a unified vulnerability management and Application Security Posture Management (ASPM) platform. At its core, it ingests security scan results from external tools, normalizes them into a common data model, applies deduplication to suppress repeated findings, and provides workflows for triage, remediation tracking, and reporting. The model hierarchy flows top-down: Product Type → Product → Engagement → Test → Finding — each layer representing a finer-grained security assessment context.

The system’s primary value proposition is its parser ecosystem. With over 200 scanner integrations (organized as individual Python packages under dojo/tools/), DefectDojo can consume output from virtually any security tool — SAST, DAST, SCA, cloud scanners, and more. Each parser implements a get_findings() method that returns normalized Finding objects. A factory pattern (dojo/tools/factory.py) registers parsers by scan type name and dispatches to the correct one at import time.

The import pipeline is the spine of the application. When a scan report is uploaded (via UI or REST API), the DefaultImporter or DefaultReImporter (for re-imports into existing tests) orchestrates: parsing, test creation, finding creation, deduplication, endpoint matching, JIRA push, and notification dispatching. Celery handles async tasks — deduplication runs in background tasks via do_dedupe_batch_task, and JIRA integration is fully decoupled through Celery dispatch.

Architecture

The codebase is a single Django app (dojo/) with ~55 top-level subdirectories representing domain modules. It runs as a Docker Compose stack with UWSGI for the web tier, Celery workers for async processing, and PostgreSQL as the database. Redis serves as the Celery broker.

dojo/
├── models.py              # 4,674 lines — ALL model definitions (monolithic)
├── forms.py               # 3,657 lines — ALL Django forms (monolithic)
├── filters.py             # 3,943 lines — ALL filter classes (monolithic)
├── api_v2/
│   ├── serializers.py     # 3,245 lines — ALL DRF serializers
│   └── views.py           # 3,668 lines — ALL API ViewSets
├── tools/                 # 221 entries — scanner parsers
├── importers/             # Import/reimport pipeline
├── finding/               # Finding helper, deduplication logic
├── jira/                  # JIRA integration (services + helper)
├── authorization/         # Role-based access control
├── url/                   # Reference module (fully reorganized)
├── {product,engagement,test,finding,...}/  # Domain modules (partially reorganized)
└── settings/              # Django settings (env-driven)

The REST API is comprehensive — dojo/urls.py registers ~60 ViewSets via DRF’s DefaultRouter, covering every domain entity. Authentication supports API keys, token auth, OAuth2/SAML2, and LDAP. An OpenAPI 3 schema is auto-generated via drf-spectacular.

The Spine

Request lifecycle for scan import (the most critical flow):

  1. Entry: ImportScanView or ReImportScanView (DRF ViewSets in api_v2/views.py) receives the scan file and metadata
  2. Validation: DRF serializers validate the payload, including tool configuration, scan type, and engagement context
  3. Parser selection: factory.get_parser(scan_type) resolves the correct parser from the PARSERS registry
  4. Import orchestration: DefaultImporter (or DefaultReImporter) creates a Test object, runs the parser, and processes each finding
  5. Deduplication: New findings are checked against existing findings using configurable algorithms (hash_code, unique_id, legacy). The dojo/finding/deduplication.py module (1,218 lines) handles this via optimized querysets that only load DEDUPLICATION_FIELDS
  6. Post-processing: Finding helper (dojo/finding/helper.py, 1,323 lines) handles JIRA push, endpoint status updates, SLA tracking, and notification creation
  7. Async dispatch: Celery tasks (DojoAsyncTask base class) carry user context through thread-local storage via crum.impersonate

UI request lifecycle follows standard Django: function-based views in each domain module (e.g., dojo/finding/views.py, dojo/product/views.py) handle form processing, authorization checks via user_has_permission_or_403, and template rendering.

Key Patterns

Modular Reorganization in Progress

The codebase is actively migrating from monolithic files to self-contained domain modules. The dojo/url/ module is the canonical example of the target architecture, with fully separated concerns:

dojo/url/
├── models.py, admin.py, signals.py, queries.py
├── ui/     (forms, filters, views, urls)
└── api/    (serializer, views, filters, urls)

Most core domains (product, engagement, test, finding) remain partially extracted — models still in dojo/models.py, views at the module root, API code in the monolithic api_v2/ files. The CLAUDE.md documents a 9-phase extraction playbook with backward-compatible re-exports at every step.

Deduplication as a First-Class Concern

Deduplication is architecturally central, not an afterthought. The Finding model explicitly declares DEDUPLICATION_FIELDS and DEDUPLICATION_DEFERRED_FIELDS — carefully curated field lists that optimize the deduplication query path. Multiple algorithms are supported (hash_code, unique_id_from_tool, legacy endpoint-based matching), configurable per engagement. Batch deduplication loads findings with select_related and prefetch_related to avoid N+1 queries.

Authorization via Roles and Permissions

dojo/authorization/authorization.py implements a custom RBAC system with product-level and product-type-level scoping. Users can be members of groups, products, or product types with specific roles. The user_has_permission_or_403 decorator gates UI views; API ViewSets use a DojoModelViewSet base class with permission mixins.

Service Layer Extraction

The JIRA integration demonstrates a clean service-layer pattern: dojo/jira/services.py acts as a thin public API that lazily loads dojo/jira/helper.py to break circular imports. This same pattern is being applied to other modules as they’re extracted.

Non-Obvious Details

Single Django App, Zero Migration Impact

Despite the modular directory structure, everything uses app_label = "dojo". Moving models to subdirectories doesn’t require database migrations — Django’s model registry resolves them regardless of file location. This is what makes the reorganization feasible without downtime.

The 4,600-Line Finding Model

The Finding model spans approximately 1,300 lines in dojo/models.py with 40+ fields, multiple managers, cached properties, and complex save logic. It’s the most coupled model in the system — referenced by deduplication, JIRA, risk acceptance, notifications, SLA, and endpoint status. Any refactoring here ripples everywhere.

Parser Registration is Runtime, Not Static

The PARSERS dict in factory.py is populated at import time by each parser module calling register(). Parsers are discovered via dojo/tools/__init__.py which dynamically imports all subdirectories. This means adding a new scanner integration is purely additive — create a directory under dojo/tools/, implement get_findings(), and it auto-registers.

Monolithic Files as Technical Debt

The five monolithic files (models, forms, filters, serializers, api views) total ~19,000 lines. While the reorganization playbook is well-documented, the migration is incomplete for the most complex domains (finding, product). The backward-compatible re-export strategy means the monoliths will grow re-export stubs faster than they shrink until a cleanup pass is dedicated.

Assessment

Strengths:

  • Parser ecosystem — 200+ integrations is unmatched in open-source vulnerability management. The factory pattern makes extension trivial.
  • Deduplication — Purpose-built, field-optimized, and algorithm-pluggable. The DEDUPLICATION_FIELDS approach shows performance awareness.
  • Well-documented reorganization — The CLAUDE.md playbook is one of the most thorough module-extraction guides I’ve seen in an open-source project.
  • Dual interface — Both full-featured UI and comprehensive REST API with OpenAPI schema generation.

Concerns:

  • Monolithic file sizes — dojo/models.py at 4,674 lines, api_v2/views.py at 3,668 lines create cognitive load and merge conflict surface. The reorganization is still early for core domains.
  • Import complexity — The import pipeline threads through base classes, options objects, helper modules, and Celery tasks. Tracing an import end-to-end requires reading 5+ files across different directories.
  • Coupling to JIRA — JIRA push logic is deeply intertwined with finding lifecycle (helper, deduplication, importers). The lazy-import service layer helps, but the conceptual coupling remains.
  • Function-based views — UI views are still largely function-based Django views with manual authorization checks, rather than class-based views with mixins.

Recommendations:

  • Prioritize extracting the Finding model and its services — it’s the keystone dependency for everything else.
  • Consider a formal parser interface (abstract base class) rather than the current duck-typed get_findings() convention.
  • Invest in the services.py layer for finding lifecycle operations to separate business logic from both UI and API views.
  • analyzing-prowler — Cloud security scanning tool whose output can be ingested by DefectDojo
  • analyzing-gitleaks — Secret detection scanner that integrates with DefectDojo’s import pipeline
  • analyzing-trufflehog — Another secret scanner with DefectDojo integration
  • analyzing-nuclei — Vulnerability scanner whose findings feed into DefectDojo
  • analyzing-opencti — Threat intelligence platform; complementary to DefectDojo’s vulnerability management

Graph View