🛡️ MacScan

Command-line malware scanner for macOS — Simple, fast, and transparent.

MacScan is an open-source CLI tool designed to scan your Mac for malware, adware, and potentially unwanted software. Built for power users and security researchers who prefer the terminal over bloated GUI applications.

✨ Features

• Quick Scan — Scan common threat locations (Downloads, Desktop, Documents, Applications)
• Full System Scan — Deep scan of your entire system
• Path Scan — Scan specific directories
• Real-time Progress — See current file being scanned with counter
• Quarantine — Isolate and manage infected files safely
• Whitelist — Exclude trusted paths from scans
• JSON Export — Export scan results for automation
• macOS Notifications — Native alerts on scan completion
• Interactive TUI — Arrow-key menu navigation with keyboard shortcuts
• Lightweight — Pure Bash with ClamAV backend
• Transparent — Open source, no telemetry, no network requests
• Safe — No auto-delete, all actions require confirmation

📦 Installation

Quick Install

# Clone the repository
git clone https://github.com/artcc/macscan.git
cd macscan

# Run the installer
./install.sh

The installer will check for dependencies and offer to install them:

• Homebrew — Package manager for macOS (if not installed)
• ClamAV — Open-source antivirus engine (if not installed)

The installer will also offer to initialize the virus database automatically.

Manual Prerequisites

If you prefer to install dependencies manually:

# Install Homebrew (if needed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install ClamAV
brew install clamav

🚀 Quick Start

# Interactive mode (TUI menu)
ms

# Quick scan (common threat locations)
ms scan

# Scan a specific directory
ms scan --path ~/Downloads

# Full system scan
ms scan --full

# Preview what will be scanned (with whitelist)
ms scan --dry-run

# Silent scan with notification
ms scan --quiet --notify

# Export results to JSON
ms scan --export results.json

# Update virus signatures
ms update

# Show status and last scan info
ms status

# Manage whitelisted paths
ms whitelist list
ms whitelist add ~/safe-folder

# Manage quarantined files
ms quarantine list
ms quarantine restore <id>

# Uninstall MacScan
ms remove

# Show version and author info
ms version
ms author

# Show help
ms help

🎮 Interactive Mode

Run ms without any arguments to launch the interactive menu:

ms

This opens a TUI with arrow key navigation:

 __  __            ____
|  \/  | __ _  ___/ ___|  ___ __ _ _ __
| |\/| |/ _` |/ __\___ \ / __/ _` | '_ \
| |  | | (_| | (__ ___) | (_| (_| | | | |
|_|  |_|\__,_|\___|____/ \___\__,_|_| |_|

  https://github.com/artcc/macscan
  Command-line malware scanner for macOS

  ▶ 1. Quick Scan    Scan common threat locations
    2. Full Scan     Deep scan of your entire system
    3. Scan Path     Scan a specific directory
    4. Update        Update virus database signatures
    5. Status        Show system status and last scan
    6. Quarantine    Manage quarantined files
    7. Whitelist     Manage excluded paths

  ─────────────────────────────────────────────
  ↑↓ Navigate  Enter Select  H Help  V Version  A Author  Q Quit

📖 Commands

Command	Description
ms scan	Quick scan of common threat locations
ms scan --path <dir>	Scan a specific directory
ms scan --full	Full system scan (takes longer)
ms update	Update ClamAV virus database
ms status	Show system status and last scan info
ms quarantine	Manage quarantined files
ms whitelist	Manage excluded paths
ms remove	Uninstall MacScan
ms help	Show help information
ms version	Show version information
ms author	Show author information

Options

Option	Description
-p, --path <dir>	Specify directory to scan
-f, --full	Perform full system scan
-v, --verbose	Show detailed output
-q, --quiet	Suppress output (for scripts)
--dry-run	Show what would be scanned without scanning
--no-color	Disable colored output
--notify	Send macOS notification on completion
--export <file>	Export results to JSON file
-h, --help	Show help for a command

📁 Directory Structure

MacScan follows the XDG Base Directory Specification:

/usr/local/bin/
├── macscan                 # Main command
└── ms                      # Short alias

