Metadata-Version: 2.4
Name: fuscan
Version: 0.1.6
Summary: 极速通用文件扫描器.
Author-email: gooker_young <gooker_young@qq.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: charset-normalizer>=3.3.0
Requires-Dist: extract-msg>=0.48.0
Requires-Dist: odfpy>=1.4.1
Requires-Dist: olefile>=0.46
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: pyside2>=5.15.2.1; python_version <= '3.10'
Requires-Dist: pyside6>=6.5.0; python_version >= '3.11'
Requires-Dist: python-docx>=1.1.0
Requires-Dist: python-pptx>=0.6.23
Requires-Dist: pyyaml>=6.0
Requires-Dist: rarfile>=4.1
Requires-Dist: striprtf>=0.0.26
Requires-Dist: typing-extensions>=4.0; python_version < '3.13'
Requires-Dist: watchdog>=3.0.0
Requires-Dist: xlrd>=2.0.1
Provides-Extra: dev
Requires-Dist: prek>=0.4.5; extra == 'dev'
Requires-Dist: pyrefly>=1.1.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-html>=4.1.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: reportlab<4.0,>=3.6.13; (python_version < '3.9') and extra == 'dev'
Requires-Dist: reportlab>=4.0.0; (python_version >= '3.9') and extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: tox-uv>=1.13.1; extra == 'dev'
Requires-Dist: tox>=4.25.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=3.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: lint
Requires-Dist: pyrefly>=1.1.1; extra == 'lint'
Requires-Dist: ruff>=0.8.0; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest-html>=4.1.1; extra == 'test'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# fuscan

> 极速通用文件扫描器.

[![PyPI](https://img.shields.io/pypi/v/fuscan)](https://pypi.org/project/fuscan/)
[![CI](https://github.com/gookeryoung/fuscan/actions/workflows/ci.yml/badge.svg)](https://github.com/gookeryoung/fuscan/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Coverage](https://img.shields.io/badge/coverage-%E2%89%A596%25-brightgreen.svg)

基于 YAML 规则的多格式文件内容扫描工具，支持 CLI、GUI 与系统托盘驻守。可扫描 PDF、Office 文档、压缩包等多种格式，按文件名/内容/路径匹配并支持 AND/OR/NOT 逻辑组合。

## 特性

- **规则引擎**：YAML 配置规则，支持文件名、文件内容、路径三类匹配目标，contains/equals/regex 等多种模式，AND/OR/NOT 逻辑组合
- **多格式支持**：PDF、DOCX、PPTX、XLSX、ODT/ODS、WPS、纯文本，及 ZIP/RAR 压缩包内扫描
- **三种使用形态**：
  - CLI：`scan`/`rules`/`gui`/`tray`/`version` 子命令，支持 text/json/csv 输出
  - GUI：PySide2 GitHub Desktop 风格界面，实时进度、结果分类、详情预览、关键词高亮
  - 托盘驻守：watchdog 监控新增文件，增量扫描（mtime 跟踪），命中通知
- **内置通用规则**：随包分发 8 条安全规则，用户规则可覆盖
- **多规则合并**：支持加载多个规则文件，按顺序链式合并，后者覆盖前者同名规则

## 安装

```bash
pip install fuscan
```

或使用 [uv](https://docs.astral.sh/uv/)：

```bash
uv add fuscan
```

GUI 与托盘功能需要 PySide2（仅支持 Python 3.8~3.10）。

## 快速上手

### CLI

```bash
# 扫描指定路径（默认使用内置通用规则）
fuscan scan /path/to/scan

# 使用自定义规则文件，输出 JSON 报告
fuscan scan /path/to/scan -r rules/custom.yaml -o json -f report.json

# 加载多个规则文件（后者覆盖前者同名规则）
fuscan scan /path/to/scan -r base.yaml -r override.yaml

# 校验规则文件格式
fuscan rules -r rules/custom.yaml

# 启动 GUI
fuscan gui

# 启动托盘驻守（监控指定目录的新增文件）
fuscan tray -w /path/to/watch -r rules/custom.yaml
```

### GUI

```bash
fuscan gui
```

GUI 提供 GitHub Desktop 风格界面：模式卡片选择扫描范围（全盘/盘符/文件夹）、规则文件列表管理、实时进度反馈（当前文件/已扫描/命中/错误/已用时）、结果分类展示与详情预览（关键词高亮）、扫描结果导出（CSV/JSON）。

### 规则配置

规则文件为 YAML 格式，详见 [rules/example.yaml](rules/example.yaml)：

```yaml
version: "1.0"

ignore_dirs:
  - .git
  - node_modules

rules:
  # 文件名匹配
  - name: 敏感文件名检测
    severity: warning
    match:
      type: filename
      mode: contains
      pattern: password

  # 内容正则匹配
  - name: AWS 密钥泄露检测
    severity: critical
    match:
      type: content
      mode: regex
      pattern: 'AKIA[0-9A-Z]{16}'

  # AND 逻辑组合：配置文件含敏感词
  - name: 配置文件敏感词
    severity: warning
    match:
      type: and
      children:
        - type: filename
          mode: regex
          pattern: '\.(conf|ini|ya?ml)$'
        - type: content
          mode: contains
          pattern: password
```

更多场景化规则示例见 [rules/examples/](rules/examples/)，程序化使用示例见 [examples/](examples/)。

## 开发

```bash
# 安装开发依赖
uv sync --extra dev

# 全套门禁（lint + typecheck + coverage）
make check

# 运行测试
uv run pytest -m "not slow" --cov=fuscan --cov-fail-under=96

# 构建 Sphinx 文档
make doc

# 多版本测试（tox）
make tox
```

更多 Make 快捷命令运行 `make help` 查看。

## 许可证

MIT