Name: FlatRun
Author: FlatRun

FlatRun includes a comprehensive security module that monitors traffic, blocks malicious IPs, protects sensitive routes, and provides real-time threat detection.

Security Overview

The security system provides multiple layers of protection:

IP Blocking — Automatic and manual blocking of suspicious IPs
Protected Routes — Authentication requirements for sensitive paths
Whitelist — Allow trusted IPs to bypass security checks
Event Logging — Track all security-related events
Real-time Capture — Live monitoring of incoming requests

Agent Configuration

Configure security settings in your agent config file:

security:
  enabled: true
  realtime_capture: false
  scan_interval: 30s
  retention_days: 30
  rate_threshold: 100
  auto_block_enabled: true
  auto_block_threshold: 50
  auto_block_duration: 24h
  # Detection thresholds
  detection_window: 2m
  not_found_threshold: 10
  auth_failure_threshold: 5
  unique_paths_threshold: 20
  repeated_hits_threshold: 30

Option	Description	Default
`enabled`	Enable security module	`true`
`realtime_capture`	Enable real-time request capture	`false`
`scan_interval`	How often to scan for threats	`30s`
`retention_days`	Days to keep security events	`30`
`rate_threshold`	Requests per IP before flagging	`100`
`auto_block_enabled`	Automatically block suspicious IPs	`true`
`auto_block_threshold`	Events before auto-blocking	`50`
`auto_block_duration`	How long to block IPs	`24h`
`detection_window`	Time window for threat detection	`2m`
`not_found_threshold`	404 errors before flagging	`10`
`auth_failure_threshold`	Auth failures before flagging	`5`
`unique_paths_threshold`	Unique paths before scan detection	`20`
`repeated_hits_threshold`	Repeated hits before flagging	`30`

IP Blocking

IPs can be blocked automatically or manually.

Automatic Blocking

When auto_block is enabled, IPs are automatically blocked when they exceed the configured threshold of security events within the specified window.

Manual Blocking

Block an IP via the API:

curl -X POST "http://localhost:8090/api/security/blocked-ips" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.1.100",
    "reason": "Suspicious activity",
    "duration": 86400
  }'

Unblocking IPs

curl -X DELETE "http://localhost:8090/api/security/blocked-ips/192.168.1.100" \
  -H "Authorization: Bearer $TOKEN"

Protected Routes

Protect sensitive paths with authentication requirements. When a route is protected, requests must include valid credentials.

Creating Protected Routes

curl -X POST "http://localhost:8090/api/security/protected-routes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/admin",
    "method": "ALL",
    "auth_type": "basic",
    "credentials": "admin:secret",
    "deployment": "my-app"
  }'

Field	Description
`path`	URL path to protect (supports wildcards)
`method`	HTTP method (GET, POST, ALL, etc.)
`auth_type`	Authentication type (basic, bearer)
`credentials`	Credentials for authentication
`deployment`	Limit protection to specific deployment

Whitelist Management

Whitelisted IPs, CIDR ranges, or paths bypass security checks.

Adding Whitelist Entries

curl -X POST "http://localhost:8090/api/security/whitelist" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ip",
    "value": "10.0.0.0/8",
    "description": "Internal network"
  }'

Whitelist types:

ip — Single IP address
cidr — IP range in CIDR notation
path — URL path pattern

Security Events

The security module logs various event types:

Event Type	Description
`blocked_ip`	Request from blocked IP
`rate_limited`	IP exceeded rate limit
`auth_failed`	Failed authentication attempt
`suspicious`	Suspicious request pattern
`scan_detected`	Vulnerability scan detected

Viewing Events

curl "http://localhost:8090/api/security/events?limit=50" \
  -H "Authorization: Bearer $TOKEN"

Real-time Capture

When enabled, real-time capture logs all incoming requests for debugging and analysis. This is resource-intensive and should only be enabled temporarily.

# Enable real-time capture
curl -X PUT "http://localhost:8090/api/security/realtime-capture" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Warning: Real-time capture can generate significant data. Only enable it for debugging purposes and disable it when done.

Deployment-Level Security

Security settings can be configured per deployment:

curl -X PUT "http://localhost:8090/api/deployments/my-app/security" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "rate_limit": 50,
    "allowed_ips": ["10.0.0.0/8"],
    "blocked_paths": ["/wp-admin"]
  }'

Nginx Integration

The security module integrates with Nginx via Lua scripts. When you update security settings, FlatRun automatically:

Regenerates Lua scripts with current rules
Updates shared memory for blocked IPs
Reloads Nginx to apply changes

To manually refresh the security configuration:

curl -X POST "http://localhost:8090/api/security/refresh" \
  -H "Authorization: Bearer $TOKEN"

Security Statistics

Get an overview of security activity:

curl "http://localhost:8090/api/security/stats" \
  -H "Authorization: Bearer $TOKEN"

Response includes:

Total events by type
Number of blocked IPs
Recent threats
Top offending IPs

Event Cleanup

Old security events are automatically cleaned up based on event_retention. You can also trigger manual cleanup:

curl -X POST "http://localhost:8090/api/security/cleanup" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"older_than": 604800}'