kicomav - KicomAV is an open source antivirus engine designe

项目说明

<img src="

KicomAV v0.41

!Platform
!Platform
!Platform<br>
!Language
![PyPI Downloads]()<br>
![Sponsor]()

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 KicomA a sustainable sponsorship level, kicomav-x will be opened as part of the project.

Features

Table of Contents

Requirements

Daemon mode dependencies (k2d, k2c):

Optional dependencies:

Installation

Via pip (Recommended)

From source

With daemon support

Configuration

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

Windows:

Linux/macOS:

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

| | 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/kicoma or C:\kicoma |
| USER_RULES_BASE | User rules path | /home/user/kicoma or C:\kicoma |

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

Components

KicomA 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 O

---

Command-Line Usage (k2)

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 |
| - | 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 | Mo 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:

Scan current directory:

Scan with archi:

Parallel scanning with 8 workers:

Scan and disinfect:

---

Ad Features

Exclusion Rules

KicomA 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=.kicoma |

Size units: B, KB, MB, GB

#### Examples

#### Ignore File Format (.kicoma)

Create a .kicoma file (similar to .gitignore):

Ignore file search order:
1. Current directory
2. Parent directories (up to root)
3. ~/.kicoma

#### 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

---

Scan Cache

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

#### How It Works

#### Cache Architecture

KicomAV uses a sophisticated dual-cache system:

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

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

#### Archi Features

#### Command-Line Options

| Option | Description | Default |
|--------|-------------|---------|
| --cache | Enable scan cache | Enabled |
| --no-cache | Disable scan cache | - |
| --cache-clear | Clear all cache entries | - |
| --cache-stats | Show cache statistics | - |
| --cache-expire=DAYS | Set expiration (0=never) | 7 |

#### Examples

#### Cache Statistics Output

#### Cache In

The cache automatically in when:

1. File modified: File size or modification time changed
2. Signature updated: Signature differs from cached
3. Cache expired: Entry older than expiration period
4. File deleted: Entry remo maintenance
5. Scan mode changed: Archi with different -r option (archi only)
6. Contents changed: Archi file list differs (archi only)

#### Performance Impact

Example scan times with caching enabled:

| Scan | Option | Time | Notes |
|------|--------|------|-------|
| First | -r -I | ~40s | Full scan, cache populated |
| Second | -r -I | ~2s | Cache hit |
| Third | -I | ~18s | Different mode, separate cache |
| Fourth | -I | ~0s | Cache hit |
| Fifth | -r -I | ~2s | Returns to cached -r results |

This ensures:

#### Library Usage

---

Parallel Scanning

Enable multi-threaded scanning for impro on multi-core systems.

---

Library Usage

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

Basic Scanning

Directory Scanning

Updating Signatures

Configuration Access

Suppress Warnings

Archi

KicomA high-level APIs for exploring and extracting archives.

Supported Formats: ZIP, RAR, 7z, CAB, ALZ, EGG, TAR, GZ, BZ2, APK, OneNote, PyInstaller (PE/ELF)

Exception Handling:

Ad: Direct Engine Access

---

Daemon Mode (k2d & k2c)

KicomAV can run as a daemon server, pro both REST API and clamd-compatible socket protocol.

Server (k2d)

#### Ser

| | Default | Description |
|----------|---------|-------------|
| K2D_HTTP_HOST | 127.0.0.1 | HTTP bind address |
| K2D_HTTP_PORT | 8311 | HTTP port |
| K2D_SOCKET_PORT | 3311 | Socket port |
| K2D_MAX_UPLOAD_SIZE | 52428800 | Max upload size (50MB) |
| K2D_MAX_WORKERS | CPU count | Max concurrent workers |
| K2D_API_KEY | - | API key for authentication |
| K2D_REQUIRE_AUTH | false | Require authentication |

Client (k2c)

k2c is a command-line client for communicating with the k2d daemon.

#### Example

REST API

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /ping | Health check |
| GET | / | and signature info |
| GET | /stats | Scan statistics |
| POST | /scan/file | Scan uploaded file |
| POST | /scan/path | Scan local path |
| POST | /scan/stream | Scan base64 encoded data |
| POST | /reload | Reload signatures |

Examples:

Socket Protocol (clamd-compatible)

| Command | Description |
|---------|-------------|
| PING | Health check (returns PONG) |
| | Get info |
| STATS | Get statistics |
| SCAN <path> | Scan a file |
| CONTSCAN <path> | Scan directory recursively |
| INSTREAM | Scan streamed data |
| RELOAD | Reload signatures |

Example (Python):

---

License

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

Author

Kei Choi

项目信息

开发语言：Python

Star 数：380

技术要点

该项目属于病毒分析方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕KicomAV is an open source antivirus engine designed for detecting malware and disinfecting it. 展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。