BP-2211: OpenGraph tutorial/quickstart

[jeff-matthews]

Purpose

This pull request (PR) adds a new tutorial/quickstart guide for OpenGraph.

TODO

• Confirm whether Base kind is required for simple search (if so, does that complicate deleting Person data on the DB mgmt page?)
• Confirm whether simple search should display custom node icons and colors
• Ensure OpenGraph iconography in docs aligns with internal decision to use circle-nodes

Staging

https://specterops-bp-2211-og-specific-updates.mintlify.app/opengraph/quickstart

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[craigw-SO]

This is a great start, and SO much better than anything we have right now. There were a handful of comments related to the intricacies of how things work, so I think this exercise alone is worth hammering out what expected behaviors and best practices are.

Reminder that I'm out the next two days. Not sure if we were aiming to release this with the v8.5 release or if there's time to keep honing this.

[craigw-SO]

Before we have the user create the file, would it be helpful to first reiterate that the basic structure is:

{
"metadata": {
"source_kind": "Person"
},
"graph": {
"nodes": [
...
],
"edges": [
...
]
}
}

As either a reminder OR a first inform, and then include a link that goes to the schema documentation where this is mentioned, as well as the broader schema.

[craigw-SO]

I think we need to pick a different source_kind and not Person. For context, source_kind refers to the data source, which is the system that the data reflects. For our built-in schemas, "Base" is the source_kind for Active Directory, and "AZBase" is the source_kind for Azure. I think it would be better to reflect this naming convention and do something like "EXBase".

Additional points of clarification:

1. Currently, the first kind listed in each node's kind list is the "Primary Kind", and determines which node type (and icon representation) is associated with that node
2. If the source_kind is declared in the metadata, then there's no need to apply it to each node individually. Using the source_kind automatically applies that kind to each of the nodes in the payload.

• We had received feedback that it was difficult to manage all of these custom nodes, and so we made a way to quickly tag and group them
• Using the source_kind also officially "registers" the kind as as source kind. That is required in order for a source_kind to show up in the DB Mgmt page for removal.
• Registering only has to be done once though. After it's been registered, the source_kind can be added to nodes individually and it will be recognized as a source.
• I'm not sure what would happen if you used a source_kind as the primary kind for something. I don't think it would be bad, but I haven't tested it, and there could be unexpected behavior.

3. We should avoid using the "Base" source_kind as that ties the data into the graph as if it were generated by SharpHound. The only way to remove it would be to delete all of the AD data out of the graph. Hence why we created a way to label OG data as belonging to different sources, for cleaner mgmt.

• "Base" could be used to reference existing nodes for hybrid edges, but I'd consider that a "201" level course and not an intro "101" type of thing.

[craigw-SO]

Same deal here, we shouldn't use "Person". Recommend "EXBase". I also wouldn't say that it

... identifies the type of data
so much as it identifies the source of the data, as in the system the data represents.

We may also want to call out here that using the source_kind property is the only way to register a kind as such, which is what populates the DB Mgmt page. Again, only has to be done once ever (unless DB is wiped), but if you don't use it at least once, it's treated as a regular old kind, no different than User or Group.

[craigw-SO]

"Base" is NOT required, and we should actually avoid "Base" (and "AZBase") specifically unless we're trying to create hybrid edges.

Other things we may want to call out here:

• Have to have at least one kind, may want to mention the actual limit to how many kinds there can be, too
• The first kind is the "Primary Kind" that determines which type the node is, and which icon is used to represent
• A source_kind is not required here, but can be added to specific nodes if the source_kind property isn't used in the meta_data

[craigw-SO]

It doesn't have to match a node ID, if you use the match_by: "name" option. Might be better to just say

... that must match either a pre-existing node, or a node declared above in the same payload

May want to avoid the match_by: "name" option for now though, as the matching gets much trickier and can seem buggy when it's really just finicky/nuanced.

Important to point out that the nodes declared as the vertices of the edge don't have to be declared in the same payload. You can create all the nodes you want in advance, and then create the edges after. In fact, that's part of our recommendation for how to generate hybrid edges right now.

[craigw-SO]

Should confirm whether everyone has access to those or not. If limited, then specify which role can do so.

[craigw-SO]

And that the # is included, I believe

[craigw-SO]

May want to call out that they're just "ID" in the payload, but objectID as represented in the graph/entity panel.

[craigw-SO]

A troubleshooting issue that can occur is that duplicate nodes can be created if there's not a perfect match. Not sure if this should be here or in the FAQ tho.

[craigw-SO]

Something that I didn't see called out is that in BHE, all nodes must have at least one edge connecting them to other nodes. Otherwise, they'll get cleaned up by the built-in reconciliation process. Our getting started example already does that, but when you get into more advanced graph generation, you may want to make nodes first and then link them. But in BHE there has to at least be one edge to each. We call it out in the FAQ, I think, but would probably be wise to point out at least in a tooltip here.

[jeff-matthews]

Thanks for the thorough and thoughtful initial review @craigw-SO!

Since we need more time to refine the quickstart, I'll move the smaller updates to the BH intro, OpenGraph FAQ, and updated iconography to a separate, smaller PR for release (#158).

That'll give us more time to iterate on the quickstart while ensuring the product intro, FAQ, and icons are correct on release, which seems more important right now.