Test

flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.54 Label Mapping API.md

@@ -0,0 +1,211 @@
+Configure Label Mapping API to automatically call your external API when alert events arrive, enabling dynamic enrichment and correlation of alert information. With this feature, you can automatically attach information from external data sources such as CMDB, HR systems, and more to your alerts.
+
+## I. Overview
+
+The Label Mapping API allows you to build custom external services to enrich alert labels. The workflow is as follows:
+
+1. Flashduty receives an alert event
+2. The system sends event information and the list of expected labels to your API based on configuration
+3. Your API queries external data sources (such as CMDB, databases, etc.)
+4. The API returns the computed enrichment labels
+5. Flashduty attaches the returned labels to the alert
+
+<span id="ApiSpec"></span>
+
+## II. API Specification
+
+### Request Method
+
+<div class="md-block">
+
+POST, Content-Type:"application/json"
+
+</div>
+
+### Request Payload:
+
+<div class="md-block">
+
+| Field | Type | Required | Description |
+| :--------: | :-------------------: | :--: | :--------- |
+| result_label_keys | []string | Yes | List of expected label keys to return, configured by users in Flashduty |
+| event | [Event](#Event) | Yes | Complete information of the current alert event |
+
+<span id="Event"></span>
+**Event**:
+
+| Field | Type | Required | Description |
+| :--------: | :-------------------: | :--: | :--------- |
+| account_id | int64 | Yes | Account ID |
+| channel_id | int64 | Yes | Channel ID |
+| data_source_id | int64 | Yes | Data source ID |
+| data_source_type | string | Yes | Data source type, e.g., prometheus, zabbix, etc. |
+| title | string | Yes | Alert title |
+| title_rule | string | No | Title rule |
+| description | string | No | Alert description |
+| alert_key | string | Yes | Alert unique identifier |
+| alert_id | string | Yes | Alert ID |
+| event_severity | string | Yes | Event severity, enum: Critical, Warning, Info |
+| event_status | string | Yes | Event status, enum: Critical, Warning, Info, Ok |
+| event_time | int64 | Yes | Event time, Unix timestamp in seconds |
+| labels | map[string]string | No | Alert original label key-value pairs |
+| images | []string | No | List of alert-related images |
+
+</div>
+
+### Request Example
+
+<div class="md-block">
+
+```json
+{
+  "result_label_keys": ["owner_team", "service_tier", "host_ip"],
+  "event": {
+    "account_id": 1,
+    "channel_id": 20,
+    "data_source_id": 15,
+    "data_source_type": "prometheus",
+    "description": "CPU usage for instance '10.0.1.101:9100' is over 95%",
+    "title": "High CPU Usage on instance 10.0.1.101:9100",
+    "title_rule": "",
+    "alert_key": "d41d8cd98f00b204e9800998ecf8427e",
+    "alert_id": "62d6c0f6b8f1b2b3c4d5e6f7",
+    "event_severity": "Critical",
+    "event_status": "Critical",
+    "event_time": 1678886400,
+    "labels": {
+      "region": "us-east-1",
+      "service": "service-A",
+      "env": "production",
+      "instance": "10.0.1.101:9100"
+    },
+    "images": []
+  }
+}
+```
+
+</div>
+
+### Response Specification
+
+<div class="md-block">
+
+**Successful Response:**
+
+| Field | Type | Required | Description |
+| :--------: | :-------------------: | :--: | :--------- |
+| result_labels | map[string]string | Yes | Returned enrichment label key-value object |
+
+- HTTP Status Code: `200 OK`
+- Response body must be a JSON object containing the `result_labels` field
+- Keys in `result_labels` must be label names specified in the request's `result_label_keys`
+- If a label cannot be retrieved, it **should not** be included in the response
+
+**Successful Response Example:**
+
+```json
+{
+  "result_labels": {
+    "owner_team": "team-database",
+    "service_tier": "tier-1",
+    "host_ip": "10.0.1.101"
+  }
+}
+```
+
+**Failure Response:**
+
+| Status Code | Meaning |
+| :--------: | :--------- |
+| 404 Not Found | No data available for enrichment based on the event information |
+| 400 Bad Request | Request body format error or event object missing required fields |
+| 5xx | Unexpected internal API error (e.g., database connection failure) |
+
+> **Note:** Returning `200 OK` status code with an empty `result_labels: {}` object will also be treated as "no results", but using the `404` status code is the more standard approach.
+
+</div>
+
+<span id="ServiceConfig"></span>
+
+## III. Configure Mapping Service
+
+When configuring label mapping in Flashduty, you need to first create a mapping service, then reference that service in your label enrichment rules.
+
+### Mapping Service Field Description
+
+<div class="md-block">
+
+| Field | Type | Required | Description |
+| :--------: | :-------------------: | :--: | :--------- |
+| api_name | string | Yes | Human-readable service name for selection and reference in the UI, e.g., "CMDB Asset Query API" |
+| description | string | No | Detailed description of the service |
+| url | string | Yes | API request URL, supports template variables |
+| headers | map[string]string | No | HTTP request headers for passing custom authentication, subject to [security blacklist](#HeaderBlacklist) restrictions |
+| timeout | int | No | Request timeout (in seconds)，scope: 1~3 |
+| retry_count | int | No | Number of retries after request failure, ，scope: 0~1  |
+| insecure_skip_verify | bool | No | Skip certificate verification for HTTPS requests |
+| status | string | No | Service status, e.g., enabled, disabled |
+
+</div>
+
+### Label Enrichment Rule Configuration
+
+When configuring label enrichment rules, you only need to focus on the following settings:
+
+1. **result_label_keys**: Specify the list of labels you expect to retrieve from the API. Flashduty will automatically combine this list with the current `event` object into a request body and send it to your API
+2. **Mapping Service**: Select or configure the API service URL, Headers, and other information
+
+<span id="HeaderBlacklist"></span>
+
+## IV. Header Security Constraints
+
+To prevent security bypasses, request smuggling, IP spoofing, and cache poisoning, the following Headers are **prohibited** when customizing API request headers. The system gateway will automatically filter or reject requests containing these Headers.
+
+<div class="md-block">
+
+| Category | Blacklisted Headers | Risk Description |
+| :--- | :--- | :--- |
+| **Authentication & Authorization** | `authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token` | Prevents credential leakage or unauthorized hijacking of existing authentication contexts |
+| **IP & Geolocation Spoofing** | `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip` | Prevents clients from spoofing source IP to bypass rate limits or allowlists/blocklists |
+| **Host & Routing Manipulation** | `host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id` | Prevents Host injection attacks, redirect loops, or spoofing internal system IDs |
+| **Protocol & Request Smuggling** | `transfer-encoding`, `upgrade`, `connection` | Prevents request smuggling attacks exploiting HTTP protocol differences |
+
+</div>
+
+### Header Best Practices
+
+1. **Allowlist Mode**: It is recommended to only allow custom Headers prefixed with `X-Custom-` or `X-Enrich-`
+2. **Length Limits**: The Key or Value length of a single Header should not exceed 1024 bytes
+3. **Format Validation**: Header Values must not contain line breaks (`\r`, `\n`) to prevent Header injection attacks
+
+## V. Best Practices
+
+1. **Performance First:** This API is on the critical path of alert processing and must ensure low latency. Queries to external data sources should be as fast as possible, and implementing caching is recommended.
+
+2. **Clear Error Handling:** Make good use of HTTP status codes (especially `404`) to convey clear execution results.
+
+3. **Idempotency:** The API design should be as idempotent as possible. Multiple calls for the same `event` should return the same result.
+
+4. **Security:** The API must be protected through authentication and authorization mechanisms. Using custom Headers (e.g., `X-Custom-Auth`) for passing authentication information is recommended.
+
+## VI. FAQ
+
+1. **Is there a response timeout for the service?**
+
+   - The service must respond within the configured timeout period; exceeding this is considered a failure
+
+2. **What happens if the API returns a failure?**
+
+   - The alert will be processed normally, but no enrichment labels will be attached
+   - Based on the configured retry count, the system may retry the request
+
+3. **Can result_label_keys be changed dynamically?**
+
+   - Yes, you can modify the list of expected labels in Flashduty at any time without modifying the API code
+
+4. **How do I secure my API?**
+
+   - It's recommended to add an `Authorization` header in the mapping service configuration
+   - You can verify the request source IP on the API side
+   - Using HTTPS for encrypted transmission is recommended
+