Firewall (CSF)¶

Overview¶

StarkOne integrates with ConfigServer Security & Firewall (CSF) to provide IP-level traffic control, port management, GeoIP country blocking, temporary denies, and rate limiting.

All firewall endpoints require the firewall_management permission.

Status & Control¶

# Firewall status
GET /api/firewall/status

# Enable firewall
POST /api/firewall/enable

# Disable firewall
POST /api/firewall/disable

# Restart firewall (applies rule changes)
POST /api/firewall/restart

IP Rules¶

Allow / Deny¶

# Add permanent allow
POST /api/firewall/allow
{ "ip": "203.0.113.5", "comment": "Office IP" }

# Add permanent deny
POST /api/firewall/deny
{ "ip": "198.51.100.1", "comment": "Bad actor" }

# Temporary deny (expires after N seconds)
POST /api/firewall/tempdeny
{
  "ip": "192.0.2.1",
  "time": 3600,
  "comment": "Rate limit exceeded"
}

# Remove from allow list
DELETE /api/firewall/allow/203.0.113.5

# Remove from deny list
DELETE /api/firewall/deny/198.51.100.1

List Rules¶

GET /api/firewall/rules

List Temporary Denies¶

GET /api/firewall/temp

# Remove temporary deny
DELETE /api/firewall/temp/:ip

Port Management¶

# List open ports
GET /api/firewall/ports

# Open a port
POST /api/firewall/port/open
{
  "port": 8080,
  "protocol": "tcp",
  "direction": "in"
}

# Close a port
POST /api/firewall/port/close
{
  "port": 8080,
  "protocol": "tcp",
  "direction": "in"
}

# Get info about a port (service name, description)
GET /api/firewall/portinfo?port=443

Country Blocking (GeoIP)¶

# Get blocked countries
GET /api/firewall/countries

# List all available countries
GET /api/firewall/countries/list

# Block/unblock countries
POST /api/firewall/countries/block
{
  "countries": ["CN", "RU", "KP"],
  "direction": "in"
}

# GeoIP lookup
GET /api/firewall/geoip?ip=203.0.113.5

# IP info (ISP, ASN, etc.)
GET /api/firewall/ipinfo?ip=203.0.113.5

Cloudflare Integration¶

Route traffic only through Cloudflare IPs - useful when proxying all traffic via Cloudflare:

# Get Cloudflare-only status
GET /api/firewall/cloudflare

# Enable/update Cloudflare-only mode
POST /api/firewall/cloudflare
{ "enabled": true }

Superaccess (Permanent Whitelist)¶

IPs in superaccess are never blocked, even by temporary denies:

# List superaccess IPs
GET /api/firewall/superaccess

# Add superaccess
POST /api/firewall/superaccess
{ "ip": "203.0.113.1", "comment": "Admin office" }

# Remove superaccess
DELETE /api/firewall/superaccess/203.0.113.1

Logs¶

GET /api/firewall/logs?lines=100

Returns the last N lines from the CSF log.

Settings¶

# Get all CSF settings
GET /api/firewall/settings

# Update a setting
POST /api/firewall/settings
{ "key": "CT_LIMIT", "value": "200" }

# Bulk update settings
PATCH /api/firewall/settings
{
  "CT_LIMIT": "200",
  "LF_TRIGGER": "10"
}

Export / Import Rules¶

# Export allow/deny lists
POST /api/firewall/export

# Import rules from file
POST /api/firewall/import
Content-Type: multipart/form-data
# Form field: file (exported rules JSON)