BED-4807: related-entity-query-results is no longer polymorphic

daviditkin commented 1 week ago

… is documented by the OpenAPI spec.

Description

The related-entity-query-results no longer describes a polymorphic result. Instead it only documents the list response. The other query types are still documented in query.entity.type.yaml . There is a note in the description that the graph is unsupported by the spec but can be used and points to the model.bh-graph.item schema as documentation of the results.

Motivation and Context

This PR addresses: Issue 848

The polymorphic result of related entity queries, related-entity-query-results, did not have an explicit discriminator which would is needed by the oapi-codegen code generator. Since there was no way to add a discriminator without breaking backwards compatibility, it was decided that for now we will only document the list query response, but provide some guidance in the description about where to look for the schema of a graph response.

How Has This Been Tested?

After the changes to the openapi spec I started up bloodhound, and ran an oapi-codegen generated client that performed both list and graph related entity queries. The list response matches the openapi spec modification.

Types of changes

New feature (non-breaking change which adds functionality)

Checklist:

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

daviditkin commented 1 week ago

@sircodemane I noticed while testing making a graph related entity query that model.bh-graph.item.yaml describes a schema where the data property is an object with an additionProperty object. (not boolean, but an unconstrained object)

oapi-codegen generates a map[string]map[string]interface{} modifying the spec to use a boolean results in map[string]interface{}

I'm not sure which is desired, so I've left this change out of the PR and we can discuss.

daviditkin commented 1 week ago

@sircodemane @irshadaj

In order to properly generate go code that can unmarshal a model.bh-graph.node I needed to change model.bh-graph.item's definition. The data property should not be an object with additional properties that are objects, but should be an object with additional properties. Only then can I properly unmarshal data like:

...
  },
  "13894" : {
    "color" : "#B153F3",
    "data" : {
      "name" : "ESC6A@PHANTOM.CORP",
      "nodetype" : "CertTemplate",
      "objectid" : "206BE95C-EFE3-4BA1-85CB-9EC6525171CF",
      "system_tags" : null
    },
    "border" : {
      "color" : "black"
    },
    "fontIcon" : {
      "text" : "fa-id-card"
    },
    "label" : {
      "backgroundColor" : "rgba(255,255,255,0.9)",
      "center" : true,
      "fontSize" : 14,
      "text" : "ESC6A@PHANTOM.CORP"
    },
    "size" : 1
  },
...

I could keep this as a separate change in a different PR, but it is required for SDK tests I run that show how to request a list response and how to request and unmarshal a graph response.

SpecterOps / BloodHound