feat(node-plugins): add abuse blocker configuration schema

[l0nelynx]

Suggested PR title

feat(node-plugins): add abuse blocker configuration schema

Summary

This PR introduces the public configuration contract for a new optional Node plugin named abuseBlocker and bumps @remnawave/node-plugins from 0.6.3 to 0.7.0.

The plugin is intended to detect scan-like abuse per user on Remnawave Node, maintain a short-lived local score, report suspicious activity to the backend, and temporarily block the current source IP when the configured score threshold is reached.

This is the first PR in a staged implementation. It adds only the shared schema and its tests. It does not yet change Node runtime behavior, Xray routing, nftables, database models, or user status handling.

Motivation

torrentBlocker can react to a single protocol classification emitted by Xray. Scan detection requires configurable aggregation across multiple connections belonging to the same user.

The new schema establishes a versioned contract between the backend, frontend schema consumers, and Node before the runtime implementation is introduced. Making the contract available first allows the Node PR to depend on a published package instead of duplicating configuration types.

Planned detection and scoring model

The runtime implementation built on this schema will process TCP routing events that contain a user ID, source IP, destination IP, and destination port. Domain-only destinations will not be counted.

Two detectors are enabled by default:

1. Horizontal scan

   • Same user and destination port.
   • Same IPv4 /24 or IPv6 /64 prefix.
   • At least 20 unique destination IPs in 60 seconds.
   • Adds 100 score points.

2. Destination sweep

   • Same user and destination port.
   • At least 50 unique destination IPs in 60 seconds.
   • Adds 50 score points.

Ports 80 and 443 are excluded by default.

The default score bands are:

• Below 50: no report or action.
• 50–99: store a suspicious event.
• 100–149: alert and retain enhanced evidence.
• 150 or more: temporarily block the current source IP for 10 minutes.

The backend follow-up will escalate repeated blocking incidents within seven days to a one-hour block and then to account disablement with manual review.

Configuration reference

All values below are defaults unless noted otherwise.

General settings

Parameter	Default	Validation	Purpose
enabled	Required	Boolean	Enables the plugin.
excludedPorts	[80, 443]	Unique ports from 1 to 65535	Destination ports ignored by both detectors.
scoreWindowSeconds	3600	60–86400	Rolling period used to retain score events.
incidentCooldownSeconds	300	0–86400	Minimum delay before the same re-armed detector key can score again.
suspiciousScore	50	1–100000	Start of the suspicious band.
alertScore	100	1–100000	Start of the alert/enhanced-evidence band.
blockScore	150	1–100000	Score at which the current source IP is blocked.
initialBlockSeconds	600	1–2592000	Initial temporary block duration.
repeatBlockSeconds	3600	1–2592000	Block duration for a repeat offender.
repeatWindowSeconds	604800	60–31536000	Window in which blocking incidents count as repeats.
evidenceLimit	10	1–1000	Maximum baseline destination evidence retained per report.
enhancedEvidenceLimit	50	1–5000	Evidence limit after reaching the alert score.
maxTrackedUsers	50000	1–1000000	Memory safety limit for locally tracked users.
maxKeysPerUser	256	1–4096	Memory safety limit for detector keys per user.
reportBufferSize	10000	1–1000000	Maximum number of reports buffered by Node.

Cross-field validation requires:

• suspiciousScore < alertScore < blockScore;
• initialBlockSeconds <= repeatBlockSeconds;
• evidenceLimit <= enhancedEvidenceLimit.

Ignore lists

Parameter	Default	Accepted values	Purpose
ignoreLists.userId	[]	Positive integer user IDs	Users excluded from scoring and blocking.
ignoreLists.sourceIp	[]	IPv4, IPv6, CIDR, or ext:list_name	Trusted source addresses excluded from the plugin.
ignoreLists.destinationIp	[]	IPv4, IPv6, CIDR, or ext:list_name	Destinations excluded from scan aggregation.

The IP lists reuse the existing sharedLists/ext: contract.

horizontalScan

Parameter	Default	Validation	Purpose
enabled	true	Boolean	Enables horizontal scan detection.
windowSeconds	60	1–3600	Rolling unique-destination window.
uniqueDestinations	20	2–65535	Unique IP threshold inside one prefix.
ipv4Prefix	24	0–32	IPv4 aggregation prefix.
ipv6Prefix	64	0–128	IPv6 aggregation prefix.
score	100	1–10000	Score added by one re-armed incident.

destinationSweep

