Install - Usage - Dynamic Analysis - YARA Rules - CI/CD

Docs: English | Tiếng Việt

Static and dynamic analysis tool for detecting malicious code, suspicious binaries, and privacy violations. Analyzes source code, compiled executables (.exe, .dll, .elf), macOS bundles (.app, .dmg, .pkg), mobile apps (.apk, .ipa), and application packages with YARA rules, Docker behavioral sandboxing, MobSF mobile analysis, payload deobfuscation, and multi-format reporting (JSON, HTML, SARIF).

Features

Static Analysis

• Source Code Scanner - Detects reverse shells, backdoors, web shells, obfuscated payloads, crypto miners, ransomware patterns, keyloggers, credential theft, supply chain attacks, and persistence mechanisms across 15+ languages
• Binary Analyzer - PE (Windows), Mach-O (macOS), and ELF (Linux) analysis with entropy detection, import table inspection, string extraction, code signing verification, and RWX section detection
• AI File Type Detection - Optional Magika integration for content-based detection of extensionless or disguised files
• YARA Engine - Signature-based scanning with bundled rules for malware families, packers, and suspicious patterns. Supports custom rule directories
• Privacy Analyzer - Detects tracking SDKs, PII field handling, invasive permissions (Android/iOS manifests), device fingerprinting, clipboard monitoring, and unauthorized data transmission

Dynamic Analysis (Docker Sandbox)

• Runs suspicious binaries in an isolated Docker container with:
  • syscall tracing via strace (network, file, process calls)
  • network monitoring via tcpdump (DNS queries, HTTP requests, C2 connections)
  • filesystem monitoring (file creation, modification, deletion)
  • process monitoring (child process spawning, injection attempts)
• Full isolation: no network (default), memory limits, dropped capabilities, read-only rootfs
• Behavioral findings: C2 port detection, mass file modification (ransomware), sensitive file access, anti-debugging

Reporting

• Console - Rich terminal output with severity-colored tables and detailed findings
• JSON - Machine-readable findings for automation pipelines
• HTML - Professional dark-themed dashboard with severity bars, finding details, and evidence
• SARIF 2.1.0 - Direct integration with GitHub Code Scanning, Azure DevOps, and GitLab SAST

Coverage

Installation

Prerequisites

• Python 3.10+
• pip or pipx

Quick Install (pip)

pip install malware-check

Quick Install (pipx) - recommended for CLI usage

pipx install malware-check

From Source

git clone https://github.com/momenbasel/malware-check.git
cd malware-check
pip install -e ".[dev]"

This installs the core CLI. Binary analysis via pefile/lief, AI-powered file detection via magika, and YARA scanning via yara-python are optional extras.

Full Install (all analyzers)

# Core + binary analysis + AI file detection + YARA
pip install malware-check[full]

# Or install only what you need
pip install malware-check[binary]
pip install malware-check[detect]
pip install malware-check[yara]

# Or install extras manually
pip install pefile lief magika yara-python

AI File Type Detection (Magika)

pip install malware-check[detect]

When installed, malware-check uses Magika to improve cross-platform file identification, enrich file_type metadata, and route extensionless or disguised files to the correct analyzer based on content instead of filename alone.

Dynamic Analysis (Docker Sandbox)

# Requires Docker - https://docs.docker.com/get-docker/
# Build the sandbox image (one-time setup)
malware-check build-sandbox

Verify Installation

malware-check info

The info command will show whether Magika-powered file detection is available.

Claude Code (Skill)

Install as a Claude Code skill so Claude can analyze files for you:

# Install the skill from GitHub
npx skills install momenbasel/malware-check --skill malware-check

# Or manually: copy skill/SKILL.md to your skills directory
cp -r skill/ ~/.claude/skills/malware-check/

Then in Claude Code, say: "scan this file for malware" or "is this binary safe?" and Claude will use malware-check automatically.

You also need the CLI tool installed:

pip install malware-check pefile lief yara-python

Codex CLI

Install the tool and add to your Codex agent instructions:

# 1. Install the CLI
pip install malware-check pefile lief yara-python

