oysterav 0.2.2

Linux security orchestrator (CLI-first). Prefer AUR/COPR/deb for Polkit helper; pip is for CLI discovery.

oysterAV

Linux security orchestrator — CLI-first backend with a thin GTK4 GUI.
ClamAV spine, pack adapters, quarantine, scheduling — without reimplementing engines.

Dashboard — posture cards, security news ticker, recent scans

---

Why oysterAV?

• Orchestrator, not engine — wraps ClamAV, rkhunter, Lynis, and friends (ADR-001)
• CLI owns security — oyst-cli is the source of truth; the GUI is a client (ADR-002)
• Full or Lite runtime — vendored tools under XDG, or host packages only (ADR-004)
• Host co-control — on-access blocking stays with ClamAV; oysterAV guides and responds (ADR-008)

Screenshots

Scan	Reports
Profiles, paths, multi-pack progress	History, export, quarantine / resolve actions

Settings — feeds, scan defaults, services, scheduling, packs

Prerequisites

• Python ≥ 3.12 and uv
• GUI: system GTK4 + libadwaita (PyGObject introspection)

Quick start

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.

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

GUI

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 and the GUI↔CLI contract.

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.

Pack runtime (Full mode, default)

Vendored upstream tools live under ~/.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 mode uses host packages only (packaging/lite/README.md):

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):

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

Install from GitHub Releases

Prefer a system package so the privileged helper is root-owned under /usr (getting started). Current install path: assets on each GitHub Release.

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
Fedora COPR	Pending listing	Spec prepared — see distro submit status
Flathub	Pending listing	Offline manifest prepared — see distro submit status
PyPI (CLI)	Pending publish	CLI discoverability only; not recommended for the privileged helper

After install, verify freshness against GitHub Releases:

oyst-cli version --check

Full packaging notes: docs/packaging/release.md. Storefront status: docs/packaging/distro-submit.md.

Health / debug

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
• CLI reference
• Pack commands
• Release / packaging
• Distro submit tracks
• Flatpak

License

GPL-3.0-or-later — GNU General Public License v3 or later.