Quick reference

The HTTP signals, the vocabulary, the go-live steps and the kokiguard command, to keep at hand.

R.2 Recognize a kokiGUARD response

Situation	Code	Signal that the client sees
Blocked by a rule	403	x-waf-action: blocked header and block page with an ID, which the X-Request-ID header also gives
Blocked by country	403	X-Geo-Blocked: 1 header
Robot blocked	403	X-Bot-Blocked header: the name of the robot, or impostor for an impostor
Challenge requested	403	Challenge page on a web page, which a browser solves by itself; 403 without a page for another type of request
Body larger than the inspected size	413	x-waf-action: body-too-large header
Rate limit exceeded	429	retry-after: 60 header
Waiting room queue full	429	retry-after: 10 header and waiting page
Maintenance mode	503	Maintenance page
JS challenge	200	Calculation page instead of the site; a browser gets through by itself
Banned IP	—	Connection cut or timeout, depending on the ban method
Site in Detect mode	200	No signal: look at the logs

R.3 Glossary

Term	Definition
WAF	Web application firewall. It reads the content of HTTP requests, where a network firewall sees only addresses and ports.
AS	Autonomous system: the network (hosting provider, operator, cloud provider) that announces an IP address on the Internet. Badge next to each address, tab of the threat radar.
CRS	OWASP Core Rule Set: the reference open-source ruleset, which kokiGUARD uses through the Coraza engine.
Anomaly score	Total of the points that the rules add when they react to a request. Above the threshold of the site, the request is blocked.
Paranoia (PL)	Severity level of the rules, from 1 to 4. The higher the level, the more it detects, and the more false positives it causes. Set with Kokiris.
Training phase	Go-live period in which Kokiris adds all your sites in Detect mode, corrects the false positives and adjusts the configuration, before the change to Block, then to Ban.
False positive	Legitimate request that the WAF takes for an attack. You correct it with the narrowest possible scope, on one or more rules and one or more fields.
Radiography	Full view of a recent request: its outcome and its HTTP code, its score, the rebuilt request with what triggered, the statistics of the field over 24 h and the correction that already covers it.
Trusted traffic	Traffic exempted from inspection (“Skip inspection”) or forced to inspection (“Always inspect”).
IP group	Named list of addresses (IP or CIDR), which the path rules of trusted traffic can use again, in “Skip inspection” or “Restricted access” (403 for the other addresses).
Reputation	Points that an IP accumulates in Ban or Challenge mode, which decide if the IP is banned or challenged.
Challenge	Calculation (proof of work) that a browser does by itself in less than one second, and that a simple script does not do. Replaces the ban in Challenge mode, and is also an action against a robot.
Verified robot, impostor	A verified robot has the User-Agent of a known robot and an address in the ranges that its owner publishes. An impostor has this User-Agent, but an address outside these ranges.
Condition	Criterion on the request (header, parameter, cookie…) that limits a correction or a trusted entry to the requests that meet it.
Body too large	Request whose body is larger than the size that kokiGUARD inspects: refused with 413 or let through, depending on the site.
Automatic apply	Setting that makes the leader apply the pending changes, when they have not changed for 90 seconds.
Jail	Fail2Ban ban queue, with its duration: 10 min, 6 h, 24 h or permanent.
Revision	Full, validated version of the configuration, which you can compare and apply again.
Back-office path	Folder of the admin area of a PrestaShop or Magento shop, declared in the site page. The Kokiris rulesets recognize the back office only under this path.
Custom profile	Read / Write permission grid, page by page, for an account or an API key. The menus follow the grid.
Reseller, member	Accounts of a shared kokiGUARD, limited to their sites. The reseller creates its members, within its rights and among its sites.
API key	Access of a script to the panel, without a password. Its rights never go above the rights of its creator.
Leader	Cluster node that accepts the changes and sends them to the other nodes.
Scanner detection	Counts, per address, the error responses of the sites. Above the threshold, the address appears in the logs (“Scan · N/min”) and, in Ban mode, it is banned from all sites.
Detection-only rule	Rule of a Kokiris ruleset that reports without blocking: 0 points, for the score and for the ban.
Canary rule	Harmless rule that blocks a known request, to check that the WAF applies the rules correctly.

R.4 The go-live steps

To follow the progress with Kokiris. You can tick the boxes to help you; they stay in this browser.

• All your sites appear in Sites, with their aliases.
• Training phase started: WAF turned on in Detect mode on each site.
• Kokiris ruleset for your CMS turned on for each site concerned.
• Back-office path set on each PrestaShop or Magento shop.
• Canary rule tested with curl: 403 and x-waf-action: blocked.
• False positives reviewed and corrected with Kokiris.
• Rate limiting set on the login pages.
• Robots and crawlers policy chosen for each site.
• Large uploads checked: upload paths exempted, or inspected size adjusted.
• Fixed IPs of your team sent to Kokiris.
• End of training: change to Block, then to Block + ban, approved with Kokiris.

R.5 kokiguard (shell)

For administrators who have root access to a kokiGUARD node, usually at Kokiris. Without shell access, do the same actions in the panel: Cluster Management (chapter 5.3) and Fail2Ban (chapter 4.1).

Command	Effect
kokiguard status	The cluster as this node sees it: leader (★), term, and for each node its role, its state and the applied revision.
kokiguard ban <ip|cidr> [--jail <prison>]	Bans an address or a network on the full cluster, through the leader: the ban is in the history and in the audit log. Default jail: waf-ban-10m.
kokiguard unban <ip|cidr>	Removes the address from all jails, on the full cluster.
kokiguard check	Health check of this node, read-only: services, API, haproxy -c, Redis, bans, scanner detection, version, disks. Icinga exit code: 0 OK, 1 WARNING, 2 CRITICAL, 3 UNKNOWN.
kokiguard update	Updates this node and its remote nodes. It does nothing if the published version is already installed. In a cluster, run it on the node that deploys the cluster (node-1).
kokiguard help <commande>	The details of a command and of its options.

terminal · root on a node

kokiguard status
kokiguard ban 203.0.113.0/24 --jail waf-ban-24h
kokiguard unban 203.0.113.0/24

--local: emergency use only

kokiguard ban --local and kokiguard unban --local go through Fail2Ban on this node only, when the API or the leader does not answer. The other nodes are not notified, and the action is not in the history or in the audit log. When the API answers again, do the action again without --local.

Installation, repair, leader failover and emergency recovery: see the installation guide INSTALL.md of the kokiGUARD repository.