# 2. Add to your Codex instructions (codex.md or system prompt)
echo 'Use `malware-check scan <path> --verbose` to analyze files for malware.' >> AGENTS.md

# 3. Or install as a Codex skill
cp -r skill/ .codex/skills/malware-check/

OpenAI Codex / Other AI Agents

For any AI coding agent that supports tool use or custom instructions:

# 1. Install
pip install malware-check

# 2. Add to agent instructions:
# "When asked to check code/binaries for malware, use: malware-check scan <target> --verbose"
# "For reports: malware-check scan <target> --format html -o report.html"
# "For CI/CD: malware-check scan <target> --format sarif -o report.sarif --exit-code"

Usage

Scan a file

malware-check scan suspicious_file.py

Scan an extensionless or renamed file

# Best results when malware-check[detect] is installed
malware-check scan suspicious_payload --verbose

Scan a directory

malware-check scan /path/to/project --verbose

Scan a binary with dynamic analysis

# Build sandbox first (one-time)
malware-check build-sandbox

# Scan with behavioral analysis
malware-check scan malware.exe --dynamic

Scan a macOS .app bundle

malware-check scan /Applications/SuspiciousApp.app --dynamic --verbose

Generate reports

# JSON report
malware-check scan target/ --format json -o report.json

# HTML dashboard
malware-check scan target/ --format html -o report.html

# SARIF for CI/CD
malware-check scan target/ --format sarif -o results.sarif

CI/CD integration

# Exit with non-zero code on findings (for CI gates)
malware-check scan . --format sarif -o results.sarif --exit-code

Check capabilities

malware-check info

GitHub Actions Integration

name: Security Scan
on: [push, pull_request]

jobs:
  malware-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install malware-check
        run: pip install malware-check

      - name: Run scan
        run: malware-check scan . --format sarif -o results.sarif --exit-code

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Architecture

malware-check/
├── src/malware_check/
│   ├── cli.py                 # Click CLI entry point
│   ├── scanner.py             # Orchestrator + optional Magika-based file detection
│   ├── models.py              # Finding, FileAnalysis, ScanResult data models
│   ├── analyzers/
│   │   ├── code.py            # Source code pattern matching (40+ rules)
│   │   ├── binary.py          # PE/Mach-O/ELF analysis
│   │   ├── privacy.py         # PII, tracking, permissions
│   │   ├── yara_engine.py     # YARA rule compilation and scanning
│   │   └── dynamic.py         # Docker sandbox behavioral analysis
│   └── reporters/
│       ├── console_reporter.py  # Rich terminal output
│       ├── json_reporter.py     # JSON export
│       ├── html_reporter.py     # HTML dashboard (Jinja2)
│       └── sarif_reporter.py    # SARIF 2.1.0 for CI/CD
├── rules/yara/                # Bundled YARA rules
├── tests/                     # pytest test suite
└── pyproject.toml             # Project metadata

Custom YARA Rules

Add custom rules to any directory and pass via --yara-rules:

malware-check scan target/ --yara-rules /path/to/my/rules/

Rules support metadata fields for severity, category, confidence, CWE, and MITRE ATT&CK mapping:

rule My_Custom_Rule {
    meta:
        description = "Detect custom malware pattern"
        severity = "critical"
        category = "backdoor"
        confidence = "0.90"
        mitre = "T1059"
        cwe = "CWE-94"
        recommendation = "Remove malicious code"

    strings:
        $pattern = "suspicious_string"

    condition:
        $pattern
}

Dynamic Analysis Details

The Docker sandbox provides behavioral analysis with full isolation:

Monitored behaviors:

• Syscalls (strace): network connections, file operations, process creation
• Network (tcpdump): DNS queries, TCP connections, protocol analysis
• Filesystem: new files, modifications, deletions with file type detection
• Processes: child spawning, fork/exec chains

MITRE ATT&CK Coverage

Contributing

# Clone and install dev dependencies
git clone https://github.com/momenbasel/malware-check.git
cd malware-check
pip install -e ".[dev]"

# Optional: include Magika, YARA, and binary extras while developing
pip install -e ".[dev,full]"

# Run tests
pytest

# Lint
ruff check src/ tests/

License

MIT License - see LICENSE for details.