Fine tuning

README.md

@@ -100,6 +100,69 @@ The WAF module includes:
 - NetSapiens exclusion rules for admin UI, ns-api, SiPbx, NqsProxy, and iNSight health checks
 - CRS tuning for allowed HTTP methods and content types used by NetSapiens
 
+### Path Restrictions (.htaccess)
+
+Restrict access to sensitive NetSapiens paths (admin UI, API, NDP, recording) using `.htaccess` IP allowlists:
+
+```bash
+# Show current restriction status
+nssec waf restrict show
+
+# Create .htaccess restrictions (interactive — shows existing IPs, asks to keep or overwrite)
+sudo nssec waf restrict init
+
+# Specify IPs directly
+sudo nssec waf restrict init --ip 1.1.1.1 --ip 1.2.3.0/22
+
+# Add/remove individual IPs
+sudo nssec waf restrict add 1.1.1.1
+sudo nssec waf restrict remove 1.1.1.1
+
+# Re-deploy after a NetSapiens package upgrade overwrites .htaccess files
+sudo nssec waf restrict reapply
+```
+
+The `init` command will:
+- Detect which paths apply to the current server type (Core, NDP, Recording, Combo)
+- Show any existing IPs from current `.htaccess` files and ask whether to keep or overwrite them
+- Always include `127.0.0.1` automatically
+- Save the IP list to `/etc/nssec/restrict-ips.json` so it survives NS package upgrades
+
+**Protected paths:**
+
+| Target | Path | Server Types |
+|--------|------|:------------:|
+| SiPbx Admin UI | `/usr/local/NetSapiens/SiPbx/html/SiPbx/` | Core, Combo |
+| ns-api | `/usr/local/NetSapiens/SiPbx/html/ns-api/` | Core, Combo |
+| NDP Endpoints | `/usr/local/NetSapiens/ndp/` | NDP, Combo |
+| LiCf Recording | `/usr/local/NetSapiens/LiCf/html/LiCf/` | Recording, Combo |
+
+### mod_evasive (HTTP Flood Protection)
+
+mod_evasive is managed independently from the WAF and provides application-layer DDoS protection. It has **no detection-only mode** — when enabled it will block IPs that exceed request thresholds (HTTP 403).
+
+```bash
+# Check mod_evasive status
+nssec waf evasive status
+
+# Enable with standard profile (high thresholds — safe default)
+sudo nssec waf evasive enable
+
+# Enable with strict profile (tuned for NetSapiens traffic)
+sudo nssec waf evasive enable --profile strict
+
+# Disable
+sudo nssec waf evasive disable
+```
+
+**Profiles:**
+| Profile | DOSPageCount | DOSSiteCount | DOSBlockingPeriod | Use Case |
+|---------|:---:|:---:|:---:|------|
+| `standard` | 100 req/page/s | 500 req/IP/s | 10s | Safe default — only catches extreme floods |
+| `strict` | 15 req/page/s | 60 req/IP/s | 60s | Tuned for NetSapiens traffic patterns |
+
+Start with `standard` and review the Apache API Usage dashboard and mod_evasive block logs before switching to `strict`. Block events are logged to `/var/log/apache2/mod_evasive.log` for Loki/Grafana ingestion.
+
 ## Server Types
 
 | Component | Core | NDP | Recording | QoS |
@@ -121,6 +184,7 @@ Pre-built dashboards are available for import into your Grafana/iNSight instance
 - `api.json` — API v1/v2 request rate monitoring (Prometheus)
 - `apacheApiUsage.json` — Apache access log analysis by IP and path (Loki)
 - `modsecurityWaf.json` — ModSecurity WAF event analysis: severity, attacking IPs, triggered rules, targeted URIs (Loki)
+- `modEvasive.json` — mod_evasive HTTP flood protection: blocked IPs, block rate, repeat offenders (Loki)
 
 ## Related Projects
 
@@ -142,6 +206,7 @@ These community projects provide additional NetSapiens security capabilities:
 - [x] ModSecurity installation and configuration with OWASP CRS
 - [x] NetSapiens-specific WAF exclusion rules
 - [x] ModSecurity WAF monitoring dashboard
