kicomav 0.40

KICOM Anti-Virus II - Open source antivirus engine for Python

KicomAV v0.40

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

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

Optional dependencies:

• pylzma - LZMA compression (for NSIS)

Quick start

Installation via pip (Recommended)

pip install kicomav

Installation from source

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

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).

Usage

$ k2 path[s] [options]

Example 1: Show help options

$ k2 --help
------------------------------------------------------------
KICOM Anti-Virus II (for WIN32) Ver 0.40 (Dec 31 2025)
Copyright (C) 1995-2025 Kei Choi. All rights reserved.
------------------------------------------------------------

Usage: k2.py path[s] [options]
Options:
        -f,  --files           scan files *
        -r,  --arc             scan archives
        -G,  --log=file        create log file
        -I,  --list            display all files
        -e,  --app             append to log file
        -F,  --infp=path       set infected quarantine folder
        -R,  --nor             do not recurse into folders
        -V,  --vlist           display virus list
        -p,  --prompt          prompt for action
        -d,  --dis             disinfect files
        -l,  --del             delete infected files
             --no-color        don't print with color
             --move            move infected files in quarantine folder
             --copy            copy infected files in quarantine folder
             --qname           quarantine by name of malware
             --qhash           quarantine by sha256 hash of malware
             --password=PWD    set password for encrypted archives
             --parallel        enable parallel file scanning
             --workers=N       number of worker threads (default: CPU count)
             --update          update
        -?,  --help            this help
                               * = default option

Example 2: Update malware signatures

$ k2 --update
------------------------------------------------------------
KICOM Anti-Virus II (for WIN32) Ver 0.40 (Dec 31 2025)
Copyright (C) 1995-2025 Kei Choi. All rights reserved.
------------------------------------------------------------

whitelist.txt  update
yara/reversinglabs-yara-rules-develop.zip  update

[Signature updates complete]

Example 3: Scan current directory

$ k2 . -I
------------------------------------------------------------
KICOM Anti-Virus II (for WIN32) Ver 0.40 (Dec 31 2025)
Copyright (C) 1995-2025 Kei Choi. All rights reserved.
------------------------------------------------------------
Last updated Tue Dec 30 06:49:08 2025 UTC
Signature number: 1,266

C:\kicomav\eicar.txt  infected : EICAR-Test-File (not a virus)

Results:
Folders           :0
Files             :1
Packed            :0
Infected files    :1
Suspect files     :0
Warnings          :0
Identified viruses:1
I/O errors        :0

Example 4: Scan directory recursively (including archives)

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

Library Usage

KicomAV can also be used as a Python library in your own projects.

Installation

pip install kicomav

Basic Scanning

import kicomav

# Scan a single file
with kicomav.Scanner() as scanner:
    result = scanner.scan_file("/path/to/suspicious_file.exe")
    if result.infected:
        print(f"Malware detected: {result.malware_name}")
    else:
        print("File is clean")

Directory Scanning

import kicomav

# Scan an entire directory
with kicomav.Scanner() as scanner:
    results = scanner.scan_directory("/path/to/folder", recursive=True)

    infected_files = [r for r in results if r.infected]
    print(f"Scanned {len(results)} files, found {len(infected_files)} infected")

    for result in infected_files:
        print(f"  {result.path}: {result.malware_name}")

Updating Signatures

import kicomav

# Update malware signatures
result = kicomav.update()

if result.package_update_available:
    print(f"New version available: {result.latest_version}")
    print("Run: pip install --upgrade kicomav")

if result.updated_files:
    print(f"Updated {len(result.updated_files)} signature files")

Configuration Access

import kicomav

# Access current configuration
config = kicomav.get_config()
print(f"System rules path: {config.system_rules_base}")
print(f"User rules path: {config.user_rules_base}")
print(f"Rules paths dict: {config.rules_paths}")

Configuration Warnings

When you import kicomav without proper configuration, warning messages will be displayed:

[KicomAV Warning] .env file not found: /home/user/.kicomav/.env
[KicomAV Warning]   Create it with: mkdir -p /home/user/.kicomav && touch /home/user/.kicomav/.env
[KicomAV Warning] No rules paths configured (SYSTEM_RULES_BASE, USER_RULES_BASE)
[KicomAV Warning]   Signature updates and YARA scanning will not work.
[KicomAV Warning]   Set SYSTEM_RULES_BASE in your .env file.
[KicomAV Warning] To suppress these warnings, set KICOMAV_SUPPRESS_WARNINGS=1

Suppress warnings via environment variable:

export KICOMAV_SUPPRESS_WARNINGS=1

Suppress warnings in code:

from kicomav.kavcore.config import suppress_warnings
suppress_warnings(True)

import kicomav  # No warnings will be shown

Advanced: Direct Engine Access

import kicomav

# For advanced use cases, access the engine directly
engine = kicomav.Engine(verbose=True)
engine.set_plugins("/path/to/plugins")

instance = engine.create_instance()
instance.init()

# Get engine information
info = instance.getinfo()
for plugin_info in info:
    print(f"Plugin: {plugin_info.get('title')}")

# Scan a single file
def on_detect(result, filename, malware_name, malware_id):
    print(f"Detected: {malware_name} in {filename}")

instance.scan("/path/to/file.exe", on_detect)

instance.uninit()

License

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

Author

Kei Choi

• http://www.hanul93.com
• http://twitter.com/hanul93
• http://facebook.com/hanul93
• http://github.com/hanul93