KicomAV v0.41

KicomAV is an open source antivirus engine designed for detecting malware and disinfecting it. This antivirus engine is created and maintained by Kei Choi.

Sponsorship

KicomAV is maintained as a production-grade open-source antivirus engine. Sponsorship keeps the engine stable, continuously improved, and usable for real security work.

kicomav-x is a high-performance experimental antivirus engine implemented in Rust. It is currently private due to its experimental nature. Once KicomAV reaches a sustainable sponsorship level, kicomav-x will be opened as part of the project.

Sponsor: https://github.com/sponsors/hanul93

Features

Multi-format scanning: Files, archives (ZIP, RAR, 7z, CAB, ALZ, EGG, APK, OneNote), and nested containers
YARA integration: Custom YARA rules support for advanced threat detection
Intelligent caching: Dual-cache system with scan mode awareness for consistent, fast rescans
Exclusion rules: Flexible file/directory exclusion with glob patterns
Parallel scanning: Multi-threaded scanning for improved performance
Daemon mode: REST API and clamd-compatible socket protocol
Cross-platform: Windows, Linux, macOS support
Library API: Use as a Python library in your projects
PyInstaller support: Scan PyInstaller executables (Windows PE and Linux ELF)

Requirements
Installation
Configuration
Components
Command-Line Usage (k2)
Advanced Features
Library Usage
Daemon Mode (k2d & k2c)
License
Author

Requirements

Python 3.10+
rich - Terminal formatting
requests - HTTP library
python-dotenv - Environment variables
yara-python - YARA rules engine
py7zr - 7z archive support
rarfile - RAR archive support
pycabfile - CAB archive support

Daemon mode dependencies (k2d, k2c):

fastapi - REST API framework
uvicorn - ASGI server
python-multipart - Form data parsing

Optional dependencies:

pylzma - LZMA compression (for NSIS)

Installation

Via pip (Recommended)

pip install kicomav

From source

git clone https://github.com/hanul93/kicomav.git
cd kicomav
pip install -e .

With daemon support

pip install kicomav[daemon]

Configuration

KicomAV uses environment variables for configuration. Create a .env file in your home directory:

Windows:

mkdir %USERPROFILE%\.kicomav
copy .env.example %USERPROFILE%\.kicomav\.env

Linux/macOS:

mkdir -p ~/.kicomav
cp .env.example ~/.kicomav/.env

Then edit ~/.kicomav/.env to configure:

| Variable | Description | Example | |----------|-------------|---------| | UNRAR_TOOL | Path to UnRAR executable | /usr/bin/unrar or C:\Program Files\WinRAR\UnRAR.exe | | RAR_TOOL | Path to RAR executable | /usr/bin/rar or C:\Program Files\WinRAR\Rar.exe | | SYSTEM_RULES_BASE | System rules path | /var/lib/kicomav/rules or C:\kicomav\rules | | USER_RULES_BASE | User rules path | /home/user/kicomav_rules or C:\kicomav\user_rules |

Note: You can also place a .env file in the current working directory for project-specific settings (takes priority over global settings).

Components

KicomAV provides three command-line tools:

| Tool | Description | |------|-------------| | k2 | Main scanner - scan files and directories for malware | | k2d | Daemon server - REST API and socket protocol service | | k2c | Client - communicate with k2d daemon |

Quick Overview

Standalone scanning: Use k2 directly for local file scanning
Client-server mode: Run k2d as a service, use k2c to send scan requests

Command-Line Usage (k2)

$ k2 path[s] [options]

Basic Options

| Option | Description | |--------|-------------| | -f, --files | Scan files (default) | | -r, --arc | Scan archives | | -R, --nor | Do not recurse into folders | | -I, --list | Display all files | | -V, --vlist | Display virus list | | -?, --help | Show help |

Scan Actions

| Option | Description | |--------|-------------| | -p, --prompt | Prompt for action | | -d, --dis | Disinfect files | | -l, --del | Delete infected files | | --move | Move infected files to quarantine | | --copy | Copy infected files to quarantine |

Performance Options

| Option | Description | |--------|-------------| | --parallel | Enable parallel file scanning | | --workers=N | Number of worker threads (default: CPU count) | | --cache | Enable scan cache (default) | | --no-cache | Disable scan cache |

