Skill v1.0.1

currentAutomated scan100/100

julianobarbosa/claude-code-skills/defectdojo

+6 new

──Details

PublishedJuly 20, 2026 at 06:31 AM

Content Hashsha256:a1d1f8fcb44e8266...

Git SHA7a1fc30bbb3d

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 23.2 KB)

SKILL.md23.2 KBactive

SKILL.md · 827 lines · 23.2 KB

version: "1.0.1" name: defectdojo description: Guide for implementing DefectDojo - an open-source DevSecOps, ASPM, and vulnerability management platform. Use when querying vulnerabilities, managing findings, configuring CI/CD pipeline imports, or working with security scan data. Includes MCP tools for direct API interaction. tools:

defectdojo_list_products
defectdojo_get_product
defectdojo_list_engagements
defectdojo_list_tests
defectdojo_list_findings
defectdojo_get_finding
defectdojo_get_statistics
defectdojo_list_endpoints
defectdojo_list_test_types
defectdojo_create_engagement
defectdojo_update_finding
defectdojo_close_engagement

DefectDojo Skill

Overview

DefectDojo is an open-source DevSecOps, Application Security Posture Management (ASPM), and vulnerability management platform. It orchestrates end-to-end security testing, vulnerability tracking, deduplication, remediation, and reporting.

Key Capabilities:

Unified vulnerability management across 200+ security tools
Automated scan import and deduplication
CI/CD pipeline integration
Bidirectional JIRA integration
Role-based access control
SLA tracking and reporting
REST API v2 for automation
MCP Tools for Claude Code integration

Official Resources:

Documentation: <https://docs.defectdojo.com/>
GitHub: <https://github.com/DefectDojo/django-DefectDojo>
Demo: <https://demo.defectdojo.org> (admin / 1Defectdojo@demo#appsec)

MCP Tools (Primary Interface)

This skill provides 12 MCP tools for direct DefectDojo API interaction. Use these tools instead of manual API calls.

Read Operations

Tool	Description	Key Parameters
`defectdojo_list_products`	List and search products	`name_contains`, `prod_type`, `limit`
`defectdojo_get_product`	Get detailed product info	`product_id` (required)
`defectdojo_list_engagements`	List engagements with filters	`product_id`, `status`, `engagement_type`
`defectdojo_list_tests`	List tests in engagements	`engagement_id`, `test_type`
`defectdojo_list_findings`	Primary tool - Search findings	`severity`, `active`, `product_id`, `cwe`
`defectdojo_get_finding`	Get finding details	`finding_id` (required)
`defectdojo_get_statistics`	Vulnerability statistics	`product_id`, `engagement_id`
`defectdojo_list_endpoints`	List product endpoints	`product_id`, `host`, `protocol`
`defectdojo_list_test_types`	List scanner types	`name_contains`

Write Operations

Tool	Description	Key Parameters
`defectdojo_create_engagement`	Create new engagement	`product_id`, `name`, `engagement_type`
`defectdojo_update_finding`	Update finding status	`finding_id`, `active`, `verified`, `false_p`
`defectdojo_close_engagement`	Close engagement	`engagement_id`

Usage Examples

List all critical active findings:

Use defectdojo_list_findings with:
- severity: "Critical"
- active: true

Get vulnerability statistics for a product:

Use defectdojo_get_statistics with:
- product_id: 1

Search for SQL injection findings:

Use defectdojo_list_findings with:
- cwe: 89
- active: true

Mark a finding as false positive:

Use defectdojo_update_finding with:
- finding_id: 123
- false_p: true
- active: false

Create a CI/CD engagement:

Use defectdojo_create_engagement with:
- product_id: 1
- name: "Pipeline Security Scan"
- engagement_type: "CI/CD"

Response Formats

All tools support two output formats via the response_format parameter:

markdown (default) - Human-readable formatted output
json - Raw JSON for programmatic processing

MCP Server Configuration

The MCP server is configured in .mcp.json:

json

{
  "mcpServers": {
    "defectdojo": {
      "command": "python",
      "args": [".claude/mcp-servers/defectdojo-mcp/defectdojo_mcp.py"],
      "env": {
        "DEFECTDOJO_URL": "https://defectdojo.dev.example.com",
        "DEFECTDOJO_API_TOKEN": "${DEFECTDOJO_API_TOKEN}"
      }
    }
  }
}

Environment Variables:

DEFECTDOJO_URL - Your DefectDojo instance URL
DEFECTDOJO_API_TOKEN - API token from /api/key-v2

