proxmox/docs/04-configuration/UDM_PRO_API_FIREWALL_ENDPOINTS.md

# UDM Pro Firewall/ACL API Endpoints

**Last Updated:** 2025-01-20  
**Status:** Active Documentation
**API Documentation:** [UniFi Network API Documentation](https://unifi.ui.com/consoles/70A74178A0F2000000000673F1400000000006C1406100000000629EBD6D:568528603/unifi-api/network)

---

## Overview

The Official UniFi Network API provides comprehensive firewall and access control configuration through **ACL Rules** (Access Control List rules). These endpoints allow programmatic configuration of firewall policies, network segmentation, and traffic filtering.

**Base URL:** `https://192.168.0.1/proxy/network/integration/v1/`  
**Authentication:** `X-API-KEY` header  
**Site ID:** `88f7af54-98f8-306a-a1c7-c9349722b1f6`

---

## Available Firewall/ACL Endpoints

### 1. ACL Rules (Access Control List Rules)

ACL Rules are the primary mechanism for configuring firewall policies in UniFi Network API.

#### List ACL Rules
```
GET /v1/sites/{siteId}/acl-rules
```

**Query Parameters:**
- `offset` (integer, default: 0)
- `limit` (integer, default: 25, max: 200)
- `filter` (string) - Filter expressions

**Response:** Paginated list of ACL rules

#### Get ACL Rule Details
```
GET /v1/sites/{siteId}/acl-rules/{aclRuleId}
```

**Response:** ACL rule object with:
- `type`: "IPV4"
- `enabled`: boolean
- `name`: string
- `description`: string
- `action`: "ALLOW" | "BLOCK"
- `index`: integer (lower index = higher priority)
- `sourceFilter`: object (traffic source filter)
- `destinationFilter`: object (traffic destination filter)
- `protocolFilter`: array of strings ("TCP", "UDP")
- `enforcingDeviceFilter`: object (device filter for enforcement)

#### Create ACL Rule
```
POST /v1/sites/{siteId}/acl-rules
```

**Request Body:**
```json
{
  "type": "IPV4",
  "enabled": true,
  "name": "Rule Name",
  "description": "Rule description",
  "action": "ALLOW|BLOCK",
  "enforcingDeviceFilter": {
    "type": "string"
  },
  "index": 0,
  "sourceFilter": {
    "type": "string"
  },
  "destinationFilter": {
    "type": "string"
  },
  "protocolFilter": ["TCP", "UDP"]
}
```

#### Update ACL Rule
```
PUT /v1/sites/{siteId}/acl-rules/{aclRuleId}
```

**Request Body:** Same as Create ACL Rule

#### Delete ACL Rule
```
DELETE /v1/sites/{siteId}/acl-rules/{aclRuleId}
```

---

### 2. Firewall Zones

Firewall Zones group networks together for firewall policy configuration.

#### List Firewall Zones
```
GET /v1/sites/{siteId}/firewall/zones
```

**Query Parameters:**
- `offset` (integer, default: 0)
- `limit` (integer, default: 25, max: 200)
- `filter` (string)

**Response:** List of firewall zones

#### Get Firewall Zone
```
GET /v1/sites/{siteId}/firewall/zones/{firewallZoneId}
```

**Response:** Firewall zone object with:
- `id`: UUID
- `name`: string
- `networkIds`: array of network UUIDs
- `metadata`: object

#### Create Custom Firewall Zone
```
POST /v1/sites/{siteId}/firewall/zones
```

**Request Body:**
```json
{
  "name": "Zone Name",
  "networkIds": ["network-uuid-1", "network-uuid-2"]
}
```

#### Update Firewall Zone
```
PUT /v1/sites/{siteId}/firewall/zones/{firewallZoneId}
```

#### Delete Custom Firewall Zone
```
DELETE /v1/sites/{siteId}/firewall/zones/{firewallZoneId}
```

---

### 3. Traffic Matching Lists

Traffic Matching Lists define port and IP address lists used in firewall policies.

#### List Traffic Matching Lists
```
GET /v1/sites/{siteId}/traffic-matching-lists
```

#### Get Traffic Matching List
```
GET /v1/sites/{siteId}/traffic-matching-lists/{trafficMatchingListId}
```

#### Create Traffic Matching List
```
POST /v1/sites/{siteId}/traffic-matching-lists
```

**Request Body:**
```json
{
  "type": "PORTS",
  "name": "List Name",
  "items": []
}
```

#### Update Traffic Matching List
```
PUT /v1/sites/{siteId}/traffic-matching-lists/{trafficMatchingListId}
```

#### Delete Traffic Matching List
```
DELETE /v1/sites/{siteId}/traffic-matching-lists/{trafficMatchingListId}
```

---

## ACL Rule Configuration Examples

### Example 1: Block Inter-VLAN Traffic (Sovereign Tenant Isolation)

Block traffic between VLANs 200-203 (sovereign tenants):

```json
{
  "type": "IPV4",
  "enabled": true,
  "name": "Block Sovereign Tenant East-West",
  "description": "Deny traffic between sovereign tenant VLANs (200-203)",
  "action": "BLOCK",
  "index": 100,
  "sourceFilter": {
    "type": "NETWORK",
    "networkIds": [
      "network-uuid-vlan-200",
      "network-uuid-vlan-201",
      "network-uuid-vlan-202",
      "network-uuid-vlan-203"
    ]
  },
  "destinationFilter": {
    "type": "NETWORK",
    "networkIds": [
      "network-uuid-vlan-200",
      "network-uuid-vlan-201",
      "network-uuid-vlan-202",
      "network-uuid-vlan-203"
    ]
  },
  "protocolFilter": null
}
```

### Example 2: Allow Management VLAN Access

Allow Management VLAN (11) to access Service VLANs on specific ports:

```json
{
  "type": "IPV4",
  "enabled": true,
  "name": "Allow Management to Service VLANs",
  "description": "Allow VLAN 11 to access service VLANs (SSH, DB, Admin ports)",
  "action": "ALLOW",
  "index": 10,
  "sourceFilter": {
    "type": "NETWORK",
    "networkIds": ["network-uuid-vlan-11"]
  },
  "destinationFilter": {
    "type": "NETWORK",
    "networkIds": [
      "network-uuid-vlan-110",
      "network-uuid-vlan-120",
      "network-uuid-vlan-130"
    ]
  },
  "protocolFilter": ["TCP"],
  "portFilter": {
    "type": "PORTS",
    "ports": [22, 5432, 8080, 443]
  }
}
```

### Example 3: Allow Monitoring Traffic

Allow Service VLANs to send monitoring data to Management VLAN:

```json
{
  "type": "IPV4",
  "enabled": true,
  "name": "Allow Monitoring to Management",
  "description": "Allow service VLANs to send monitoring/logging to VLAN 11",
  "action": "ALLOW",
  "index": 20,
  "sourceFilter": {
    "type": "NETWORK",
    "networkIds": [
      "network-uuid-vlan-110",
      "network-uuid-vlan-120",
      "network-uuid-vlan-130"
    ]
  },
  "destinationFilter": {
    "type": "NETWORK",
    "networkIds": ["network-uuid-vlan-11"]
  },
  "protocolFilter": ["UDP", "TCP"],
  "portFilter": {
    "type": "PORTS",
    "ports": [161, 9090, 9091]
  }
}
```

---

## Important Notes

### ACL Rule Priority

- **Index Field:** Lower index values have higher priority
- Rules are evaluated in order of index (ascending)
- First matching rule applies

### Filter Types

ACL Rules support various filter types for source and destination:
- **Network Filters:** Filter by network/VLAN IDs
- **IP Address Filters:** Filter by IP addresses or ranges
- **Port Filters:** Filter by port numbers or ranges
- **Protocol Filters:** TCP, UDP (or null for all protocols)

### Device Enforcement

- `enforcingDeviceFilter`: Specify which devices enforce the rule
- If null, rule applies to all switches on the site
- Useful for device-specific policies

### Network References

To use network IDs in filters:
1. List networks: `GET /v1/sites/{siteId}/networks`
2. Extract network IDs from the response
3. Use network IDs in ACL rule filters

---

## Implementation Strategy

### Phase 1: List Current Configuration

1. List existing ACL rules
2. List firewall zones
3. List networks (to get network IDs)
4. Document current state

### Phase 2: Create Firewall Rules

1. **Sovereign Tenant Isolation:**
   - Create BLOCK rules for VLANs 200-203 inter-VLAN traffic

2. **Management VLAN Access:**
   - Create ALLOW rules for VLAN 11 → Service VLANs
   - Use appropriate port filters

3. **Monitoring Access:**
   - Create ALLOW rules for Service VLANs → VLAN 11
   - Use monitoring port filters

### Phase 3: Verify and Test

1. Verify rules are created correctly
2. Test connectivity between VLANs
3. Adjust priorities (index values) as needed

---

## Related Documentation

- [UDM_PRO_STATUS.md](./UDM_PRO_STATUS.md) - Configuration status
- [UDM_PRO_API_ENDPOINT_EXPLORATION.md](./UDM_PRO_API_ENDPOINT_EXPLORATION.md) - API endpoint exploration
- [UniFi Network API Documentation](https://unifi.ui.com/consoles/70A74178A0F2000000000673F1400000000006C1406100000000629EBD6D:568528603/unifi-api/network) - Official API documentation

---

**Last Updated:** 2025-01-20