Support

Documentation, email and bug report channels, and a FAQ on installation, configuration, detection and troubleshooting.

Ways to get help

Documentation

Installation, configuration, architecture reference, and API docs. Start here.

Read the documentation

Bug reports and feedback

Found a bug or have a feature request? Send us a detailed report and we'll investigate promptly.

Email a bug report

Email support

For sensitive questions or professional assistance. We respond within 48 hours on business days.

Email hello@wafio.cloud

Frequently asked questions

Answers on general questions, installation, detection, configuration, performance, data privacy and troubleshooting, grouped by topic.

Malicious uploads detection

Where do I get the MalwareBazaar Auth-Key?

Obtain the key from the abuse.ch Authentication Portal, then save its value in Administration › Security Data › MalwareBazaar. Select Check access & update hashes and verify each WAF agent’s database status. It is not a WAFio license or agent credential.

Will an incomplete scan interrupt client uploads?

The default incomplete-scan policy is Forward and log. Reject upload can block incomplete scans in Block mode; Log only mode still forwards. Other WAF rules and the application may reject the request independently.

Does a successful EICAR test mean the malware database is ready?

No. The offline fallback contains EICAR alone and is not currently classified as an incomplete scan. Check database source, hash count, and synchronization separately. Unknown or modified malware may not match; archives are not unpacked.

Installation and requirements

What are the system requirements?

WAFio requires a Linux host (kernel ≥ 5.10 with BTF enabled for eBPF features), root or CAP_BPF privileges, and a 64-bit x86_64 architecture. The control plane and WAF agent run on most Linux distributions. The host agent requires a kernel with BTF support. Most distributions shipping kernel 5.10+ satisfy this. Kernels 5.8 and 5.9 are not supported.

Which Linux distributions are supported?

Any distribution running Linux kernel ≥ 5.10 with BTF enabled. This includes Ubuntu 22.04+ (or 20.04 with the HWE kernel), Debian 11+, CentOS Stream 9, Rocky Linux 9, Fedora 34+, and most modern cloud provider images (AWS AL2023, GCP COS, Azure Ubuntu). Older kernels without BTF support the WAF agent but not the eBPF host agent.

Can I run WAFio on a single VPS?

Yes. A single server can run the control plane, WAF agent, and host agent together. Production workloads benefit from dedicated agent hosts, but it is not required.

What does install.sh do?

With install.sh, a basic deployment (control plane + WAF agent protecting one application) needs one command: the installer sets up PostgreSQL and TimescaleDB, downloads and verifies the signed binaries, writes the config, and starts the systemd services. Adding a host agent is one command copied from the dashboard (Hosts › Connect this host). The Download page shows a recorded walkthrough of each install.

Do I need to change my application code?

No. WAFio is a reverse proxy sidecar. The WAF agent sits in front of your application and intercepts HTTP traffic transparently. No SDK, no library, no code change required. Works with any language, framework, or runtime.

Can WAFio run in an air-gapped environment?

Yes. WAFio has no mandatory outbound connections. The binary is self-contained. Rule updates and configuration changes are pushed from your own control plane to agents via gRPC, with no internet access required anywhere in the data path.

Does WAFio support Docker and Kubernetes?

Yes. The WAF agent runs as a container or sidecar. The host agent is container-aware via cgroup and namespace attribution: events from containers are tagged with container ID, image name, and Kubernetes pod/namespace metadata. Works with Docker, Podman, and Kubernetes.

Does WAFio support Windows Server?

No. WAFio is Linux-only. The WAF agent, host agent, and eBPF subsystem are compiled exclusively for Linux x86_64. Windows Server is not supported and there are no plans to add Windows support, because eBPF is a Linux kernel feature with no equivalent on Windows, and the runtime security layer depends on Linux kprobes and tracepoints. If you run Windows Server as your application host, consider running WAFio on a Linux VM or container in front of the Windows server and proxying HTTP traffic through it.

Does WAFio support macOS or FreeBSD?

macOS is supported for the control plane in development environments: you can run the wafio control plane binary on macOS for local testing. However, the WAF agent and host agent are Linux-only for production use. FreeBSD, OpenBSD, and other BSDs are not supported. Production deployments must use a Linux host for agent nodes.