Data Model (Product Hierarchy)

DefectDojo uses five interconnected data classes to organize security work:

Product Type
    └── Product
        └── Engagement (CI/CD or Interactive)
            └── Test
                └── Finding
                    └── Endpoint

Product Types

The topmost organizational level that categorizes products by business domain, team, or security area. Enables role-based access control at the category level.

Products

Individual applications or systems under security testing. Each product maintains:

Its own testing history
Deduplication scope (findings deduplicate within products)
SLA configuration
Team assignments

Engagements

Scheduled testing periods containing one or more tests. Two types:

Type	Purpose	Use Case
CI/CD	Automated pipeline integration	Automated scans per build/commit
Interactive	Manual testing by engineers	Penetration tests, manual reviews

Tests

Individual security scans grouped by tool type. Tests support:

Reimporting (add findings to existing test)
Environment tagging
Version tracking

Findings

Specific vulnerabilities discovered during testing:

Severity	Description
Critical	Immediate action required
High	High priority remediation
Medium	Standard priority
Low	Low priority
Info	Informational only

Finding States:

Active / Inactive
Verified / Unverified
Duplicate
Mitigated
False Positive
Risk Accepted
Out of Scope

Endpoints

References to affected hosts, URLs, or systems. Enables vulnerability tracking by infrastructure component.

API v2 Reference

Note: For most operations, use the MCP Tools above instead of direct API calls. Use direct API calls only for scan imports or operations not covered by MCP tools.

Authentication

Generate API token at: <your-instance>/api/key-v2

bash

# Header format
Authorization: Token <api_key>

Environment Variables:

DD_API_TOKENS_ENABLED=False - Disable API tokens entirely
DD_API_TOKEN_AUTH_ENDPOINT_ENABLED=False - Disable only token auth endpoint

Core Endpoints

Endpoint	Method	Purpose
`/api/v2/import-scan/`	POST	Initial scan import
`/api/v2/reimport-scan/`	POST	Subsequent imports (deduplication)
`/api/v2/products/`	GET/POST	Manage products
`/api/v2/engagements/`	GET/POST	Manage engagements
`/api/v2/tests/`	GET/POST	Manage tests
`/api/v2/findings/`	GET/POST/PATCH	Manage findings
`/api/v2/endpoints/`	GET/POST	Manage endpoints
`/api/v2/users/`	GET	List users

Import Scan Parameters

bash

curl -X POST "https://defectdojo.example.com/api/v2/import-scan/" \
  -H "Authorization: Token <api-token>" \
  -F "scan_type=<scanner-type>" \
  -F "file=@results.json" \
  -F "engagement=<engagement-id>" \
  -F "minimum_severity=Info" \
  -F "active=true" \
  -F "verified=false" \
  -F "scan_date=2024-01-15"

Key Parameters:

Parameter	Description
`scan_type`	Scanner identifier (e.g., "Trivy Scan", "Semgrep JSON Report")
`engagement`	Target engagement ID
`test_title`	Custom test name
`minimum_severity`	Filter threshold (Info, Low, Medium, High, Critical)
`active`	Mark findings as active (boolean)
`verified`	Mark findings as verified (boolean)
`scan_date`	Override scan completion date
`do_not_reactivate`	Prevent reopening closed findings
`auto_create_context`	Auto-create Product/Engagement if missing

Reimport Scan (Deduplication)

bash

curl -X POST "https://defectdojo.example.com/api/v2/reimport-scan/" \
  -H "Authorization: Token <api-token>" \
  -F "scan_type=Trivy Scan" \
  -F "file=@trivy-results.json" \
  -F "test=<test-id>" \
  -F "do_not_reactivate=true"

The reimport endpoint:

Detects new vs. existing findings
Updates existing findings
Closes findings not in the new scan
Can auto-create context when auto_create_context=true

Interactive API Documentation

Access Swagger UI at: <your-instance>/api/v2/oa3/swagger-ui/

CI/CD Integration

Pipeline Integration Pattern

yaml

# GitLab CI Example
stages:
  - security-scan
  - upload-results
 
trivy-scan:
  stage: security-scan
  script:
    - trivy image --format json -o trivy-results.json $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  artifacts:
    paths:
      - trivy-results.json
 
