SemanticsAV CLI

Free, Offline, AI-Native Malware Scanner for Linux

Detects evasive threats using structural logic instead of signatures. No network required for scanning.

Offline Detection • Cloud Intelligence • Privacy-by-Design

Quick Demo

What Is SemanticsAV?

SemanticsAV is an AI-native antivirus engine designed to solve the limitations of traditional signature-based detection. While legacy tools rely on static fingerprint matching—which is reactive and easily bypassed by packing—SemanticsAV analyzes the invariant structural patterns of the binary. This allows it to detect evasive and polymorphic threats based on their architectural intent, not just their hash.

Benchmark: SemanticsAV vs. ClamAV

We tested our engine against ClamAV on unseen future malware.
Read the full report on Hashnode

SemanticsAV provides analysis through three components:

Key Capabilities:

• Offline Scanner: Complete malware scanning without network dependency during analysis (Zero-Network Runtime).
• Constant Scan Speed: No performance degradation as threat coverage grows.
• Archive Inspection: Recursively scans nested archives (ZIP, TAR, RAR, etc.) for supported threats, with built-in protection against decompression bombs.
• Explainable Verdicts: Understand verdict reasoning with attack campaign identification and threat vector analysis.
• Privacy-First: SDK has zero network capability. All communication occurs through auditable open-source CLI.
• Free on Linux: Unlimited scanning for personal, commercial, and service provider use.

Quick Start

Installation

User Installation (recommended for personal use):

curl -sSL https://raw.githubusercontent.com/metaforensics-ai/semantics-av-cli/main/scripts/install.sh | bash -s -- --user

System Installation (for server/multi-user environments):

curl -sSL https://raw.githubusercontent.com/metaforensics-ai/semantics-av-cli/main/scripts/install.sh | bash -s -- --system

Initial Setup

# 1. Configure
semantics-av config init --defaults

# 2. Update detection models
semantics-av update

# 3. Start scanning
semantics-av scan /path/to/file

Optional: Enable Cloud Intelligence

# Get your API key from: https://console.semanticsav.ai

# Configure API key
semantics-av config set api_key "your-api-key-here"

# Analyze with full intelligence report
semantics-av analyze suspicious.exe --format html -o report.html

Supported File Formats

Currently Supported:

• PE (Portable Executable): Windows executables (.exe, .dll, .sys)
• ELF (Executable and Linkable Format): Linux/Unix executables and shared objects
• Archives: Compressed containers (ZIP, TAR, 7Z, RAR, etc.) automatically unpacked for recursive inspection.

Expanding Coverage:
Our immediate roadmap prioritizes Server-Side WebShells & Scripts (PHP, JSP, Bash, Python, Perl, etc.). Beyond this, we plan to support other exploitable file formats across various platforms, focusing on active attack vectors.

Architecture & Privacy

SemanticsAV operates in two modes: offline malware detection and optional cloud intelligence.

sequenceDiagram
    participant User
    participant CLI as CLI<br/>(Open Source)
    participant SDK as SDK<br/>(Engine)
    participant Cloud as Intelligence<br/>(Cloud API)
    
    rect rgb(240, 250, 240)
        Note right of User: Offline Detection<br/>(Free, No Network)
        User->>CLI: scan file.exe
        CLI->>SDK: Scan
        SDK-->>CLI: MALICIOUS (98.3%)
        CLI-->>User: Instant verdict
    end
    
    rect rgb(240, 245, 255)
        Note right of User: Cloud Intelligence<br/>(Requires API Key)
        User->>CLI: analyze file.exe
        CLI->>SDK: Extract Analysis Payload
        Note over SDK: Privacy guarantee:<br/>Encrypted payload only<br/>Original file never transmitted
        SDK-->>CLI: Encrypted analysis payload
        Note over CLI: Open-source transparency:<br/>Audit network communication
        CLI->>Cloud: POST /analyze
        Cloud-->>CLI: Intelligence report
        CLI-->>User: Context + Attribution
    end

Privacy-First Architecture:

The SemanticsAV SDK performs complete AI-based malware analysis locally without any network dependency. Your files never leave your system during scanning. When using the Intelligence API, only an encrypted, proprietary analysis payload is transmitted. The original file is never uploaded and cannot be reconstructed from the payload. All network communication occurs through the open-source CLI wrapper, enabling you to audit exactly what data is transmitted.

See PRIVACY_POLICY.md for complete data handling practices.

Installation Details

System Requirements

SemanticsAV SDK Binary Compatibility:

Verify your system compatibility:

# Check glibc version
ldd --version

# Check libstdc++ version
strings /usr/lib64/libstdc++.so.6 | grep GLIBCXX  # or /usr/lib/x86_64-linux-gnu/libstdc++.so.6

Manual Installation (From Source)

# Clone repository
git clone https://github.com/metaforensics-ai/semantics-av-cli.git
cd semantics-av-cli

# Build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

# System-wide installation (requires root)
sudo make install
sudo /usr/local/share/semantics-av/post_install.sh

