rsac-labs/quantickleUn toolkit di grafici per la ricerca sulle minacce - e altre cose
Questo progetto è stato in gran parte generato tramite vibecoding, quindi prendi le dovute precauzioni. Il codice è stato revisionato da programmatori veri, ma non è stato indurito contro le vulnerabilità. Non esporlo all’esterno senza un’approfondita verifica di sicurezza.
Quantickle è un kit di strumenti interattivo, incentrato sul browser, per costruire ed esplorare grafi di rete. Il front-end (Cytoscape.js + interfaccia personalizzata) gestisce rendering, modifica ed esecuzione dei layout, mentre il server Express leggero serve l’interfaccia, funge da proxy per le chiamate di integrazione e, opzionalmente, salva i grafi in Neo4j. In altre parole, il browser possiede lo stato del grafo e la visualizzazione, mentre il server esiste per fornire risorse e integrazioni quando necessario.
bezier), dritte, bundle (unbundled-bezier), taxi e taxi arrotondato.haystack e segments tramite stili personalizzati.Ecco alcuni esempi di ciò che Quantickle può fare:
Quantickle si basa su un piccolo insieme di concetti condivisi che collegano la documentazione:
Sistema di coordinate e layout spaziali — I layout assoluti e basati sulla profondità di Quantickle utilizzano un cubo 0–1000 per le coordinate x, y e z. Vedi COORDINATE_SYSTEM.md per tutte le regole spaziali e il comportamento dell’illuminazione.
Gestione dei file grafo e file di progetto — I file .qut sono lo stato salvato canonico; memorizzano nodi, archi, metadati e la gerarchia dei contenitori.
Integrazione Neo4j — il server può persistere e recuperare grafi da Neo4j, comprese istantanee di metadati. Vedi NEO4J_INTEGRATION_README.md per configurazione e dettagli sul flusso di lavoro.
Un grafo Quantickle è un insieme di nodi e archi con metadati che guidano il layout, lo stile e il raggruppamento.
metadata, array di nodi, array di archi e stato opzionale del layout o della vista.id obbligatorio più attributi opzionali come , , , e coordinate. I nodi possono includere anche in Markdown o proprietà personalizzate utilizzate dalle integrazioni.labeltypesizecolorinfosource + target e attributi opzionali come label, type, weight e metadati di stile.Il JSON interno del grafo di Quantickle è una struttura appiattita con array nodes ed edges. Le relazioni di contenitore e le classi vengono preservate come metadati dei nodi.
Quantickle accetta diversi formati di importazione tramite File → Importa dati e tramite integrazioni automatiche. Ogni importatore alimenta la stessa pipeline del grafo utilizzata quando si salvano file di progetto .qut, quindi le strutture seguenti rappresentano anche le forme di esportazione.
L’importatore CSV riconosce due layout:
Sezioni nodi + archi – formato di esportazione utilizzato da Quantickle e opzione più sicura quando si preparano dati manualmente. Il file contiene una tabella di nodi seguita da una riga vuota e una tabella di archi: ```csv node_id,node_label,node_type,node_size,node_color,node_x,node_y srv-1,Gateway,server,40,#2dd4bf,100,250 cli-1,Analyst,client,28,#38bdf8,320,210
source,target,label,weight,type srv-1,cli-1,allows,1,connection
Additional columns are tolerated—the importer normalises headers such as
Node Label, nodeLabel, or label, preserves any explicit color/size
values, and keeps coordinates when provided.
source and target columns. Optional columns such as label, type,
weight, source_type, target_type, source_label, or color are merged
into the generated nodes and edges when present: ```csv
source,target,label,source_type,target_type
srv-1,cli-1,allows,server,client
srv-1,sensor-2,monitors,server,sensor
Quantickle analizza le intestazioni senza distinzione tra maiuscole e minuscole, accetta sia snake_case che nomi con spazi, e salta automaticamente le righe vuote.
.edges)Coppie di archi separate da semplici spazi bianchi sono supportate per creare rapidamente grafici scheletro. I nodi mancanti vengono creati automaticamente:
a b
b c
c a
``````text
srv-1 cli-1
srv-1 sensor-2
Nota: I workbook Excel (
.xlsx) non sono più supportati. Esporta o salva i dati come CSV prima di importarli in Quantickle.
File → Import Data accetta anche esportazioni JSON prodotte da Quantickle o raccolte
di elementi Cytoscape grezze. Quando il file contiene elements con voci data annidate,
vengono normalizzate nella struttura interna di Quantickle.
.qut)I file .qut sono documenti JSON con oggetti nodo e arco appiattiti. Un grafico minimo
ha il seguente aspetto:```json
{
"metadata": { "name": "My graph" },
"nodes": [
{ "id": "srv-1", "label": "Gateway", "type": "server", "size": 40 }
],
"edges": [
{ "id": "srv-1_cli-1", "source": "srv-1", "target": "cli-1", "label": "allows" }
]
}
I file legacy che memorizzano nodi/archi all'interno di un oggetto `data` sono ancora accettati—il
loader li appiattisce automaticamente e preserva le coordinate, le classi e
i metadati della gerarchia dei contenitori.
#### API payloads
Quando si scambiano dati con l'API HTTP o l'integrazione Neo4j, invia la stessa
struttura appiattita utilizzata dai file `.qut`:```json
{
"nodes": [
{ "id": "srv-1", "label": "Gateway", "type": "server", "size": 40 }
],
"edges": [
{ "id": "srv-1_cli-1", "source": "srv-1", "target": "cli-1", "label": "allows" }
]
}
Il campo opzionale info supporta ancora Markdown e viene conservato insieme a qualsiasi proprietà personalizzata.
Quantickle raggruppa i layout in famiglie pratiche in modo da poter scegliere quello giusto per il compito:
// js/layouts.js const layoutOptions = { 'force': { name: 'force', animate: true, randomize: false, infinite: false }, 'grid': { name: 'grid', rows: undefined, cols: undefined } // ... more layouts }
### Layout Timeline
Il layout personalizzato `timeline` posiziona i nodi lungo un asse temporale. Puoi personalizzare la barra centrale tramite l'opzione `barStyle`:```javascript
cy.layout({
name: 'timeline',
barStyle: {
color: '#3498db', // bar color
height: 15, // bar height in pixels
className: 'my-timeline-bar' // optional CSS class
}
}).run();
Quando viene fornito className, la barra della timeline riceve quella classe e il suo stile predefinito di colore e altezza vengono rimossi in modo da poterla targetizzare tramite CSS.
Usa radial-recency per tracciare gli elementi più recenti vicino al centro e quelli più vecchi sugli anelli esterni. Il layout mappa l'angolo su un attributo secondario (tipo/cluster/gruppo) in modo che i nodi correlati rimangano allineati attorno al cerchio. Puoi regolare gli anelli con alcune opzioni:```javascript
cy.layout({
name: 'radial-recency',
ringThickness: 140, // radial spacing between time rings
minSeparation: 80, // minimum distance between neighbors along a ring
angleJitter: 0.15, // optional jitter (radians) to break perfect symmetry
angleStrategy: 'grouped' // or 'alphabetical' for deterministic ordering
}).run();
Vedi `graphs/radial_time_rings.qut` per un piccolo fixture che dimostra fasce temporali concentriche raggruppate per metadati di cluster/tipo.
### Layout Scatter della Timeline
Usa il layout `timeline-scatter` per mappare i timestamp direttamente alle posizioni x mentre distribuisci i nodi verticalmente per similarità, categoria o comunità. Accetta scale regolabili per entrambi gli assi e un jitter opzionale per ridurre la sovrapposizione:```javascript
cy.layout({
name: 'timeline-scatter',
xScale: 0.5, // pixels per millisecond (auto-calculated when omitted)
yScale: 60, // spread for similarity/category lanes
jitter: 4, // optional per-node jitter to minimise overlap
barStyle: { // applied when timeline bars already exist
color: '#222',
height: 12,
className: 'scatter-bar'
}
}).run();
Usa la distanza del timestamp per orientare le forze delle molle mantenendo leggera la repulsione:```javascript cy.layout({ name: 'temporal-attraction', timeMode: 'gaussian', // or 'bucket' timeSigma: 60 * 60 * 1000, // Gaussian falloff window (in ms) bucketSize: 24 * 60 * 60 * 1000, // bucket size when using bucket mode repulsionStrength: 12 // minimal node repulsion }).run();
Seleziona **Layout → Temporal Attraction - Time Weighted** nell'interfaccia utente o passa `name: 'temporal-attraction'` attraverso la configurazione del layout CLI/API per abilitarlo.
<a id="integrations"></a>
## Integrazioni
Quantickle può recuperare dati da o sincronizzare con sistemi esterni. Le integrazioni generalmente passano attraverso il server perché richiedono credenziali, regole proxy o persistenza.
- **Neo4j** — memorizza e interroga snapshot di grafi; vedere [NEO4J_INTEGRATION_README.md](https://github.com/rsac-labs/quantickle/blob/HEAD/NEO4J_INTEGRATION_README.md).
- **SerpAPI** — utilizzato dalla pipeline RAG per la ricerca web; vedere [API keys](#api-keys).
- **VirusTotal** — arricchisce i nodi con intelligence su domini/IP/file/URL e grafi di relazioni.
- **CIRCL-LU (MISP OSINT feed)** — importa eventi MISP curati dal feed CIRCL-LU.
- **OPML RSS watcher** — importa elenchi di feed OPML e trasforma gli articoli corrispondenti in grafi.
<a id="workflows"></a>
## Flussi di lavoro
### 🧭 Primi passi nell'app
- Avvia l'interfaccia utente nel tuo browser all'indirizzo `http://localhost:3000`.
- Usa **File → Set workspace** per scegliere dove risiedono i file del progetto.
- Importa dataset tramite **File → Import Data**, incolla dati dagli appunti o posiziona manualmente i nodi usando il menu contestuale.
- Passa tra le viste Grafo, Definizioni dei tipi e Tabella dati secondo necessità.
- Apri l'editor dei nodi tramite **Tools → Node Editor** per modifiche dettagliate.
- Per impostare i valori predefiniti del grafo, usa **Tools → Graph Area Editor**.
Per tutorial più approfonditi e screenshot, consulta la [Guida all'uso](https://github.com/rsac-labs/quantickle/blob/HEAD/USAGE_GUIDE.md).
### Esportazione e condivisione
- Salva in `.qut` per un'istantanea del progetto ad alta fedeltà (layout, metadati, contenitori).
- Esporta CSV per l'interoperabilità con strumenti per fogli di calcolo o pipeline di grafi.
- Esporta HTML statico, PNG o PDF per output pronti per report.
### Inizializzazione
Quantickle si inizializza tramite il globale `window.QuantickleApp` definito in [`js/main.js`](https://github.com/rsac-labs/quantickle/blob/HEAD/js/main.js). L'applicazione chiama automaticamente `window.QuantickleApp.init()` quando il DOM è pronto.
<a id="configuration"></a>
## Configurazione
### Impostazioni delle prestazioni```javascript
// js/config.js
const config = {
performance: {
nodeLimit: 1000, // Max nodes to render at once
batchSize: 100, // Nodes to add per batch
webgl: true, // Enable WebGL rendering
hideEdgesOnViewport: false // Hide edges while dragging
}
}
Il server Express (server.js) serve il front-end statico ed espone diversi endpoint JSON utilizzati dall'interfaccia utente. Tutte le route sono prefissate con /api:
| Method & Path | Description |
|---|---|
GET /api/domain-files | Elenca le definizioni di dominio JSON presenti in assets/domains/. |
GET /api/examples | Restituisce i metadati sugli esempi di grafici .qut inclusi nel bundle. |
GET /api/serpapi | Funge da proxy per le richieste di Google Search verso SerpApi; richiede SERPAPI_API_KEY nella stringa di query o nell'ambiente. |
GET /api/openai/models | Funge da proxy per le richieste di elenco modelli di OpenAI verso api.openai.com; richiede un header Authorization: Bearer .... |
GET /api/proxy?url=… | Inoltra le richieste HTTP/HTTPS a host consentiti con header simili a quelli del browser. |
POST /api/neo4j/graph | Persiste un grafico su Neo4j. Accetta il corpo JSON del grafico Quantickle appiattito descritto sopra. |
POST /api/neo4j/node-graphs | Trova i grafici salvati che contengono nodi corrispondenti all'array labels fornito. |
GET /api/neo4j/graphs | Elenca i grafici memorizzati in Neo4j insieme ai metadati di riepilogo. |
GET /api/neo4j/graph/:name | Recupera un grafico salvato, restituendo metadata, nodes e edges. |
DELETE /api/neo4j/graph/:name | Rimuove un grafico memorizzato da Neo4j. |
Tutti gli endpoint Neo4j accettano credenziali tramite gli header X-Neo4j-Url, X-Neo4j-Username e X-Neo4j-Password (oppure le variabili d'ambiente NEO4J_URL, NEO4J_USER e NEO4J_PASSWORD sul server). Quando fornito, l'oggetto metadata viene salvato insieme al grafico e un timestamp savedAt viene aggiunto automaticamente.
Alcune funzionalità richiedono chiavi API. Queste sono memorizzate nell'archiviazione locale del browser tramite il pannello Integrazioni.
Per l'uso da riga di comando, puoi alternativamente impostare SERPAPI_API_KEY nell'ambiente.
Il server espone un proxy che bypassa CORS e inoltra le richieste HTTP(S) agli host elencati nella lista consentita del proxy. Usa /api/proxy con un parametro URL:```
curl "http://localhost:3000/api/proxy?url=https%3A%2F%2Fopentip.kaspersky.com%2F"
The base allowlist lives in `config/proxy-allowlist.json`. You **must** provide this file (or set a comma-separated `PROXY_ALLOWLIST` environment variable before starting the server); otherwise the proxy logs a fatal configuration error and rejects every request with HTTP 403.
Integration-specific hosts (for backend integration adapters like OpenAI and VirusTotal) are governed by `config/integration-allowlist.json` (or `INTEGRATION_ALLOWLIST`). At runtime, both allowlists are merged. Each entry should list a host or wildcard pattern that the proxy may reach. Wildcards using `*` are supported anywhere in an entry, so `*.example.com` permits any subdomain of `example.com`, and masks like `news-*` behave as expected. Subdomains also inherit their parent domain's entry, so adding `example.com` automatically permits `www.example.com`.
A minimal allowlist file looks like:```json
{
"allowlist": ["otx.alienvault.com", "feeds.example.org"]
}
Se preferisci le variabili d'ambiente, imposta PROXY_ALLOWLIST="otx.alienvault.com,feeds.example.org" prima di avviare il server.
Quando il proxy inoltra una richiesta, ora invia un set di intestazioni simili a un browser (incluse le moderne User-Agent, Accept, Accept-Language e i valori Sec-Fetch-* di Chrome) in modo che i siti che filtrano il contenuto dietro barriere anti-bot rispondano allo stesso modo di un normale caricamento della pagina. Qualsiasi di queste intestazioni può essere sovrascritta fornendo override x-proxy-<header> dalla richiesta del client quando necessario.
Quantickle mantiene lo stato del grafo nel browser mentre lavori, poi lo persiste quando esporti o sincronizzi.
.qut) — salvati nella cartella del workspace per snapshot del grafo ad alta fedeltà. Vedi GRAPH_FILE_MANAGEMENT_README.md per le regole del workspace e il ciclo di vita dei file.quantickle/
├── assets/ # Static assets
│ ├── backgrounds/ # Background graphics
│ ├── icons/ # Mostly empty now; icons are colocated with node types
│ ├── domains/ # Node type definitions
│ ├── help/ # Help pages
│ ├── examples/ # Example graphs
│ └── css/ # Stylesheets referenced by index.html
├── config/ # Proxy allowlist
├── data_retrieval/ # SerpAPI/web search helpers used by the RAG pipeline
├── graphs/ # Workspace folder for bundled and test .qut graphs
├── js/ # Front-end source modules
│ ├── main.js # Application bootstrap
│ ├── ai-input-manager.js # Currently unused
│ ├── api.js # HTTP client for server endpoints
│ ├── graph.js # Graph rendering and management
│ ├── graph-manager.js # High-level graph state orchestration
│ ├── graph-reference-resolver.js # Normalization of graph references
│ ├── layouts.js # Layout registration and options
│ ├── 3d-globe-layout.js # 3D Layout
│ ├── absolute-layout.js # Absolute coordinate layout
│ ├── custom-layouts.js # Other custom layouts
│ ├── aggressive-performance-fix.js # Aggressive Performance Fix for Large Graph Panning
│ ├── non-invasive-performance-fix.js # Non-Invasive Performance Fix for Large Graphs
│ ├── lod-system.js # Level of Detail (LOD) System
│ ├── auto-refresh.js # Auto-refresh functionality when new data arrives
│ ├── config.js # Default settings
│ ├── domain-loader.js # Loading and managing domain-specific node type configurations
│ ├── edge-editor.js # Editing edge styles
│ ├── extensions.js # Loading and registration of Cytoscape extensions
│ ├── integrations.js # Configuration and connection to external services
│ ├── rag-pipeline.js # Handles AI-assisted data ingestion
│ ├── secure-storage.js # Encrypts sensitive values in sessionStorage
│ ├── source-editor.js # Editor for the JSON graph source
│ ├── tables.js # Data table updates, filtering, and display
│ ├── ui.js # User interface interactions and notifications
│ ├── validation.js # Validation of all data inputs
│ ├── workspace-manager.js # Workspace file functionality
│ ├── utils.js # Shared browser utilities
│ ├── integrations/ # Integration-specific helpers (MISP/CIRCL-LU, etc.)
│ └── features/ # Feature modules (node editor, callouts, timeline, ...)
├── tests/ # Automated regression tests covering UI flows, imports, and APIs
├── utils/ # Node helpers (Neo4j client, readability shim, CLI scripts)
├── public/
│ ├── index.html # Static front-end
│ └── favicon.ico # Main app icon
├── package.json # Node dependencies and scripts
└── server.js # Express server exposing the HTTP API
<a id="troubleshooting"></a>
## 🐛 Risoluzione dei problemi
### Problemi comuni
1. **Il grafico non viene visualizzato**
- Controlla la console del browser per errori
- Verifica il formato dei dati
- Controlla il supporto WebGL
2. **Scarse prestazioni**
- Riduci il limite di nodi nella configurazione
- Abilita il rendering WebGL
- Usa layout più semplici per grafici di grandi dimensioni
3. **Problemi di layout**
- Prova diversi algoritmi di layout
- Regola i parametri del layout
- Verifica la presenza di nodi disconnessi
## 🤝 Contribuire
Questo progetto non è mantenuto attivamente come repository canonico. Le pull request verranno probabilmente ignorate. Tuttavia, feedback, segnalazioni di bug e commenti sono benvenuti.
## 📄 Licenza
Questo progetto è concesso in licenza secondo la Licenza Apache 2.0 - consulta il file LICENSE per i dettagli.
## 🙏 Ringraziamenti
- Realizzato con [Cytoscape.js](https://js.cytoscape.org/)
- Algoritmi di layout da vari contributori di Cytoscape
- Ottimizzazioni delle prestazioni ispirate dalla ricerca sulla visualizzazione di grafici su larga scala
<a id="additional-documentation"></a>
## 📚 Documentazione aggiuntiva
- [Guida all'uso](https://github.com/rsac-labs/quantickle/blob/HEAD/USAGE_GUIDE.md)
- [Gestione dei file di grafico](https://github.com/rsac-labs/quantickle/blob/HEAD/GRAPH_FILE_MANAGEMENT_README.md)
- [Integrazione con Neo4j](https://github.com/rsac-labs/quantickle/blob/HEAD/NEO4J_INTEGRATION_README.md)
- [Sistema di coordinate](https://github.com/rsac-labs/quantickle/blob/HEAD/COORDINATE_SYSTEM.md)
- [Guida alle prestazioni](https://github.com/rsac-labs/quantickle/blob/HEAD/PERFORMANCE.md)