Metadata-Version: 2.4
Name: oysterav
Version: 0.2.2
Summary: Linux security orchestrator (CLI-first). Prefer AUR/COPR/deb for Polkit helper; pip is for CLI discovery.
Project-URL: Homepage, https://github.com/asafelobotomy/oysterAV
Project-URL: Repository, https://github.com/asafelobotomy/oysterAV
Project-URL: Issues, https://github.com/asafelobotomy/oysterAV/issues
Author: oysterAV contributors
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: antivirus,clamav,cli,linux,security
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications :: GTK
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: click>=8.1.0
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: mypy>=1.11.0; extra == 'all'
Requires-Dist: pygobject>=3.48.0; extra == 'all'
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: ruff>=0.6.0; extra == 'all'
Requires-Dist: types-defusedxml>=0.7.0.20260504; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: types-defusedxml>=0.7.0.20260504; extra == 'dev'
Provides-Extra: gui
Requires-Dist: pygobject>=3.48.0; extra == 'gui'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/oysterav-icon-256.png" alt="oysterAV icon" width="128" height="128">
</p>

<h1 align="center">oysterAV</h1>

<p align="center">
  <strong>Linux security orchestrator</strong> — CLI-first backend with a thin GTK4 GUI.<br>
  ClamAV spine, pack adapters, quarantine, scheduling — without reimplementing engines.
</p>

<p align="center">
  <a href="https://github.com/asafelobotomy/oysterAV"><img alt="GitHub" src="https://img.shields.io/badge/github-asafelobotomy%2FoysterAV-blue?logo=github"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-GPL--3.0--or--later-green"></a>
  <img alt="Python" src="https://img.shields.io/badge/python-%E2%89%A5%203.12-3776AB?logo=python&logoColor=white">
</p>

<p align="center">
  <img src="docs/assets/screenshots/dashboard.png" alt="oysterAV Dashboard" width="720">
</p>

<p align="center"><em>Dashboard — posture cards, security news ticker, recent scans</em></p>

---

## Why oysterAV?

- **Orchestrator, not engine** — wraps ClamAV, rkhunter, Lynis, and friends ([ADR-001](docs/adr/001-orchestrator-not-engine.md))
- **CLI owns security** — `oyst-cli` is the source of truth; the GUI is a client ([ADR-002](docs/adr/002-cli-first-gui-is-client.md))
- **Full or Lite runtime** — vendored tools under XDG, or host packages only ([ADR-004](docs/adr/004-pack-runtime-delivery.md))
- **Host co-control** — on-access blocking stays with ClamAV; oysterAV guides and responds ([ADR-008](docs/adr/008-clamav-host-cocontrol.md))

## Screenshots

| Scan | Reports |
|:----:|:-------:|
| <img src="docs/assets/screenshots/scan.png" alt="Scan tab" width="360"> | <img src="docs/assets/screenshots/reports.png" alt="Reports tab" width="360"> |
| Profiles, paths, multi-pack progress | History, export, quarantine / resolve actions |

<p align="center">
  <img src="docs/assets/screenshots/settings.png" alt="Settings" width="720"><br>
  <em>Settings — feeds, scan defaults, services, scheduling, packs</em>
</p>

## Prerequisites

- Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/)
- GUI: system GTK4 + libadwaita (PyGObject introspection)

## Quick start

```bash
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` can take several minutes on a cold machine (signatures / packs). Soft-failed steps (schedule, rkhunter) are non-fatal — check `--json` output.

Privileged helper install (`install-privileged-helper`) needs a root-owned
`oyst_core` prefix (distro package) or `sudo uv run oyst-cli install-privileged-helper --dev`
for a checkout. See [docs/cli/reference.md](docs/cli/reference.md#helper).

```bash
./scripts/check.sh --quick   # local validation
./scripts/check.sh --format  # also enforce ruff format
```

## GUI

```bash
uv sync --extra gui --extra dev
uv run oysterav
```

The GUI talks only through `OystClient` / `oyst-cli serve` — never runs security tools itself. See [ADR-007](docs/adr/007-gui-remapping-phase.md) and the [GUI↔CLI contract](docs/cli/gui-contract.md).

## Architecture

| Package | Role |
|---------|------|
| `oyst_core` | Packs, orchestrator, quarantine, RPC serve |
| `oyst_cli` | Full CLI (`oyst-cli`) |
| `oysterav` | Thin GTK4 / libadwaita client |

Decision log: [docs/adr/README.md](docs/adr/README.md).

## Pack runtime (Full mode, default)

Vendored upstream tools live under `~/.local/share/oysterav/runtime/`:

```bash
uv run oyst-cli runtime status
uv run oyst-cli runtime install --all
uv run oyst-cli runtime update   # ClamAV CDIFF updates
```

**Lite mode** uses host packages only ([packaging/lite/README.md](packaging/lite/README.md)):

```bash
uv run oyst-cli config set runtime.mode lite
```

## Packs

| Tier | Packs |
|------|-------|
| Required | clamav, freshclam |
| Recommended | rkhunter, chkrootkit, lynis, clamonacc, firewall |
| Optional | maldet, unhide, fail2ban, fangfrisch |

Host package examples (Lite / clamd on the host):

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

On-access prevention with the host: [operator guide](docs/user-guide/clamonacc-prevention.md).

## Install from GitHub Releases

Prefer a **system package** so the privileged helper is root-owned under `/usr`
([getting started](docs/user-guide/getting-started.md)). **Current install path:**
assets on each [GitHub Release](https://github.com/asafelobotomy/oysterAV/releases).

| Channel | Status | Install |
|---------|--------|---------|
| **Debian/Ubuntu (.deb)** | Available | Download `oysterav_*_amd64.deb`, then `sudo apt install ./oysterav_*_amd64.deb` |
| **Fedora/RHEL (.rpm)** | Available | Download `oysterav-*-1.x86_64.rpm`, then `sudo dnf install ./oysterav-*.rpm` |
| **Flatpak (GitHub bundle)** | Available | `flatpak install --user ./oysterAV-*-x86_64.flatpak` — **also install a host `.deb`/`.rpm`** for Polkit helper elevation |
| **Wheel / uv (dev)** | Available | Download the `.whl` or clone and `uv sync --extra all` |
| **AUR** (Arch / CachyOS) | Pending listing | Packaging prepared — see [distro submit status](docs/packaging/distro-submit.md) |
| **Fedora COPR** | Pending listing | Spec prepared — see [distro submit status](docs/packaging/distro-submit.md) |
| **Flathub** | Pending listing | Offline manifest prepared — see [distro submit status](docs/packaging/distro-submit.md) |
| **PyPI (CLI)** | Pending publish | CLI discoverability only; not recommended for the privileged helper |

After install, verify freshness against GitHub Releases:

```bash
oyst-cli version --check
```

Full packaging notes: [docs/packaging/release.md](docs/packaging/release.md).
Storefront status: [docs/packaging/distro-submit.md](docs/packaging/distro-submit.md).

## Health / debug

```bash
uv run oyst-cli doctor --json
uv run oyst-cli status assess --json
uv run oyst-cli serve --foreground   # RPC for the GUI
```

## Docs

- [Getting started](docs/user-guide/getting-started.md)
- [CLI reference](docs/cli/reference.md)
- [Pack commands](docs/cli/pack-commands.md)
- [Release / packaging](docs/packaging/release.md)
- [Distro submit tracks](docs/packaging/distro-submit.md)
- [Flatpak](packaging/oysterav/flatpak/README.md)

## License

[GPL-3.0-or-later](LICENSE) — GNU General Public License v3 or later.
