cheburcheck

The project is divided into several specialized modules:

• querying: Module for checking sites against databases.
• reporter: Cheburcheck Reporter for collecting white lists.
• reports: Common protocol for sending reports.
• website: Rocket API and server-side logic.
• probe: Cheburcheck Probe.
• frontend: SvelteKit SSR interface.

Cheburcheck uses nginx as a public entry point to route traffic between the backend API and the frontend SSR service:

• Backend (Rocket API): Routes starting with /api/v1/*, /agency/*, and /whitelist/* are proxied to the Rocket server.
• Frontend (SvelteKit SSR): All other requests are proxied to the SvelteKit SSR service.

Core Workflow:

1. A user submits a domain or IP address.
2. The server performs a DNS query via Quad9 DoH (DNS-over-HTTPS) to ensure data accuracy and bypass local restrictions.
3. The resulting domain/IP is checked against blocking lists using prefix trees.
4. Results are returned via the API and rendered by the SvelteKit frontend.

The probe acts as a dynamic scanner that connects to the Cheburcheck MQTT broker via WebSocket.

Workflow:

1. Status Update: Publishes a retained online status to MQTT.
2. Subscription: Subscribes to dynamic scanning configurations.
3. Task Acquisition: Receives domain check tasks.
4. Execution: Performs parallel checks on configured test hosts.
5. Reporting: Sends technical results back to Cheburcheck.

Technical Check Details: For each test host, the probe:

• Opens a TCP connection.
• Initiates a TLS handshake with the target domain in the SNI.
• Sends a simple HTTP GET request.

Note: TLS certificate validation is intentionally disabled because the goal is to measure connection availability, not certificate trust.

To recreate the current project with its exact configuration (minimal template, TypeScript, and TailwindCSS with no plugins), use the following command with pnpm:

pnpm dlx sv@0.15.3 create --template minimal --types ts --add tailwindcss="plugins:none" --install pnpm frontend

Use npx sv create to initialize a new Svelte project. This uses the sv CLI tool.

npx sv create my-app

To generate a production build, run npm run build. You can then use npm run preview to test the production build locally. Note that for actual deployment, you may need to install a SvelteKit adapter specific to your target environment.

npm run build

# preview the production build
npm run preview

You can build the reporter for Debian-based distributions using cargo-deb or run it directly from the source on other operating systems.

Note on System Limits: If you are performing a high volume of concurrent requests, ensure your system's open files limit is sufficient. You can check and modify this value using ulimit -n.

# For Debian-based distributions
cargo deb

# For other distributions/OS
cargo run

You can run the probe directly from source or using Docker.

Run from source

PROBE_ID=1 \
PROBE_TOKEN=ваш-токен \
MQTT_HOST=wss://cheburcheck.ru/mqtt \
MQTT_PORT=443 \
cargo run --package probe --bin cheburprobe

Run via Docker

docker run --rm \
  -e PROBE_ID=1 \
  -e PROBE_TOKEN=ваш-токен \
  -e MQTT_HOST=wss://cheburcheck.ru/mqtt \
  -e MQTT_PORT=443 \
  ghcr.io/lowderplay/cheburcheck-probe:latest

After creating the project and installing dependencies (via npm install, pnpm install, or yarn), start the development server using npm run dev. To automatically open the application in a new browser tab, use the --open flag.

npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

The reporter is pre-configured to scan the top 100,000 domains from the Tranco list (as of November 26, 2025). You can use the CLI to either save results locally or upload them to the Cheburcheck Agency.

To obtain an API key for uploading results, contact agency@cheburcheck.ru with your ISP and region details.

# Save results to a CSV file
cheburchecker output.csv

# Send results to Cheburcheck Agency using an API key
cheburchecker -k <API-KEY>

You can deploy the entire Cheburcheck stack using Docker Compose. By default, the nginx entry point listens on http://localhost:8080.

To start the services, run:

docker compose up --build

If you need to change the listening port, use the HTTP_PORT environment variable.