init/configs/examples/acl-example.yaml at main · cboxdk/init · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
version: "1.0"

# IP-Based Access Control List (ACL) Configuration Example
# This example demonstrates IP ACL for API and metrics endpoints

global:
  shutdown_timeout: 30
  log_level: info
  log_format: json

  # API Configuration with IP ACL
  api_enabled: true
  api_port: 9180
  api_auth: "your-secret-token-here"

  # IP ACL for API Server (Whitelist Mode)
  # Only allow specific IPs or CIDR ranges to access the API
  api_acl:
    enabled: true
    mode: "allow"  # "allow" = whitelist (deny all except listed), "deny" = blacklist (allow all except listed)
    allow_list:
      - "127.0.0.1"           # localhost
      - "192.168.1.100"       # specific internal IP
      - "10.0.0.0/8"          # entire 10.x.x.x range
      - "172.16.0.0/12"       # 172.16.x.x - 172.31.x.x range
      - "2001:db8::1"         # IPv6 address
    deny_list: []             # empty in allow mode
    trust_proxy: false        # Set to true if behind proxy/load balancer to use X-Forwarded-For

  # TLS Configuration for API (optional - combine with ACL)
  api_tls:
    enabled: false
    # cert_file: "/etc/cbox-init/certs/server.crt"
    # key_file: "/etc/cbox-init/certs/server.key"

  # Metrics Configuration with IP ACL
  metrics_enabled: true
  metrics_port: 9090
  metrics_path: "/metrics"

  # IP ACL for Metrics Server (Same or different from API)
  metrics_acl:
    enabled: true
    mode: "allow"
    allow_list:
      - "127.0.0.1"           # localhost
      - "192.168.1.0/24"      # monitoring subnet
      - "10.0.0.50"           # Prometheus server
    deny_list: []
    trust_proxy: false

  # TLS Configuration for Metrics (optional)
  metrics_tls:
    enabled: false

processes:
  php-fpm:
    enabled: true
    command: ["php-fpm", "-F", "-R"]
    restart: always
    scale: 1

  nginx:
    enabled: true
    command: ["nginx", "-g", "daemon off;"]
    restart: always
    scale: 1
    depends_on: [php-fpm]

# ========================================
# Additional ACL Configuration Examples
# ========================================

# Example 1: Blacklist Mode (Allow all except specific IPs)
# Useful when you want to block specific bad actors
#
# api_acl:
#   enabled: true
#   mode: "deny"
#   allow_list: []
#   deny_list:
#     - "203.0.113.0/24"     # Known malicious subnet
#     - "198.51.100.50"      # Specific attacker IP
#     - "2001:db8:bad::/48"  # IPv6 range to block
#   trust_proxy: false

# Example 2: Behind Load Balancer / Proxy
# When behind AWS ELB, Nginx, or other proxy/load balancer
#
# api_acl:
#   enabled: true
#   mode: "allow"
#   allow_list:
#     - "10.0.0.0/8"         # Internal VPC range
#   deny_list: []
#   trust_proxy: true        # IMPORTANT: Trust X-Forwarded-For header

# Example 3: Development Environment (Allow localhost only)
#
# api_acl:
#   enabled: true
#   mode: "allow"
#   allow_list:
#     - "127.0.0.1"
#     - "::1"                # IPv6 localhost
#   deny_list: []
#   trust_proxy: false

# Example 4: Production with Multiple Subnets
#
# api_acl:
#   enabled: true
#   mode: "allow"
#   allow_list:
#     - "10.0.0.0/8"         # Primary VPC
#     - "172.16.0.0/12"      # Secondary VPC
#     - "192.168.1.0/24"     # Office network
#     - "203.0.113.10"       # Specific management IP
#   deny_list: []
#   trust_proxy: false

# Example 5: Combined with TLS and mTLS
# Maximum security: IP ACL + TLS + Client Certificates
#
# api_acl:
#   enabled: true
#   mode: "allow"
#   allow_list:
#     - "10.0.0.0/8"
#   trust_proxy: false
#
# api_tls:
#   enabled: true
#   cert_file: "/etc/cbox-init/certs/server.crt"
#   key_file: "/etc/cbox-init/certs/server.key"
#   ca_file: "/etc/cbox-init/certs/ca.crt"
#   client_auth: "verify"   # Require client certificates
#   min_version: "TLS 1.3"

# ========================================
# Testing ACL Configuration
# ========================================

# Test allowed IP (should succeed):
# curl http://localhost:8080/api/v1/health -H "Authorization: Bearer your-token"

# Test from different IP (if behind proxy):
# curl http://localhost:8080/api/v1/health \
#   -H "Authorization: Bearer your-token" \
#   -H "X-Forwarded-For: 192.168.1.100"

# Test denied IP (should get 403 Forbidden):
# curl http://localhost:8080/api/v1/health \
#   -H "Authorization: Bearer your-token" \
#   --resolve localhost:8080:203.0.113.50

# ========================================
# Security Best Practices
# ========================================

# 1. Use Whitelist Mode for Production
#    - mode: "allow" is more secure than "deny"
#    - Explicitly list allowed IPs/ranges
#    - Deny by default, allow by exception

# 2. Combine ACL with TLS
#    - Use both IP ACL and TLS for defense in depth
#    - ACL protects at network layer
#    - TLS protects data in transit

# 3. Trust Proxy Carefully
#    - Only enable trust_proxy if behind verified proxy
#    - Untrusted proxies can spoof X-Forwarded-For
#    - Validate proxy is properly configured

# 4. Use CIDR Notation for Ranges
#    - More efficient than listing individual IPs
#    - Easier to manage subnets
#    - Example: 10.0.0.0/8 covers 10.0.0.0 - 10.255.255.255

# 5. Monitor and Log
#    - Enable structured logging (log_format: json)
#    - Monitor 403 Forbidden responses
#    - Alert on unusual access patterns

# 6. Regular Review
#    - Periodically review ACL rules
#    - Remove stale IP addresses
#    - Update for infrastructure changes