Does WAFio support ARM or ARM64 (Raspberry Pi, AWS Graviton, Apple Silicon)?

Current official builds target Linux x86_64. ARM64 builds are not yet in the official release pipeline. Running WAFio on AWS Graviton, Ampere, or Raspberry Pi requires compiling from source with GOARCH=arm64. The Go codebase is architecture-agnostic, but eBPF CO-RE objects need to be compiled with the correct target architecture. Contact us at hello@wafio.cloud for the latest ARM64 build status.

Can WAFio run on a cPanel server?

It depends on the hosting type. Shared cPanel hosting is not supported: shared hosts do not provide root access or the ability to run custom system services. On a cPanel VPS or dedicated server with root access, WAFio can run alongside cPanel/WHM with some configuration. The standard approach: reconfigure Apache to listen on a non-standard port (e.g., 8080) via WHM › Apache Configuration › Global Configuration › HTTP Port, then run WAFio's WAF agent on port 80/443 as the front-facing proxy. WAFio forwards clean traffic to Apache on 8080. cPanel's "Reverse Proxy" feature in WHM (Apache › Module Handlers) can also assist with this routing. eBPF firewall and Runtime Security features require kernel ≥ 5.10 with BTF, available on modern CloudLinux 9 or AlmaLinux 9 cPanel hosts, but not on older CentOS 6/7 stacks. For managed cPanel environments where port changes are restricted, contact your host to confirm whether a reverse proxy configuration is permitted before deploying.

Performance and operations

What is the performance overhead of WAFio?

Every request passes through the detection pipeline of the WAF agent before it reaches your application, so the agent adds inspection time to each request. The eBPF firewall drops blocked packets at the kernel driver level, before the Linux network stack. Measure the overhead on your own traffic: the project Overview shows the average decision latency of recorded decisions.

What happens if the WAF agent crashes?

WAFio is designed to fail-open on agent panic. If a detection engine panics, the request is allowed through with an error metric recorded, and your application continues to serve traffic. The agent also supports zero-downtime upgrades via tableflip: SIGUSR2 spawns a new process that inherits listeners, drains the old one, and exits cleanly.

How do I update WAFio to a new version?

Download the new binary and replace the existing one. For systemd deployments, send SIGUSR2 for zero-downtime reload (tableflip), or do a standard systemctl restart. Database migrations run automatically on startup with the --migrate flag, or manually via the wafio migrate up command.

Does WAFio support high-availability deployments?

Yes. Multiple WAF agents can connect to a single control plane. Agents receive configuration updates via gRPC bidirectional streaming: rule changes push to all agents without restart. The control plane itself can run behind a load balancer. Database (PostgreSQL + TimescaleDB) is the stateful component.

How are WAF rules pushed to agents?

The control plane maintains a persistent gRPC bidirectional stream with each agent. When you update a project's WAF configuration in the dashboard, the new bundle is pushed to all connected agents immediately. No agent restart, no polling delay.

Data and privacy

Does WAFio send my traffic data anywhere?

No. WAFio is fully self-hosted. No request payload, IP address, user session, or security log is sent to WAFio servers or any third-party infrastructure. All data stays inside your own network. There is no telemetry, no phone-home, and no cloud dependency in the data path.

Where are WAF logs and events stored?

WAF decision events are stored in your PostgreSQL + TimescaleDB database (waf_decisions table, a hypertable partitioned by time, compressed after a day). Host security events are stored in the same database. Retention is automatic: 30 days by default (host security events 7), adjustable by a system administrator under Administration › Data retention, with an optional database size alert. Credentials in request headers, query strings and bodies are redacted before a decision is stored. All storage is inside your own infrastructure.

Is WAFio compliant with OJK, PCI-DSS, or GDPR?

WAFio's architecture supports compliance requirements that mandate data sovereignty: no request payload leaves your server, no third-party processes your traffic, and audit logs are fully under your control. Compliance status depends on your overall environment and controls. WAFio provides the infrastructure foundation, not a compliance certificate.

Can WAFio run in an environment with strict data residency requirements?

Yes. WAFio has no mandatory outbound connections. Data residency is architectural: all processing happens inside your network. Air-gapped deployments (no internet access) are fully supported.

General

