ExploitFA

A clear, honest, English-first desktop client for Xray VLESS on Windows.

No telemetry. No account. No hidden network calls. A real Qt interface, a strict configuration format, and a VPN core you control.

Download · Documentation · Roadmap · FAQ · Report a bug

Why ExploitFA
Screenshots
Features
How it works: demo mode vs. live mode
Requirements
Quick start
Configuration
Connecting a real VPN core
Command-line interface
Building the Windows executable
Project architecture
Testing and quality
Troubleshooting
FAQ
Roadmap
Contributing
Privacy and security
License and acknowledgements

Why ExploitFA

Most desktop VPN clients for VLESS are either heavyweight Electron applications that phone home, opaque binaries, or quick scripts with no interface at all. ExploitFA takes a different position:

The interface is honest. Demo mode is the default and the UI says so on every screen. Nothing implies your traffic is protected when it is not.
You own the core. ExploitFA never silently downloads a VPN binary. You place xray.exe or sing-box.exe in cores/, and the build verifies its SHA-256 before packaging it.
Configuration is a file, not a black box. Servers live in config/servers.json, hot-reload while the app is open, and are validated with actionable error messages instead of a generic failure toast.
The codebase is small and testable. Pure parsing, validation and core supervision logic is separated from the widgets and covered by a growing test suite (92 tests, no network required).
It respects your machine. No telemetry, no background services, no registry changes, no startup entries, and no system-wide routing installed behind your back.

ExploitFA is a young project. It is intentionally scoped, and the roadmap shows what is real today and what is not.

Screenshots


_{Dashboard — selected route, session state and metrics}	_{Demo session — clearly labelled, never claims protection}


_{Servers — external JSON, hot reload, VLESS import}	_{Settings — appearance, scale, connection mode}

_{Activity — a readable timeline you can export}	_{About — version, scope and licence}

Light theme preview (click to expand)


_{Dashboard — light palette}	_{Servers — light palette}

Screenshots are generated from the real application, not mocked up: python tools/capture_screenshots.py renders every page in both themes headlessly with QT_QPA_PLATFORM=offscreen.

Features

Interface

Frameless, draggable Windows shell with native minimise / maximise / close
English, left-to-right layout by design
Dark, Light and System appearance modes
Interface scale from 90 % to 115 %
Bundled Inter variable font — no font downloads, identical rendering everywhere
Dashboard with route visual, session timer and transfer metrics
Servers view with country flags, protocol, port, ping and load
Activity timeline with friendly copy and plain-text export
About page that states the project scope instead of marketing it

Configuration and data

External config/servers.json with automatic hot reload (file watcher)
Strict validation with actionable, non-technical error banners
vless:// share-link import from the clipboard or the CLI
Per-field validation: port range, security mode, transport, tags, optional metadata
Preferences stored in config/app.json with atomic writes
Local-only data: no telemetry, no account, no remote configuration

Core integration (optional, opt-in)

Xray configuration builder for VLESS (Reality, TLS, plaintext)
Transports: TCP, WebSocket, gRPC
Loopback-only SOCKS5 (127.0.0.1:10808) and HTTP (127.0.0.1:10809) inbounds
Process supervisor with readiness probing, graceful stop and kill fallback
sing-box / xray discovery in cores/, SHA-256 verified at package time
Live mode switch in Settings; demo mode remains the default

Engineering

92 tests across parsing, validation, configuration, process supervision, CLI and UI
Headless UI smoke tests (no display server required)
Ruff lint + format enforcement
CI on Ubuntu and Windows × Python 3.11, 3.12, 3.13
One-command PyInstaller build with checksum output
Type hints throughout, from __future__ import annotations, immutable data models

Not implemented yet

System-wide TUN adapter (live mode exposes a local proxy only)
Kill switch, split tunnelling, auto-connect on startup
Subscriptions, traffic statistics, latency benchmarking
Tray icon, notifications, Windows startup integration
Credential encryption at rest (OS keystore)
Protocols other than VLESS in the config builder (VMess, Trojan, Shadowsocks)

