Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion .github/workflows/ci-linux.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ on:
- "update.sh"
- "uninstall.sh"
- "validation/**"
- "libexec/**"
- ".github/workflows/ci-linux.yml"
workflow_dispatch:

Expand Down Expand Up @@ -55,4 +56,34 @@ jobs:
echo "::error::$fails validation test(s) failed"
exit 1
fi
echo "All validation tests passed"
echo "All validation tests passed"

udp-runtime:
runs-on: ubuntu-24.04
strategy:
fail-fast: false
matrix:
include:
- version: "26.6.27"
sha256: "b3e5902d06d6282fe53cfa2fc426058b9aeaa429b2c812e20887cd47f26d08bf"
- version: "26.10.31"
sha256: "e4bd9119f50ae7c41658b1abd0679ae06f98bd864a2907ff33f2f2cf7081b214"
steps:
- uses: actions/checkout@v4
- name: Install runtime fixture dependencies
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends jq uuid-runtime curl unzip python3
- name: Verify official Xray release
env:
CORE_VERSION: ${{ matrix.version }}
CORE_SHA256: ${{ matrix.sha256 }}
run: |
mkdir -p "$RUNNER_TEMP/xray"
curl -fsSL "https://github.com/XTLS/Xray-core/releases/download/v${CORE_VERSION}/Xray-linux-64.zip" -o "$RUNNER_TEMP/xray.zip"
printf '%s %s\n' "$CORE_SHA256" "$RUNNER_TEMP/xray.zip" | sha256sum -c -
unzip -q "$RUNNER_TEMP/xray.zip" -d "$RUNNER_TEMP/xray"
- name: Verify UDP destination changes and failure isolation
timeout-minutes: 3
run: |
python3 validation/test-private-cascade-udp-runtime.py --repo "$GITHUB_WORKSPACE" --xray "$RUNNER_TEMP/xray/xray" --local-ip 127.0.0.2
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,6 @@ DESIGN-REVIEW-*.md
# OS
.DS_Store
Thumbs.db

# Python UDP helper validation
__pycache__/
9 changes: 8 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@

User-facing Xrayebator changes. The server manager and Electron application are published from the canonical `howdeploy/Xrayebator` repository.

## [Unreleased]

### Added

- Opt-in private cascade configuration generation for a Russian ingress and foreign exit, with ordered TCP/UDP routing, a Python 3 UDP destination helper, fail-closed foreign routes, and deployment, update and removal guides.
- `profile-create --transport xhttp --without-pq` creates a legacy XHTTP profile with `encryption=none`. XHTTP profile creation uses PQ by default.

## [0.7.3] - 2026-11-07

Secrets no longer travel in process arguments. `/proc/<pid>/cmdline` is readable by every local
Expand Down Expand Up @@ -856,4 +863,4 @@ The first combined release of the updated server manager and **Xrayebator Deskto
- Hardening tasks found in a later audit around `safe_jq_write`, lifecycle rollback, JSON escaping, and existing-inbound validation are not included in this release.

Detailed English release notes: [docs/releases/v0.5.0.en.md](docs/releases/v0.5.0.en.md).
Russian release notes: [docs/releases/v0.5.0.md](docs/releases/v0.5.0.md).
Russian release notes: [docs/releases/v0.5.0.md](docs/releases/v0.5.0.md).
10 changes: 7 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Xrayebator — automated Xray Reality VPN manager for bypassing DPI censorship i
## Validation

There IS automated test coverage (despite what older notes said):
- **`validation/`** — 49 Bash test scripts, including `test-main-readiness-regressions.sh`, covering migrations, VLESS URL generation, subscription formats (Clash/mihomo YAML + sing-box JSON), DNS-01 certificate wiring, transaction safety, dedup, firewall, menu numbering, the backend registry, the Hysteria 2 backend renderers/lifecycle, the AmneziaWG backend junk/renderers, per-profile traffic accounting and limits, Telegram alerts/monitoring, the bypass/sni-change/port-change/profile-revoke/profile-expire CLIs, the HAPP client-routing generator, update branch pinning, quickstart, email/inspect regressions, apt-lock race regressions, the quickstart http_tls fallback and audit regressions. They run on the host (`bash validation/test-*.sh`); CI installs `jq`, `uuidgen` and `ripgrep` on Ubuntu. A bare Windows Git Bash checkout is not equivalent to the Linux environment.
- **`validation/`** — 51 Bash test scripts, including `test-main-readiness-regressions.sh` and the Python-backed `test-private-cascade-udp.sh`, covering migrations, VLESS URL generation, subscription formats (Clash/mihomo YAML + sing-box JSON), DNS-01 certificate wiring, transaction safety, dedup, firewall, menu numbering, the backend registry, the Hysteria 2 backend renderers/lifecycle, the AmneziaWG backend junk/renderers, per-profile traffic accounting and limits, Telegram alerts/monitoring, the bypass/sni-change/port-change/profile-revoke/profile-expire CLIs, the HAPP client-routing generator, update branch pinning, quickstart, email/inspect regressions, apt-lock race regressions, the quickstart http_tls fallback and audit regressions. They run on the host (`bash validation/test-*.sh`); CI uses Python 3 and installs `jq`, `uuidgen` and `ripgrep` on Ubuntu. A bare Windows Git Bash checkout is not equivalent to the Linux environment.
- **`gui-legacy/tests/`** — 16 pytest modules covering SSH, deploy, connection, subscription and TUN runtime (legacy PySide6 GUI). Run with the GUI venv: `gui-legacy/.venv/Scripts/python -m pytest gui-legacy/tests`.
- **GUI (Electron)** — Vitest unit tests in `tests/`: `npm test`, plus `npm run typecheck`.
- **CI** — `.github/workflows/ci-linux.yml` runs the full `validation/` suite; `.github/workflows/gui-release.yml` runs `ruff` + `pytest gui-legacy/tests` and builds Windows/macOS bundles; `.github/workflows/release.yml` ships the Electron app.
Expand All @@ -26,7 +26,9 @@ bash -n uninstall.sh