How much does WAFio cost?

WAFio software is free: no tiers, no feature locks, no license keys and no agent limits. Every feature, including all 20 semantic engines, the eBPF firewall, runtime security and the full dashboard, is included at no cost. For teams that need hands-on help, professional services are available: installation, SLA support contracts, and hardening audits. See the Services page for professional assistance.

Is WAFio open source?

WAFio follows an open-core model. Core detection logic, configuration schema, and deployment tooling are publicly available. The platform is freely downloadable and self-hostable without registration or license keys.

Do I need to create an account or register to use WAFio?

No. Download the binary, configure it, and run it. No sign-up, no API key, no phone-home required. WAFio does not require any external account to operate.

Does WAFio replace a cloud WAF?

WAFio covers the traffic inspection, injection detection, rate limiting and network filtering functions of a cloud WAF while keeping all data inside your own infrastructure. It also adds eBPF kernel-level network filtering and runtime process security inside the host.

Detection and features

What attacks does WAFio detect?

WAFio's 20 semantic engines detect: SQL injection, XSS, command injection, Prompt Injection (AI/LLM jailbreaks), Open Redirect, Local File Inclusion (LFI), Server-Side Request Forgery (SSRF), LDAP injection, prototype pollution, Java injection / Log4Shell, PHP injection, Python injection, NoSQL injection, Server-Side Template Injection (SSTI), XML External Entity (XXE), deserialization attacks, HTTP header (CRLF) injection, GraphQL introspection and batch abuse, JWT header attacks (alg:none, kid path traversal), and anomalous input.

How does semantic detection work?

Each semantic engine decodes, normalizes, and parses the payload for its target attack category. URL encoding, Base64, hex encoding, comment injection, whitespace tricks, and protocol obfuscation are all unwrapped before analysis. The engine evaluates the intent of the payload, not just its shape, making it resistant to common signature bypass techniques.

What is the eBPF firewall and what does it block?

The eBPF Network Firewall uses XDP (eXpress Data Path) and TC hooks to inspect and drop packets at the kernel driver level, before the Linux network stack processes them. It blocks traffic based on individual IPs, CIDR ranges, ASNs (autonomous systems), port/protocol combinations, and per-source rate limits. Effective against SYN floods, port scans, brute force, and IP-based attack infrastructure.

What does Runtime Security monitor?

Runtime Security uses eBPF kprobes and tracepoints to monitor live kernel activity: process execution (execve), file system operations (open, write, unlink on sensitive paths), outbound connections (connect, bind), privilege changes, and container boundary events. Every event is enriched with PID, parent process tree, binary hash, user, cgroup, and namespace identifiers.

Can WAFio detect Log4Shell and similar Java attacks?

Yes. The Java semantic engine specifically handles Log4j JNDI lookup obfuscation: nested ${lower:...} and ${upper:...} lookups are recursively unfolded up to 10 levels deep. URL-encoded colons and slashes in JNDI strings are decoded before analysis. Log4Shell variants that bypass single-pass detection are covered.

Does WAFio detect SEO hijacking / web shell activity?

WAFio blocks the attack vectors that lead to SEO hijacking (SQL injection, LFI, RFI, malicious file uploads) at the HTTP layer before they reach the application. If an attacker finds another entry point, Runtime Security detects the spawned web shell process via kprobe on execve: a web server spawning /bin/bash triggers an immediate alert.

Will WAFio generate false positives?

All WAFs can produce false positives. WAFio's Decision Engine uses configurable sensitivity levels (Safe / Balanced / Aggressive) and score thresholds per project. You can tune per-project sensitivity, raise score thresholds, or add path exceptions for specific endpoints.

Configuration and tuning

How do I tune detection sensitivity?

Each project has a configurable sensitivity level: Safe (1), Balanced (2), or Aggressive (3). Rules with a sensitivity level higher than your project setting are silently dropped: this is the primary false positive control. Lower sensitivity = fewer detections, fewer false positives. Raise it for higher-risk environments.

What are block and log thresholds?

WAFio's Decision Engine sums weighted scores from matched rules. Requests above the block_threshold (default 5.0) receive HTTP 403. Requests between log_threshold (default 2.0) and block_threshold are logged but allowed. Below log_threshold, requests pass silently. Both thresholds are configurable per project via the dashboard or rules JSON.