See docs/ROADMAP.md for the honest, prioritised list.

How it works: demo mode vs. live mode

ExploitFA deliberately separates "exploring the interface" from "routing traffic". You choose the mode in Settings → Connection mode.

	Demo mode (default)	Live core mode
What Connect does	Simulates a session in the UI	Starts `xray.exe` with a generated config
Traffic protection	None — nothing is routed	Local SOCKS5/HTTP proxy on loopback
Needs a core binary	No	Yes, `cores/xray.exe` (or `sing-box.exe`)
Needs valid credentials	No	Yes — a VLESS UUID (and Reality keys if used)
Interface label	`DEMO MODE` badge, "Demo" in the status line	`LIVE CORE` badge, real proxy endpoints
Safe to click around	Yes	Yes, but reads real credentials from your config

In live mode ExploitFA writes config/xray.generated.json, launches the core with run -c <config>, waits until the SOCKS port accepts connections, and stops the process when you disconnect or close the window.

Important: live mode exposes a local proxy, it does not install a system-wide tunnel. Applications must be pointed at 127.0.0.1:10808 (SOCKS5) or 127.0.0.1:10809 (HTTP). A TUN adapter is the top item on the roadmap.

Requirements

Requirement	Details
Operating system	Windows 10 or 11 (x64). The test suite also runs on Linux and macOS in CI.
Python (source only)	3.11+ — 3.11, 3.12 and 3.13 are tested
Runtime dependency	`PySide6 >= 6.7, < 7`
Optional	An Xray or sing-box binary placed in `cores/` for live mode
Disk	~150 MB for a virtual environment, ~70–120 MB for the packaged EXE

Quick start

Option A — download the executable (recommended)

Open the Releases page.
Download ExploitFA-<version>-windows-x64.zip.

Verify the download against SHA256SUMS.txt included in the release:

Get-FileHash .\ExploitFA-0.2.0-windows-x64.zip -Algorithm SHA256

Extract the archive anywhere writable (for example %LOCALAPPDATA%\ExploitFA).
Run ExploitFA.exe. The app starts in demo mode with an empty server list.

Option B — run from source

git clone https://github.com/Largo-m/ExploitFA.git
cd ExploitFA

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

python -m src.main

If your network cannot reach PyPI, these mirrors serve the PySide6 wheels:

python -m pip install -r requirements.txt --index-url https://mirrors.sustech.edu.cn/pypi/web/simple

First run

The app creates config/servers.json (empty) and config/app.json (defaults).
Open Servers and click Import link after copying a vless:// URL, or edit config/servers.json by hand — it reloads automatically.
Optional: open Settings → Connection mode and switch to Live core if a binary is present in cores/.
Press Connect.

Configuration

ExploitFA keeps every piece of user data in plain, portable JSON next to the executable (or in the repository root when running from source). Nothing is written to the registry.

config/
├── servers.json            # your servers and credentials  (git-ignored)
├── app.json                # appearance and connection mode (git-ignored)
├── xray.generated.json     # generated core config          (git-ignored)
├── servers.example.json    # documented example, safe to copy
└── subscriptions.json      # reserved for subscription URLs

A complete server entry:

{
  "version": 1,
  "servers": [
    {
      "id": "frankfurt-reality",
      "name": "Germany - Frankfurt",
      "country": "DE",
      "protocol": "vless",
      "address": "de.example.com",
      "port": 443,
      "uuid": "11111111-1111-4111-8111-111111111111",
      "flow": "xtls-rprx-vision",
      "security": "reality",
      "sni": "www.example.com",
      "fingerprint": "chrome",
      "public_key": "REPLACE-WITH-REALITY-PUBLIC-KEY",
      "short_id": "0123456789abcdef",
      "network": "tcp",
      "tags": ["fast"],
      "is_favorite": true,
      "load": 23,
      "ping_ms": 42
    }
  ]
}

