Metadata-Version: 2.4
Name: florida-push
Version: 0.1.0
Summary: Download a matching Frida Android server release and push it to an adb device.
Author: xihan123
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/xihan123/florida-push
Project-URL: Repository, https://github.com/xihan123/florida-push
Project-URL: Issues, https://github.com/xihan123/florida-push/issues
Keywords: android,adb,frida,florida,reverse-engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: frida
Requires-Dist: frida>=16; extra == "frida"
Dynamic: license-file

![florida-push](https://socialify.git.ci/xihan123/florida-push/image?description=1&forks=1&issues=1&language=1&name=1&owner=1&pulls=1&stargazers=1&theme=Auto)

![Python](https://img.shields.io/badge/Python-3.9%2B-brightgreen.svg)
![Python 3.14](https://img.shields.io/badge/Python-3.14-blue.svg)
[![Build and publish](https://github.com/xihan123/florida-push/actions/workflows/release.yml/badge.svg)](https://github.com/xihan123/florida-push/actions/workflows/release.yml)
![PyPI](https://img.shields.io/pypi/v/florida-push)
![下载量](https://img.shields.io/pypi/dm/florida-push)

# florida-push

Frida Android server 自动下载与推送工具。

它会根据本地 Frida 版本，从 GitHub Release 中查找匹配设备架构的 server
压缩包，解压后重命名为 `fs`，推送到 Android 设备的
`/data/local/tmp/fs`，并通过 `adb shell /data/local/tmp/fs --version`
验证远端版本。

默认目标仓库是 [`xihan123/Florida`](https://github.com/xihan123/Florida)，
兼容 Florida release 中的命名：

```text
florida-server-17.11.0-android-arm64.gz
```

也兼容上游 Frida 常见命名：

```text
frida-server-17.11.0-android-arm64.xz
```

## 目录

- [功能特性](#功能特性)
- [环境要求](#环境要求)
- [项目结构](#项目结构)
- [使用说明](#使用说明)
  - [安装](#安装)
  - [基本使用](#基本使用)
  - [指定设备](#指定设备)
  - [指定版本](#指定版本)
  - [自定义仓库](#自定义仓库)
  - [代理设置](#代理设置)
- [验证与构建](#验证与构建)
- [常见问题](#常见问题)
- [致谢](#致谢)
- [免责声明](#免责声明)

## 功能特性

- **GitHub API 获取 Release**：使用 GitHub Releases API，不抓取 HTML 页面。
- **自动版本匹配**：优先读取本地 `frida` Python 包版本，也支持 `frida --version`、`frida-ps --version`。
- **设备架构识别**：读取 `ro.product.cpu.abi`，自动映射到 `arm`、`arm64`、`x86`、`x86_64`。
- **灵活命名匹配**：不固定 `frida-server` 前缀，支持 `florida-server`、`custom-server` 等命名。
- **多压缩格式支持**：支持 `.gz` 和 `.xz`，下载后自动解压并重命名为 `fs`。
- **代理支持**：支持 `--proxy`，未指定时自动读取 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`。
- **推送后验证**：推送到设备后执行 `fs --version`，确认远端版本和目标版本一致。

## 环境要求

- Python 3.9 及以上，已验证 Python 3.14。
- `adb` 已加入 `PATH`。
- Android 设备已通过 USB 连接并完成 adb 授权。
- 已安装本地 Frida，或者运行时传入 `--frida-version`。

安装 Frida 工具：

```bash
python -m pip install frida-tools
```

## 项目结构

```text
.
├── .github/
│   └── workflows/
│       ├── release-please.yml
│       └── release.yml
├── src/
│   └── florida_push/
│       ├── __init__.py
│       ├── __main__.py
│       └── cli.py
├── tests/
│   └── test_cli.py
├── .release-please-manifest.json
├── LICENSE
├── README.md
├── release-please-config.json
├── main.py
└── pyproject.toml
```

项目使用标准 `src/` 布局，发布后提供 `florida-push` 命令。

## 使用说明

### 安装

发布包：

```bash
python -m pip install florida-push
```

源码：

```bash
python -m pip install .
```

开发模式：

```bash
python -m pip install -e ".[dev]"
```

### 基本使用

使用默认 Florida 仓库：

```bash
florida-push
```

源码仓库中也可以直接运行：

```bash
python main.py
```

命令会输出目标仓库、设备名称、设备架构、目标版本、代理来源、远端路径和最终验证结果。

示例输出：

```text
Target repository: xihan123/Florida
Device serial: ABC123
Device ABI: arm64-v8a
Device architecture: arm64
Target Frida version: 17.11.0
Proxy: none
Remote path: /data/local/tmp/fs
Release asset: florida-server-17.11.0-android-arm64.gz
Download: https://github.com/xihan123/Florida/releases/download/17.11.0/florida-server-17.11.0-android-arm64.gz
Pushing server...
Remote version: 17.11.0
Done.
```

### 指定设备

当存在多个 adb 设备时，需要指定设备序列号：

```bash
florida-push --serial <device-serial>
```

设备序列号来自：

```bash
adb devices
```

### 指定版本

默认会自动检测本地 Frida 版本。需要手动指定时：

```bash
florida-push --frida-version 17.11.0
```

### 自定义仓库

默认仓库是 `xihan123/Florida`。需要改为其他 owner/repo：

```bash
florida-push --owner frida --repo frida
```

或者：

```bash
florida-push --owner xihan123 --repo Florida
```

### 代理设置

显式指定代理：

```bash
florida-push --proxy http://127.0.0.1:7890
```

如果没有传入 `--proxy`，会自动读取环境变量：

```bash
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890
```

代理中包含账号密码时，日志会脱敏：

```text
Proxy: environment (https=http://***:***@127.0.0.1:7890)
```

## 验证与构建

本地测试：

```bash
python -m unittest discover -s tests
```

本地编译检查：

```bash
python -m compileall -q src tests main.py
```

构建发布包：

```bash
python -m build
```

检查 PyPI 元数据：

```bash
python -m twine check dist/*
```

当前发布流程会在 Python 3.9 和 3.14 上运行测试，并使用 Python 3.14 构建发布包。

## 常见问题

### Q: 找不到匹配的 release 怎么办？

**A:** 先确认目标仓库存在对应版本 tag，例如 `17.11.0` 或 `v17.11.0`。再确认该 release
中存在以 `android-<arch>.gz` 或 `android-<arch>.xz` 结尾的 server asset。

### Q: 多个设备连接时为什么直接退出？

**A:** 为了避免推送到错误设备，多个 adb 设备同时在线时必须使用 `--serial` 明确选择。

### Q: 没安装 Frida 可以使用吗？

**A:** 可以。没有本地 Frida 时传入 `--frida-version` 即可：

```bash
florida-push --frida-version 17.11.0
```

### Q: 推送后如何手动验证？

**A:** 可以直接执行：

```bash
adb shell /data/local/tmp/fs --version
```

## 致谢

- [Frida](https://github.com/frida/frida)
- [Florida](https://github.com/xihan123/Florida)

## 免责声明

- 本项目仅供学习交流、逆向分析辅助和安全研究使用。
- 使用者应确保自己拥有分析目标和 Android 设备的合法授权。
- 请勿在未授权环境中使用本工具。
- 工具会写入并可能覆盖目标设备上的 `/data/local/tmp/fs`。

---
