Files

Azreen Jamal a3c6d09350 remove infra.md.example, infra.md is the source of truth

2026-03-03 03:06:13 +08:00

19 KiB

Raw Blame History

██████╗ ██╗   ██╗███╗   ██╗
██╔══██╗╚██╗ ██╔╝████╗  ██║
███████║ ╚████╔╝ ██╔██╗ ██║
██╔══██║  ╚██╔╝  ██║╚██╗██║
██║  ██║   ██║   ██║ ╚████║
╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═══╝
⚔️ AYN ANTIVIRUS v1.0.0 ⚔️
Server Protection Suite

AYN Antivirus

Comprehensive anti-virus, anti-malware, anti-spyware, and anti-cryptominer protection for Linux servers.

AYN Antivirus is a purpose-built security suite designed for server environments. It combines signature-based detection, YARA rules, heuristic analysis, and live system inspection to catch threats that traditional AV tools miss — from cryptominers draining your CPU to rootkits hiding in kernel modules.

Features

🛡️ Real-time file system monitoring — watches directories with inotify/FSEvents via watchdog, scans new and modified files instantly
🔍 Deep file scanning with multiple detection engines — parallel, multi-threaded scans across signature, YARA, and heuristic detectors
🧬 YARA rule support — load custom and community YARA rules for flexible pattern matching
📊 Heuristic analysis — Shannon entropy scoring, obfuscation detection, reverse-shell patterns, permission anomalies
⛏️ Cryptominer detection — process-level, network-level, and file-content analysis (stratum URLs, wallet addresses, pool domains)
🕵️ Spyware & keylogger detection — identifies keyloggers, screen/audio capture tools, data exfiltration, and shell-profile backdoors
🦠 Rootkit detection — hidden processes, hidden kernel modules, LD_PRELOAD hijacking, tampered logs, hidden network ports
🌐 Auto-updating threat signatures — pulls from abuse.ch feeds (MalwareBazaar, ThreatFox, URLhaus, Feodo Tracker) and Emerging Threats
🔒 Encrypted quarantine vault — isolates malicious files with Fernet (AES-128-CBC + HMAC-SHA256) encryption and JSON metadata
🔧 Auto-remediation & patching — kills rogue processes, fixes permissions, blocks IPs/domains, cleans cron jobs, restores system binaries
📝 Reports in Text, JSON, HTML — generate human-readable or machine-parseable reports from scan results
⏰ Scheduled scanning — built-in cron-style scheduler for unattended operation

Quick Start

# Install
pip install .

# Update threat signatures
sudo ayn-antivirus update

# Run a full scan
sudo ayn-antivirus scan

# Quick scan (high-risk dirs only)
sudo ayn-antivirus scan --quick

# Check protection status
ayn-antivirus status

Installation

From pip (local)

pip install .

Editable install (development)

pip install -e ".[dev]"

From source with Make

make install        # production
make dev-install    # development (includes pytest, black, ruff)

System dependencies

AYN uses yara-python for rule-based detection. On most systems pip handles this automatically, but you may need the YARA C library:

Distro	Command
Debian / Ubuntu	`sudo apt install yara libyara-dev`
RHEL / CentOS / Fedora	`sudo dnf install yara yara-devel`
Arch	`sudo pacman -S yara`
macOS (Homebrew)	`brew install yara`

After the system library is installed, pip install yara-python (or pip install .) will link against it.

Usage

All commands accept --verbose / -v for detailed output and --config <path> to load a custom YAML config file.

File System Scanning

# Full scan — all configured paths
sudo ayn-antivirus scan

# Quick scan — /tmp, /var/tmp, /dev/shm, crontabs
sudo ayn-antivirus scan --quick

# Deep scan — includes memory and hidden artifacts
sudo ayn-antivirus scan --deep

# Scan a single file
ayn-antivirus scan --file /tmp/suspicious.bin

# Targeted path with exclusions
sudo ayn-antivirus scan --path /home --exclude '*.log' --exclude '*.gz'

Process Scanning

# Scan running processes for miners & suspicious CPU usage
sudo ayn-antivirus scan-processes

Checks every running process against known miner names (xmrig, minerd, ethminer, etc.) and flags anything above the CPU threshold (default 80%).

Network Scanning

# Inspect active connections for mining pool traffic
sudo ayn-antivirus scan-network