Other Options

| Option | Description | |--------|-------------| | -G, --log=FILE | Create log file | | -e, --app | Append to log file | | -F, --infp=PATH | Set quarantine folder | | --password=PWD | Password for encrypted archives | | --no-color | Disable colored output | | --sigtool | Extract files from archives to output folder | | --update | Update malware signatures |

Examples

Update signatures:

$ k2 --update

Scan current directory:

$ k2 . -I

Scan with archive support:

$ k2 /path/to/scan -r -I

Parallel scanning with 8 workers:

$ k2 /path/to/scan --parallel --workers=8

Scan and disinfect:

$ k2 /path/to/scan -d

Advanced Features

Exclusion Rules

KicomAV supports flexible file exclusion to skip unwanted files during scans.

Command-Line Options

| Option | Description | Example | |--------|-------------|---------| | --exclude=PATTERN | Exclude files matching glob pattern | --exclude=*.log | | --exclude-ext=EXT | Exclude by extension (comma-separated) | --exclude-ext=log,tmp | | --max-size=SIZE | Skip files larger than size | --max-size=100MB | | --ignore-file=FILE | Load rules from file | --ignore-file=.kicomav-ignore |

Size units: B, KB, MB, GB

Examples

# Skip log files and files over 50MB
k2 /path/to/scan --exclude-ext=log --max-size=50MB

# Skip multiple patterns
k2 /path/to/scan --exclude=**/node_modules/** --exclude=**/cache/**

# Use an ignore file
k2 /path/to/scan --ignore-file=.kicomav-ignore

Ignore File Format (.kicomav-ignore)

Create a .kicomav-ignore file (similar to .gitignore):

# Comment lines start with #
*.log                    # Exclude all .log files
*.tmp                    # Exclude all .tmp files
node_modules/            # Exclude node_modules directory
build/                   # Exclude build directory
**/cache/**              # Exclude cache directories anywhere
>100MB                   # Skip files larger than 100MB

Ignore file search order:

Current directory
Parent directories (up to root)
~/.kicomav/.kicomav-ignore

Pattern Matching

| Pattern | Matches | Does Not Match | |---------|---------|----------------| | *.log | app.log, error.log | app.txt, log.txt | | **/cache/** | /project/cache/file.txt | /project/cached/file.txt | | node_modules/ | /project/node_modules/pkg.json | /project/my_modules/pkg.json | | file?.txt | file1.txt, fileA.txt | file10.txt, file.txt |

Library Usage

from kicomav.kavcore.k2exclude import ExclusionRule, create_exclusion_rule

# Create rule with factory function
rule = create_exclusion_rule(
    patterns=["**/node_modules/**", "**/cache/**"],
    extensions=["log", "tmp", "bak"],
    max_size="100MB"
)

# Check if a file should be excluded
if rule.should_exclude("/path/to/file.log"):
    print("File excluded")

Scan Cache

KicomAV supports intelligent caching to skip unchanged files during rescans, significantly improving scan performance.

How It Works

SQLite database stored at ~/.kicomav/cache.db
Dual cache system: Separate caches for regular files and archives
Files are skipped if unchanged since last scan
Cache invalidates when signature version changes
Configurable expiration period (default: 7 days)

Cache Architecture

KicomAV uses a sophisticated dual-cache system:

| Cache Type | Purpose | Key | |------------|---------|-----| | scan_cache | Regular files | file_path | | archive_cache | Archives (ZIP, RAR, 7z, etc.) | (archive_path, scan_mode) |

Scan Mode Awareness: The archive cache tracks whether -r (deep archive scan) option was used:

-I and -r -I scans maintain separate cache entries
Switching between scan mode

Kicomav

Install / Use

README

KicomAV v0.41

Sponsorship

Features

Table of Contents

Requirements

Installation

Via pip (Recommended)

From source

With daemon support

Configuration

Components

Quick Overview

Command-Line Usage (k2)

Basic Options

Scan Actions

Performance Options

Other Options

Examples

Advanced Features

Exclusion Rules

Command-Line Options

Examples

Ignore File Format (.kicomav-ignore)

Pattern Matching

Library Usage

Scan Cache

How It Works

Cache Architecture