━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
RFlameGuard — Official Documentation
AntiVPN & Connection Firewall
by Krud Studio
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

TABLE OF CONTENTS
1. Requirements
2. Installation
3. Configuration
4. Firewall Modes
5. Modules
6. VPN Detection
7. Commands
8. Permissions
9. Discord Webhooks
10. FAQ

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Paper / Purpur / Folia 1.18 – 1.21.x
• Java 17 or higher (Java 21 recommended)
• No external dependencies required

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2. INSTALLATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Download RFlameGuard.jar
2. Place it in your /plugins folder
3. Start or restart your server
4. Edit plugins/RFlameGuard/config.yml
5. Run /rfg reload to apply changes
(No full restart needed after config edits)

Generated files on first start:
plugins/RFlameGuard/
├── config.yml — Main configuration
├── state.yml — Persisted firewall state
└── rflameguard.db — SQLite database

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
3. CONFIGURATION (config.yml)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

── GENERAL ──────────────────────────────────────

# CPS threshold to trigger attack detection
attack-cps-threshold: 50

# Seconds after attack ends before returning to normal
stand-down-delay-seconds: 10

# Default firewall mode on startup (NORMAL/STRICT/LOCKDOWN)
firewall-mode: NORMAL

── AUTO-ESCALATION ──────────────────────────────

auto-escalate:
enabled: true
strict-at-cps: 100 # Switch to STRICT at this CPS
lockdown-at-cps: 500 # Switch to LOCKDOWN at this CPS
de-escalate-after-seconds: 30 # Return to NORMAL after attack

── VPN DETECTION ────────────────────────────────

vpn-detection:
enabled: false
provider: ip-api # ip-api or proxycheck
timeout-ms: 3000
cache-results: true
cache-expire-minutes: 60
block-vpn: true
block-hosting: true
on-api-failure: ALLOW # ALLOW or BLOCK
trusted-ips: []

# proxycheck.io (optional)
proxycheck:
api-key: ""

# Auto-blacklist after repeated VPN attempts
auto-blacklist:
enabled: true
warn-at-attempt: 10
blacklist-at-attempt: 20
reset-after-hours: 24

── MODULES ──────────────────────────────────────

modules:

ratelimit:
enabled: true
always-active: false # Active even without attack
max-per-ip: 3 # Max connections per window
burst-allowance: 2

cache-filter:
enabled: true
always-active: false
reconnect-window-seconds: 5

blacklist-autoban:
enabled: true
always-active: false
auto-threshold: 20 # Hits before auto-ban
window-seconds: 10
ban-duration-minutes: 60

geo-block:
enabled: false
allow-if-whitelisted: true
api-url: " https://ip-api.com/json/{ip}?fields=countryCode"
blocked-countries:
- CN
- RU

── DISCORD ──────────────────────────────────────

discord:
enabled: false
webhook-url: ""
ping-role-id: "" # Role ID to ping on attack
notify-on-attack-start: true
notify-on-attack-end: true
notify-on-autoban: true
notify-on-lockdown: true
embed:
color-attack: 16711822
color-safe: 16744448
color-ban: 16711680
thumbnail-url: ""
footer: "RFlameGuard · Krud Studio"

── LOGGING ──────────────────────────────────────

logging:
enabled: true
database-file: rflameguard.db

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4. FIREWALL MODES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

NORMAL
Standard protection. Blacklist and whitelist are always
checked. Modules only activate if always-active is true
or an attack is detected.

STRICT
All modules become active regardless of attack state.
Rate limiting and cache filter enforce on every connection.
Reconnect challenge required for new IPs.

LOCKDOWN
All new connections are blocked immediately.
Only whitelisted IPs are allowed through.
Use during severe attacks or maintenance.

Auto-escalation example:
CPS reaches 100 → switches to STRICT automatically
CPS reaches 500 → switches to LOCKDOWN automatically
Attack ends + 30s → returns to NORMAL automatically

Manual override:
/rfg mode normal
/rfg mode strict
/rfg mode lockdown

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
5. MODULES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

RATE LIMIT
Limits how many times a single IP can connect within
a rolling 1-second window. Excess connections are dropped.
Set always-active: true to enforce at all times.

CACHE FILTER
Tracks IPs that reconnect rapidly within a short window.
IPs that reconnect 3+ times within reconnect-window-seconds
are blocked. Helps stop reconnect flood attacks.

BLACKLIST AUTO-BAN
Automatically adds an IP to the blacklist after it triggers
the firewall more than auto-threshold times within
window-seconds. The ban lasts ban-duration-minutes.

