ensign-scan added to PyPI

Ensign-scan has been added to the Python Package Index (PyPI) as a novel tool designed to enhance file scanning capabilities on Linux systems. This utility operates alongside ClamAV, a well-established antivirus engine, by focusing on local file hashing and change detection to optimize scanning efficiency.

The tool originated as a personal project to address several limitations encountered with ClamAV’s default scanner, clamscan. The developer experienced issues such as permission denials, oversized file restrictions, broken symbolic links, and recursive scanning loops—particularly problematic with Steam Proton’s Z: drive integration, which caused a compounding duplication of scanned files. These challenges motivated the creation of Ensign-scan to provide a more intelligent and robust solution.

At its core, Ensign-scan maintains a comprehensive SQLite database that records detailed metadata for every file on the system. This includes identifiers like file path, hash, size, modification and inode change times, scan results, threat information, and timestamps of previous scans. By tracking these attributes, the scanner only re-examines files flagged as altered, significantly reducing redundant processing.

The system is built with Python 3.11 or newer and utilizes SQLAlchemy for database interactions. Ensign-scan interfaces with ClamAV’s daemon (clamd) via a local Unix socket, ensuring no external network connections are initiated by the scanner itself. Signature updates remain the responsibility of ClamAV’s freshclam utility, which operates independently.

To accommodate the Linux ecosystem’s diversity, Ensign-scan is designed for broad compatibility across distributions, requiring only Python 3.11+ and an operational ClamAV daemon. An optional feature, --verify-pacman, integrates with Arch Linux’s package manager for integrity verification, but gracefully disables itself on non-Arch systems.

The scanner employs concurrent file processing through threading, optimizing performance for I/O-bound operations such as hashing and communicating with clamd. The number of worker threads adapts dynamically based on ClamAV’s configured limits and system CPU availability, ensuring responsiveness without overwhelming resources.

Notably, the scanner avoids modifying file permissions directly. Instead, it generates suggested commands (setfacl) for users to apply manually if permission issues are detected during scans. This cautious approach prioritizes safety by preventing unintentional system changes.

During development, the recursive file duplication caused by Steam Proton’s Z: drive was a significant obstacle. Because the Z: drive exposes the entire filesystem, including snapshots and backups, the scanner originally entered an infinite loop of scanning identical files multiple times. The solution was to disable following symbolic links for directories, thereby preventing redundant and endless directory traversal.

The project remains in an alpha phase, with testing thus far limited to the author’s Arch Linux environment. Users should consider the output advisory rather than authoritative, as further validation and community feedback are welcomed. Ensign-scan is released under the MIT License and is independent of any affiliations with commercial or governmental entities.

Installation is facilitated via pip or pipx, with instructions accommodating virtual environments and source code usage. On first execution, users must avoid running with elevated privileges to ensure proper ownership of configuration and database files. The scanner provides real-time progress indicators and desktop notifications upon completion, including alerts for detected threats.

Ensign-scan emphasizes transparency and user control, logging errors and findings separately without automatic file quarantine or deletion. It offers mechanisms to purge stale records when files are removed and supports user extensions for custom path and file classifications.

While detailed documentation accompanies the project, certain operational nuances—such as handling of temporary files and permission resets following software updates—require user attention. The tool’s comprehensive database and reporting capabilities offer advanced insights beyond typical scanning utilities.

As a new entrant in the Linux security landscape, Ensign-scan presents a thoughtful approach to malware detection by integrating meticulous file tracking with ClamAV’s signature-based scanning. Its local-first design and cautious operational philosophy may appeal to users seeking granular control and efficiency in maintaining system integrity. Further development and broader testing will determine its long-term suitability for diverse Linux environments.