MacScan is a transparent Bash CLI for running ClamAV on macOS. It complements Gatekeeper, XProtect and professional security tools; it does not replace them.

• Quick scan of common user and application locations.
• Path-specific and extended scans.
• Reliable ClamAV exit codes for automation.
• Private quarantine with validated IDs and restorable permissions.
• Exact-path whitelist converted to escaped ClamAV exclusions.
• Atomic JSON export with escaped paths and threat names.
• Configuration through CLI, file and XDG paths.
• Quiet, verbose, NO_COLOR and native notification modes.
• Daily and weekly LaunchAgents for Apple Silicon Macs.
• Ownership-aware installation and removal.
• Dependency-free tests running on macOS Bash 3.2.

MacScan does not include telemetry or make application-specific network requests. Homebrew installation and ClamAV signature updates require network access.

• macOS on Apple Silicon
• Bash 3.2 or newer
• ClamAV (clamscan and freshclam)
• Homebrew is recommended for installing ClamAV

brew install clamav

git clone https://github.com/artcc/macscan.git
cd macscan
./install.sh
macscan update

The only third-party runtime dependency is ClamAV. If Homebrew already exists, the installer can offer to run brew install clamav; it never installs Homebrew, Bats, jq, ShellCheck or any other package. It also refuses to overwrite unrelated macscan or ms commands unless --force is explicitly supplied.

Upgrading an installation older than 0.0.5, which has no ownership manifest, requires one explicit ./install.sh --force; subsequent upgrades are verified by hash.

ms                         # Interactive menu
ms scan                    # Common locations
ms scan --path ~/Downloads # One file or directory
ms scan --full             # Extended configured locations
ms scan --dry-run          # Preview roots and approximate file counts
ms scan --verbose          # Print each ClamAV result
ms scan --quiet --notify   # Automation-friendly scan
ms scan --export result.json
ms scan --yes              # Auto-quarantine detections
ms update
ms status

Quick Scan is recursive over Downloads, Desktop, Documents, user Applications and /Applications. Extended Scan is recursive over $HOME, /Applications, /Library and /usr/local; it is not a byte-for-byte scan of every mounted filesystem.

Threats keep exit code 1 even when quarantine succeeds. A ClamAV failure is never reported as clean.

ms quarantine list
ms quarantine restore <id>
ms quarantine delete <id>
ms quarantine clean

Quarantined payloads are stored under a private 0700 directory with separate encoded metadata. Restore refuses to overwrite an existing destination. Non-interactive scans only quarantine automatically when --yes or quarantine_auto=1 is set.

ms whitelist list
ms whitelist add ~/Library/Caches
ms whitelist remove ~/Library/Caches
ms whitelist edit

Entries are exact files or directory roots. Regex metacharacters are escaped before passing exclusions to ClamAV.

ms config list
ms config get db_max_age
ms config set auto_update 1
ms config edit

Supported keys are verbose, quiet, auto_update, notify, quarantine_auto and db_max_age. CLI options override file values.

MacScan respects XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_CACHE_HOME. Defaults are:

~/.config/macscan/          configuration, libraries and install manifest
~/.local/share/macscan/     logs and quarantine
~/.cache/macscan/           last-scan state

ms schedule daily 22:00
ms schedule weekly monday 03:00
ms schedule list
ms schedule remove

MacScan generates and validates one LaunchAgent using launchctl bootstrap/bootout. The job has an explicit Homebrew-aware PATH, invokes macscan directly and writes logs under the MacScan data directory.

--export works with quick, path and extended scans. Files are written atomically with mode 0600. The document contains scan status, engine information, error details and quarantine state for each detection.

ms remove              # Remove owned binaries and LaunchAgent
ms remove --purge      # Also remove config, logs, cache and quarantine

Normal removal preserves user data and quarantined files. Installed command hashes are checked before deletion; changed or unrelated commands are preserved unless --force is explicitly requested. ClamAV is never removed.

/bin/bash tests/run.sh
/bin/bash -n bin/macscan install.sh uninstall.sh $(find lib -name '*.sh')
zsh -n completions/_macscan
shellcheck -x bin/macscan bin/ms install.sh uninstall.sh tests/run.sh

Tests use isolated directories and mocked ClamAV/launchd commands. They do not use network access, sudo, the real quarantine or the real LaunchAgent.

No antivirus detects every threat, and false positives are possible. Review detections before restoring or deleting files and keep current backups. Please report security issues privately to the repository owner before public disclosure.

MIT. See LICENSE.