# fact_cli **Repository Path**: little77/fact_cli ## Basic Information - **Project Name**: fact_cli - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-17 - **Last Updated**: 2026-11-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # FACT CLI FACT (Firmware Analysis and Comparison Tool) CLI - 固件分析和比较工具命令行集 ## 快速开始 ```bash # 一键安装(推荐) ./scripts/install_deps.sh # 初始化环境 .venv/bin/fact-init # 计算文件哈希 .venv/bin/fact-hash calculate firmware.bin # 解包固件 .venv/bin/fact-unpack firmware.bin ``` ## 文档 完整文档请查看 [docs/README.md](docs/README.md) ## 安装 ### 自动安装(推荐) 使用一键安装脚本,自动处理所有依赖: ```bash # 标准安装(包含系统依赖) ./scripts/install_deps.sh # 跳过系统依赖(如果已安装) ./scripts/install_deps.sh --skip-system-deps ``` 安装脚本会自动处理: - ✅ 系统依赖(yara, tlsh, ssdeep, unblob 工具) - ✅ Python 构建依赖 - ✅ 项目依赖(108 个包) 详细说明请查看 [scripts/README.md](scripts/README.md) ### 手动安装 #### 基础安装 ```bash uv sync ``` #### 完整安装(包含所有工具) ```bash # 先安装系统依赖 sudo apt install libyara-dev libtlsh-dev libfuzzy-dev build-essential \ p7zip-full e2fsprogs lz4 lzop squashfs-tools file \ erofs-utils lzip partclone android-sdk-libsparse unar # 安装构建依赖 uv sync --group build # 安装项目依赖 uv sync --extra all ``` **宿主机直跑 CLI 注意**:第二行的 `erofs-utils lzip partclone android-sdk-libsparse unar` 提供 unblob 的外部提取命令(fsck.erofs、 lziprecover、partclone.restore、simg2img、unar)。Docker 镜像已内置; 宿主机缺失时 fact-unpack 每次启动会打 5 行 WARNING 并跳过对应格式 (其中 erofs 为小米新固件常用文件系统格式)。 **注意**:某些功能需要额外的系统依赖: - **TLSH 模糊哈希**: 需要 `libtlsh-dev` (Ubuntu/Debian) 或 `tlsh-devel` (CentOS/RHEL) - **YARA**: 需要 `libyara-dev` (Ubuntu/Debian) 或 `yara-devel` (CentOS/RHEL) - **SSDEEP**: 需要 `libfuzzy-dev` (Ubuntu/Debian) - **Python-magic**: 需要 `libmagic1` (Ubuntu/Debian) 或 `file-devel` (CentOS/RHEL) - **unblob 工具**: 需要 `p7zip-full e2fsprogs lz4 lzop squashfs-tools` ### 固件 magic 数据库(firmware.mgc) `firmware.mgc` 与本机 `libmagic` 版本绑定,不能把别的机器或镜像里编出来的文件直接拷来用。容器镜像在构建期编译并安装到 `/usr/share/file/firmware.mgc`,因此仓库配置 `[filetype].magic_database` 默认是: ```toml magic_database = "/usr/share/file/firmware.mgc:/usr/share/file/magic.mgc" ``` 宿主机没有这份构建产物。若 `dependencies/firmware-magic-database/mime/` 已经在本地(不联网、不克隆),安装脚本或下面的命令会用本机 `file -C` 编译: ```bash ./scripts/build_firmware_magic.sh # 产物: data/magic/firmware.mgc # /usr/share/file 可写时同时复制到 /usr/share/file/firmware.mgc ``` 源目录不存在时脚本直接跳过。编译成功后,把宿主机配置链改成仓库产物优先、系统 magic 兜底: ```toml magic_database = "data/magic/firmware.mgc:/usr/share/file/magic.mgc" ``` `fact-filetype` 只在链的第一段存在时使用整条链;第一段缺失则整链弃用并回退系统默认 magic,同时打出 WARNING。 ### fact-vuln deep 与 Ghidra 地址 `[ghidra].api_url` 默认 `http://vuln-ghidra:13100`(compose 内网主机名)。宿主机 CLI 用环境变量覆盖,不改镜像拓扑: ```bash FACT_VULN_GHIDRA_URL=http://127.0.0.1:13100 fact-vuln scan -d deep ``` deep 被请求但该地址不可达时,stderr 输出 WARNING(含原因和生效地址),JSON 里 `degraded` 为 true,`depth` 为实际执行的 `standard`。 ### fact-cve scan-dir 落库 `fact-cve scan-dir` 默认把每个文件写入 `cve.db`(`cve_scan_result`)。不需要落库时显式加 `--no-db`。`--save-db` 仍表示保存。 ## 工具列表 - `fact-init` - 环境初始化 - `fact-db` - 数据库管理 - `fact-config` - 配置管理 - `fact-hash` - 哈希计算(MD5, SHA1, SHA256, SHA512, BLAKE2, SSDEEP, TLSH) - `fact-filetype` - 文件类型检测(80+ 格式) - `fact-crypto` - 加密材料检测 - `fact-cve` - CVE 查询(`scan-dir` 默认写入 cve.db,`--no-db` 关闭;知识库 NVD 增量更新:`make update-cve`,API key 配置见 `config/fact-cli-config.toml` 的 `[update.cve]`) - `fact-strings` - 字符串提取 - `fact-arch` - 架构检测(CPU 架构、ABI) - `fact-unpack` - 文件解包(支持 80+ 格式,基于 unblob) - `fact-web` - Web 界面 - `fact-vuln` - 二进制漏洞分析 - `fact-leaks` - 敏感数据检测 - `fact-network` - 网络分析(GeoIP 查询) ## 项目结构 ``` fact_cli/ ├── scripts/ # 安装和实用脚本 │ ├── install_deps.sh # 一键安装脚本 │ └── README.md # 脚本使用说明 ├── config/ # 配置文件 │ └── fact-cli-config.toml ├── data/ # 数据目录 │ ├── databases/ # SQLite 数据库 │ ├── geoip/ # GeoIP 数据库 │ ├── magic/ # Magic 文件数据库 │ ├── trid/ # TrID 签名数据库 │ └── yara_rules/ # YARA 规则 ├── docs/ # 文档 ├── fact_*/ # 各工具模块 ├── shared/ # 共享模块 └── pyproject.toml # 项目配置 ``` ## MCP 工具集成 本项目支持以 Model Context Protocol (MCP) HTTP/SSE 服务的形式运行,允许 Cursor、Claude Desktop 等支持 MCP 协议的 LLM 客户端跨网络直接、准确地调用底层的固件分析工具(含 1 个上传入口工具与 15 个分析扫描工具——其中 3 个为认知/完备性工具,共 16 个 MCP 工具)。 ### 1. 本地安装与启动 首先,安装 MCP 扩展依赖组: ```bash uv pip install -e ".[mcp]" ``` **独立 HTTP/SSE 服务启动**: ```bash uv run fact-mcp ``` 服务将在本地 `http://localhost:8000` 启动,其 SSE 传输入口为 `http://localhost:8000/sse`,消息交换入口为 `http://localhost:8000/messages`。 ### 2. 容器部署与集成 (推荐) MCP 服务已通过子应用(ASGI App)形式内嵌并挂载到了本项目的 `fact-web` 主 Web 容器上。 使用 Docker Compose 启动容器后: ```bash docker compose up -d ``` 您不需要暴露额外的端口,直接通过已有的 `fact-web` 宿主机映射端口进行跨网络长连接握手: * **MCP SSE 入口**: `http://localhost:8001/mcp/sse` * **MCP Messages 入口**: `http://localhost:8001/mcp/messages` ### 3. 客户端连接配置 (以 Claude Desktop 为例) 编辑 `~/.config/Claude/claude_desktop_config.json` 配置文件加入该 HTTP MCP 服务: ```json { "mcpServers": { "fact-mcp-http": { "url": "http://localhost:8001/mcp/sse" } } } ``` ## 许可证 Apache 2.0 License