README

Note on Features & Quotas: Advanced features (like Bot Challenge and Custom Shield Pages) are tied to your subscription plan. If you exceed your monthly API quota, the agent will operate in a degraded mode (basic protection) before ultimately failing-open to prevent locking you out of your own site. All configuration rules are centrally managed via the dashboard.

Overview

The Relintio PHP agent is a single-file, framework-agnostic WAF that protects any PHP 7.4+ application. It intercepts requests at the earliest possible point via auto_prepend_file or a require_once in your entrypoint.

Risk-Scoring Engine

Every request is evaluated by an additive 0–100 risk-scoring engine. Signals are scored independently and summed:

Signal	Points	Rationale
Empty/missing UA	+40	No legitimate browser omits UA
Headless UA hint	+25	Puppeteer, PhantomJS, Playwright
Missing Accept-*	+15	Real browsers always send Accept
POST without Referer	+20	Form spam / API abuse pattern
Rate burst (>24/sec)	+35	Automated scanning / DDoS

5-Tier Graduated Response

Tier	Score Range	Action
ALLOW	0 – 39	Request proceeds normally
SLOW	40 – 59	2-second `usleep()` delay
CHALLENGE	60 – 74	JavaScript challenge page
DECOY	75 – 84	Serve fake/scrambled content
BLOCK	85 – 100	Hard block (403 + `exit`)

Installation

Method 1: auto_prepend_file (Recommended)

; php.ini or .user.ini
auto_prepend_file = /path/to/agent.php

Method 2: require_once

<?php
// index.php (first line)
require_once __DIR__ . '/agent.php';

Method 3: Composer (Laravel/Symfony)

composer require relintio/agent

Then register middleware in your framework bootstrap.

Configuration

All config via environment variables or constants:

Variable	Default	Description
`UP_LICENSE_KEY`	—	License key from Relintio console
`UP_API_URL`	`https://relintio.com/api`	API endpoint
`UP_MODE`	`enforce`	`observe` (log only) or `enforce`
`UP_LOG_ALLOWED`	`false`	Log ALLOW-tier requests
`UP_RATE_TOKENS`	`8`	Token-bucket refill rate (tokens/sec)
`UP_RATE_BURST`	`24`	Maximum burst capacity
`UP_CACHE_TTL`	`300`	Rules cache TTL in seconds

Token-Bucket Rate Limiting

The agent uses a path-aware token-bucket rate limiter (8 tokens/sec, 24 burst). Each unique IP+path pair gets its own bucket. Exceeding the burst triggers a +35 risk score contribution.

SEO Safety

When enabled, verified Googlebot and Bingbot crawlers bypass challenge/block tiers.

Fail-Open Guarantee

If the Relintio API is unreachable, the agent silently passes all traffic. Your site is never blocked due to connectivity issues.

Compatibility

PHP 7.4+ (PHP 8.x recommended)
Works with Laravel, Symfony, WordPress, Magento, Drupal, CodeIgniter, and vanilla PHP
No external dependencies (cURL or file_get_contents for HTTP)

relintio-agent/agent

包简介

关键字：

README 文档