DefectDojo API v2 Complete Reference

DefectDojo API v2 Complete Reference

Authentication

API Token Generation

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

Request Headers

Authorization: Token <your-api-token>
Content-Type: application/json  # For JSON requests
Accept: application/json

Python Example

import requests

headers = {
    'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff',
    'Accept': 'application/json'
}

response = requests.get(
    'https://defectdojo.example.com/api/v2/products/',
    headers=headers
)

Environment Variables

Products API

List Products

curl -X GET "https://defectdojo.example.com/api/v2/products/" \
  -H "Authorization: Token <api-token>"

Query Parameters:

• name - Filter by exact name
• name__contains - Filter by partial name match
• prod_type - Filter by product type ID
• offset - Pagination offset
• limit - Number of results per page

Create Product

curl -X POST "https://defectdojo.example.com/api/v2/products/" \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Application",
    "description": "Description of the application",
    "prod_type": 1
  }'

Required Fields:

• name (string)
• prod_type (integer) - Product type ID

Optional Fields:

• description (string)
• tags (array of strings)
• business_criticality (string): "very high", "high", "medium", "low", "very low", "none"
• platform (string): "web service", "desktop", "iot", "mobile", "web"
• lifecycle (string): "construction", "production", "retirement"
• origin (string): "third party library", "purchased", "contractor", "internal", "open source", "outsourced"
• external_audience (boolean)
• internet_accessible (boolean)

Get Product by ID

curl -X GET "https://defectdojo.example.com/api/v2/products/1/" \
  -H "Authorization: Token <api-token>"

Update Product

curl -X PATCH "https://defectdojo.example.com/api/v2/products/1/" \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description"
  }'

Product Types API

List Product Types

curl -X GET "https://defectdojo.example.com/api/v2/product_types/" \
  -H "Authorization: Token <api-token>"

Create Product Type

curl -X POST "https://defectdojo.example.com/api/v2/product_types/" \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web Applications",
    "description": "All web-based applications"
  }'

Engagements API

List Engagements

curl -X GET "https://defectdojo.example.com/api/v2/engagements/" \
  -H "Authorization: Token <api-token>"

Query Parameters:

• product - Filter by product ID
• engagement_type - "Interactive" or "CI/CD"
• status - "Not Started", "In Progress", "Completed", "Cancelled"
• name__contains - Partial name match

Create Engagement

curl -X POST "https://defectdojo.example.com/api/v2/engagements/" \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2024 Security Review",
    "product": 1,
    "target_start": "2024-01-01",
    "target_end": "2024-03-31",
    "engagement_type": "Interactive",
    "status": "In Progress"
  }'

Required Fields:

• name (string)
• product (integer) - Product ID
• target_start (date) - YYYY-MM-DD format
• target_end (date) - YYYY-MM-DD format

Optional Fields:

• engagement_type (string): "Interactive" or "CI/CD"
• status (string): "Not Started", "In Progress", "Completed", "Cancelled"
• description (string)
• lead (integer) - User ID
• build_id (string) - CI/CD build identifier
• commit_hash (string)
• branch_tag (string)
• source_code_management_uri (string)
• deduplication_on_engagement (boolean)

Tests API

List Tests

curl -X GET "https://defectdojo.example.com/api/v2/tests/" \
  -H "Authorization: Token <api-token>"

Query Parameters:

• engagement - Filter by engagement ID
• test_type - Filter by test type ID
• title__contains - Partial title match

Create Test

curl -X POST "https://defectdojo.example.com/api/v2/tests/" \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "engagement": 1,
    "test_type": 1,
    "target_start": "2024-01-15",
    "target_end": "2024-01-15"
  }'

Findings API

List Findings

curl -X GET "https://defectdojo.example.com/api/v2/findings/" \
  -H "Authorization: Token <api-token>"

Query Parameters:

• test - Filter by test ID
• test__engagement - Filter by engagement ID
• test__engagement__product - Filter by product ID
• severity - "Critical", "High", "Medium", "Low", "Info"
• active - Boolean
• verified - Boolean
• duplicate - Boolean
• false_p - Boolean (false positive)
• cwe - CWE ID
• title__contains - Partial title match

Get Finding by ID

curl -X GET "https://defectdojo.example.com/api/v2/findings/1/" \
  -H "Authorization: Token <api-token>"

Update Finding

curl -X PATCH "https://defectdojo.example.com/api/v2/findings/1/" \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "verified": true,
    "false_p": false
  }'

Create Finding Manually

curl -X POST "https://defectdojo.example.com/api/v2/findings/" \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SQL Injection in Login",
    "description": "Detailed description of the vulnerability",
    "severity": "High",
    "test": 1,
    "active": true,
    "verified": true,
    "cwe": 89,
    "mitigation": "Use parameterized queries"
  }'

Required Fields:

• title (string)
• severity (string): "Critical", "High", "Medium", "Low", "Info"
• test (integer) - Test ID

Import Scan API

Import Scan (First Import)

curl -X POST "https://defectdojo.example.com/api/v2/import-scan/" \
  -H "Authorization: Token <api-token>" \
  -F "scan_type=Trivy Scan" \
  -F "file=@trivy-results.json" \
  -F "engagement=1" \
  -F "minimum_severity=Info" \
  -F "active=true" \
  -F "verified=false"

Parameters:

Reimport Scan (Subsequent Imports)

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=1" \
  -F "do_not_reactivate=true"

Additional Parameters:

Reimport Behavior:

• New findings are created
• Existing findings are updated
• Findings not in new scan are closed (unless close_old_findings=false)
• Can also auto-create context like /import-scan/

Endpoints API

List Endpoints

curl -X GET "https://defectdojo.example.com/api/v2/endpoints/" \
  -H "Authorization: Token <api-token>"

Query Parameters:

• product - Filter by product ID
• host - Filter by hostname
• protocol - "http", "https", etc.

Create Endpoint

curl -X POST "https://defectdojo.example.com/api/v2/endpoints/" \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "api.example.com",
    "protocol": "https",
    "port": 443,
    "path": "/api/v1",
    "product": 1
  }'

Test Types API

List Test Types (Scanner Types)

curl -X GET "https://defectdojo.example.com/api/v2/test_types/" \
  -H "Authorization: Token <api-token>"

This returns all available scanner types that can be used in scan_type parameter.

Users API

List Users

curl -X GET "https://defectdojo.example.com/api/v2/users/" \
  -H "Authorization: Token <api-token>"

Query Parameters:

• username__contains - Partial username match
• email__contains - Partial email match
• is_active - Boolean

Common Scan Types

Pagination

All list endpoints support pagination:

curl "https://defectdojo.example.com/api/v2/findings/?limit=100&offset=0"

Response Format:

{
  "count": 1234,
  "next": "https://defectdojo.example.com/api/v2/findings/?limit=100&offset=100",
  "previous": null,
  "results": [...]
}

Error Handling

Common HTTP Status Codes

Error Response Format

{
  "detail": "Error message here"
}

Or for validation errors:

{
  "field_name": ["Error message for this field"]
}

Rate Limiting

DefectDojo doesn't have built-in rate limiting, but consider:

• Implementing client-side delays for bulk operations
• Using batch operations where available
• Monitoring API response times

Interactive Documentation

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

This provides:

• Interactive API testing
• Complete schema documentation
• Request/response examples