oysterAV 是一个 Linux 安全编排器，以 CLI 为核心后端配合 GTK4 图形界面，统一封装和调度 ClamAV、rkhunter、Lynis 等安全工具，实现扫描调度、隔离管理与安全态势可视化。
oysterAV
Linux 安全编排器 — CLI 优先的后端，带有轻量级的 GTK4 GUI。
ClamAV 核心、pack 适配器、隔离区、调度 — 无需重新实现引擎。
仪表盘 — 安全态势卡片、安全新闻滚动条、近期扫描
## 为什么选择 oysterAV？
- **是编排器，而非引擎** — 封装 ClamAV、rkhunter、Lynis 等工具 ([ADR-001](docs/adr/001-orchestrator-not-engine.md))
- **CLI 掌控安全** — `oyst-cli` 是唯一事实来源；GUI 只是客户端 ([ADR-002](docs/adr/002-cli-first-gui-is-client.md))
- **完整或精简运行时** — XDG 下内置的工具，或仅使用主机软件包 ([ADR-004](docs/adr/004-pack-runtime-delivery.md))
- **主机协同控制** — 访问时拦截仍由 ClamAV 负责；oysterAV 负责引导和响应 ([ADR-008](docs/adr/008-clamav-host-cocontrol.md))
## 截图
| 扫描 | 报告 |
|:----:|:-------:|
|
|
|
| 配置文件、路径、多 pack 进度 | 历史记录、导出、隔离 / 解决操作 |
Settings — feeds, scan defaults, services, scheduling, packs
## 前置条件
- Python ≥ 3.12 和 [uv](https://docs.astral.sh/uv/)
- GUI：系统 GTK4 + libadwaita（PyGObject introspection）
## 快速开始
```
uv sync --extra all
uv run oyst-cli setup run --confirm --json
uv run oyst-cli status assess --json
uv run oyst-cli scan ~/Downloads --json
```
`setup run` 在冷启动的机器上可能需要几分钟（特征库 / pack）。软失败的步骤（调度、rkhunter）是非致命的 — 请检查 `--json` 输出。
特权辅助程序的安装（`install-privileged-helper`）需要 root 拥有的
`oyst_core` 前缀（发行版软件包），或者对于检出代码使用 `sudo uv run oyst-cli install-privileged-helper --dev`。
请参阅 [docs/cli/reference.md](docs/cli/reference.md#helper)。
```
./scripts/check.sh --quick # local validation
./scripts/check.sh --format # also enforce ruff format
```
## GUI
```
uv sync --extra gui --extra dev
uv run oysterav
```
GUI 仅通过 `OystClient` / `oyst-cli serve` 进行通信 — 本身绝不运行安全工具。请参阅 [ADR-007](docs/adr/007-gui-remapping-phase.md) 和 [GUI↔CLI 契约](docs/cli/gui-contract.md)。
## 架构
| 软件包 | 角色 |
|---------|------|
| `oyst_core` | Pack、编排器、隔离区、RPC 服务 |
| `oyst_cli` | 完整的 CLI (`oyst-cli`) |
| `oysterav` | 轻量级 GTK4 / libadwaita 客户端 |
决策日志：[docs/adr/README.md](docs/adr/README.md)。
## Pack 运行时（Full 模式，默认）
内置的上游工具位于 `~/.local/share/oysterav/runtime/`：
```
uv run oyst-cli runtime status
uv run oyst-cli runtime install --all
uv run oyst-cli runtime update # ClamAV CDIFF updates
```
**Lite 模式**仅使用主机软件包 ([packaging/lite/README.md](packaging/lite/README.md))：
```
uv run oyst-cli config set runtime.mode lite
```
## Pack
| 级别 | Pack |
|------|-------|
| 必需 | clamav, freshclam |
| 推荐 | rkhunter, chkrootkit, lynis, clamonacc, firewall |
| 可选 | maldet, unhide, fail2ban, fangfrisch |
主机软件包示例（主机上的 Lite / clamd）：
```
# Debian/Ubuntu
sudo apt install clamav clamav-daemon rkhunter chkrootkit lynis
# Arch / CachyOS
sudo pacman -S clamav rkhunter chkrootkit lynis
# Fedora
sudo dnf install clamav clamav-update rkhunter chkrootkit lynis
```
在主机上进行访问时预防：[操作指南](docs/user-guide/clamonacc-prevention.md)。
## 健康 / 调试
```
uv run oyst-cli doctor --json
uv run oyst-cli status assess --json
uv run oyst-cli serve --foreground # RPC for the GUI
```
## 文档
- [入门指南](docs/user-guide/getting-started.md)
- [CLI 参考](docs/cli/reference.md)
- [Pack 命令](docs/cli/pack-commands.md)
- [发布 / 打包](docs/packaging/release.md)
- [Flatpak](packaging/oysterav/flatpak/README.md)
## 许可证
[GPL-3.0-or-later](LICENSE) — GNU General Public License v3 或更高版本。