Parameter	Default	Validation	Purpose
enabled	true	Boolean	Enables destination sweep detection.
windowSeconds	60	1–3600	Rolling unique-destination window.
uniqueDestinations	50	2–65535	Unique destination threshold for one port.
score	50	1–10000	Score added by one re-armed incident.

Compatibility

• abuseBlocker is optional in NodePluginSchema.
• Existing plugin documents continue to parse without modification.
• No runtime behavior changes until a Node explicitly consumes and enables this section.
• The minor package version bump reflects the backward-compatible schema addition.

Tests

Added Node test coverage for:

• documented defaults;
• custom thresholds, prefixes, shared lists, and scores;
• invalid score ordering;
• duplicate excluded ports and invalid prefixes;
• backward compatibility when abuseBlocker is absent.

Validation performed locally:

cd libs/node-plugins
npm run test
npm run build:frontend
npm pack --dry-run

All five schema tests pass, and both backend and frontend package builds succeed.

Implementation roadmap

• PR 1/3 — Configuration contract (this PR): add the optional abuseBlocker schema, validation, defaults, tests, and publish @remnawave/node-plugins@0.7.0.
• PR 2/3 — Node runtime (remnawave/node#46, Draft): update Remnawave Node to @remnawave/node-plugins@0.7.0 and add Xray observation, local detection/scoring, report buffering, health state, nftables enforcement, and the extended @remnawave/node-contract. The Draft uses the locally packed schema until the package is published; its final contract version bump and lockfile remain release-gated.
• PR 3/3 — Backend runtime (remnawave/backend#208, Draft): add report persistence, repeat-offender escalation, manual-review APIs, and Telegram/webhook integrations. The Draft uses the locally packed Node contract until that package is published; dependency versions and lockfiles remain release-gated.

All three PRs target the dev branches and remain Draft until the cross-repository package versions are published, registry dependencies and lockfiles are finalized, and the complete test suites are green.

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[what-the-diff]

PR Summary

• Added Configuration for Blocking Abusive Behavior
  Introduced a new AbuseBlockerPluginSchema that contains a variety of configurations to identify and block any signs of abusive behavior. It includes features to ignore identified errant user IDs and IPs, to detect unique patterns in user behavior, and to track if users are contacting an extraordinary number of destination IPs. Additional properties for scoring and blocking rates have also been added.

• Upgraded Node Plugin Configuration
  The existing NodePluginSchema has been updated to include a newly introduced abuseBlocker property. This allows for optional configuration of the Abuse Blocker as per user preference.

• Package Version Incremented
  The software package version has been updated from 0.6.3 to 0.7.0. A new test script has also been added to facilitate testing capacity of the package.

• Created Tests for New Plugin
  A new test file named node-plugins.schema.test.cjs has been created. This file validates the functionalities of the AbuseBlockerPluginSchema. It checks if the default and custom configurations are parsed correctly, and it also tests for conditions that should result in rejection - like unordered scores and duplicate ports. It ensures the software is backward compatible for configurations that do not utilize the Abuse Blocker.

• TypeScript Configuration Updated
  To improve efficiency, the TypeScript configurations have been edited to exclude build and test directories from the software compilation process. This modification ensures only fundamental segments of the code are compiled, saving time and processing power.

[greptile-apps]

Greptile Summary

The PR adds the optional abuseBlocker configuration contract and prepares version 0.7.0 of the node-plugins package.

• Defines validated defaults, ignore lists, detector settings, resource limits, and cross-field constraints.
• Adds schema tests for defaults, customization, invalid configurations, and backward compatibility.
• Updates TypeScript exclusions and package scripts for isolated builds and compiled-schema testing.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
libs/node-plugins/models/node-plugins.schema.ts	Adds the optional Abuse Blocker schema with bounded defaults and cross-field validation; no eligible follow-up defect was established.
libs/node-plugins/tests/node-plugins.schema.test.cjs	Covers the new schema’s defaults, custom values, validation failures, and compatibility when the plugin is absent.
libs/node-plugins/package.json	Bumps the package to 0.7.0 and adds a test command that rebuilds backend output before running tests.
libs/node-plugins/tsconfig.backend.json	Excludes generated build output from backend compilation without excluding required source files.
libs/node-plugins/tsconfig.frontend.json	Excludes generated output and test files from frontend compilation without excluding required source files.

_{Reviews (2): Last reviewed commit: "test(node-plugins): validate abuse block..." | Re-trigger Greptile}