upload-to-defectdojo:
  stage: upload-results
  script: |
    curl -X POST "${DEFECTDOJO_URL}/api/v2/reimport-scan/" \
      -H "Authorization: Token ${DEFECTDOJO_API_TOKEN}" \
      -F "scan_type=Trivy Scan" \
      -F "file=@trivy-results.json" \
      -F "product_name=${CI_PROJECT_NAME}" \
      -F "engagement_name=CI/CD-${CI_PIPELINE_ID}" \
      -F "auto_create_context=true" \
      -F "minimum_severity=Low"

Jenkins Integration

Install the DefectDojo Jenkins plugin from: <https://plugins.jenkins.io/defectdojo/>

Pipeline Configuration:

groovy

pipeline {
    agent any
    environment {
        DEFECTDOJO_URL = 'https://defectdojo.example.com'
        DEFECTDOJO_API_KEY = credentials('defectdojo-api-key')
    }
    stages {
        stage('Security Scan') {
            steps {
                sh 'trivy image --format json -o trivy.json myapp:latest'
            }
        }
        stage('Upload to DefectDojo') {
            steps {
                defectDojoPublisher(
                    artifact: 'trivy.json',
                    productName: 'MyApp',
                    scanType: 'Trivy Scan',
                    engagementName: "Build-${BUILD_NUMBER}"
                )
            }
        }
    }
}

GitHub Actions Integration

yaml

name: Security Scan
on: [push]
 
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Run Trivy
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          format: 'json'
          output: 'trivy-results.json'
 
      - name: Upload to DefectDojo
        run: |
          curl -X POST "${{ secrets.DEFECTDOJO_URL }}/api/v2/reimport-scan/" \
            -H "Authorization: Token ${{ secrets.DEFECTDOJO_TOKEN }}" \
            -F "scan_type=Trivy Scan" \
            -F "file=@trivy-results.json" \
            -F "product_name=${{ github.repository }}" \
            -F "engagement_name=GitHub-${{ github.run_id }}" \
            -F "auto_create_context=true"

Python API Examples

Tip: For Claude Code interactions, use the MCP tools (defectdojo_list_findings, etc.) instead of writing Python code. The examples below are for CI/CD scripts and external integrations.

Basic API Connection

python

