Integrating kk-anti-reptile Anti‑Crawler into Spring‑Boot Applications

kk-anti-reptile is an anti‑crawler component designed for distributed systems built on Spring‑Boot .

System Requirements

Spring‑Boot 1.x or 2.x

Redis

Workflow

The component registers a Filter via Spring’s extension points, injects it with FilterRegistrationBean, and processes each request. Inside the filter a chain‑of‑responsibility weaves various rules; if a rule blocks the request, a 509 status and a captcha page are returned.

Built‑in Rules

ip‑rule : counts requests within a configurable time window, with adjustable maximum request count and optional IP whitelist.

ua‑rule : inspects the User‑Agent header to extract OS, device, and browser information, allowing filtering based on configurable dimensions such as allowed platforms.

When a rule matches, the request is blocked and a captcha is presented. Captchas include Chinese characters, alphanumeric strings, or simple arithmetic, each available as a static image or GIF; correct entry restores access.

Integration

Add the Maven dependency:

<dependency>
    <groupId>cn.keking.project</groupId>
    <artifactId>kk-anti-reptile</artifactId>
    <version>1.0.0‑SNAPSHOT</version>
</dependency>

Enable the component in application.properties (or bootstrap.properties when using Apollo): anti.reptile.manager.enabled=true The frontend must intercept HTTP 509 responses, display the captcha page, and pass the baseUrl parameter to the backend. Example using Axios interceptors:

import axios from 'axios';
import { baseUrl } from './config';

axios.interceptors.response.use(
  response => response,
  error => {
    if (error.response && error.response.status === 509) {
      const html = error.response.data;
      const verifyWindow = window.open('', '_blank', 'height=400,width=560');
      verifyWindow.document.write(html);
      verifyWindow.document.getElementById('baseUrl').value = baseUrl;
    }
    return Promise.reject(error);
  }
);
export default axios;

Additional Notes

If using Apollo, enable bootstrap ( apollo.bootstrap.enabled=true) and ensure the component’s @ConditionalOnProperty can read the configuration.

If Redisson is not already in the project, provide connection settings, e.g.:

spring.redisson.address=redis://192.168.1.204:6379
spring.redisson.password=yourPassword

Configuration Overview

enabled

– whether the anti‑crawler plugin is active (default true). include-urls – comma‑separated list of URL patterns to protect (e.g., /client,/user). ip-rule.enabled – toggle IP rule (default true). ip-rule.expiration-time – length of the time window in milliseconds (default 5000). ip-rule.request-max-size – maximum requests per window (default 20). ip-rule.ignore-ip – IP whitelist, supports * wildcard. ua-rule.enabled – toggle User‑Agent rule (default true). ua-rule.allowed-linux – allow Linux clients (default false). ua-rule.allowed-mobile – allow mobile devices (default true). ua-rule.allowed-pc – allow PC clients (default true). ua-rule.allowed-iot – allow IoT devices (default false). ua-rule.allowed-proxy – allow proxy access (default false).