> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safedep.io/llms.txt
> Use this file to discover all available pages before exploring further.

# DefectDojo Integration

> Integrate Vet with DefectDojo for centralized vulnerability tracking and management

`vet` integrates with [DefectDojo](https://github.com/DefectDojo/django-DefectDojo) to export vulnerabilities, policy violations, and other findings. Each scan is reported as a new engagement in DefectDojo.

## Prerequisites

<CardGroup cols={2}>
  <Card title="Docker & Docker Compose" icon="docker">
    Required for running DefectDojo locally
  </Card>

  <Card title="DefectDojo Instance" icon="server">
    Either local or cloud-hosted DefectDojo installation
  </Card>

  <Card title="Vet CLI" icon="terminal">
    Install Vet following the quickstart guide
  </Card>

  <Card title="API Access" icon="key">
    DefectDojo API key for authentication
  </Card>
</CardGroup>

If you don't have Vet installed yet, follow the [quickstart guide](/governance/vet/quickstart) to get started.

## Quick Setup with Docker

The steps below use Docker Compose to run DefectDojo locally and scan the [demo-client-python](https://github.com/safedep/demo-client-python) repository as a worked example.

### Setup DefectDojo

<Steps>
  <Step title="Clone DefectDojo">
    Download the DefectDojo repository:

    ```bash theme={null}
    git clone https://github.com/DefectDojo/django-DefectDojo.git --depth 1
    cd django-DefectDojo
    ```
  </Step>

  <Step title="Start Services">
    Launch DefectDojo with Docker Compose:

    ```bash theme={null}
    docker compose up -d
    ```

    <Info>
      This will take a while as it builds images and downloads dependencies.
    </Info>
  </Step>

  <Step title="Get Admin Password">
    Retrieve the admin password from the logs:

    ```bash theme={null}
    docker compose logs initializer | grep "Admin password:"
    ```

    <Note>
      The initializer container runs migrations and creates initial data, which may take several minutes.
    </Note>
  </Step>

  <Step title="Access DefectDojo">
    Navigate to `http://localhost:8080` and login with:

    * **Username**: `admin`
    * **Password**: (from previous step)

    <img src="https://mintcdn.com/safedep/A0tSXvZ_XcagO9QB/images/defect-dojo-integration/dd-1-login.png?fit=max&auto=format&n=A0tSXvZ_XcagO9QB&q=85&s=b925e220475eccc1a93ee6a6e8d286a7" alt="DefectDojo Login" width="3448" height="562" data-path="images/defect-dojo-integration/dd-1-login.png" />
  </Step>
</Steps>

### Configure Your Project

<Steps>
  <Step title="Create Product">
    Create a new product called `demo-client-python` and note the product ID:

    <img src="https://mintcdn.com/safedep/A0tSXvZ_XcagO9QB/images/defect-dojo-integration/dd-2-add-product.png?fit=max&auto=format&n=A0tSXvZ_XcagO9QB&q=85&s=7819b8b4dd84cd493cd3001a1c5500fd" alt="DefectDojo Add Product" width="3448" height="1782" data-path="images/defect-dojo-integration/dd-2-add-product.png" />

    <img src="https://mintcdn.com/safedep/A0tSXvZ_XcagO9QB/images/defect-dojo-integration/dd-3-observe-product-id.png?fit=max&auto=format&n=A0tSXvZ_XcagO9QB&q=85&s=672f362fc7f0180e7511506e3b187201" alt="DefectDojo Product ID" width="2462" height="612" data-path="images/defect-dojo-integration/dd-3-observe-product-id.png" />
  </Step>

  <Step title="Generate API Key">
    Navigate to `http://localhost:8080/api/key-v2` to generate an API key for Vet integration.
  </Step>

  <Step title="Set Environment Variable">
    Configure the API key for Vet usage:

    ```bash theme={null}
    export DEFECT_DOJO_APIV2_KEY=<your-api-key>
    ```
  </Step>
</Steps>

## Scanning with Vet

Now you can scan a project and send results to DefectDojo:

```bash theme={null}
vet scan --github https://github.com/safedep/demo-client-python \
  --filter-suite /path/to/your/policy-suite.yml \
  --report-defect-dojo \
  --defect-dojo-host-url http://localhost:8080/ \
  --defect-dojo-product-id <your-product-id>
```

Each scan creates a new engagement in DefectDojo; policy violations are reported as findings and visible in DefectDojo's dashboard.

<Warning>
  Currently, Vet reports only policy violations to DefectDojo. Support for reporting vulnerabilities and malicious package information is planned in [GitHub issue #430](https://github.com/safedep/vet/issues/430).
</Warning>

## Advanced Configuration

### Custom Policy Suites

Example policy suite for DefectDojo integration:

```yaml theme={null}
# defectdojo-policy.yml
name: DefectDojo Security Policy
description: Comprehensive policy for DefectDojo integration
filters:
  - name: critical-vulnerabilities
    value: |
      vulns.critical.size() > 0
      
  - name: high-risk-packages
    value: |
      vulns.high.size() > 3
      
  - name: license-violations
    value: |
      !licenses.exists(p, p in ["MIT", "Apache-2.0", "BSD-3-Clause"])
      
  - name: unmaintained-packages
    value: |
      scorecard.scores.Maintained < 5
```

### CI/CD Integration

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    name: Security Scan to DefectDojo
    on: [push, pull_request]

    jobs:
      security-scan:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          
          - name: Run vet security scan
            run: |
              vet scan -D . \
                --filter-suite .github/security-policy.yml \
                --report-defect-dojo \
                --defect-dojo-host-url ${{ secrets.DEFECT_DOJO_URL }} \
                --defect-dojo-product-id ${{ secrets.DEFECT_DOJO_PRODUCT_ID }}
            env:
              DEFECT_DOJO_APIV2_KEY: ${{ secrets.DEFECT_DOJO_API_KEY }}
    ```
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    security-scan:
      image: ghcr.io/safedep/vet:latest
      script:
        - vet scan -D . 
            --filter-suite security-policy.yml
            --report-defect-dojo
            --defect-dojo-host-url $DEFECT_DOJO_URL
            --defect-dojo-product-id $DEFECT_DOJO_PRODUCT_ID
      variables:
        DEFECT_DOJO_APIV2_KEY: $DEFECT_DOJO_API_KEY
    ```
  </Tab>
</Tabs>

### Multiple Projects

For organizations with multiple projects, create separate products in DefectDojo:

```bash theme={null}
# Project A
vet scan -D ./project-a \
  --report-defect-dojo \
  --defect-dojo-product-id 1

# Project B  
vet scan -D ./project-b \
  --report-defect-dojo \
  --defect-dojo-product-id 2
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="API Key Issues">
    If authentication fails:

    * Verify the API key is correctly set in the environment
    * Check that the API key has sufficient permissions
    * Ensure the DefectDojo URL is accessible from your environment
  </Accordion>

  <Accordion title="Product ID Errors">
    If the product ID is invalid:

    * Verify the product exists in DefectDojo
    * Check that you have access to the specified product
    * Ensure the product ID is numeric, not the product name
  </Accordion>

  <Accordion title="No Findings Reported">
    If no findings appear in DefectDojo:

    * Confirm that policy violations exist in your scan
    * Check the Vet scan output for errors
    * Verify the DefectDojo integration is properly configured
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="DefectDojo Documentation" icon="book" href="https://documentation.defectdojo.com/">
    Learn more about DefectDojo features and configuration
  </Card>

  <Card title="Policy as Code Guide" icon="file-code" href="/reference/policy-as-code">
    Create effective security policies for DefectDojo integration
  </Card>

  <Card title="Vet GitHub Issues" icon="bug" href="https://github.com/safedep/vet/issues/430">
    Track progress on enhanced DefectDojo integration features
  </Card>

  <Card title="Demo Repository" icon="github" href="https://github.com/safedep/demo-client-python">
    Use the demo repository to test your DefectDojo integration
  </Card>
</CardGroup>