Field	Required	Description
`id`	yes	Unique identifier, also used by the CLI
`name`	yes	Display name
`country`	yes	Two-letter country code used for the flag
`protocol`	yes	`vless` is supported by the core builder
`address` / `port`	yes	Endpoint, port must be 1–65535
`uuid`	for live mode	VLESS user id
`flow`	no	e.g. `xtls-rprx-vision`
`security`	no	`none` (default), `tls`, `reality`
`sni`	for TLS/Reality	Server name used for the handshake
`fingerprint`	no	uTLS fingerprint, e.g. `chrome`
`public_key` / `short_id`	for Reality	Reality key pair
`network`	no	`tcp` (default), `ws`, `grpc`
`tags`, `is_favorite`, `load`, `ping_ms`	no	Display metadata only

The full reference, including every validation rule and error message, is in docs/CONFIGURATION.md.

Treat this file as a password store. Anyone with your UUID and Reality keys can use your server. config/servers.json is git-ignored by default — keep it that way.

Connecting a real VPN core

ExploitFA does not ship or download a VPN core. To use live mode:

Download an Xray-core release for Windows x64 from its official release page.
Verify its checksum yourself, then place the binary at cores/xray.exe.
Record the SHA-256 in cores/SHA256SUMS.json (copy the example file):
```
{
  "xray.exe": "64-character-lowercase-sha256"
}
```
Start the app, open Settings → Connection mode → Live core, select a server with credentials, and press Connect.

build.py refuses to package any binary whose hash does not match the manifest, so a release built by the maintainer always carries a verified core.

Live mode currently starts the core with a generated configuration:

inbounds     socks 127.0.0.1:10808  ·  http 127.0.0.1:10809
outbounds    vless (Reality / TLS / plaintext, tcp / ws / grpc)
routing      proxy inbounds → vless outbound

You can generate and inspect that document without launching anything:

python -m src.cli generate-config --server frankfurt-reality --output config/xray.generated.json

Command-line interface

The GUI is optional. exploitfa-cli (or python -m src.cli) exposes the same logic for diagnostics and headless use:

# Environment and configuration health check (redacted output)
python -m src.cli doctor

# Validate servers.json and print a redacted table
python -m src.cli validate

# Write an Xray configuration for one server
python -m src.cli generate-config --server frankfurt --socks-port 10808

# Import a share link without opening the GUI
python -m src.cli import-link "vless://uuid@node.example:443?security=tls&sni=node.example#Frankfurt"

# Run the core in the foreground (Ctrl+C to stop)
python -m src.cli run-core --core cores\xray.exe

# Machine-readable health check for installers and dashboards (no credentials)
python -m src.cli doctor --json

Command	Purpose
`doctor`	Python, PySide6, config permissions, server table, core presence (`--json`)
`validate`	Parse and validate `servers.json`, show readiness per server (`--json`)
`servers`	List the configured servers with readiness, no diagnostics (`--json`)
`remove-server`	Remove one server by id or unique display name (`--json`)
`generate-config`	Build the Xray document and write it atomically
`import-link`	Parse a `vless://` link and append it to `servers.json`
`run-core`	Generate a config and supervise the core until interrupted

Full flags and examples: docs/CLI.md.

Building the Windows executable

python -m pip install -r requirements.txt
python build.py

The script:

installs dependencies (falling back to the Kargadan and SUSTech mirrors),
verifies every core binary against cores/SHA256SUMS.json,
builds a one-file executable with PyInstaller,
assembles a portable folder with editable config and an empty server list,
writes SHA256SUMS.txt for release verification.

Output:

dist/ExploitFA/
├── ExploitFA.exe
├── SHA256SUMS.txt
├── config/
│   ├── servers.json          (empty)
│   ├── servers.example.json
│   └── subscriptions.json
├── cores/                    (only if a verified core is present)
├── logs/
└── data/

Useful options:

python build.py --skip-install   # use the current environment
python build.py --keep-work      # keep PyInstaller work files for debugging

Detailed walkthrough and code-signing notes: docs/BUILDING.md.

Project architecture