+- [x] .htaccess IP restrictions for sensitive paths
 - [ ] MySQL password rotation across all NS services
 - [ ] Fail2ban SIP plugin for NetSapiens
 

docs/waf-setup-guide.md

@@ -35,6 +35,8 @@ Optionally install mod_evasive for HTTP flood protection alongside ModSecurity:
 sudo apt-get install -y libapache2-mod-evasive
 ```
 
+> **Note:** mod_evasive has **no detection-only mode**. When enabled it will block IPs that exceed request thresholds (HTTP 403). See [mod_evasive Configuration](#mod_evasive-configuration) for details on threshold tuning.
+
 ## Step 2: Enable the Apache Module
 
 ```bash
@@ -441,6 +443,163 @@ SecRuleRemoveById RULE_ID
 - [Christian Folini's CRS Tuning Tutorials](https://www.netnea.com/cms/apache-tutorials/)
 - [CRS Paranoia Levels Explained](https://coreruleset.org/docs/concepts/paranoia_levels/)
 
+## mod_evasive Configuration
+
+mod_evasive provides application-layer HTTP flood and DDoS protection. Unlike ModSecurity, it has **no detection-only mode** — when enabled it will return HTTP 403 to IPs that exceed thresholds.
+
+### Understanding the thresholds
+
+| Directive | Description |
+|-----------|-------------|
+| `DOSPageCount` | Max requests to the same page per IP per interval |
+| `DOSSiteCount` | Max total requests from one IP per interval |
+| `DOSPageInterval` / `DOSSiteInterval` | Sliding window in seconds |
+| `DOSBlockingPeriod` | How long (seconds) an IP is blocked |
+| `DOSWhitelist` | IPs excluded from blocking (RFC 1918 ranges by default) |
+
+### Threshold profiles
+
+If using `nssec`, two profiles are available:
+
+| Profile | DOSPageCount | DOSSiteCount | DOSBlockingPeriod | Use Case |
+|---------|:---:|:---:|:---:|------|
+| `standard` (default) | 100 | 500 | 10s | Safe default — only catches extreme floods |
+| `strict` | 15 | 60 | 60s | Tuned for NetSapiens traffic (~270 req/s sustained) |
+
+```bash
+# Enable with standard profile (recommended starting point)
+sudo nssec waf evasive enable
+
+# Switch to strict after reviewing traffic
+sudo nssec waf evasive enable --profile strict
+```
+
+### Manual configuration
+
+If configuring manually, edit `/etc/apache2/mods-available/evasive.conf`:
+
+```apache
+<IfModule mod_evasive20.c>
+    DOSHashTableSize        3097
+    DOSPageCount            100
+    DOSSiteCount            500
+    DOSPageInterval         1
+    DOSSiteInterval         1
+    DOSBlockingPeriod       10
+    DOSLogDir               /var/log/apache2/mod_evasive
+
+    # Structured logging for Loki/Grafana
+    DOSSystemCommand        "/bin/sh -c 'echo $(date -Is) action=blocked src_ip=%s >> /var/log/apache2/mod_evasive.log'"
+
+    # Whitelist internal traffic
+    DOSWhitelist            127.0.0.1
+    DOSWhitelist            10.*.*.*
+    DOSWhitelist            192.168.*.*
+</IfModule>
+```
+
+Create the log directory:
+
+```bash
+sudo mkdir -p /var/log/apache2/mod_evasive
+```
+
+### Tuning recommendations
+
+1. **Start with the standard profile** (or high thresholds manually) to avoid blocking legitimate traffic
+2. **Review traffic patterns** using the Apache API Usage dashboard (`insight/apacheApiUsage.json`) or access logs
+3. **Monitor block events** in `/var/log/apache2/mod_evasive.log` and the mod_evasive dashboard (`insight/modEvasive.json`)
+4. **Lower thresholds gradually** once you understand your traffic baseline
+5. **Always whitelist** internal service IPs and monitoring endpoints
+
+### Enabling and disabling
+
+mod_evasive is managed independently from ModSecurity. Enabling/disabling the WAF (`nssec waf enable`/`nssec waf disable`) does **not** affect mod_evasive.
+
+```bash
+# Check status
+nssec waf evasive status
+
+# Enable/disable independently
+sudo nssec waf evasive enable
+sudo nssec waf evasive disable
+```
+
+## Path Restrictions (.htaccess)
+
+NetSapiens recommends restricting access to sensitive directories using `.htaccess` IP allowlists. This limits who can reach the admin login page, API, and provisioning endpoints.
+
+### Which paths to protect
+
+| Target | .htaccess Path | Server Types |
+|--------|---------------|:------------:|
+| SiPbx Admin UI | `/usr/local/NetSapiens/SiPbx/html/SiPbx/.htaccess` | Core, Combo |
+| ns-api | `/usr/local/NetSapiens/SiPbx/html/ns-api/.htaccess` | Core, Combo |
+| NDP Endpoints | `/usr/local/NetSapiens/ndp/.htaccess` | NDP, Combo |
+| LiCf Recording | `/usr/local/NetSapiens/LiCf/html/LiCf/.htaccess` | Recording, Combo |
+
+### .htaccess format
+
+Each `.htaccess` file should follow this format:
+
+```apache
+<Files "adminlogin.php">
+    Order allow,deny
+    Allow from 127.0.0.1
+    Allow from X.X.X.X
+    Allow from 1.1.1.1
+    Allow from 2.2.2.2
+</Files>
+```
+
+**IPs to include:**
+- `127.0.0.1` — required for internal NS service communication
+- NetSapiens support IPs — so support can access your admin UI for support
+- Your admin office IP(s) — for your own management access
+
+### Using nssec
+
+```bash
+# Show current restriction status across all applicable paths
+nssec waf restrict show
+
+# Create/update .htaccess restrictions interactively
+# Shows existing IPs and asks whether to keep or overwrite them
+sudo nssec waf restrict init
+
+# Or specify IPs directly on the command line
+sudo nssec waf restrict init --ip 1.1.1.1 --ip 1.2.3.0/22
+
+# Add a single IP to all managed .htaccess files
+sudo nssec waf restrict add 1.1.1.1
+
+# Remove an IP (cannot remove 127.0.0.1)
+sudo nssec waf restrict remove 2.2.2.2
+
+# Re-deploy after a NetSapiens package upgrade overwrites .htaccess files
+sudo nssec waf restrict reapply
+```
+
+### Surviving NS package upgrades
+
+NetSapiens package upgrades can overwrite `.htaccess` files. The `nssec waf restrict init` command saves the IP list to `/etc/nssec/restrict-ips.json`. After an upgrade, run:
+
+```bash
+sudo nssec waf restrict reapply
+```
+
+This re-creates all `.htaccess` files from the cached IP list.
+
+### Manual configuration
+
+If configuring manually, create the `.htaccess` file in each applicable directory with the format shown above. Ensure `127.0.0.1` is always included.
+
+After creating or modifying `.htaccess` files, test and reload Apache:
+
+```bash
+sudo apache2ctl configtest && sudo systemctl reload apache2
+```
+
 ## File Summary
 
 | File | Purpose |
@@ -450,7 +609,10 @@ SecRuleRemoveById RULE_ID
 | `/etc/modsecurity/crs/crs-setup.conf` | CRS settings (paranoia level, thresholds) |
 | `/etc/modsecurity/crs/rules/*.conf` | CRS rule files (do not edit) |
 | `/etc/apache2/mods-available/security2.conf` | Apache Include directives |
+| `/etc/apache2/mods-available/evasive.conf` | mod_evasive threshold configuration |
 | `/var/log/apache2/modsec_audit.log` | Audit log for triggered rules |
+| `/var/log/apache2/mod_evasive.log` | mod_evasive block event log |
+| `/var/log/apache2/mod_evasive/` | Per-IP block files (native mod_evasive) |
 
 ## Complementary Security Tools