### Single-file application

All logic lives in `xrayebator`. Supporting scripts (`install.sh`, `update.sh`, `uninstall.sh`) handle lifecycle but are not part of the runtime. The repository is a single runtime source file, but a deployed VPS is not literally one file: `xrayebator` generates additional root-owned runtime artifacts from heredocs — `/usr/local/bin/subhttp.sh` (the subscription/geo HTTP handler, which sources `xrayebator` in source-mode), systemd units (`xrayebator-sub.service`, `xrayebator-expire.service/.timer`, `xrayebator-traffic.service/.timer`, `xrayebator-monitor.service/.timer`, backend units) and nginx vhosts. Never edit those on the server — change `xrayebator` and regenerate.
The Bash manager lives in `xrayebator`. Supporting scripts (`install.sh`, `update.sh`, `uninstall.sh`) handle lifecycle. The optional private cascade also uses the maintained `libexec/private_cascade_udp.py` runtime helper, which requires Python 3 and its standard library. Its unit tests and real-core fixture also require `python3`. The cascade guide installs the helper as `/usr/local/libexec/xrayebator-private-udp.py` with two separate systemd units and documents their manual update and removal.

`xrayebator` generates additional root-owned runtime artifacts from heredocs, including `/usr/local/bin/subhttp.sh` (the subscription/geo HTTP handler, which sources `xrayebator` in source-mode), systemd units (`xrayebator-sub.service`, `xrayebator-expire.service/.timer`, `xrayebator-traffic.service/.timer`, `xrayebator-monitor.service/.timer`, backend units) and nginx vhosts. Change their sources in `xrayebator` and regenerate them.

### Production paths