Compares remote addresses against known mining pool domains and suspicious ports (3333, 4444, 5555, 14444, etc.).

Update Signatures

# Fetch latest threat intelligence from all feeds
sudo ayn-antivirus update

# Force re-download even if signatures are fresh
sudo ayn-antivirus update --force

Quarantine Management

# List quarantined items
ayn-antivirus quarantine list

# View details of a quarantined item
ayn-antivirus quarantine info 1

# Restore a quarantined file to its original location
sudo ayn-antivirus quarantine restore 1

# Permanently delete a quarantined item
ayn-antivirus quarantine delete 1

Real-Time Monitoring

# Watch configured paths in the foreground (Ctrl+C to stop)
sudo ayn-antivirus monitor

# Watch specific paths
sudo ayn-antivirus monitor --paths /var/www --paths /tmp

# Run as a background daemon
sudo ayn-antivirus monitor --daemon

Report Generation

# Plain text report to stdout
ayn-antivirus report

# JSON report to a file
ayn-antivirus report --format json --output /tmp/report.json

# HTML report
ayn-antivirus report --format html --output report.html

Auto-Fix / Remediation

# Preview all remediation actions (no changes)
sudo ayn-antivirus fix --all --dry-run

# Apply all remediations
sudo ayn-antivirus fix --all

# Fix a specific threat by ID
sudo ayn-antivirus fix --threat-id 3

Status Check

# View protection status at a glance
ayn-antivirus status

Displays signature freshness, last scan time, quarantine count, real-time monitor state, and engine toggles.

Configuration

# Show active configuration
ayn-antivirus config

# Set a config value (persisted to ~/.ayn-antivirus/config.yaml)
ayn-antivirus config --set auto_quarantine true
ayn-antivirus config --set scan_schedule '0 3 * * *'

Configuration

Config file locations

AYN loads configuration from the first file found (in order):

Priority	Path
1	Explicit `--config <path>` flag
2	`/etc/ayn-antivirus/config.yaml`
3	`~/.ayn-antivirus/config.yaml`

Config file options

# Directories to scan
scan_paths:
  - /
exclude_paths:
  - /proc
  - /sys
  - /dev
  - /run
  - /snap

# Storage
quarantine_path: /var/lib/ayn-antivirus/quarantine
db_path: /var/lib/ayn-antivirus/signatures.db
log_path: /var/log/ayn-antivirus/

# Behavior
auto_quarantine: false
scan_schedule: "0 2 * * *"
max_file_size: 104857600  # 100 MB

# Engines
enable_yara: true
enable_heuristics: true
enable_realtime_monitor: false

# API keys (optional)
api_keys:
  malwarebazaar: ""
  virustotal: ""

Environment variables

Environment variables override config file values. Copy .env.sample to .env and populate as needed.

Variable	Description	Default
`AYN_SCAN_PATH`	Comma-separated scan paths	`/`
`AYN_QUARANTINE_PATH`	Quarantine vault directory	`/var/lib/ayn-antivirus/quarantine`
`AYN_DB_PATH`	Signature database path	`/var/lib/ayn-antivirus/signatures.db`
`AYN_LOG_PATH`	Log directory	`/var/log/ayn-antivirus/`
`AYN_AUTO_QUARANTINE`	Auto-quarantine on detection (`true`/`false`)	`false`
`AYN_SCAN_SCHEDULE`	Cron expression for scheduled scans	`0 2 * * *`
`AYN_MAX_FILE_SIZE`	Max file size to scan (bytes)	`104857600`
`AYN_MALWAREBAZAAR_API_KEY`	MalwareBazaar API key	—
`AYN_VIRUSTOTAL_API_KEY`	VirusTotal API key	—

Threat Intelligence Feeds

AYN aggregates indicators from multiple open-source threat intelligence feeds:

Feed	Source	Data Type
MalwareBazaar	bazaar.abuse.ch	Malware sample hashes (SHA-256)
ThreatFox	threatfox.abuse.ch	IOCs — IPs, domains, URLs
URLhaus	urlhaus.abuse.ch	Malware distribution URLs
Feodo Tracker	feodotracker.abuse.ch	Botnet C2 IP addresses
Emerging Threats	rules.emergingthreats.net	Suricata / Snort IOCs
YARA Rules	Community & custom	Pattern-matching rules (`signatures/yara_rules/`)