src/
├── main.py                  application entry point
├── cli.py                   doctor / validate / servers / remove-server / generate-config / import-link / run-core
├── app/
│   ├── paths.py             project root, config dir, resource resolution, first-run seeding
│   ├── config_store.py      immutable Server model + validated servers.json loader
│   ├── settings_store.py    AppSettings + atomic app.json persistence
│   └── activity.py          ActivityEvent/ActivityLog with friendly copy and export
├── core/
│   ├── config/vless.py      vless:// parsing (pure functions)
│   └── runtime/
│       ├── xray_config.py   Xray configuration builder
│       └── core_process.py  process discovery, readiness probe, lifecycle
└── ui/
    ├── main_window.py       window shell and page composition
    ├── title_bar.py         frameless draggable title bar
    ├── theme.py             theme resolution and font scaling
    └── styles/              app.qss (dark) and app_light.qss (light)

flowchart LR
    subgraph UI["PySide6 interface"]
        MW[MainWindow]
        TB[TitleBar]
        TH[theme.py]
    end

    subgraph App["Application layer"]
        CS[ServersConfigStore]
        SS[SettingsStore]
        AL[ActivityLog]
    end

    subgraph Core["Core layer"]
        VL[vless parser]
        XC[Xray config builder]
        CP[CoreRunner]
    end

    MW --> CS
    MW --> SS
    MW --> AL
    MW --> TH
    MW -->|import link| VL
    MW -->|live mode| XC
    XC --> CP
    CP -->|run -c| XRAY[(xray.exe / sing-box.exe)]
    CS -.->|hot reload| MW

Design rules that keep the codebase predictable:

The UI never parses user data. Parsing, validation and core documents live in src/app and src/core and are pure, testable functions.
Paths only come from src/app/paths.py, so frozen (PyInstaller) builds resolve resources and writable directories correctly.
Credentials never leave the machine and never reach logs. The CLI prints redacted tables; the activity log stores friendly sentences, not endpoints.
Failures degrade, they do not crash. Bad JSON produces an error banner; a missing core or an early exit produces a status-strip message.

More detail: docs/ARCHITECTURE.md.

Testing and quality

python -m pip install -r requirements-dev.txt

python -m ruff check .          # lint
python -m ruff format --check . # formatting
python -m pytest -q             # 92 tests
python -m pytest -q --cov=src   # with coverage

What is covered:

Area	Examples
Configuration	defaults, malformed JSON, clamping, atomic writes, unknown themes
Server model	required fields, port bounds, security/transport validation, tags
VLESS parsing	Reality links, rejected schemes, persistence of private fields
Xray builder	Reality/TLS/plaintext, tcp/ws/grpc, credential and port validation
Core supervisor	real child processes, early exit, never-listens, missing binary
CLI	every subcommand, redacted output, error paths
UI (offscreen)	all five pages, theme persistence, demo toggle, live start/stop

The UI tests run headless with QT_QPA_PLATFORM=offscreen and are skipped automatically when PySide6 is not installed, so the suite also runs on a server without a display.

CI matrix: Ubuntu and Windows × Python 3.11, 3.12, 3.13, plus a Ruff lint and format job.

Troubleshooting

Symptom	Cause	Fix
"config/servers.json was not found"	the file was deleted or is unreadable	delete nothing needed — restart the app, it recreates an empty file
Error banner about the server file	invalid JSON or an unknown version	run `python -m src.cli validate` for the exact field
`Import failed: Only vless:// links are supported`	a VMess/Trojan share link was pasted	use a VLESS link, or add the server manually
"No VPN core found" in live mode	no binary in `cores/`	place `xray.exe` in `cores/` and enable live mode again
"The VPN core exited with code N"	invalid credentials or a blocked port	check the server entry and try `generate-config`, then run the core manually
Nothing is routed through the VPN	live mode exposes a local proxy only	configure your application to use SOCKS5 `127.0.0.1:10808`
Text looks small on a 4K display	interface scale	Settings → Interface scale, up to 115 %
PySide6 install fails	network restrictions	use the SUSTech mirror shown in Quick start

