# 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-07-16

## 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

# 安装构建依赖
uv sync --group build

# 安装项目依赖
uv sync --extra all
```

**注意**：某些功能需要额外的系统依赖：
- **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`

## 工具列表

- `fact-init` - 环境初始化
- `fact-db` - 数据库管理
- `fact-config` - 配置管理
- `fact-hash` - 哈希计算（MD5, SHA1, SHA256, SHA512, BLAKE2, SSDEEP, TLSH）
- `fact-filetype` - 文件类型检测（80+ 格式）
- `fact-crypto` - 加密材料检测
- `fact-cve` - 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 客户端跨网络直接、准确地调用底层的固件分析工具（支持解包、哈希、CVE漏洞检索、逆向字符串、架构大小端、敏感密钥探测等 12 个分析扫描工具）。

### 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