~/.config/macscan/          # Configuration
├── config.conf             # User settings
├── whitelist               # Scan exclusions
├── bin/                    # Installed scripts
└── lib/                    # Library modules

~/.local/share/macscan/     # Persistent data
├── quarantine/             # Isolated threats
└── logs/                   # Scan history

~/.cache/macscan/           # Temporary cache
└── last_scan               # Last scan info

🔧 Configuration

Configuration file: ~/.config/macscan/config.conf

# Example configuration
verbose=0
auto_update=1

Whitelist

Exclude paths from scanning using the whitelist command:

# List whitelisted paths
ms whitelist list

# Add a path to whitelist
ms whitelist add ~/Library/Caches

# Remove a path from whitelist
ms whitelist remove ~/Library/Caches

# Edit whitelist manually
ms whitelist edit

Or edit the file directly at ~/.config/macscan/whitelist:

# Lines starting with # are comments
/path/to/exclude
/another/path

Database Age Warning

MacScan automatically warns you if the virus database is older than 7 days before each scan. Keep your database updated with:

ms update

🧪 Development

Project Structure

macscan/
├── bin/
│   ├── macscan             # Main entry point
│   └── ms                  # Alias script
├── lib/
│   ├── core/
│   │   ├── common.sh       # Utilities and helpers
│   │   └── colors.sh       # ANSI colors and formatting
│   ├── scan/
│   │   └── clamav.sh       # ClamAV wrapper
│   └── ui/
│       ├── spinner.sh      # Loading spinners
│       └── progress.sh     # Progress bars
├── completions/
│   ├── macscan.bash        # Bash completion
│   └── _macscan            # Zsh completion
├── docs/
│   └── TROUBLESHOOTING.md  # Common issues
├── .github/
│   └── workflows/ci.yml    # GitHub Actions
├── install.sh              # Installer
├── uninstall.sh            # Uninstaller
├── LICENSE                 # MIT License
└── README.md               # This file

Running from Source

# Clone and enter directory
git clone https://github.com/artcc/macscan.git
cd macscan

# Run directly without installing
./bin/ms scan
./bin/ms --help

🗑️ Uninstallation

# If installed
ms remove

# Or run the uninstaller directly
~/.config/macscan/uninstall.sh

# Or from the source directory
./uninstall.sh

This will remove:

• /usr/local/bin/macscan and /usr/local/bin/ms
• ~/.config/macscan/
• ~/.local/share/macscan/
• ~/.cache/macscan/

Note: ClamAV is not removed. To remove it: brew uninstall clamav

🛣️ Roadmap

Phase 1 - MVP ✅

• Basic CLI structure
• ClamAV integration
• Quick/Full/Path scanning
• TUI with colors and progress
• Installer/Uninstaller

Phase 2 - Core Features ✅

• Quarantine management
• Whitelist support (CLI)
• JSON export
• macOS notifications
• Shell completions (Bash/Zsh)
• Database age warning
• Dry-run mode
• Signal handling (Ctrl+C safety)
• GitHub Actions CI
• Interactive TUI menu

Phase 3 - Advanced

• macOS-specific malware hashes (Objective-See)
• Scheduled scans (launchd)
• Homebrew

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🙏 Acknowledgments

• ClamAV - Open source antivirus engine
• Mole - Inspiration for TUI design
• Objective-See - macOS security research

⚠️ Disclaimer

MacScan is provided "as is" without warranty of any kind, express or implied.

• No antivirus solution can detect 100% of malware. MacScan uses ClamAV's open-source virus database, which may not include the latest threats or macOS-specific malware.
• This tool is for educational and supplementary security purposes only. It should not replace macOS built-in security features (Gatekeeper, XProtect, Malware Removal Tool) or professional security solutions.
• False positives may occur. ClamAV may flag legitimate files as threats. Always verify before deleting.
• The authors are not responsible for any damage, data loss, or security incidents resulting from the use or misuse of this software.
• Use at your own risk. Always maintain current backups of important data.

By using MacScan, you acknowledge that you understand these limitations and accept full responsibility for its use on your system.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

_{Made with ❤️ for the macOS community
Built with GitHub Copilot (Claude Opus 4.5)
Arturo Carretero Calvo — 2026}