NetBird Posture Checks API

openapi: 3.1.0
info:
  title: NetBird REST Accounts Posture Checks API
  description: API to manipulate groups, rules, policies and retrieve information about peers and users
  version: 0.0.1
servers:
- url: https://api.netbird.io
  description: Default server
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: Posture Checks
  description: Interact with and view information about posture checks.
paths:
  /api/posture-checks:
    get:
      summary: List all Posture Checks
      description: Returns a list of all posture checks
      tags:
      - Posture Checks
      security:
      - BearerAuth: []
      - TokenAuth: []
      responses:
        '200':
          description: A JSON Array of posture checks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostureCheck'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal_error'
    post:
      summary: Create a Posture Check
      description: Creates a posture check
      tags:
      - Posture Checks
      security:
      - BearerAuth: []
      - TokenAuth: []
      requestBody:
        description: New posture check request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostureCheckUpdate'
      responses:
        '200':
          description: A posture check Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
  /api/posture-checks/{postureCheckId}:
    get:
      summary: Retrieve a Posture Check
      description: Get information about a posture check
      tags:
      - Posture Checks
      security:
      - BearerAuth: []
      - TokenAuth: []
      parameters:
      - in: path
        name: postureCheckId
        required: true
        schema:
          type: string
        description: The unique identifier of a posture check
      responses:
        '200':
          description: A posture check object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal_error'
    put:
      summary: Update a Posture Check
      description: Update/Replace a posture check
      tags:
      - Posture Checks
      security:
      - BearerAuth: []
      - TokenAuth: []
      parameters:
      - in: path
        name: postureCheckId
        required: true
        schema:
          type: string
        description: The unique identifier of a posture check
      requestBody:
        description: Update Rule request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostureCheckUpdate'
      responses:
        '200':
          description: A posture check object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal_error'
    delete:
      summary: Delete a Posture Check
      description: Delete a posture check
      tags:
      - Posture Checks
      security:
      - BearerAuth: []
      - TokenAuth: []
      parameters:
      - in: path
        name: postureCheckId
        required: true
        schema:
          type: string
        description: The unique identifier of a posture check
      responses:
        '200':
          description: Delete status code
          content: {}
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal_error'
components:
  schemas:
    Process:
      description: Describes the operational activity within a peer's system.
      type: object
      properties:
        linux_path:
          description: Path to the process executable file in a Linux operating system
          type: string
          example: /usr/local/bin/netbird
        mac_path:
          description: Path to the process executable file in a Mac operating system
          type: string
          example: /Applications/NetBird.app/Contents/MacOS/netbird
        windows_path:
          description: Path to the process executable file in a Windows operating system
          type: string
          example: 'C:
            rogramData etBird

            etbird.exe'
    NBVersionCheck:
      description: Posture check for the version of NetBird
      type: object
      $ref: '#/components/schemas/MinVersionCheck'
    ProcessCheck:
      description: Posture Check for binaries exist and are running in the peer’s system
      type: object
      properties:
        processes:
          type: array
          items:
            $ref: '#/components/schemas/Process'
      required:
      - processes
    MinVersionCheck:
      description: Posture check for the version of operating system
      type: object
      properties:
        min_version:
          description: Minimum acceptable version
          type: string
          example: '14.3'
      required:
      - min_version
    PostureCheckUpdate:
      type: object
      properties:
        name:
          description: Posture check name identifier
          type: string
          example: Default
        description:
          description: Posture check friendly description
          type: string
          example: This checks if the peer is running required NetBird's version
        checks:
          $ref: '#/components/schemas/Checks'
      required:
      - name
      - description
    Location:
      description: Describe geographical location information
      type: object
      properties:
        country_code:
          $ref: '#/components/schemas/CountryCode'
        city_name:
          $ref: '#/components/schemas/CityName'
      required:
      - country_code
    OSVersionCheck:
      description: Posture check for the version of operating system
      type: object
      properties:
        android:
          description: Minimum version of Android
          $ref: '#/components/schemas/MinVersionCheck'
        darwin:
          $ref: '#/components/schemas/MinVersionCheck'
        ios:
          description: Minimum version of iOS
          $ref: '#/components/schemas/MinVersionCheck'
        linux:
          description: Minimum Linux kernel version
          $ref: '#/components/schemas/MinKernelVersionCheck'
        windows:
          description: Minimum Windows kernel build version
          $ref: '#/components/schemas/MinKernelVersionCheck'
      example:
        android:
          min_version: '13'
        ios:
          min_version: 17.3.1
        darwin:
          min_version: 14.2.1
        linux:
          min_kernel_version: 5.3.3
        windows:
          min_kernel_version: 10.0.1234
    GeoLocationCheck:
      description: Posture check for geo location
      type: object
      properties:
        locations:
          description: List of geo locations to which the policy applies
          type: array
          items:
            $ref: '#/components/schemas/Location'
        action:
          description: Action to take upon policy match
          type: string
          enum:
          - allow
          - deny
          example: allow
      required:
      - locations
      - action
    PostureCheck:
      type: object
      properties:
        id:
          description: Posture check ID
          type: string
          example: ch8i4ug6lnn4g9hqv7mg
        name:
          description: Posture check unique name identifier
          type: string
          example: Default
        description:
          description: Posture check friendly description
          type: string
          example: This checks if the peer is running required NetBird's version
        checks:
          $ref: '#/components/schemas/Checks'
      required:
      - id
      - name
      - checks
    PeerNetworkRangeCheck:
      description: 'Posture check for allow or deny access based on the peer''s IP addresses. A range matches when it

        contains any of the peer''s local network interface IPs or its public connection (NAT egress) IP,

        so ranges may target private subnets, public CIDRs, or single hosts via a /32 or /128.

        '
      type: object
      properties:
        ranges:
          description: List of network ranges in CIDR notation, matched against the peer's local interface IPs and its public connection IP
          type: array
          items:
            type: string
          example:
          - 192.168.1.0/24
          - 10.0.0.0/8
          - 1.0.0.0/24
          - 2.2.2.2/32
          - 2001:db8:1234:1a00::/56
        action:
          description: Action to take upon policy match
          type: string
          enum:
          - allow
          - deny
          example: allow
      required:
      - ranges
      - action
    CountryCode:
      description: 2-letter ISO 3166-1 alpha-2 code that represents the country
      type: string
      example: DE
    MinKernelVersionCheck:
      description: Posture check with the kernel version
      type: object
      properties:
        min_kernel_version:
          description: Minimum acceptable version
          type: string
          example: 6.6.12
      required:
      - min_kernel_version
    Checks:
      description: List of objects that perform the actual checks
      type: object
      properties:
        nb_version_check:
          $ref: '#/components/schemas/NBVersionCheck'
        os_version_check:
          $ref: '#/components/schemas/OSVersionCheck'
        geo_location_check:
          $ref: '#/components/schemas/GeoLocationCheck'
        peer_network_range_check:
          $ref: '#/components/schemas/PeerNetworkRangeCheck'
        process_check:
          $ref: '#/components/schemas/ProcessCheck'
    CityName:
      description: Commonly used English name of the city
      type: string
      example: Berlin
  responses:
    forbidden:
      description: Forbidden
      content: {}
    internal_error:
      description: Internal Server Error
      content: {}
    requires_authentication:
      description: Requires authentication
      content: {}
    bad_request:
      description: Bad Request
      content: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Enter the token with the `Token` prefix, e.g. "Token nbp_F3f0d.....".