Signatures are stored in a local SQLite database (signatures.db) with separate tables for hashes, IPs, domains, and URLs. Run ayn-antivirus update to pull the latest data.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          CLI (cli.py)                           │
│                     Click commands + Rich UI                    │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                    ┌───────────▼───────────┐
                    │    Core Scan Engine   │
                    │     (core/engine.py)  │
                    └───┬────┬────┬────┬───┘
                        │    │    │    │
          ┌─────────────┘    │    │    └─────────────┐
          ▼                  ▼    ▼                   ▼
 ┌─────────────────┐ ┌──────────────┐ ┌──────────────────────┐
 │    Detectors     │ │   Scanners   │ │    Monitor           │
 │ ┌─────────────┐ │ │ ┌──────────┐ │ │ ┌──────────────────┐ │
 │ │  Signature   │ │ │ │  File    │ │ │ │  Real-time       │ │
 │ │  YARA        │ │ │ │  Process │ │ │ │  (watchdog)      │ │
 │ │  Heuristic   │ │ │ │  Network │ │ │ └──────────────────┘ │
 │ │  Cryptominer │ │ │ │  Memory  │ │ └──────────────────────┘
 │ │  Spyware     │ │ │ └──────────┘ │
 │ │  Rootkit     │ │ └──────────────┘
 │ └─────────────┘ │
 └─────────────────┘
          │                              ┌──────────────────────┐
          │    ┌───────────────────┐     │     Signatures       │
          └───►│   Event Bus       │     │ ┌──────────────────┐ │
               │ (core/event_bus)  │     │ │  Feed Manager    │ │
               └──────┬────────────┘     │ │  Hash DB         │ │
                      │                  │ │  IOC DB          │ │
           ┌──────────┼──────────┐       │ │  YARA Rules      │ │
           ▼          ▼          ▼       │ └──────────────────┘ │
    ┌────────────┐ ┌────────┐ ┌───────┐  └──────────────────────┘
    │ Quarantine │ │Reports │ │Remedy │
    │   Vault    │ │  Gen.  │ │Patcher│
    │ (Fernet)   │ │txt/json│ │       │
    │            │ │  /html │ │       │
    └────────────┘ └────────┘ └───────┘

Module summary

Module	Path	Responsibility
CLI	`cli.py`	User-facing commands (Click + Rich)
Config	`config.py`	YAML & env-var configuration loader
Engine	`core/engine.py`	Orchestrates file/process/network scans
Event Bus	`core/event_bus.py`	Internal pub/sub for scan events
Scheduler	`core/scheduler.py`	Cron-based scheduled scans
Detectors	`detectors/`	Pluggable detection engines (signature, YARA, heuristic, cryptominer, spyware, rootkit)
Scanners	`scanners/`	File, process, network, and memory scanners
Monitor	`monitor/realtime.py`	Watchdog-based real-time file watcher
Quarantine	`quarantine/vault.py`	Fernet-encrypted file isolation vault
Remediation	`remediation/patcher.py`	Auto-fix engine (kill, block, clean, restore)
Reports	`reports/generator.py`	Text, JSON, and HTML report generation
Signatures	`signatures/`	Feed fetchers, hash DB, IOC DB, YARA rules

Auto-Patching Capabilities

The remediation engine (ayn-antivirus fix) can automatically apply the following fixes:

Action	Description
Fix permissions	Strips SUID, SGID, and world-writable bits from compromised files
Kill processes	Sends SIGKILL to confirmed malicious processes (miners, reverse shells)
Block IPs	Adds `iptables` DROP rules for C2 and mining pool IP addresses
Block domains	Redirects malicious domains to `127.0.0.1` via `/etc/hosts`
Clean cron jobs	Removes entries matching suspicious patterns (curl\|bash, xmrig, etc.)
Fix LD_PRELOAD	Clears `/etc/ld.so.preload` entries injected by rootkits
Clean SSH keys	Removes `command=` forced-command entries from `authorized_keys`
Remove startup entries	Strips malicious lines from init scripts, systemd units, and `rc.local`
Restore binaries	Reinstalls tampered system binaries via `apt`/`dnf`/`yum` package manager

Tip: Always run with --dry-run first to preview changes before applying.

Running as a Service

Create a systemd unit to run AYN as a persistent real-time monitor:

# /etc/systemd/system/ayn-antivirus.service
[Unit]
Description=AYN Antivirus Real-Time Monitor
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/ayn-antivirus monitor --daemon
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=10
User=root
Group=root

# Hardening
ProtectSystem=strict
ReadWritePaths=/var/lib/ayn-antivirus /var/log/ayn-antivirus
NoNewPrivileges=false
PrivateTmp=true

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable ayn-antivirus
sudo systemctl start ayn-antivirus

# Check status
sudo systemctl status ayn-antivirus

# View logs
sudo journalctl -u ayn-antivirus -f

Optionally add a timer unit for scheduled signature updates:

# /etc/systemd/system/ayn-antivirus-update.timer
[Unit]
Description=AYN Antivirus Signature Update Timer

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true

[Install]
WantedBy=timers.target

# /etc/systemd/system/ayn-antivirus-update.service
[Unit]
Description=AYN Antivirus Signature Update

[Service]
Type=oneshot
ExecStart=/usr/local/bin/ayn-antivirus update
User=root

sudo systemctl enable --now ayn-antivirus-update.timer

Development

Prerequisites

Python 3.9+
YARA C library (for yara-python)

Setup

git clone <repo-url>
cd ayn-antivirus
pip install -e ".[dev]"

Run tests

make test
# or directly:
pytest --cov=ayn_antivirus tests/

Lint & format

make lint
# or directly:
ruff check ayn_antivirus/
black --check ayn_antivirus/

Auto-format

black ayn_antivirus/

Project layout

ayn-antivirus/
├── ayn_antivirus/
│   ├── __init__.py          # Package version
│   ├── __main__.py          # python -m ayn_antivirus entry point
│   ├── cli.py               # Click CLI commands
│   ├── config.py            # Configuration loader
│   ├── constants.py         # Thresholds, paths, known indicators
│   ├── core/
│   │   ├── engine.py        # Scan engine orchestrator
│   │   ├── event_bus.py     # Internal event system
│   │   └── scheduler.py     # Cron-based scheduler
│   ├── detectors/
│   │   ├── base.py          # BaseDetector ABC + DetectionResult
│   │   ├── signature_detector.py
│   │   ├── yara_detector.py
│   │   ├── heuristic_detector.py
│   │   ├── cryptominer_detector.py
│   │   ├── spyware_detector.py
│   │   └── rootkit_detector.py
│   ├── scanners/
│   │   ├── file_scanner.py
│   │   ├── process_scanner.py
│   │   ├── network_scanner.py
│   │   └── memory_scanner.py
│   ├── monitor/
│   │   └── realtime.py      # Watchdog-based file watcher
│   ├── quarantine/
│   │   └── vault.py         # Fernet-encrypted quarantine
│   ├── remediation/
│   │   └── patcher.py       # Auto-fix engine
│   ├── reports/
│   │   └── generator.py     # Report output (text/json/html)
│   ├── signatures/
│   │   ├── manager.py       # Feed orchestrator
│   │   ├── db/              # Hash DB + IOC DB (SQLite)
│   │   ├── feeds/           # Feed fetchers (abuse.ch, ET, etc.)
│   │   └── yara_rules/      # .yar rule files
│   └── utils/
│       ├── helpers.py
│       └── logger.py
├── tests/                   # pytest test suite
├── pyproject.toml           # Build config & dependencies
├── Makefile                 # Dev shortcuts
├── .env.sample              # Environment variable template
└── README.md

Contributing

Fork the repo and create a feature branch
Write tests for new functionality
Ensure make lint and make test pass
Submit a pull request

License

This project is licensed under the MIT License. See LICENSE for details.

⚔️ Stay protected. Stay vigilant. ⚔️

19 KiB Raw Blame History

AYN Antivirus

Features

Quick Start

Installation

From pip (local)

Editable install (development)

From source with Make

System dependencies

Usage

File System Scanning

Process Scanning

Network Scanning

Update Signatures

Quarantine Management

Real-Time Monitoring

Report Generation

Auto-Fix / Remediation

Status Check

Configuration

Configuration

Config file locations

Config file options

Environment variables

Threat Intelligence Feeds

Architecture

Module summary

Auto-Patching Capabilities

Running as a Service

Development

Prerequisites

Setup

Run tests

Lint & format

Auto-format

Project layout

Contributing

License

19 KiB

Raw Blame History