How do I whitelist a path or exclude an endpoint?

WAFio supports path exceptions: configure specific URL paths to skip individual rule categories (e.g., skip SQL semantic check on /api/search while keeping XSS protection active). This is done per-project in the WAF configuration. Health check paths and webhook endpoints are common candidates for partial exceptions.

Can I block traffic from specific countries?

Yes. WAFio includes GeoIP country blocking. In the project WAF configuration, add country codes to the block list. Country identification uses MaxMind GeoIP data bundled with WAFio. Blocked requests receive a configurable HTTP response.

Can I block specific IPs, CIDRs, or ASNs?

Yes, at two layers. The eBPF Network Firewall handles IP/CIDR/ASN blocks at the kernel level (dropped before userspace). The WAF agent also maintains block and allow lists at the application layer. Both are manageable from the dashboard in real-time, with no agent restart required.

How do I add custom WAF rules?

Open Custom Rules in the project sidebar. Condition-based rules match request fields and allow, block, log or challenge; only allow and block end inspection, while log and challenge record the match and let the pipeline continue. Script rules run in a sandbox with fixed time and memory limits, and only project owners can save or edit them.

Can I configure different settings per application?

Yes. WAFio is multi-tenant. Each project has its own WAF configuration: sensitivity level, score thresholds, blocked countries, rate limit settings, and path exceptions. One control plane manages multiple projects and agents independently.

Troubleshooting

WAFio is blocking legitimate traffic. What do I do?

First, check the dashboard for the blocked request details: which rule category triggered, the score, and the matched payload. Options to fix: (1) Lower project sensitivity from Aggressive to Balanced. (2) Raise the block_threshold. (3) Add a path exception for the affected endpoint. (4) Lower the base score of the semantic engine that fires, under Protection › Advanced scoring › Semantic engines.

The dashboard shows no events even though traffic is flowing.

Verify the WAF agent is connected: check agent status in the dashboard or look for "bundle received" in the agent log. Confirm the agent is configured as the upstream proxy for your application (traffic must route through the WAF agent, not bypass it). Check that the control plane is reachable from the agent host on the gRPC port (default :9090).

The WAF agent is not connecting to the control plane.

Common causes: (1) mTLS certificate mismatch: re-run the install command from Hosts › Connect this host (rotate the host key first if its 24-hour enrollment window has closed), or re-provision a credential from the Credentials page. (2) Wrong gRPC server address or port: check WAFIO_GRPC_SERVER in agent config. (3) SNI mismatch if connecting over IP: set WAFIO_GRPC_SERVER_NAME to the server's hostname. (4) Firewall blocking port 9090 on the control plane host.

The host agent fails to load eBPF programs.

The host agent requires a Linux kernel ≥ 5.10 with BTF (BPF Type Format) enabled. Check: uname -r (kernel version) and ls /sys/kernel/btf/vmlinux (BTF present). The agent must run as root or with CAP_BPF + CAP_PERFMON capabilities. Check systemd unit file for the correct User and AmbientCapabilities settings.

Login pages or APIs are triggering false positives.

Login endpoints often send passwords or tokens that trigger detection rules (special characters, base64 content). Solutions: (1) Add a path exception for /login or /api/auth that skips specific rule categories. (2) If the endpoint is internal-only, use the AllowLocalIPs configuration to bypass bot challenge for local/private address ranges. (3) Add the endpoint to the path exception list in the project WAF config.

Database migrations are failing on startup.

Run wafio migrate up manually from the directory containing config.yaml to see the specific error. Common causes: PostgreSQL TimescaleDB extension not installed (run CREATE EXTENSION IF NOT EXISTS timescaledb in psql), wrong database credentials, or a migration version mismatch. Use wafio migrate version to check current state.

How do I report a security vulnerability in WAFio?

Send a detailed report to hello@wafio.cloud with a description of the vulnerability, reproduction steps, and potential impact. Do not discuss security vulnerabilities in public channels. We aim to acknowledge reports within 48 hours and provide a remediation timeline within 5 business days.

If the FAQ does not cover what you need, send a detailed email. We respond to technical questions, bug reports, and deployment-specific issues.