Api endpoint for copy functionality of an engagement (currently only possible via GUI)

[Hertog-PJ]

Is your feature request related to a problem? Please describe
For our workflow we would like to duplicate/copy an existing engagement whenever we start a new feature branch which we want to analyse/register the results of our security tests.

For example, when we create a feature branch foo branching from our main branch at version 1.0.0 we want to copy the engagement that belongs to version 1.0.0. From here on we can upload the test results of our feature foo to the new engagement. This way the engagement of the feature branch will show a clear delta in findings compared to what is already existing on the main branch. This will help reduce the time spent on reflagging findings as mitigated for example, but also shows which findings from the main engagement are resolved as well as introduced in this feature branch.

Currently it is possible to create a copy of an engagement via the GUI by clicking the 3 dots on an engagement and selecting Copy. However, for our CI/CD pipelines we would like to be able to automate this, and this GUI functionality is not exposed via the API.

Describe the solution you'd like
As a DevOps engineer, I want an API endpoint which can copy an engagement by Id, so that I can create a solid starting point for analysing findings on my new work.

In terms of the API I would like to see an endpoint under the engagements model with a path /api/v2/engagements/{id}/copy, this would create a new engagement which is a clone of the engagement referenced by {id}.

This API would yield the same result as the copy functionality which can be achieved by the GUI.

Describe alternatives you've considered
We've considered reproducing the calls that the GUI does under the Copy functionality in order to be able to automate this, but it proves close to impossible because of tokens and access that is required to set this up in a clean way.

Another alternative we've considered is to reconstruct the copy functionality by using the API endpoints that are available, however some things like adding risk acceptances to an engagement does not seem possible via the available endpoints.

[mtesauro]

I did an Office hours video recently that covered the very situation you're facing without needing to copy engagements and in a way that is more likely to produce the results you want vs the options you've tried.

If you look for the February 2025 Office Hours video "Common Use Cases in DefectDojo" you'll find it. Here's a direct link as well.

You can skip to the fake example company "Sassy Software" which uses main/feature branches pretty much like you describe above. I explain how the organize their data into engagements & tests, how the setup dedup to work best for them and how they use RBAC (might not be an issue for you).

Also, if you're not familiar with it, you should look at the auto_create_context option on the /api/v2/reimport-scan/ & /api/v2/import-scan/ endpoints:

which makes coping an existing engagement not necessary. You can create a new structure (engagement => Test) in one API call.

Finally, if you're using CICD or automation to run the tests against your repo, you should look at reimport as that's what you'll want to make your life easier:
https://docs.defectdojo.com/en/working_with_findings/finding_deduplication/avoiding_duplicates_via_reimport/

[Hertog-PJ]

Hi Matt, thanks for your quick response :)

It seems that indeed the 'Sassy Software' usecase is similar to what we want to achieve.

I just tried the reimport-scan with auto-create-context option enabled. What I seem to miss with how I tried to recreate it, is that for example Risk Acceptances of findings don't carry over between engagements that have the same findings.

To me it seems reasonable that if a finding X is accepted on the main branch version 1.0.0, that this same finding X that would be present on a feature branch or the next version of that branch still carries the same risk acceptance on that finding. The reasoning behind that is that when, for whatever (undesirable) reason, you get a long list of accepted findings, it will quickly pollute any new engagements you create. It would be cumbersome to check the findings for a new feature branch and you'd first have to check which of the findings were actually an accepted risk for the time being. This would take the attention away to any new findings that have been introduced or verifying if a specific findings has been resolved in the feature branch.

Is it possible to have these risk acceptance of findings carry over between engagements if the findings are the same?

With the copy functionality via the GUI the risk acceptances do carry over and that's why we are interested in exposing that functionality via the API for automation purposes.

Please let me know if you'd like any clarification on our situation.