# Or user-local installation (no root required)
cmake -DCMAKE_INSTALL_PREFIX=~/.local ..
make install
~/.local/share/semantics-av/post_install_user.sh
export PATH="$HOME/.local/bin:$PATH"

Usage Guide

Configuration

Quick setup:

semantics-av config init --defaults

View configuration:

semantics-av config show

Set specific values:

semantics-av config set log_level DEBUG
semantics-av config set scan.default_threads 8

Configuration locations:

• System mode: /etc/semantics-av/semantics-av.conf
• User mode: ~/.config/semantics-av/config.conf

API Key Configuration

Required for cloud analysis features. Obtain your API key from SemanticsAV Console.

semantics-av config set api_key "sav_your_api_key_here"

Model Management

# Download latest models
semantics-av update

# Check for updates without downloading
semantics-av update --check-only

# Force complete model re-download
semantics-av update --force

Scanning Files (Offline, Free)

Basic scanning:

# Scan single file
semantics-av scan /path/to/file.exe

# Recursive directory scan
semantics-av scan /path/to/directory -r -t 8

# Show only infected files
semantics-av scan /path/to/directory -r -i

# Include file hashes
semantics-av scan /path/to/file.exe -H

# JSON output
semantics-av scan /path/to/file.exe --json

Cloud Analysis (Requires API Key)

Generate forensic intelligence reports:

# Basic analysis
semantics-av analyze /path/to/suspicious.exe

# HTML report (opens in browser)
semantics-av analyze suspicious.exe --format html -o report.html

# Markdown report
semantics-av analyze suspicious.exe --format markdown -o report.md

# Multi-language support (en, ko, ja, zh, es, fr, de, it, pt, ru, ar)
semantics-av analyze suspicious.exe --language ko

# Skip natural language report generation
semantics-av analyze suspicious.exe --no-report

Report Management

# List all reports
semantics-av report list

# Filter by verdict/date/type
semantics-av report list --filter verdict:malicious
semantics-av report list --filter date:week

# Show specific report
semantics-av report show <report-id>

# Convert format
semantics-av report convert <report-id> --format html -o report.html

# Delete reports
semantics-av report delete <report-id>
semantics-av report delete --older-than 90

Advanced Features

Daemon Management

Start/stop daemon:

# System daemon
sudo systemctl start semantics-av
sudo systemctl stop semantics-av
sudo systemctl status semantics-av

# User daemon
systemctl --user start semantics-av
systemctl --user stop semantics-av
systemctl --user status semantics-av

HTTP API Integration

When daemon is running, REST API is available at http://127.0.0.1:9216 (configurable).

Scan file:

curl -X POST http://127.0.0.1:9216/api/v1/scan \
     -F "file=@suspicious.exe"

Response:

{
  "success": true,
  "data": {
    "result": "MALICIOUS",
    "confidence": 0.983,
    "file_type": "pe",
    "scan_time_ms": 127
  }
}

Additional endpoints:

• POST /api/v1/analyze: Cloud analysis
• POST /api/v1/models/update: Update models
• GET /api/v1/status: Daemon status
• GET /api/v1/health: Health check

Unix Socket Integration

For high-performance local integration:

• System: /var/run/semantics-av/semantics-av.sock
• User: ~/.local/state/semantics-av/semantics-av.sock

Binary protocol with zero-copy file descriptor passing. Specification in include/semantics_av/daemon/protocol.hpp.

Maintenance

Uninstallation

curl -sSL https://raw.githubusercontent.com/metaforensics-ai/semantics-av-cli/main/scripts/uninstall.sh | bash

The uninstaller automatically detects installation type and optionally removes configuration/data files.

License & Platform Support

Linux SDK: Free for Internal Use and Service Delivery

The SemanticsAV SDK for Linux is provided under a perpetual, royalty-free EULA. All commercial uses are permitted for internal business operations and service delivery. Public redistribution of SDK binaries is prohibited - users must obtain SDK from official sources.

Full details: EULA.md

Component Licensing

When You Need a Commercial License

Commercial licenses are available for:

• Cross-Platform Deployment: Windows, macOS, and other non-Linux platforms
• Customized Advanced Features: Tailored detection models and specialized deployments
• Commercial Intelligence Integration: Services that redistribute Intelligence analysis to customers
• Enterprise Support: Dedicated technical support, custom SLAs, professional services

Licensing inquiries: sales@metaforensics.ai

Contributing

Contributions welcome to MIT-licensed wrapper code:

• CLI commands and features
• Daemon optimizations and protocols
• Output formatters and report generators
• Build system and packaging improvements
• Documentation and examples

Not modifiable: SemanticsAV SDK (proprietary binary)

Process: Fork → Feature branch → Pull request

Support

Legal Documents:

• SDK EULA: EULA.md
• Intelligence ToS: INTELLIGENCE_TOS.md
• Privacy Policy: PRIVACY_POLICY.md
• Third-Party Licenses: ThirdPartyNotices.txt