defectdojo

What this skill does

# 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.cafehyna.com.br",
        "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](#mcp-tools-primary-interface) 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 "[email protected]" \
  -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 "[email protected]" \
  -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:
  - sec