Expand Down Expand Up @@ -131,6 +133,8 @@ Do NOT use raw `jq ... > temp && mv temp file` — always go through `safe_jq_wr

## CLI commands

- `xrayebator private-cascade render --policy-file F --upstream-file U --output O.json` — write a separate, protected ingress configuration and validate it with the installed Xray core. The live configuration is preserved. Deployment uses the Python 3 helper from `libexec/` and the dedicated units described in [Private cascade](docs/private-cascade.md).

Apart from the interactive menu (`sudo xrayebator`), the script exposes subcommands used by the GUI and by automation. They are dispatched at the very bottom of `xrayebator` (the `case "${1:-}" in ... esac` block guarded by `XRAYEBATOR_SOURCED`):

- `xrayebator update` — update only the Xray-core binary; `xrayebator update <branch>` self-updates the manager from the canonical raw branch, pins that branch in `/usr/local/etc/xray/.current_branch` (the GUI updater reads this file), then updates Xray-core.
Expand Down Expand Up @@ -172,4 +176,4 @@ CLI JSON hygiene: `profile-create`/`profile-delete` **must** print only JSON on

## Language

Bash/server-facing strings, comments, and commit messages are in **Russian**. The active Electron renderer is intentionally multilingual (`ru`, `en`, `zh`); code identifiers and function names are in English.
Bash/server-facing strings, comments, and commit messages are in **Russian**. The active Electron renderer is intentionally multilingual (`ru`, `en`, `zh`); code identifiers and function names are in English.
7 changes: 6 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ is a client-side profile/route setting; changing it does not restart Xray or alt
| `sudo xrayebator kernel-guard [--status\|--enable\|--disable] [--quiet]` | Hardening against CVE-2026-98432 (a use-after-free in IPv4 option processing, CVSS 9.8, affecting every IPv4 TCP listener). `--enable` disables MPTCP in the kernel (`net.mptcp.enabled = 0` in `/etc/sysctl.d/99-xrayebator-netguard.conf`) and drops inbound IPv4 TCP packets that carry IP options using Ubuntu Security Team's rule in a dedicated nftables table plus its own boot unit — deliberately not `nftables.service`, whose default `flush ruleset` would wipe the UFW ruleset at boot. MPTCP is also disabled automatically by migration `netguard_mptcp_2026`; the nft drop stays opt-in because it changes which packets the server accepts. `--status` reports the running kernel, `newer_kernel_installed`, `reboot_required`, `mptcp_enabled`, `ipv4_options_drop`, the Xray-core version and whether it is at or above `26.10.31` (`xray_mptcp_safe`). It is a mitigation, not a kernel update. Also available as menu item 16 |
| `sudo xrayebator ssh-protect [--status\|--enable\|--disable] [--unban IP\|--prune-ignore] [--quiet]` | SSH brute-force protection: installs `fail2ban` with a journald-backed `sshd` jail (4 failures in 10 minutes → 30-minute ban, repeat offenders escalate up to a day) plus a `sshd_config.d` drop-in with `MaxAuthTries 3` / `LoginGraceTime 30`. **Password login stays enabled** — the desktop GUI manages the server with it, and key-only access remains a separate operator decision. Idempotent: the drop-in is validated with `sshd -t` before `ssh` is reloaded (not restarted), so open GUI sessions survive. Enabled automatically by `install.sh` and `quickstart` (the deploy JSON reports `ssh_protect`); `--quiet` suppresses the JSON for scripts. Also available as menu item 15 and as the **Security and TLS** tab in the GUI. Live measurement on a public VPS: 9 953 failed logins in 24 h from 115 addresses before, ≈72/h after. The address the command was run from is exempted from bans for 24 hours (`ignoreip` plus an epoch stamp; `--prune-ignore`, driven by `xrayebator-ssh-ignoreip.timer`, removes it on expiry) |
| `sudo xrayebator profiles` | Print all server profiles as a JSON array for the desktop GUI Server Settings page; expiry includes both epoch seconds (`expire`) for enforcement and the server-local calendar date (`expire_date`) for display, so clients in another timezone still see the selected date |
| `sudo xrayebator profile-create --name NAME [--transport tcp\|tcp-utls\|tcp-xudp\|tcp-mux\|grpc\|xhttp] [--port P] [--count N] [--expire DATE]` | Create one or more profiles non-interactively; `--expire` accepts `YYYY-MM-DD[ HH:MM]`, epoch seconds or 13-digit milliseconds. A date without time is inclusive through `23:59:59` in the server's local timezone; an explicit time uses that server-local time. Past expiries are rejected; existing names are never overwritten — they are reported in `errors` (the GUI also pre-checks a name collision before creating, since deletion is per-profile and unique names keep it precise); prints `{"ok":true,"names":[...],"errors":[...]}` |
| `sudo xrayebator profile-create --name NAME [--transport tcp\|tcp-utls\|tcp-xudp\|tcp-mux\|grpc\|xhttp] [--port P] [--count N] [--expire DATE] [--without-pq]` | Create one or more profiles non-interactively; XHTTP uses PQ by default. `--without-pq` is valid only for XHTTP and creates a legacy `encryption=none` profile on a free port or a compatible existing inbound. `--expire` accepts `YYYY-MM-DD[ HH:MM]`, epoch seconds or 13-digit milliseconds. A date without time is inclusive through `23:59:59` in the server's local timezone; an explicit time uses that server-local time. Past expiries are rejected; existing names are never overwritten — they are reported in `errors` (the GUI also pre-checks a name collision before creating, since deletion is per-profile and unique names keep it precise); prints `{"ok":true,"names":[...],"errors":[...]}` |
| `sudo xrayebator profile-delete --name NAME` | Delete a profile non-interactively; the deleted profile's backend grants are revoked immediately (the AWG peer is dropped from `awg0.conf`, the Hysteria password from `server.yaml` — no orphaned credentials) and the name is free for reuse; prints `{"ok":true,"name":"..."}` |
| `sudo xrayebator profile-revoke --name NAME [--full]` | Reissue the subscription link: new `sub_token`; with `--full` also a new uuid in every inbound of the profile (already-downloaded configs are cut off); prints JSON |
| `sudo xrayebator profile-expire --name NAME --expire DATE\|epoch\|none` | Set, extend or remove a profile expiry; a date without time is inclusive through `23:59:59` in the server's local timezone, while an explicit time is used as given in that timezone; applied immediately (a passed expiry removes the client, an extension restores it); prints JSON |
Expand Down Expand Up @@ -676,6 +676,8 @@ button in Server settings.

## Cascade and upstream nodes

The scope of `--without-pq` depends on the command. `quickstart --without-pq` skips the additional PQ route in the managed multi-route profile. `profile-create --transport xhttp --without-pq` creates the base XHTTP profile with `encryption=none` instead of PQ.

The cascade is a server-side outbound and routing mode, not a new client profile. The client keeps
connecting to the current VPS:

Expand All @@ -696,6 +698,9 @@ Disabling the cascade removes the `cascade-upstream` outbound and returns the ca
Item `10` configures the other side: it turns the current VPS into the foreign node that a cascade
from another server connects to.

For a separate Russian ingress that routes selected destinations locally and sends other traffic
through a restricted foreign node, see [Private cascade deployment](private-cascade.md).

## Custom domain and self-steal stub

Self-steal puts nginx with a valid certificate on `127.0.0.1:9444`, and Reality inbounds receive
Expand Down
Loading
Loading