SpecterOps Graph API

openapi: 3.2.0
info:
  title: BloodHound Graph 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.
servers:
- url: /
  description: This is the base path for all endpoints, relative to the domain where the API is being hosted.
security:
- JWTBearerToken: []
- SignedRequest: []
  RequestDate: []
  HMACSignature: []
tags:
- name: Graph
paths:
  /api/v2/graphs/kinds:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetKinds
      summary: Get kinds
      description: Gets kinds
      tags:
      - Graph
      parameters:
      - name: type
        in: query
        description: Filter by type, valid types are node or edge, e.g. "eq:node"
        required: false
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string-strict'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      kinds:
                        type: array
                        items:
                          type: string
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/pathfinding:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: Pathfinding
      deprecated: true
      summary: Get pathfinding result
      description: DEPRECATED use GetShortestPath instead. Get the result of pathfinding between two nodes in graph format.
      tags:
      - Graph
      parameters:
      - name: start_node
        description: Start Node
        in: query
        required: true
        schema:
          type: string
      - name: end_node
        description: End Node
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.bh-graph.graph'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/graph-search:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetSearchResult
      summary: Get search result
      description: Get the result of searching a graph for a node by name
      tags:
      - Graph
      parameters:
      - name: query
        description: Search query
        in: query
        required: true
        schema:
          type: string
      - name: type
        description: The type of search strategy to use. Default is `fuzzy`.
        in: query
        schema:
          type: string
          enum:
          - fuzzy
          - exact
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/model.bh-graph.node'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/graphs/shortest-path:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetShortestPath
      summary: Get the shortest path graph
      description: A graph of the shortest path from `start_node` to `end_node`.
      tags:
      - Graph
      parameters:
      - name: start_node
        description: The start node objectId
        in: query
        required: true
        schema:
          type: string
      - name: end_node
        description: The end node objectId
        in: query
        required: true
        schema:
          type: string
      - name: relationship_kinds
        description: Specific relationship kinds to include in the pathfinding search. If the kinds are not valid kinds, the query will error.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.contains'
      - name: only_traversable
        description: Whether or not to only include traversable kinds. If true and no `relationship_kinds` are specified, all traversable kinds will be searched. If true, and `relationship_kinds` param includes non-traversable kinds, the non-traversable kinds will be excluded from the path search. If false or omitted, all kinds will be searched.
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: A graph of the shortest path from `start_node` to `end_node`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.unified-graph.graph'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/graphs/edge-composition:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetPathComposition
      summary: Get path composition
      description: Returns a graph representing the various nodes and edges that make up the complex post-processed edge.
      tags:
      - Graph
      parameters:
      - name: source_node
        description: The ID of the starting node.
        in: query
        required: true
        schema:
          type: integer
          format: int32
      - name: target_node
        description: The ID of the ending node.
        in: query
        required: true
        schema:
          type: integer
          format: int32
      - name: edge_type
        description: The type of edge to show the composition for.
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns graph data that contains a collection of nodes and edges related to the composition of the edge queried.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.unified-graph.graph'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/graphs/relay-targets:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetRelayTargets
      summary: Get relay targets
      description: Returns a graph representing the various nodes that are valid relay targets for this edge
      tags:
      - Graph
      parameters:
      - name: source_node
        description: The ID of the starting node.
        in: query
        required: true
        schema:
          type: integer
          format: int32
      - name: target_node
        description: The ID of the ending node.
        in: query
        required: true
        schema:
          type: integer
          format: int32
      - name: edge_type
        description: The type of edge to show the composition for.
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns graph data that contains a collection of nodes that are valid relay targets related to the composition of the edge queried.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.unified-graph.graph'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/graphs/acl-inheritance:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetACLInheritancePath
      summary: Get ACL inheritance path
      description: Returns a graph representing the path that an ACE is inherited through for a given edge.
      tags:
      - Graph
      parameters:
      - name: source_node
        description: The ID of the starting node.
        in: query
        required: true
        schema:
          type: integer
          format: int32
      - name: target_node
        description: The ID of the ending node.
        in: query
        required: true
        schema:
          type: integer
          format: int32
      - name: edge_type
        description: The type of edge the ACL inheritance path is being fetched for.
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns graph data that contains a collection of nodes and edges that make up the ACL inheritance path.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.unified-graph.graph'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
components:
  responses:
    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
    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.
    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
    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.
    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.
  schemas:
    model.bh-graph.graph:
      type: object
      additionalProperties:
        anyOf:
        - $ref: '#/components/schemas/model.bh-graph.node'
        - $ref: '#/components/schemas/model.bh-graph.edge'
    model.bh-graph.item:
      type: object
      properties:
        color:
          type: string
        fade:
          type: boolean
        data:
          type: object
          additionalProperties: true
        glyphs:
          type: array
          items:
            $ref: '#/components/schemas/model.bh-graph.glyph'
    model.unified-graph.graph:
      type: object
      properties:
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/model.unified-graph.node'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/model.unified-graph.edge'
    model.unified-graph.edge:
      type: object
      properties:
        source:
          type: string
        target:
          type: string
        label:
          type: string
        kind:
          type: string
        lastSeen:
          type: string
          format: date-time
        properties:
          type: object
          additionalProperties:
            type: object
    model.unified-graph.node:
      type: object
      properties:
        label:
          type: string
        kind:
          type: string
        kinds:
          type: array
          items:
            type: string
        objectId:
          type: string
        isTierZero:
          type: boolean
        isOwnedObject:
          type: boolean
        lastSeen:
          type: string
          format: date-time
        properties:
          type: object
          additionalProperties:
            type: object
    model.bh-graph.glyph:
      type: object
      properties:
        angle:
          type: integer
        blink:
          type: boolean
        border:
          $ref: '#/components/schemas/model.bh-graph.item-border'
        color:
          type: string
        fontIcon:
          $ref: '#/components/schemas/model.bh-graph.font-icon'
        image:
          type: string
        label:
          $ref: '#/components/schemas/model.bh-graph.label'
        position:
          type: string
        radius:
          type: integer
        size:
          type: integer
    model.bh-graph.edge:
      allOf:
      - $ref: '#/components/schemas/model.bh-graph.item'
      - type: object
        properties:
          end1:
            $ref: '#/components/schemas/model.bh-graph.link-end'
          end2:
            $ref: '#/components/schemas/model.bh-graph.link-end'
          flow:
            type: object
            properties:
              velocity:
                type: integer
          id1:
            type: string
          id2:
            type: string
          label:
            $ref: '#/components/schemas/model.bh-graph.label'
          lineStyle:
            type: string
          width:
            type: integer
    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
    api.params.predicate.filter.contains:
      type: string
      pattern: ^(in|nin):(\w+)(,\s*\w+)*$
      description: "The contains predicate checks a property against the values in a given comma separated list.\n- `in` checks if the property matches an element in the given comma separated list.\n  - `in:Contains,GetChangesAll,MemberOf`\n- `nin` checks if the property does not match an element in the given comma separated list.\n  - `nin:LocalToComputer,MemberOfLocalGroup`\n"
    model.bh-graph.item-border:
      type: object
      properties:
        color:
          type: string
    api.params.predicate.filter.string-strict:
      type: string
      pattern: ^((eq|neq):)?[^:]+$
      description: 'Filter results by column string value. Valid filter predicates are `eq`, `neq`.

        '
    model.bh-graph.node:
      allOf:
      - $ref: '#/components/schemas/model.bh-graph.item'
      - type: object
        properties:
          border:
            type: object
            properties:
              color:
                type: string
              lineStyle:
                type: string
              width:
                type: integer
          coordinates:
            type: object
            properties:
              lat:
                type: integer
              lng:
                type: integer
          cutout:
            type: boolean
          fontIcon:
            $ref: '#/components/schemas/model.bh-graph.font-icon'
          halos:
            type: array
            items:
              type: object
              properties:
                color:
                  type: string
                radius:
                  type: integer
                width:
                  type: integer
          image:
            type: string
          label:
            type: object
            properties:
              backgroundColor:
                type: string
              bold:
                type: boolean
              center:
                type: boolean
              color:
                type: string
              fontFamily:
                type: string
              fontSize:
                type: integer
              text:
                type: string
          shape:
            type: string
          size:
            type: integer
    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
    model.bh-graph.label:
      type: object
      properties:
        bold:
          type: boolean
        color:
          type: string
        fontFamily:
          type: string
        text:
          type: string
    model.bh-graph.link-end:
      type: object
      properties:
        arrow:
          type: boolean
        backOff:
          type: integer
        color:
          type: string
        glyphs:
          type: array
          items:
            $ref: '#/components/schemas/model.bh-graph.glyph'
        label:
          $ref: '#/components/schemas/model.bh-graph.label'
    model.bh-graph.font-icon:
      type: object
      properties:
        color:
          type: string
        fontFamily:
          type: string
        text:
          type: string
  parameters:
    header.prefer:
      name: Prefer
      description: Prefer header, used to specify a custom timeout in seconds using the wait parameter as per RFC7240. Passing in wait=-1 bypasses all timeout limits when the feature is enabled.
      in: header
      required: false
      schema:
        type: string
        default: wait=30
        pattern: ^wait=(-1|[0-9]+)$
  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
x-tagGroups:
- name: Community & Enterprise
  tags:
  - Auth
  - Roles
  - Permissions
  - API Tokens
  - BloodHound Users
  - Collectors
  - Collection Uploads
  - Custom Node Management
  - API Info
  - Search
  - Audit
  - Config
  - Asset Isolation
  - Graph
  - Azure Entities
  - AD Base Entities
  - Computers
  - Containers
  - Domains
  - GPOs
  - AIA CAs
  - Root CAs
  - Enterprise CAs
  - NT Auth Stores
  - Cert Templates
  - OUs
  - AD Users
  - Groups
  - Data Quality
  - Datapipe
  - Cypher
  - OpenGraph (Experimental)
- name: Enterprise Only
  tags:
  - EULA
  - BHE Users
  - Analysis
  - Client Ingest
  - Clients
  - Jobs
  - Tasks
  - Events (Schedules)
  - Attack Paths
  - Risk Posture
  - Meta Entities
  - Alerts