> ## Documentation Index > Fetch the complete documentation index at: https://bloodhound.specterops.io/llms.txt > Use this file to discover all available pages before exploring further. # Upserts the OpenGraph Extension > **Experimental** - Upserts the OpenGraph extension Applies to BloodHound Enterprise and CE ## OpenAPI ````yaml put /api/v2/extensions openapi: 3.0.3 info: title: BloodHound API contact: name: BloodHound Enterprise Support url: https://bloodhound.specterops.io/ email: support@specterops.io license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: v2 description: > This is the API that drives BloodHound Enterprise and Community Edition. Endpoint availability is denoted using the `Community` and `Enterprise` tags. Contact information listed is for BloodHound Enterprise customers. To get help with BloodHound Community Edition, please join our [Slack community](https://ghst.ly/BHSlack/). ## Authentication The BloodHound API supports two kinds of authentication: JWT bearer tokens and Signed Requests. For quick tests or one-time calls, the JWT used by your browser may be the simplest route. For more secure and long lived API integrations, the recommended option is signed requests. ### JWT Bearer Token The API will accept calls using the following header structure in the HTTP request: ``` Authorization: Bearer $JWT_TOKEN ``` If you open the Network tab within your browser, you will see calls against the API made utilizing this structure. JWT bearer tokens are supported by the BloodHound API, however it is recommended they only be used for temporary access. JWT tokens expire after a set amount of time and require re-authentication using secret credentials. ### Signed Requests Signed requests are the recommended form of authentication for the BloodHound API. Not only are signed requests better for long lived integrations, they also provide more security for the requests being sent. They provide authentication of the client, as well as verification of request integrity when received by the server. Signed requests consist of three main parts: The client token ID, the request timestamp, and a base64 encoded HMAC signature. These three pieces of information are sent with the request using the following header structure: ``` Authorization: bhesignature $TOKEN_ID RequestDate: $RFC3339_DATETIME Signature: $BASE64ENCODED_HMAC_SIGNATURE ``` To use signed requests, you will need to generate an API token. Each API token generated in the BloodHound API comes with two parts: The Token ID, which is used in the `Authorization` header, and the Token Key, which is used as part of the HMAC hashing process. The token ID should be considered as public (like a username) and the token key should be considered secret (like a password). Once an API token is generated, you can use the key to sign requests. For more documentation about how to work with authentication in the API, including examples of how to generate an API token in the BloodHound UI, please refer to this support doc: [Working with the BloodHound API](https://bloodhound.specterops.io/integrations/bloodhound-api/working-with-api). #### Signed Request Pseudo-code Example First, a digest is initiated with HMAC-SHA-256 using the token key as the digest key: ```python digester = hmac.new(sha256, api_token_key) ``` OperationKey is the first HMAC digest link in the signature chain. This prevents replay attacks that seek to modify the request method or URI. It is composed of concatenating the request method and the request URI with no delimiter and computing the HMAC digest using the token key as the digest secret: ```python # Example: GET /api/v2/test/resource HTTP/1.1 # Signature Component: GET/api/v2/test/resource digester.write(request_method + request_uri) # Update the digester for further chaining digester = hmac.New(sha256, digester.hash()) ``` DateKey is the next HMAC digest link in the signature chain. This encodes the RFC3339 formatted datetime value as part of the signature to the hour to prevent replay attacks that are older than max two hours. This value is added to the signature chain by cutting off all values from the RFC3339 formatted datetime from the hours value forward: ```python # Example: 2020-12-01T23:59:60Z # Signature Component: 2020-12-01T23 request_datetime = date.now() digester.write(request_datetime[:13]) # Update the digester for further chaining digester = hmac.New(sha256, digester.hash()) ``` Body signing is the last HMAC digest link in the signature chain. This encodes the request body as part of the signature to prevent replay attacks that seek to modify the payload of a signed request. In the case where there is no body content the HMAC digest is computed anyway, simply with no values written to the digester: ```python if request.body is not empty: digester.write(request.body) ``` Finally, base64 encode the final hash and write the three required headers before sending the request: ```python encoded_hash = base64_encode(digester.hash()) request.header.write('Authorization', 'bhesignature ' + token_id) request.header.write('RequestDate', request_datetime) request.header.write('Signature', encoded_hash) ``` servers: - url: https://your-tenant.bloodhoundenterprise.io description: >- This is the base path for all endpoints, relative to the domain where the API is being hosted. security: - JWTBearerToken: [] - SignedRequest: [] RequestDate: [] HMACSignature: [] paths: /api/v2/extensions: put: tags: - OpenGraph (Experimental) - Community - Enterprise summary: Upserts the OpenGraph Extension description: '**Experimental** - Upserts the OpenGraph extension' operationId: UpsertOpenGraphExtension requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/model.graph-extension.payload' examples: Generic: summary: Generic OpenGraph Extension Example description: An example generic OpenGraph Extension payload. value: schema: name: OpenGraph_Extension display_name: OpenGraph Extension version: v1.0.0 namespace: OGE node_kinds: - name: OGE_Node_Kind_1 display_name: Node Kind 1 description: A generic node kind is_display_kind: true icon: computer color: '#FF0000' - name: OGE_Node_Kind_2 display_name: Node Kind 2 description: A secondary generic node kind is_display_kind: false - name: OGE_Environment_Kind display_name: Environment description: A generic environment kind icon: sitemap color: '#00FF00' is_display_kind: true relationship_kinds: - name: OGE_ConnectedTo description: A generic relationship kind is_traversable: true environments: - environment_kind: OGE_Environment_Kind source_kind: OGExtension principal_kinds: - OGE_Node_Kind_1 - OGE_Node_Kind_2 relationship_findings: - name: OGE_Finding_1 display_name: Finding 1 relationship_kind: OGE_ConnectedTo environment_kind: OGE_Environment_Kind remediation: short_description: a remediation long_description: a remediation to fix Finding 1 short_remediation: Do X long_remediation: Do X to fix Finding 1 Active Directory: summary: Active Directory Example description: >- An example Active Directory OpenGraph Extension. As a note, the Active Directory objects in the DB do not currently conform to the expected validation rules. This will change in the future. The example provided is how an Active Directory extension would look in the OpenGraph framework. value: schema: name: Active_Directory display_name: Active Directory version: v1.0.0 namespace: AD node_kinds: - name: AD_Computer display_name: Computer description: An Active Directory Computer object is_display_kind: true icon: computer color: '#FF0000' - name: AD_User display_name: User description: An Active Directory User object is_display_kind: true icon: user color: '#0000FF' - name: AD_LocalGroup display_name: Local Group description: An Active Directory Local Group object is_display_kind: false - name: AD_Domain display_name: Domain description: An Active Directory Domain environment object icon: sitemap color: '#00FF00' is_display_kind: true relationship_kinds: - name: AD_MemberOf description: An Active Directory relationship kind is_traversable: true environments: - environment_kind: AD_Domain source_kind: ActiveDirectory principal_kinds: - AD_User - AD_Computer relationship_findings: - name: AD_Finding_1 display_name: Finding 1 (Active Directory) relationship_kind: AD_MemberOf environment_kind: AD_Domain remediation: short_description: a remediation long_description: a remediation to fix Finding 1 short_remediation: Do X long_remediation: Do X to fix Finding 1 responses: '200': description: OK '201': description: CREATED '400': $ref: '#/components/responses/bad-request' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/not-found' '429': $ref: '#/components/responses/too-many-requests' '500': $ref: '#/components/responses/internal-server-error' components: schemas: model.graph-extension.payload: type: object properties: schema: type: object properties: name: type: string example: OpenGraph_Extension display_name: type: string example: OpenGraph Extension version: type: string example: v1.0.0 namespace: type: string example: OGE node_kinds: type: array items: type: object properties: name: type: string example: OGE_Computer display_name: type: string example: OGE Computer description: type: string example: An OpenGraph Extension Computer object is_display_kind: type: boolean icon: type: string example: Desktop color: type: string example: '#FF0000' relationship_kinds: type: array items: type: object properties: name: type: string example: OGE_ConnectedTo description: type: string example: An OpenGraph Extension ConnectedTo edge is_traversable: type: boolean environments: type: array items: type: object properties: environment_kind: type: string example: OGE_Environment source_kind: type: string example: OGExtension principal_kinds: type: array items: type: string example: - OGE_User - OGE_Computer relationship_findings: type: array items: type: object properties: name: type: string example: OGE_Malicious_Finding_1 display_name: type: string example: Malicious Finding 1 (OG Extension) relationship_kind: type: string example: OGE_ConnectedTo environment_kind: type: string example: OGE_Environment remediation: type: object properties: short_description: type: string long_description: type: string short_remediation: type: string long_remediation: type: string api.error-wrapper: type: object description: '' properties: http_status: type: integer description: The HTTP status code minimum: 100 maximum: 600 timestamp: type: string format: date-time description: The RFC-3339 timestamp in which the error response was sent request_id: type: string format: uuid description: The unique identifier of the request that failed errors: type: array items: $ref: '#/components/schemas/api.error-detail' description: The error(s) that occurred from processing the request api.error-detail: type: object properties: context: type: string description: The context in which the error took place message: type: string description: A human-readable description of the error responses: bad-request: description: > **Bad Request** This could be due to one of the following reasons: - JSON payload is missing or malformed - Path or query parameters are missing or invalid/malformed - The data sent is not valid (ex- sending a `string` in an `integer` field) content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 400 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: The JSON payload could not be unmarshalled. unauthorized: description: > **Unauthorized** This endpoint failed an authentication requirement. Either the client tried to access a protected endpoint without being authenticated, or an auth validation failed (ex- invalid credentials or expired token). content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 401 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: login message: Unauthorized forbidden: description: | **Forbidden** This is most commonly caused by an authenticated client trying to access a resource that it does not have permission for. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 403 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: You do not have permission to access this resource not-found: description: > **Not Found** This error typically comes from operations where a valid ID was passed to the request to look up an entity but the entity could not be found. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 404 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: The requested client could not be found. too-many-requests: description: | **Too Many Requests** The client has sent too many requests within a certain time window and tripped the rate limiting middleware. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 429 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: middleware message: Too many requests. Please try again later. internal-server-error: description: > **Internal Server Error** This is usually the result of either an unexpected database or application error. The client may try modifying or resending the request, but the error is likely not related to the client doing something wrong. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 500 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: >- The request could not be handled due to an unexpected database error. securitySchemes: JWTBearerToken: description: | `Authorization: Bearer $JWT_TOKEN` type: http scheme: bearer bearerFormat: JWT SignedRequest: description: | `Authorization: bhesignature $TOKEN_ID` type: apiKey name: Authorization in: header RequestDate: description: | `RequestDate: $RFC3339_DATETIME` type: apiKey name: RequestDate in: header HMACSignature: description: | `Signature: $BASE64ENCODED_HMAC_SIGNATURE` type: apiKey name: Signature in: header ````