feat: queue managment operation endpoints BED-8089

[lrfalslev]

Description

Adds queue management operation endpoint to openapi schema, for BHE pr 1565

Motivation and Context

Resolves BED-8089

Why is this change required? What problem does it solve?

How Has This Been Tested?

Please describe in detail how you tested your changes.
Include details of your testing environment, and the tests you ran to
see how your change affects other areas of the code, etc.

Screenshots (optional):

Types of changes

• Chore (a change that does not modify the application functionality)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Database Migrations

Checklist:

• I have met the contributing prerequisites
  • Assigned myself to this PR
  • Added the appropriate labels
  • Associated an issue: Issues and Pull Requests README #672
  • Read the Contributing guide: https://github.com/SpecterOps/BloodHound/wiki/Contributing
• I have ensured that related documentation is up-to-date
  • Open API docs
  • Code comments (GoDocs / JSDocs)
• I have followed proper test practices
  • Added/updated tests to cover my changes
  • All new and existing tests passed

Summary by CodeRabbit

• New Features
  • Added a new API endpoint to queue client management operations for a specific client.
  • Request payloads now require an operation_type and an execution_time timestamp.
  • Responses return details of the queued management operation.
  • Documented supported operation types and standard error responses (400/401/403/404/429/500).

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 294411c1-2e01-4035-949f-7864f72b3023

📥 Commits

Reviewing files that changed from the base of the PR and between 5e3f7bc and 2f264e2.

📒 Files selected for processing (4)

• packages/go/openapi/doc/openapi.json
• packages/go/openapi/src/openapi.yaml
• packages/go/openapi/src/paths/clients.clients.id.management.yaml
• packages/go/openapi/src/schemas/model.client-management-operation-queue-request.yaml

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/go/openapi/src/schemas/model.client-management-operation-queue-request.yaml
• packages/go/openapi/src/paths/clients.clients.id.management.yaml
• packages/go/openapi/src/openapi.yaml

---

📝 Walkthrough

Walkthrough

Adds a POST endpoint for queuing client management operations, including its request schema, success responses, and documented error responses.

Changes

Client management operation API

Layer / File(s)	Summary
Operation request and response contract packages/go/openapi/src/schemas/model.client-management-operation-queue-request.yaml, packages/go/openapi/doc/openapi.json	Defines required operation_type and execution_time fields, including the operation type reference and date-time format.
Queue operation endpoint wiring packages/go/openapi/src/paths/clients.clients.id.management.yaml, packages/go/openapi/src/openapi.yaml, packages/go/openapi/doc/openapi.json	Registers POST /api/v2/clients/{client_id}/management with UUID client identification, queue request handling, 200/201 responses, and documented error responses.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• SpecterOps/BloodHound#2948: Extends related client management operation endpoints and shared schemas.
• SpecterOps/BloodHound#2984: Extends the client management operations OpenAPI surface and related schemas.

Suggested labels: api, enhancement

Suggested reviewers: sirisjo, lawsonwillard, brandonshearin

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is specific and matches the added queue-management OpenAPI endpoint and related schema work.
Description check	✅ Passed	The PR description follows the required template and includes the ticket, description, and checklist, though testing details are sparse.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lfalslev/bed-8089

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Checkov (3.3.8)

packages/go/openapi/src/openapi.yaml

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

packages/go/openapi/src/paths/clients.clients.id.management.yaml

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

packages/go/openapi/src/schemas/model.client-management-operation-queue-request.yaml

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

• 1 others

🔧 oasdiff (1.23.0)

packages/go/openapi/src/openapi.yaml

Error: failed to load base spec from "/tmp/coderabbit-oasdiff-base.7BdaOr": encountered disallowed external reference: "./paths/eula.accept-eula.yaml"

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/go/openapi/src/paths/clients.clients.id.management.yaml (1)

41-59: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Clarify when 200 vs 201 is returned.

Both success responses return the identical model.client-management-operation schema with no description distinguishing them. Since this looks like an idempotent-queue pattern (200 for an already-queued/existing operation, 201 for a newly created one), a short note in the endpoint description or per-response description would help API consumers understand which to expect and why.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/go/openapi/src/paths/clients.clients.id.management.yaml` around
lines 41 - 59, Clarify the status-code semantics for the 200 and 201 responses
in the client management operation endpoint: update the endpoint or per-response
descriptions to state that 200 indicates an existing/already-queued operation,
while 201 indicates a newly created operation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/go/openapi/src/paths/clients.clients.id.management.yaml`:
- Around line 41-69: Add a 404 response to this endpoint’s responses,
referencing the existing not-found response definition used by sibling
client-scoped operations such as GetClient, UpdateClient, and DeleteClient. Keep
the existing 400, 401, 403, 429, and 500 responses unchanged.

---

Nitpick comments:
In `@packages/go/openapi/src/paths/clients.clients.id.management.yaml`:
- Around line 41-59: Clarify the status-code semantics for the 200 and 201
responses in the client management operation endpoint: update the endpoint or
per-response descriptions to state that 200 indicates an existing/already-queued
operation, while 201 indicates a newly created operation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: f306e065-ff29-496e-a882-fef39c0e0d8a

📥 Commits

Reviewing files that changed from the base of the PR and between 275141e and 51c28e1.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (8)

• go.mod
• packages/go/openapi/doc/openapi.json
• packages/go/openapi/src/openapi.yaml
• packages/go/openapi/src/paths/clients.clients.id.management.yaml
• packages/go/openapi/src/schemas/enum.client-management-operation-status.yaml
• packages/go/openapi/src/schemas/enum.client-management-operation-type.yaml
• packages/go/openapi/src/schemas/model.client-management-operation-queue-request.yaml
• packages/go/openapi/src/schemas/model.client-management-operation.yaml