Xray Subscription Analyzer

xray-subscription-analyzer (xsa) turns an authorized VPN subscription, proxy-link file, local config, or raw payload into a local report.

The basic idea is:

xsa inspect "https://example.com/subscription-token"

Normal reports redact credentials. Active checks are off by default. Raw exports that contain credentials require an explicit sensitive-output flag.

What This Tool Does

xsa helps you inspect client-visible proxy configuration data:

• parse subscription URLs, local files, Base64 payloads, Xray JSON, proxy share links, line-delimited link files, and Hysteria 2 YAML/JSON configs;
• preserve unknown fields and explicit values such as false, 0, "", {}, and [];
• produce Markdown, JSON, JSONL, CSV, and sensitive raw/config exports where supported;
• validate Xray-compatible generated configs with Xray-core when installed;
• report passive DNS, registry, ASN, and GeoIP enrichment where configured;
• run bounded reachability checks only when explicitly authorized.

What This Tool Does Not Do

xsa does not discover subscriptions, guess tokens, brute-force credentials, scan adjacent infrastructure, exploit vulnerabilities, bypass authentication, or upload telemetry. It cannot recover server-side secrets or REALITY private keys.

Quickest Possible Start

Use the safest beginner command:

xsa quick "https://example.com/subscription-token"

For a text file with one proxy link per line:

xsa quick proxies.txt

quick writes a redacted Markdown report and does not perform active checks or raw exports.

Choose Your Input Type

What do you have?

1. One subscription URL: xsa inspect "https://example.com/subscription-token"
2. A text file containing one proxy link per line: xsa inspect-links proxies.txt
3. A text file containing one subscription URL per line: xsa inspect --input-file subscriptions.txt --input-file-mode subscription-urls
4. A raw JSON/Base64 subscription payload: xsa inspect payload.txt
5. A Hysteria 2 YAML file: xsa inspect hysteria-client.yaml
6. Need syntax validation: add --validate
7. Need actual connectivity checks: add --check-reachability --authorized
8. Need unredacted source artifacts: use xsa raw export ... --include-sensitive --yes

Safe First Commands

xsa guide
xsa examples
xsa doctor
xsa validator list

These commands do not fetch subscriptions, start proxy clients, or write sensitive raw artifacts.

Installation

From a checkout:

python -m pip install -e ".[dev]"
xsa doctor

Python 3.12 or newer is the target. Xray-core is optional but required for Xray-compatible validation. The official Hysteria binary is optional and required for Hysteria 2 validation.

Common Examples

Analyze one subscription:

xsa inspect "https://example.com/subscription-token" --output /tmp/xsa-report.md

Analyze one proxy-link file:

xsa inspect-links proxies.txt --output /tmp/xsa-links.md

Analyze many subscription URLs:

xsa inspect \
  --input-file subscriptions.txt \
  --input-file-mode subscription-urls \
  --aggregate-report \
  --output-dir /tmp/xsa-subscriptions

Validate generated client configs:

xsa inspect-links proxies.txt --validate

Run passive enrichment:

xsa inspect "https://example.com/subscription-token" --full

Run authorized reachability checks:

xsa inspect "https://example.com/subscription-token" \
  --check-reachability \
  --authorized

Understanding The Output

Markdown reports are for human review. JSON is for automation. JSONL is useful for large proxy-link files because each input line becomes one output line. Normal reports redact credentials. Sensitive raw exports intentionally do not.

Sensitive Operations

These operations may write credentials:

• xsa raw export ... --include-sensitive
• xsa config build ... --include-sensitive
• xsa hysteria2 export ... --include-sensitive

Do not commit or publish those outputs. Prefer output directories under /tmp for local experiments.

Active Checks And Authorization

Parsing and validation are not availability tests. --validate checks whether a generated config is syntactically accepted by a local validator. Reachability and latency checks contact endpoints extracted from your input and require --authorized.

TCP reachability does not prove proxy availability. Hysteria 2 is QUIC/UDP based and needs protocol-aware Hysteria client testing for strong availability evidence; that remains incomplete unless the official client check is available.

External Binaries

Check installed validators:

xsa validator list
xsa validator doctor

Xray-compatible validation requires xray. Hysteria 2 validation requires the official Hysteria binary. Missing validators are reported as unavailable, not as parse failures.

Documentation Map

• Five-minute quick start
• Input types
• Concepts
• Command reference
• Output formats
• Security
• Troubleshooting
• Feature status
• Glossary

Current Project Status

The project is a functional beta. Xray-compatible parsing and validation are working with local Xray-core. Hysteria 2 parsing and reconstructed YAML export are beta; official Hysteria validation requires an installed binary. Workspace history, WHOIS fallback, Happ encrypted-link support, and protocol-aware proxy tunnel checks remain incomplete.

License

MIT. See LICENSE.