yayaya142/maldroid

# MalDroid MalDroid 是一款用于 Android 恶意软件研究的本地静态分析助手。它能够管理调查案例，启动一个本地 `llama-server`，通过本地 Python MCP 服务器暴露特定于配置的工具集，并持久化保存有证据支撑的发现结果。调查数据绝不会被发送至云端模型。 MalDroid 并非自动 APK 扫描器、恶意软件沙箱、动态分析系统或任意 shell 代理。它不会运行 APK、DEX 文件、本地库、脚本、ADB、Frida 或模拟器。 ## 支持的系统与配置文件 V1 支持 macOS 和 Kali Linux，需配合 Python 3.11–3.14 使用。目前提供针对 `generic`、`react-native`、`native`、`flutter`、`unity`、`cordova` 和 `cocos` 的配置文件。对版本敏感的外部适配器会保持明确状态，并会报告兼容性限制，而不是默认提供支持。 ## 安装 ``` git clone https://github.com/yayaya142/maldroid.git cd maldroid ./install.sh ``` 安装程序会创建 `~/.local/share/maldroid/venv`，将 MalDroid 安装到该目录中，并创建 `~/.local/bin/maldroid`。它绝不会将 Python 包安装到系统解释器中。使用 `./install.sh --dry-run` 可预览所有操作。 安装完成后，启用原生 shell 补全并查看命令映射： ``` maldroid --install-completion maldroid --version maldroid --help maldroid help mcp serve ``` 首次使用设置会请求本地 `llama-server` 和 GGUF 路径。系统提供的 macOS 默认模型为： ``` ~/Desktop/Tools/Ai Models/gemma-4-12B-it-qat-q4_0.gguf ``` 在用于研究之前，请验证模型的工具调用功能： ``` maldroid doctor --show-command maldroid doctor --model-tool-test ``` ## 日常使用 ``` maldroid maldroid new CASE_NAME maldroid /path/to/investigation maldroid /path/to/index.android.bundle --profile react-native maldroid /path/to/artifact --copy maldroid /path/to/artifact --mcp-port 8765 maldroid resume maldroid cases ``` 打开现有目录时最初只会创建 `.maldroid/`。打开文件时会创建一个托管案例，并默认注册一个符号链接。不会仅仅因为检测到工件就自动开始分析。 聊天界面支持 `/help`、`/status`、`/profile`、`/tools`、`/files`、`/findings`、`/todo`、`/note`、`/compact`、`/clear`、`/server`、`/knowledge` 和 `/exit`。 ## MCP 工具 每次正常的交互式运行都会启动一个仅限 loopback 的 MCP Streamable HTTP 服务器，并输出其确切的 endpoint 和所选端口。模型侧的工具执行器通过官方 MCP 客户端连接到此 endpoint；它不会绕过 MCP。要在不启动模型聊天的情况下暴露某个案例： ``` maldroid mcp serve /path/to/case maldroid mcp serve /path/to/case --port 8765 maldroid mcp serve /path/to/case --json ``` 将 MCP 客户端连接到输出的 URL，通常为 `http://127.0.0.1:8765/mcp`。典型的客户端配置如下： ``` { "mcpServers": { "maldroid": { "type": "http", "url": "http://127.0.0.1:8765/mcp" } } } ``` MCP 端口是固定的。默认端口为 8765，如果该端口被占用，MalDroid 会明确报错，而不会悄悄更改 endpoint。使用 `maldroid config set mcp.preferred_port PORT` 持久化设置另一个固定端口（只需设置一次）；`mcp serve` 上的 `--port` 以及正常聊天中的 `--mcp-port` 属于单次运行覆盖参数。工具发现始终只返回核心工具加上该案例当前激活的配置文件。该 endpoint 不会向 loopback 之外暴露；任何连接到它的本地客户端都可以调用案例范围内的工具，直到服务器停止运行。 ## 配置 配置文件存储于 `~/.config/maldroid/config.toml`： ``` maldroid config init maldroid config show maldroid config show --json maldroid config get mcp.preferred_port maldroid config set llama.temperature 0.1 maldroid config validate maldroid config reset llama.temperature --yes maldroid config path ``` `config show` 会按部分对每个生效的值进行分组，将其标记为默认或自定义，并说明其用途。设置器在执行原子保存之前会验证完整配置。使用 `maldroid mcp client-config` 可生成可直接粘贴的连接器定义。 CLI 选项会在单次运行中覆盖配置。首选的模型端口为 7575，当配置为默认值时可能会发生回退。MCP 端口默认固定为 8765，且永远不会回退。 MalDroid 会拒绝在 `extra_args` 中使用 `--tools`、`--agent` 和 MCP 代理标志。它的 MCP 服务器是 Python 的安全边界；`llama-server` 内置工具和实验性 MCP 代理将保持禁用状态。 ## 证据、发现结果与大型文件 发现结果、TODO、笔记、会话事件和摘要会在退出和恢复期间保留。每一项基于代码的发现都应标明案例路径、行号或偏移量范围、使用的工具以及置信度。 ## 知识库 ``` maldroid knowledge add ./playbook.md --profile react-native --copy maldroid knowledge list maldroid knowledge reindex ``` 内置、用户和案例 playbook 均通过 SQLite FTS5 在本地进行索引。只有有限范围的匹配摘录会进入模型上下文。 ## 故障排除 - `llama-server was not found`：运行 `maldroid config init` 并提供其绝对路径。 - 缺少模型：更新 `llama.model`；支持带有空格的路径。 - 工具调用以纯文本形式返回：运行 `maldroid doctor --model-tool-test` 并配置兼容的 Jinja 聊天模板。 - 服务器启动失败：检查 `/.maldroid/logs/llama-server.stderr.log`。 - MCP 端口不可用：停止正在占用该端口的进程，或者使用 `maldroid config set mcp.preferred_port PORT` 持久化保存另一个固定值，并更新 MCP 客户端。 - Kali 上无法使用 Python venv：安装 `python3-full` 和 `python3-venv`。 仅在需要 traceback（回溯）时使用 `--debug`。使用 `./uninstall.sh` 可安全卸载；默认情况下会保留案例和用户知识库。 ## 分发 维护者无需手动激活 Python 即可运行完整的本地发布门禁并构建可安装的 wheel： ``` ./scripts/dev release-check ./scripts/dev build ``` wheel 会生成在 `dist/` 目录下，可以通过 `python3 -m pip install /path/to/maldroid-0.1.0-py3-none-any.whl` 安装到任何受支持的隔离环境中。有关命令和自动化输出参考，请参阅 [`docs/CLI.md`](docs/CLI.md)。

标签：文档结构分析, 逆向工具