More: docs/TROUBLESHOOTING.md.

FAQ

Is ExploitFA a VPN? It is a desktop client for VLESS/Reality servers. In demo mode it is a UI preview. In live mode it starts a real Xray core and exposes a local proxy; a system-wide tunnel is on the roadmap.

Does it work without an internet connection? The interface, configuration, parsing and tests do. Live mode obviously needs a reachable server.

Does it send my data anywhere? No. There is no telemetry, no analytics endpoint and no auto-update service.

Where are my servers stored? config/servers.json next to the executable (or in the repository root). It is git-ignored and never uploaded.

Why is the interface English-only? It is an English-first, left-to-right design decision. Language packs are a roadmap item.

Can I use it commercially? Yes, under the MIT licence. See LICENSE.

Why is it called ExploitFA? Originally a small internal tool; the name stuck. The project is a privacy client, not an exploitation framework.

Roadmap

Priority	Item	Status
P0	System-wide TUN adapter (real VPN mode)	planned
P0	Kill switch	planned
P1	Traffic statistics via the core API	planned
P1	Subscription URL support (base64 lists)	planned
P1	Latency probing per server	planned
P2	Credential encryption via the Windows Credential Manager	planned
P2	Tray icon and notifications	planned
P2	VMess / Trojan / Shadowsocks in the config builder	planned
P3	Language packs (RTL support)	planned
P3	Auto-connect on startup	planned

Vote on priorities by opening an issue or reacting to existing ones: issues.

Contributing

Contributions are genuinely welcome — tests, documentation, bug reports and small focused pull requests.

git checkout -b feat/your-idea
# implement + test
python -m ruff check .; python -m ruff format --check .; python -m pytest -q
git commit -m "feat(scope): short summary"

Please read CONTRIBUTING.md first. By participating you agree to the Code of Conduct.

Good first issues are labelled good first issue.

Privacy and security

No telemetry, no account, no remote configuration.
Local-only storage. config/, logs/ and data/ remain on your disk.
Secrets are git-ignored and never printed by the CLI.
Core binaries are checksum-verified before packaging.
Activity export is explicit. Nothing is written unless you click Export.

To report a vulnerability, follow SECURITY.md and use a private GitHub security advisory. Please do not open a public issue for security reports.

License and acknowledgements

ExploitFA is released under the MIT License.

Bundled third-party assets:

Inter by Rasmus Andersson — SIL Open Font License 1.1 (notice)
Lucide icons — ISC License (notice)
Qt / PySide6 — LGPLv3 / commercial, used as an unmodified runtime dependency

Third-party VPN cores are not bundled by default; if you add one, you are responsible for complying with its licence.

If ExploitFA saves you time, a star helps other people find it.

_{Built with care, named by accident.}

Navigation Menu

Repository navigation

About

Repository files navigation

ExploitFA

Table of contents

Why ExploitFA

Screenshots

Features

Interface

Configuration and data

Core integration (optional, opt-in)

Engineering

Not implemented yet

How it works: demo mode vs. live mode

Requirements

Quick start

Option A — download the executable (recommended)

Option B — run from source

First run

Configuration

Connecting a real VPN core

Command-line interface

Building the Windows executable

Project architecture

Testing and quality

Troubleshooting

FAQ

Roadmap

Contributing

Privacy and security

License and acknowledgements

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
config		config
cores		cores
docs		docs
src		src
tests		tests
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
ExploitFA.spec		ExploitFA.spec
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
build.py		build.py
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

ExploitFA

Table of contents

Why ExploitFA

Screenshots

Features

Interface

Configuration and data

Core integration (optional, opt-in)

Engineering

Not implemented yet

How it works: demo mode vs. live mode

Requirements

Quick start

Option A — download the executable (recommended)

Option B — run from source

First run

Configuration

Connecting a real VPN core

Command-line interface

Building the Windows executable

Project architecture

Testing and quality

Troubleshooting

FAQ

Roadmap

Contributing

Privacy and security

License and acknowledgements

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages