mirror of
https://github.com/xweiba/location-spoofer.git
synced 2026-09-21 22:30:46 +08:00
218 lines
14 KiB
Markdown
218 lines
14 KiB
Markdown
<div align="center">
|
||
|
||
# 📍 Location Spoofer
|
||
|
||
### iOS Location Spoofer · DingTalk · WeChat · Apple Watch Region Unlock · Fake GPS
|
||
|
||
**No jailbreak — rewrite Apple location-service responses through App Mode's on-device Wi-Fi HTTP proxy or Third-party Proxy Mode (Wi-Fi/4G/5G).**<br>
|
||
Designed for DingTalk, WeChat, Apple Maps, and other apps that read system location. Map selection, favorites, mode setup, environment checks, and diagnostics live in one app.
|
||
|
||
[](project.yml)
|
||
[](project.yml)
|
||
[](Core/go.mod)
|
||
[](docs/CHANGELOG.md)
|
||
[](#how-it-works)
|
||
|
||
[Features](#key-features) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [中文](README.md) · [Changelog](docs/CHANGELOG.md)
|
||
|
||
<img src="images/主界面.jpg" alt="Location Spoofer iOS Fake GPS main interface" width="380">
|
||
|
||
</div>
|
||
|
||
> [!IMPORTANT]
|
||
> This project is only for education, security research, and testing on devices you own. App Mode requires a locally generated CA and a manual HTTP proxy on the current Wi-Fi network. In Third-party Proxy Mode, the selected client owns certificate, MITM, and proxy/VPN setup. Results vary by iOS version, network, location cache, and target-app behavior. Follow applicable laws, network policies, and service terms.
|
||
|
||
## Credits
|
||
|
||
The core location-response rewriting approach and Go implementation are based on [Yu9191/wloc](https://github.com/Yu9191/wloc). This project adds a SwiftUI interface, MapKit selection, certificate and proxy guidance, environment verification, favorites, and diagnostics.
|
||
|
||
## Why Location Spoofer?
|
||
|
||
Unlike tools that require a computer to stay connected, developer debugging, or a jailbroken device, Location Spoofer keeps selection and control on the iPhone. It provides two mutually exclusive paths: run the Go proxy inside the app, or synchronize coordinates to an existing third-party proxy client.
|
||
|
||
| Feature | Description |
|
||
|---|---|
|
||
| 🔀 **Two runtime modes** | App Mode needs no third-party client and works over Wi-Fi; Third-party Proxy Mode can follow its client across Wi-Fi, 4G, and 5G. |
|
||
| 📱 **No jailbreak** | Can be installed through self-signing; minimum deployment target is iOS 15. |
|
||
| 🗺️ **Native Maps experience** | The same blue dot and selection gestures as Apple Maps — search, tap, and drag. |
|
||
| 📍 **Location-response rewriting** | Can affect DingTalk, WeChat, Apple Maps, Amap, and other apps that read system location; verify compatibility on-device. |
|
||
| 🔍 **Visible map scale** | Left-side controls show the current visible range; place name adapts to zoom level. |
|
||
| 🧭 **Coordinate consistency** | Reconciles MapKit map coordinates with WGS-84 for favorites, restoration, and third-party sync. |
|
||
| 🧪 **Mode-aware checks** | App Mode checks the local proxy, CA trust, and Wi-Fi path; Third-party Mode verifies real module interception. |
|
||
| 🧾 **Diagnostics** | Search and copy logs, or generate a sanitized GitHub Issue report from inside the app. |
|
||
|
||
## Screenshots
|
||
|
||
| Main Interface | Apple Maps | Amap | Apple Watch |
|
||
|---|---|---|---|
|
||
|  |  |  |  |
|
||
|
||
## Key Features
|
||
|
||
- **iOS Location Spoofer / Fake GPS**: Apply the selected pin to App Mode's proxy or synchronize it to a third-party WLOC module.
|
||
- **Native map and real-time location**: Uses MapKit's blue dot with search, tap, map-center drag, zoom controls, and a shortcut to Apple Maps.
|
||
- **Concurrency-safe selection**: Pan, tap, search, favorites, and async location respect the user's latest intent; stale results won't overwrite newer selections.
|
||
- **Hierarchical place names**: POI, street, or road at close zoom; neighborhood, district, city, or province at wider zoom.
|
||
- **Map scale display**: Zoom controls show the current visible range.
|
||
- **Favorites and state restoration**: Save, rename, and switch frequent locations while remembering the last pin and map range.
|
||
- **Automatic coordinate handling**: Resolves the map's coordinate convention at startup and keeps paired WGS-84/map coordinates to reduce mainland-China map offsets.
|
||
- **Mode-specific onboarding**: App Mode guides local proxy and CA setup; Third-party Mode guides client selection, subscription import, and connection testing.
|
||
- **Local-proxy keep-alive**: App Mode uses silent audio while spoofing to remain active in the background and rechecks the environment after Wi-Fi changes.
|
||
- **Structured diagnostics**: Logs rotate automatically, retain only three days, and can be filtered, copied, cleared, or attached to an Issue report.
|
||
- **Third-party Proxy Mode (testing)**: Query, save, or clear WGS-84 coordinates through a WLOC module. The proxy client persists state, so spoofing may continue after this app closes.
|
||
|
||
## Quick Start
|
||
|
||
### 1. Install the App
|
||
|
||
Release assets are unsigned IPA files and must be installed with a sideloading tool:
|
||
|
||
1. **Enable sideloading support**: On iOS 16 or later, open Settings → Privacy & Security → Developer Mode, enable it, then restart and confirm when prompted. iOS 15 does not have this switch, so skip this step there.
|
||
2. **Download the IPA**: Open this project's [Releases](https://github.com/xweiba/location-spoofer/releases) and download the latest `PaopaoLocationSpoofer-unsigned.ipa`.
|
||
3. **Prepare a sideloading tool**: Download the appropriate Impact build from [Impact Releases](https://github.com/claration/Impactor/releases/latest). Aisi Assistant/i4Tools or another tool that supports signing and installing IPA files may also be used.
|
||
4. **Connect and install**: Connect the iPhone to the computer with a USB cable, tap “Trust This Computer” on the phone, select the downloaded IPA in the sideloading tool, and follow that tool's prompts to sign and install it.
|
||
|
||
> Impact supports Windows, macOS, and Linux. If Windows cannot detect the device, install iTunes to provide the Apple device drivers. Aisi Assistant/i4Tools is third-party software; download it only from its official source and assess its account, certificate, and privacy risks yourself.
|
||
|
||
If iOS blocks the installed app, trust its developer app under Settings → General → VPN & Device Management. A free Apple ID signature normally expires after seven days and must then be renewed; this is separate from the WLOC CA certificate. Keep the app Bundle ID `com.paopaolabs.location-spoofer`, the App Group `group.com.paopaolabs.location-spoofer`, and the declared entitlements unchanged.
|
||
|
||
To build the unsigned IPA yourself on macOS with Xcode, follow the [build guide](docs/BUILD.md), then use the same sideloading steps above to sign and install it.
|
||
|
||
### 2. Choose a Runtime Mode
|
||
|
||
#### App Mode (On-device Wi-Fi)
|
||
|
||
Choose App Mode during first launch, then follow the in-app guide to configure the proxy and CA. This mode starts `wloccore` on the device and has no third-party client dependency, but its traffic entry point covers only the current Wi-Fi.
|
||
|
||
On the current Wi-Fi network, set Configure Proxy to Manual:
|
||
|
||
```text
|
||
Server: 127.0.0.1
|
||
Port: 8888
|
||
Authentication: off
|
||
```
|
||
|
||
Return to the app and run the environment check. If the CA is not trusted, the app opens the complete certificate setup flow. Download the profile, then:
|
||
|
||
```text
|
||
Settings → General → VPN & Device Management → install WLOC CA
|
||
Settings → General → About → Certificate Trust Settings → enable full trust
|
||
```
|
||
|
||
#### Third-party Proxy Mode (Testing)
|
||
|
||
The app handles map selection, favorites, and querying, saving, or clearing WGS-84 coordinates. A third-party proxy client handles WLOC interception, MITM, and persistence. This mode does not start the local Go proxy, use the app-generated CA, or require `127.0.0.1:8888`. Network coverage depends on the selected client and may include Wi-Fi, 4G, and 5G.
|
||
|
||
Select a client during onboarding or from Settings → Runtime Mode. The app can copy the official subscription URL and open the selected client; paste that URL into its module, rewrite, or override subscription UI.
|
||
|
||
| Client | Verification status | Configuration |
|
||
|---|---|---|
|
||
| Shadowrocket | **Currently available for testing** | [wloc.module](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.module) |
|
||
| Surge | Provided, not verified | [wloc.sgmodule](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.sgmodule) |
|
||
| Quantumult X | Provided, not verified | [wloc.conf](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.conf) |
|
||
| Loon | Provided, not verified | [wloc.lpx](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.lpx) |
|
||
| Stash | Provided, not verified | [wloc.stoverride](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.stoverride) |
|
||
| Egern | Provided, not verified | Uses the Surge module |
|
||
|
||
For Shadowrocket, also enable HTTPS decryption for `gs-loc.apple.com`. Import `.stoverride` directly into Stash without Script Hub conversion; Egern reuses the Surge module. The client—not this app—owns module enablement, MITM, certificates, and proxy/VPN state. A connection test passes only when the endpoint returns valid module JSON, not merely HTTP 200. Bundled snapshots and provenance are documented in [Third-party Module Snapshots](docs/THIRD_PARTY_MODULES.md).
|
||
|
||
### 3. Select a Location & Enable
|
||
|
||
1. Search, tap, or drag the map to pick a location; use the location button to return to the MapKit blue dot, or save the pin as a favorite.
|
||
2. In App Mode, tap “Start Spoofing” and wait for verification. In Third-party Proxy Mode, tap “Sync to Third-party Proxy.”
|
||
3. Follow the in‑app activation instructions to refresh airplane mode, Wi‑Fi, and location services.
|
||
4. Open Apple Maps or your target app to verify.
|
||
|
||
### 4. Restore Your Real Location
|
||
|
||
In App Mode, stop spoofing and disable the current Wi-Fi's manual proxy. In Third-party Mode, use “Clear Third-party Proxy Coordinates,” then disable the module or proxy connection if needed. Follow the in-app deactivation instructions to refresh the system location cache; restart the device if the old location remains.
|
||
|
||
## How It Works
|
||
|
||
### Why App Mode Needs No VPN
|
||
|
||
```text
|
||
iPhone location request
|
||
│ Wi‑Fi HTTP proxy: 127.0.0.1:8888
|
||
▼
|
||
Local wloccore Go proxy
|
||
│ Handles only the targeted Apple location-service traffic
|
||
▼
|
||
Apple location service response
|
||
│ The selected coordinate is written into the response
|
||
▼
|
||
The system and applications receive the modified result
|
||
```
|
||
|
||
App Mode does not create a Network Extension tunnel, so it does not display or occupy a VPN connection. **It still requires the current Wi-Fi's manual HTTP proxy and a fully trusted local CA.**
|
||
|
||
### Third-party Proxy Mode
|
||
|
||
```text
|
||
Map pin (WGS-84) → WLOC settings endpoint → proxy module stores coordinate
|
||
│
|
||
Location request → third-party proxy/VPN + MITM ┘→ rewritten response
|
||
```
|
||
|
||
The selected client owns proxy/VPN, certificates, and MITM and may cover cellular networks. Do not enable both interception paths at once.
|
||
|
||
## Data & Security Notes
|
||
|
||
- App Mode generates its CA and private key on-device. The private key is stored in the iOS Keychain; only the CA profile is installed into the system trust store.
|
||
- Third-party modules and runtime scripts come from the upstream project. Review them before importing. Bundled snapshots provide release provenance and do not imply that every client has been verified.
|
||
- Runtime logs live in the App Group container, rotate automatically, and retain only three days. They can be copied or cleared in-app. Exportable real-time-location diagnostics omit exact coordinates by default.
|
||
- A self-signed CA or third-party MITM changes the device's HTTPS trust/proxy path. Disable the proxy or module when unused and remove certificates if appropriate.
|
||
|
||
## Compatibility
|
||
|
||
| Item | Requirement |
|
||
|---|---|
|
||
| iOS | 15.0+ |
|
||
| Build | macOS, Xcode, XcodeGen |
|
||
| Swift | 5.9 |
|
||
| Go | 1.23+ |
|
||
| Network | App Mode: Wi-Fi with manual HTTP proxy support; Third-party Mode (testing): client-dependent Wi-Fi/4G/5G |
|
||
| Installation | Self-sign or use release builds |
|
||
|
||
Actual behavior may vary with iOS version, network conditions, system location cache, device model, and the target app's own location strategy. Compatibility with every iOS version or third-party app is not guaranteed.
|
||
|
||
## Build & Project Structure
|
||
|
||
Building requires macOS, Xcode Command Line Tools, Go 1.23+, and XcodeGen:
|
||
|
||
```bash
|
||
./build.sh # build the unsigned IPA
|
||
./build.sh --test # also run iOS Simulator unit tests
|
||
```
|
||
|
||
The unsigned IPA is at:
|
||
|
||
```text
|
||
dist/PaopaoLocationSpoofer-unsigned.ipa
|
||
```
|
||
|
||
```text
|
||
App/ SwiftUI, MapKit, location and setup flow
|
||
Core/ Go local proxy and location response rewriting
|
||
Shared/ Favorites, settings, logs, and shared models
|
||
Resources/ Info.plist, Entitlements, and icons
|
||
Config/ Build configuration
|
||
Scripts/ Build, signing, and verification scripts
|
||
Tests/ XCTest and Bash contract tests
|
||
docs/ Build, third-party module, and release documentation
|
||
```
|
||
|
||
## Documentation & Feedback
|
||
|
||
- [Build guide](docs/BUILD.md)
|
||
- [Third-party module snapshots](docs/THIRD_PARTY_MODULES.md)
|
||
- [Changelog](docs/CHANGELOG.md)
|
||
- [中文文档](README.md)
|
||
- [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)
|
||
|
||
When reporting issues, please include reproduction steps, iOS version, device model, and sanitized runtime logs.
|
||
|
||
## Links
|
||
|
||
**LinuxDo** — [https://linux.do](https://linux.do/)
|