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

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

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.

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.