[management] Feature/fleetdm api spec (#5597)

add fleetdm api spec
2026-04-16 07:16:38 +00:00 · 2026-03-31 14:03:34 +02:00
parent 6553ce4cea
commit 405c3f4003
3 changed files with 418 additions and 0 deletions
--- a/shared/management/client/rest/edr.go
+++ b/shared/management/client/rest/edr.go
@@ -265,6 +265,65 @@ func (a *EDRAPI) DeleteHuntressIntegration(ctx context.Context) error {
 	return nil
 }

+// GetFleetDMIntegration retrieves the EDR FleetDM integration.
+func (a *EDRAPI) GetFleetDMIntegration(ctx context.Context) (*api.EDRFleetDMResponse, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/integrations/edr/fleetdm", nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.EDRFleetDMResponse](resp)
+	return &ret, err
+}
+
+// CreateFleetDMIntegration creates a new EDR FleetDM integration.
+func (a *EDRAPI) CreateFleetDMIntegration(ctx context.Context, request api.EDRFleetDMRequest) (*api.EDRFleetDMResponse, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "POST", "/api/integrations/edr/fleetdm", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.EDRFleetDMResponse](resp)
+	return &ret, err
+}
+
+// UpdateFleetDMIntegration updates an existing EDR FleetDM integration.
+func (a *EDRAPI) UpdateFleetDMIntegration(ctx context.Context, request api.EDRFleetDMRequest) (*api.EDRFleetDMResponse, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "PUT", "/api/integrations/edr/fleetdm", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.EDRFleetDMResponse](resp)
+	return &ret, err
+}
+
+// DeleteFleetDMIntegration deletes the EDR FleetDM integration.
+func (a *EDRAPI) DeleteFleetDMIntegration(ctx context.Context) error {
+	resp, err := a.c.NewRequest(ctx, "DELETE", "/api/integrations/edr/fleetdm", nil, nil)
+	if err != nil {
+		return err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	return nil
+}
+
 // BypassPeerCompliance bypasses compliance for a non-compliant peer
 // See more: https://docs.netbird.io/api/resources/edr#bypass-peer-compliance
 func (a *EDRAPI) BypassPeerCompliance(ctx context.Context, peerID string) (*api.BypassResponse, error) {
--- a/shared/management/http/api/openapi.yml
+++ b/shared/management/http/api/openapi.yml
@@ -92,6 +92,9 @@ tags:
  - name: EDR Huntress Integrations
    description: Manage Huntress EDR integrations.
    x-cloud-only: true
+  - name: EDR FleetDM Integrations
+    description: Manage FleetDM EDR integrations.
+    x-cloud-only: true
  - name: EDR Peers
    description: Manage EDR compliance bypass for peers.
    x-cloud-only: true
@@ -4276,6 +4279,126 @@ components:
          description: Status of agent firewall. Can be one of Disabled, Enabled, Pending Isolation, Isolated, Pending Release.
          example: "Enabled"

+    EDRFleetDMRequest:
+      type: object
+      description: Request payload for creating or updating a FleetDM EDR integration
+      properties:
+        api_url:
+          type: string
+          description: FleetDM server URL
+        api_token:
+          type: string
+          description: FleetDM API token
+        groups:
+          type: array
+          description: The Groups this integrations applies to
+          items:
+            type: string
+        last_synced_interval:
+          type: integer
+          description: The devices last sync requirement interval in hours. Minimum value is 24 hours
+          minimum: 24
+        enabled:
+          type: boolean
+          description: Indicates whether the integration is enabled
+          default: true
+        match_attributes:
+          $ref: '#/components/schemas/FleetDMMatchAttributes'
+      required:
+        - api_url
+        - api_token
+        - groups
+        - last_synced_interval
+        - match_attributes
+    EDRFleetDMResponse:
+      type: object
+      description: Represents a FleetDM EDR integration configuration
+      required:
+        - id
+        - account_id
+        - api_url
+        - created_by
+        - last_synced_at
+        - created_at
+        - updated_at
+        - groups
+        - last_synced_interval
+        - match_attributes
+        - enabled
+      properties:
+        id:
+          type: integer
+          format: int64
+          description: The unique numeric identifier for the integration.
+          example: 123
+        account_id:
+          type: string
+          description: The identifier of the account this integration belongs to.
+          example: "ch8i4ug6lnn4g9hqv7l0"
+        api_url:
+          type: string
+          description: FleetDM server URL
+        last_synced_at:
+          type: string
+          format: date-time
+          description: Timestamp of when the integration was last synced.
+          example: "2023-05-15T10:30:00Z"
+        created_by:
+          type: string
+          description: The user id that created the integration
+        created_at:
+          type: string
+          format: date-time
+          description: Timestamp of when the integration was created.
+          example: "2023-05-15T10:30:00Z"
+        updated_at:
+          type: string
+          format: date-time
+          description: Timestamp of when the integration was last updated.
+          example: "2023-05-16T11:45:00Z"
+        groups:
+          type: array
+          description: List of groups
+          items:
+            $ref: '#/components/schemas/Group'
+        last_synced_interval:
+          type: integer
+          description: The devices last sync requirement interval in hours.
+        enabled:
+          type: boolean
+          description: Indicates whether the integration is enabled
+          default: true
+        match_attributes:
+          $ref: '#/components/schemas/FleetDMMatchAttributes'
+
+    FleetDMMatchAttributes:
+      type: object
+      description: Attribute conditions to match when approving FleetDM hosts. Most attributes work with FleetDM's free/open-source version. Premium-only attributes are marked accordingly
+      additionalProperties: false
+      properties:
+        disk_encryption_enabled:
+          type: boolean
+          description: Whether disk encryption (FileVault/BitLocker) must be enabled on the host
+        failing_policies_count_max:
+          type: integer
+          description: Maximum number of allowed failing policies. Use 0 to require all policies to pass
+          minimum: 0
+          example: 0
+        vulnerable_software_count_max:
+          type: integer
+          description: Maximum number of allowed vulnerable software on the host
+          minimum: 0
+          example: 0
+        status_online:
+          type: boolean
+          description: Whether the host must be online (recently seen by Fleet)
+        required_policies:
+          type: array
+          description: List of FleetDM policy IDs that must be passing on the host. If any of these policies is failing, the host is non-compliant
+          items:
+            type: integer
+          example: [1, 5, 12]
+
    IntegrationSyncFilters:
      type: object
      properties:
@@ -10684,6 +10807,161 @@ paths:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

+  /api/integrations/edr/fleetdm:
+    post:
+      tags:
+        - EDR FleetDM Integrations
+      summary: Create EDR FleetDM Integration
+      description: Creates a new EDR FleetDM integration
+      operationId: createFleetDMEDRIntegration
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/EDRFleetDMRequest'
+      responses:
+        '200':
+          description: Integration created successfully. Returns the created integration.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EDRFleetDMResponse'
+        '400':
+          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized (e.g., missing or invalid authentication token).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal Server Error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    get:
+      tags:
+        - EDR FleetDM Integrations
+      summary: Get EDR FleetDM Integration
+      description: Retrieves a specific EDR FleetDM integration by its ID.
+      responses:
+        '200':
+          description: Successfully retrieved the integration details.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EDRFleetDMResponse'
+        '400':
+          description: Bad Request (e.g., invalid integration ID format).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Not Found (e.g., integration with the given ID does not exist).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal Server Error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    put:
+      tags:
+        - EDR FleetDM Integrations
+      summary: Update EDR FleetDM Integration
+      description: Updates an existing EDR FleetDM Integration.
+      operationId: updateFleetDMEDRIntegration
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/EDRFleetDMRequest'
+      responses:
+        '200':
+          description: Integration updated successfully. Returns the updated integration.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EDRFleetDMResponse'
+        '400':
+          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Not Found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal Server Error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    delete:
+      tags:
+        - EDR FleetDM Integrations
+      summary: Delete EDR FleetDM Integration
+      description: Deletes an EDR FleetDM Integration by its ID.
+      responses:
+        '200':
+          description: Integration deleted successfully. Returns an empty object.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: { }
+        '400':
+          description: Bad Request (e.g., invalid integration ID format).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Not Found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal Server Error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
  /api/peers/{peer-id}/edr/bypass:
    parameters:
      - name: peer-id
--- a/shared/management/http/api/types.gen.go
+++ b/shared/management/http/api/types.gen.go
@@ -1849,6 +1849,63 @@ type EDRFalconResponse struct {
 	ZtaScoreThreshold int `json:"zta_score_threshold"`
 }

+// EDRFleetDMRequest Request payload for creating or updating a FleetDM EDR integration
+type EDRFleetDMRequest struct {
+	// ApiToken FleetDM API token
+	ApiToken string `json:"api_token"`
+
+	// ApiUrl FleetDM server URL
+	ApiUrl string `json:"api_url"`
+
+	// Enabled Indicates whether the integration is enabled
+	Enabled *bool `json:"enabled,omitempty"`
+
+	// Groups The Groups this integrations applies to
+	Groups []string `json:"groups"`
+
+	// LastSyncedInterval The devices last sync requirement interval in hours. Minimum value is 24 hours
+	LastSyncedInterval int `json:"last_synced_interval"`
+
+	// MatchAttributes Attribute conditions to match when approving FleetDM hosts. Most attributes work with FleetDM's free/open-source version. Premium-only attributes are marked accordingly
+	MatchAttributes FleetDMMatchAttributes `json:"match_attributes"`
+}
+
+// EDRFleetDMResponse Represents a FleetDM EDR integration configuration
+type EDRFleetDMResponse struct {
+	// AccountId The identifier of the account this integration belongs to.
+	AccountId string `json:"account_id"`
+
+	// ApiUrl FleetDM server URL
+	ApiUrl string `json:"api_url"`
+
+	// CreatedAt Timestamp of when the integration was created.
+	CreatedAt time.Time `json:"created_at"`
+
+	// CreatedBy The user id that created the integration
+	CreatedBy string `json:"created_by"`
+
+	// Enabled Indicates whether the integration is enabled
+	Enabled bool `json:"enabled"`
+
+	// Groups List of groups
+	Groups []Group `json:"groups"`
+
+	// Id The unique numeric identifier for the integration.
+	Id int64 `json:"id"`
+
+	// LastSyncedAt Timestamp of when the integration was last synced.
+	LastSyncedAt time.Time `json:"last_synced_at"`
+
+	// LastSyncedInterval The devices last sync requirement interval in hours.
+	LastSyncedInterval int `json:"last_synced_interval"`
+
+	// MatchAttributes Attribute conditions to match when approving FleetDM hosts. Most attributes work with FleetDM's free/open-source version. Premium-only attributes are marked accordingly
+	MatchAttributes FleetDMMatchAttributes `json:"match_attributes"`
+
+	// UpdatedAt Timestamp of when the integration was last updated.
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
 // EDRHuntressRequest Request payload for creating or updating a EDR Huntress integration
 type EDRHuntressRequest struct {
 	// ApiKey Huntress API key
@@ -2062,6 +2119,24 @@ type Event struct {
 // EventActivityCode The string code of the activity that occurred during the event
 type EventActivityCode string

+// FleetDMMatchAttributes Attribute conditions to match when approving FleetDM hosts. Most attributes work with FleetDM's free/open-source version. Premium-only attributes are marked accordingly
+type FleetDMMatchAttributes struct {
+	// DiskEncryptionEnabled Whether disk encryption (FileVault/BitLocker) must be enabled on the host
+	DiskEncryptionEnabled *bool `json:"disk_encryption_enabled,omitempty"`
+
+	// FailingPoliciesCountMax Maximum number of allowed failing policies. Use 0 to require all policies to pass
+	FailingPoliciesCountMax *int `json:"failing_policies_count_max,omitempty"`
+
+	// RequiredPolicies List of FleetDM policy IDs that must be passing on the host. If any of these policies is failing, the host is non-compliant
+	RequiredPolicies *[]int `json:"required_policies,omitempty"`
+
+	// StatusOnline Whether the host must be online (recently seen by Fleet)
+	StatusOnline *bool `json:"status_online,omitempty"`
+
+	// VulnerableSoftwareCountMax Maximum number of allowed vulnerable software on the host
+	VulnerableSoftwareCountMax *int `json:"vulnerable_software_count_max,omitempty"`
+}
+
 // GeoLocationCheck Posture check for geo location
 type GeoLocationCheck struct {
 	// Action Action to take upon policy match
@@ -4869,6 +4944,12 @@ type CreateFalconEDRIntegrationJSONRequestBody = EDRFalconRequest
 // UpdateFalconEDRIntegrationJSONRequestBody defines body for UpdateFalconEDRIntegration for application/json ContentType.
 type UpdateFalconEDRIntegrationJSONRequestBody = EDRFalconRequest

+// CreateFleetDMEDRIntegrationJSONRequestBody defines body for CreateFleetDMEDRIntegration for application/json ContentType.
+type CreateFleetDMEDRIntegrationJSONRequestBody = EDRFleetDMRequest
+
+// UpdateFleetDMEDRIntegrationJSONRequestBody defines body for UpdateFleetDMEDRIntegration for application/json ContentType.
+type UpdateFleetDMEDRIntegrationJSONRequestBody = EDRFleetDMRequest
+
 // CreateHuntressEDRIntegrationJSONRequestBody defines body for CreateHuntressEDRIntegration for application/json ContentType.
 type CreateHuntressEDRIntegrationJSONRequestBody = EDRHuntressRequest