import requests
class DefectDojoAPI:
    def __init__(self, url, api_token):
        self.url = url.rstrip('/')
        self.headers = {
            'Authorization': f'Token {api_token}',
            'Accept': 'application/json'
        }
    def get_products(self):
        response = requests.get(
            f'{self.url}/api/v2/products/',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()
    def import_scan(self, engagement_id, scan_type, file_path, **kwargs):
        with open(file_path, 'rb') as f:
            data = {
                'engagement': engagement_id,
                'scan_type': scan_type,
                'minimum_severity': kwargs.get('minimum_severity', 'Info'),
                'active': kwargs.get('active', True),
                'verified': kwargs.get('verified', False),
            }
            files = {'file': f}
            response = requests.post(
                f'{self.url}/api/v2/import-scan/',
                headers={'Authorization': self.headers['Authorization']},
                data=data,
                files=files
            )
        response.raise_for_status()
        return response.json()
# Usage
api = DefectDojoAPI('https://defectdojo.example.com', 'your-api-token')
products = api.get_products()

Create Product and Engagement

python

def create_product(api, name, prod_type_id, description=''):
    response = requests.post(
        f'{api.url}/api/v2/products/',
        headers=api.headers,
        json={
            'name': name,
            'prod_type': prod_type_id,
            'description': description
        }
    )
    response.raise_for_status()
    return response.json()
def create_engagement(api, product_id, name, target_start, target_end,
                      engagement_type='CI/CD'):
    response = requests.post(
        f'{api.url}/api/v2/engagements/',
        headers=api.headers,
        json={
            'name': name,
            'product': product_id,
            'target_start': target_start,
            'target_end': target_end,
            'engagement_type': engagement_type,
            'status': 'In Progress'
        }
    )
    response.raise_for_status()
    return response.json()

Query Findings

python

def get_findings(api, product_id=None, severity=None, active=True):
    params = {'active': active}
    if product_id:
        params['test__engagement__product'] = product_id
    if severity:
        params['severity'] = severity
    response = requests.get(
        f'{api.url}/api/v2/findings/',
        headers=api.headers,
        params=params
    )
    response.raise_for_status()
    return response.json()
# Get all critical findings
critical = get_findings(api, severity='Critical')

Supported Security Tools (200+)

SAST / Code Analysis

Bandit, Checkmarx, Fortify, SonarQube, Semgrep
CodeQL, Horusec, Brakeman, SpotBugs

Dependency / SCA

Snyk, OWASP Dependency-Check, Dependency-Track
npm Audit, pip-audit, Trivy, Safety

DAST / Web Scanning

Burp Suite, OWASP ZAP, Nikto, Nessus
Qualys, OpenVAS, Acunetix, AppScan

Container / Infrastructure

Trivy, Aqua, Anchore, Wiz, NeuVector
kube-bench, Kubescape, Prisma Cloud

Secrets Detection

Gitleaks, Trufflehog, Detect-secrets
GitHub Secret Scanning

Cloud Security

AWS Inspector, AWS Prowler, ScoutSuite
Azure Security Center, Checkov

IaC Scanning

Checkov, Terrascan, KICS, TFSec, Dockle

Full list: <https://docs.defectdojo.com/supported_tools/>

JIRA Integration

Configuration

Enable in System Settings:

`` Configuration > System Settings > Enable JIRA Integration ``

Add JIRA Instance:

`` Enterprise Settings > JIRA Instances > + New JIRA Instance ``

Configure Webhook (bidirectional sync):

Create webhook in JIRA pointing to:

https://<defectdojo>/jira/webhook/<webhook-secret>

Enable in DefectDojo: "Enable JIRA web hook"

Environment Variables

yaml

extraEnv:
  - name: DD_JIRA_URL
    value: "https://your-jira.atlassian.net"
  - name: DD_JIRA_MAX_RETRIES
    value: "3"

Features

Push findings to JIRA as issues
Bidirectional comment sync
Auto-close findings when JIRA issues close
SLA notifications as JIRA comments

Project File Locations

File Type	Path
ApplicationSet	`infra-team/applicationset/defectdojo.yaml`
Helm Values	`argo-cd-helm-values/kube-addons/defectdojo/<cluster>/values.yaml`
SecretProviderClass	`argo-cd-helm-values/kube-addons/defectdojo/<cluster>/secretproviderclass.yaml`

Environment Configuration

Cluster	Key Vault	Azure AD Tenant ID
example-app-dev	`kv-example-dev-hlg`	`<TENANT_ID>`

Azure AD App Registration

Setting	Value
Application (Client) ID	`<AZURE_AD_APP_ID>`
Tenant ID	`<TENANT_ID>`
Redirect URI	`https://defectdojo.dev.example.com/complete/azuread-tenant-oauth2/`

Azure AD SSO Configuration

Required Environment Variables

yaml

extraEnv:
  # Enable Azure AD OAuth2
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_ENABLED
    value: "True"
  # Application (Client) ID
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY
    value: "<client-id>"
  # Directory (Tenant) ID
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID
    value: "<tenant-id>"
  # Client Secret (from Key Vault)
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET
    valueFrom:
      secretKeyRef:
        name: defectdojo
        key: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET

Group Synchronization

yaml

extraEnv:
  # Sync groups from Azure AD token
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GET_GROUPS
    value: "True"
  # Remove users from groups when removed in Azure AD
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_CLEANUP_GROUPS
    value: "True"
  # Filter to only sync DefectDojo groups
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GROUPS_FILTER
    value: "^G-Usuarios-DefectDojo-.*"

Required Azure AD Permissions (Application type, Admin consent required):

Group.Read.All
GroupMember.Read.All
User.Read.All

For complete Azure AD SSO details, see references/azure-ad-sso.md.

DefectDojo Roles

Role	Permissions
Superuser	Full system access, manage users, system settings
Owner	Delete products, designate other owners
Maintainer	Edit products, add members, delete findings
Writer	Add/edit engagements, tests, findings
Reader	View-only, add comments
API Importer	Limited API access for CI/CD pipelines

Azure AD Groups for Role Mapping

Azure AD Group	DefectDojo Role
`G-Usuarios-DefectDojo-Superuser`	Superuser
`G-Usuarios-DefectDojo-Owner`	Owner
`G-Usuarios-DefectDojo-Maintainer`	Maintainer
`G-Usuarios-DefectDojo-Writer`	Writer
`G-Usuarios-DefectDojo-Reader`	Reader

Helm Chart Quick Reference

Key Values

yaml

# Host configuration
host: defectdojo.dev.example.com
siteUrl: https://defectdojo.dev.example.com
 
# Secrets (use CSI driver)
createSecret: false
disableHooks: true
 
# Django
django:
  replicas: 1
  ingress:
    enabled: true
    activateTLS: true
    className: nginx
 
# Celery (keep beat at 1 replica)
celery:
  beat:
    enabled: true
    replicas: 1
  worker:
    enabled: true
    replicas: 1
 
# Database
postgresql:
  enabled: true
 
# Cache
redis:
  enabled: true

For complete Helm values reference, see references/helm-values.md.

Kubernetes Deployment

Basic Helm Install

bash

git clone https://github.com/DefectDojo/django-DefectDojo
cd django-DefectDojo
 
helm install defectdojo ./helm/defectdojo \
  -n defectdojo --create-namespace \
  --set django.ingress.enabled=true \
  --set django.ingress.activateTLS=false \
  --set createSecret=true \
  --set createRabbitMqSecret=true \
  --set createPostgresqlSecret=true

Access DefectDojo

bash

kubectl port-forward --namespace=defectdojo service/defectdojo-django 8080:80

Secrets Management

Secrets are managed via Azure Key Vault CSI Driver:

Key Vault Secret	K8s Secret Key	Purpose
`defectdojo-admin-password`	`DD_ADMIN_PASSWORD`	Admin user password
`defectdojo-secret-key`	`DD_SECRET_KEY`	Django secret key
`defectdojo-credential-aes-key`	`DD_CREDENTIAL_AES_256_KEY`	Credential encryption
`defectdojo-azuread-client-secret`	`DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET`	Azure AD client secret

Common Troubleshooting

User Not in Groups After SSO Login

Symptoms: User logged in via Azure AD but shows "No group members found"

Solutions:

Verify DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GET_GROUPS=True
Check Azure AD API permissions (Group.Read.All with admin consent)
Verify Azure AD token includes group claim (not role claims)
User must log out and log back in to sync groups
Create matching groups in DefectDojo UI

HTTPS Redirect URI Mismatch (ADSTS50011)

Error: "The redirect URI specified in the request does not match"

Solution: Ensure these are set:

yaml

- name: DD_SESSION_COOKIE_SECURE
  value: "True"
- name: DD_CSRF_COOKIE_SECURE
  value: "True"
- name: DD_SECURE_PROXY_SSL_HEADER
  value: "True"

ERR_TOO_MANY_REDIRECTS

Cause: DD_SECURE_SSL_REDIRECT=True with TLS-terminating proxy

Solution: Set DD_SECURE_SSL_REDIRECT=False when behind NGINX Ingress

Emergency Login Access

If SSO breaks, access standard login form:

https://defectdojo.dev.example.com/login?force_login_form

For complete troubleshooting guide, see references/troubleshooting.md.

Useful Commands

Check Pod Status

bash

KUBECONFIG=~/.kube/aks-rg-example-dev-config kubectl get pods -n defectdojo

View Logs

bash

KUBECONFIG=~/.kube/aks-rg-example-dev-config kubectl logs -n defectdojo -l app.kubernetes.io/name=defectdojo -c uwsgi

Restart Deployment

bash

KUBECONFIG=~/.kube/aks-rg-example-dev-config kubectl rollout restart deployment/defectdojo-django -n defectdojo

Additional References

MCP Server

MCP Server README - MCP server setup and usage
MCP Server Source - Server implementation

Skill References

Azure AD SSO Configuration - Complete SSO setup guide
Helm Values Reference - Full Helm chart configuration
Troubleshooting Guide - Common issues and solutions
API v2 Reference - Complete API documentation
CI/CD Integration Guide - Pipeline integration patterns

External

Official Documentation
Swagger UI - Interactive API docs

Gotchas

Deduplication is per-product, not global: The same CVE in two products counts twice — portfolio metrics inflate. Configure cross-product deduplication via hash_code algorithm if you need global counts.
`reimport-scan` closes missing findings silently: Reimporting a partial scan (one path instead of full) auto-closes every finding not in the new file. Use do_not_reactivate=true and scope tests carefully.
`auto_create_context=true` creates duplicate products on name drift: "MyApp" vs "myapp" vs "MyApp " produce three products. Normalize product_name upstream — DefectDojo does not fuzzy-match.
API tokens are user-scoped, not team-scoped: A pipeline token inherits the creator's full permissions. Create a dedicated CI user with API Importer role rather than reusing a human's token.
`DD_SECURE_SSL_REDIRECT=True` behind NGINX Ingress causes redirect loops: TLS terminates at the ingress, Django then redirects HTTP to HTTPS again. Set to False and rely on the ingress for TLS enforcement.
Azure AD group sync only fires on login: Adding a user to an Azure AD group does not retro-sync — the user must log out and back in before DefectDojo sees the new membership.

← v1.0.0 All versions