GEO-BLOCK
Blocks connections from specific countries using country
codes (ISO 3166-1 alpha-2). Uses ip-api.com by default.
Players on the whitelist bypass this check.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
6. VPN DETECTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

RFlameGuard supports two VPN detection providers:

── ip-api.com (default, free) ───────────────────
No API key required for basic use.
Rate limited to 45 requests/minute on free tier.
Detects: proxy, hosting, Cloudflare WARP.

vpn-detection:
provider: ip-api

── proxycheck.io (recommended for high traffic) ──
Free tier: 1,000 queries/day
Paid plans available at proxycheck.io

vpn-detection:
provider: proxycheck
proxycheck:
api-key: "YOUR_API_KEY"

── Auto-Blacklist Flow ───────────────────────────
Attempt 1–9 → Player kicked, warning logged
Attempt 10–19 → Kick message shows remaining attempts
Attempt 20+ → IP permanently blacklisted

Reset counter resets after reset-after-hours (default 24h).

── Trusted IPs ──────────────────────────────────
Add IPs that should always bypass VPN checks:
trusted-ips:
- 1.1.1.1
- 8.8.8.8

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
7. COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All commands use /rflameguard or /rfg

GENERAL
/rfg help [page] Paginated help menu
/rfg info Live status (CPS, mode, uptime)
/rfg stats Summary statistics
/rfg reload Reload config.yml without restart

PROTECTION TOGGLE
/rfg enable Enable all protection
/rfg disable Disable all protection
/rfg toggle Toggle protection on/off

FIREWALL MODE
/rfg mode Show current mode
/rfg mode normal Set mode to NORMAL
/rfg mode strict Set mode to STRICT
/rfg mode lockdown Set mode to LOCKDOWN

WHITELIST
/rfg whitelist list Show all whitelisted IPs
/rfg whitelist add <ip> Add IP to whitelist
/rfg whitelist remove <ip> Remove IP from whitelist

BLACKLIST
/rfg blacklist list Show all blacklisted IPs
/rfg blacklist add <ip> Add IP to blacklist
/rfg blacklist remove <ip> Remove IP from blacklist

IP TOOLS
/rfg lookup <ip> View reputation data for an IP
/rfg unban <ip> Remove IP from blacklist

GUI
/rfg dashboard Open 54-slot live stats GUI
/rfg logs [page] Open paginated attack log GUI

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
8. PERMISSIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

rflameguard.admin
Full access to all /rfg commands.
Default: op

rflameguard.notify
Receive attack alerts in chat and action bar telemetry.
Default: op

rflameguard.bypass
Bypass all firewall checks entirely.
Assign to trusted staff or bot accounts.
Default: false

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
9. DISCORD WEBHOOKS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Create a webhook in your Discord channel
Channel Settings → Integrations → Webhooks → New

Step 2: Copy the webhook URL and paste into config.yml:
discord:
enabled: true
webhook-url: " https://discord.com/api/webhooks/..."

Step 3: (Optional) Add a role ID to ping on attacks:
ping-role-id: "123456789012345678"

Step 4: Run /rfg reload

Alert types:
⚠️ Attack detected — Sent when CPS exceeds threshold
✅ Attack ended — Sent with duration and total blocked
Auto-ban — Sent when an IP is auto-blacklisted
Lockdown — Sent when mode changes to LOCKDOWN

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
10. FAQ
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Q: Does this work with Geyser/Bedrock players?
A: Yes. Bedrock players connecting via Geyser are not
affected by firewall checks that target Java connections.

Q: Will VPN detection kick my staff?
A: Add your staff IPs to trusted-ips or give them the
rflameguard.bypass permission to skip all checks.

Q: My country is getting blocked. How do I fix it?
A: Add your IP to the whitelist with:
/rfg whitelist add <your-ip>

Q: How do I disable just one module?
A: Set enabled: false under that module in config.yml
then run /rfg reload.

Q: Does RFlameGuard affect server performance?
A: No. All heavy operations (VPN checks, DB writes) run
asynchronously and never block the main thread.

Q: VPN detection is blocking legitimate players. Help?
A: Set block-hosting: false if players use mobile data
or ISPs that route through datacenters. Or set
on-api-failure: ALLOW as a safe fallback.

Q: Can I use this on a Velocity proxy?
A: RFlameGuard is a backend plugin. For Velocity,
install it on each backend server or use a
dedicated proxy-level firewall alongside it.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Made with ❤️ by Krud Studio
play.krud.qzz.io
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━