Quipu

Un ambiente di lavoro desktop per scrivere, validare, compilare e testare regole YARA.

Quipu (pronunciato “KEE-poo”) riunisce un esploratore di progetti, un editor consapevole di YARA, il compilatore YARA-X e risultati di scansione mirati in un'unica applicazione locale. Integra sia YARA-X sia il suo language server, quindi non è necessaria un'installazione separata di YARA.

[!IMPORTANT] Quipu è in fase MVP. La piattaforma inizialmente supportata è Linux a 64 bit; il supporto per Windows e macOS seguirà.

Funzionalità

• Apri una cartella di file .yar e .yara come workspace, oppure inizia con una regola scratch.
• Esplora entrypoint inferiti o configurati, include annidati, include esterni e problemi del progetto.
• Modifica con evidenziazione della sintassi di Monaco, completamento, documentazione al passaggio del mouse e diagnostica YARA-X in tempo reale.
• Compila un workspace completo, poi scansiona testo digitato o un file selezionato.
• Ispeziona regole corrispondenti, pattern, offset, lunghezze in byte e byte evidenziati in un visualizzatore esadecimale.
• Salta dalla diagnostica e dalle corrispondenze direttamente alle loro definizioni nel sorgente.
• Ripristina set di regole compilati e invariati da una cache locale a dimensione limitata.
• Lavora da una serie di piccoli progetti di esempio autonomi inclusi con l'applicazione.

Le regole e i target di scansione vengono elaborati localmente. Quipu non invia i loro contenuti a un servizio remoto.

Installazione su Linux

I pacchetti Linux x86-64 sono pubblicati nella pagina GitHub Releases:

Pacchetto	Ideale per	Installazione o esecuzione
AppImage	Uso portatile su distribuzioni supportate	chmod +x Quipu_*.AppImage && ./Quipu_*.AppImage
.deb	Ubuntu 22.04+ e Debian 12+	sudo apt install ./Quipu_*.deb
.rpm	Versioni recenti di Fedora	sudo dnf install ./Quipu-*.rpm

I pacchetti .deb e .rpm utilizzano il runtime WebKitGTK di sistema. Se la tua distribuzione non riesce a soddisfare quella dipendenza, usa l'AppImage.

I pacchetti Quipu al momento non sono firmati. Ogni release include un file SHA256SUMS; scaricalo insieme ai pacchetti e verifica i file scaricati con:

sha256sum --ignore-missing --check SHA256SUMS

I checksum rilevano corruzioni accidentali ma non sono una firma autenticata.

Avvio rapido

1. Avvia Quipu e scegli File → Open Example… → Basic text match.
2. Esplora text_indicators.yar nell'editor.
3. Scegli Rules → Compile Workspace o premi Ctrl+Shift+B.
4. Scansiona il target preparato con Rules → Scan Target o premi Ctrl+Shift+Enter.
5. Espandi una corrispondenza e selezionala per ispezionare i byte evidenziati.

La guida completa è inclusa in Quipu sotto Help → Documentation. Il suo sorgente è disponibile anche in documentation/content.

Workspace e quipu.toml

Senza configurazione, Quipu scopre ricorsivamente i file di regole e inferisce un entrypoint da ogni file che non è incluso da un altro file. Aggiungi un quipu.toml nella radice del workspace quando hai bisogno di entrypoint espliciti, directory di include o esclusioni:

schema = 1
entrypoints = ["main.yar"]
include_dirs = ["rules", "../shared-rules"]
exclude = ["fixtures/**", "vendor/legacy/**"]

Vedi Workspaces and projects per il modello di progetto completo e il riferimento del manifest.

Compilazione dal sorgente

Quipu attualmente è destinato a Linux x86-64. Una build richiede:

• Rust 1.93 o successivo
• Node.js 22.6 o successivo
• Zola 0.23
• Git
• le librerie native richieste da Tauri e WebKitGTK

Su Debian o Ubuntu, installa le dipendenze native con:

sudo apt update
sudo apt install -y \
  build-essential \
  curl \
  file \
  libayatana-appindicator3-dev \
  libgtk-3-dev \
  librsvg2-dev \
  libssl-dev \
  libwebkit2gtk-4.1-dev \
  patchelf \
  rpm \
  wget

Poi compila tutti e tre i formati di pacchetto Linux:

git clone https://github.com/corelight/quipu.git
cd quipu/app
npm ci
npm run tauri -- build --bundles appimage,deb,rpm

Gli artefatti vengono scritti sotto app/src-tauri/target/release/bundle/. La prima build può richiedere un po' di tempo perché Cargo compila YARA-X e le sue dipendenze dal sorgente.

Sviluppo e test

Installa le dipendenze e avvia l'applicazione di sviluppo:

cd app
npm ci
npm run tauri -- dev

Esegui i test unitari del frontend, la build di produzione del frontend e i test Rust con:

cd app
npm test
npm run build

cd src-tauri
cargo test --locked

La suite di accettazione del menu nativo ha ulteriori requisiti per il display server Linux. Vedi test/README.md per la sua configurazione e il suo utilizzo.

Architettura

Quipu è un'applicazione Tauri con un frontend TypeScript vanilla e un backend Rust:

• Vite raggruppa il frontend e l'editor Monaco nella webview dell'applicazione.
• L'IPC di Tauri collega l'interfaccia utente ai servizi di workspace, filesystem, compilazione, cache e scansione in Rust.
• Il compilatore YARA-X e il language server vengono eseguiti in-process.
• Zola costruisce un sito di documentazione offline che è incorporato nell'app.

app/src/           TypeScript frontend
app/src-tauri/     Rust backend and desktop packaging
documentation/    Source for the bundled offline guide
examples/          Projects bundled with the application
test/ui/           Native-menu acceptance test harness

La versione dell'applicazione è definita in app/package.json; Tauri legge quel valore quando assegna i nomi ai pacchetti e riporta la versione in esecuzione.

Limitazioni attuali

• Inizialmente sono supportati solo i pacchetti Linux x86-64.
• Quipu scansiona un file selezionato o un buffer di testo alla volta, non directory o batch.
• Le nuove regole vengono create nella radice del workspace. Le operazioni di spostamento ed eliminazione vengono eseguite al di fuori di Quipu.
• Una regola scratch può essere compilata e scansionata, ma non salvata o messa in cache.

Contributi e sicurezza

I contributi sono benvenuti. Leggi CONTRIBUTING.md prima di aprire una pull request.

Non segnalare vulnerabilità di sicurezza in una issue pubblica. Segui il processo di segnalazione privata in SECURITY.md.

Riconoscimenti