Open Source · MIT

Costruisci sulla
piattaforma MinervaAI

MinervaAI aggrega feed di aviazione, traffico marittimo, sismologia, conflitti, cyber e OSINT su un’unica mappa renderizzata via GPU, ed espone ognuno di essi come semplice endpoint HTTP. È la stessa API su cui gira la dashboard: non esiste un livello interno separato e privilegiato.

57
Endpoint
20+
Feed live
0
Chiavi richieste
Guida

Panoramica

Ogni dato sulla mappa è renderizzato in WebGL tramite MapLibre GL: è questo che permette all’interfaccia di gestire migliaia di entità simultanee a 60fps. L’applicazione è un’app Next.js: la mappa e l’HUD girano nel browser, e ogni feed live viene normalizzato da una route sotto /api prima di arrivare al client.

Questo confine è voluto. Le sorgenti upstream differiscono per formati, rate limit e policy CORS, quindi il livello API assorbe queste differenze e restituisce JSON coerente.

Nessuna credenziale necessaria
Aviazione, traffico marittimo, satelliti, incendi, terremoti, meteo, notizie e dati CVE provengono tutti da feed pubblici senza chiave. Le chiavi servono solo per lo scanner RECON opzionale e per alzare i rate limit.
Guida

Guida rapida

Ogni endpoint di lettura è una semplice GET che restituisce JSON. Niente di quanto segue richiede autenticazione: puoi incollare tutto direttamente in un terminale.

curl -s https://minervaai-steel.vercel.app/api/flights | jq '.commercial_flights | length'

Se ti servono solo i numeri e non la geometria, /api/stats è l’endpoint giusto da interrogare periodicamente: riduce i feed pesanti a una manciata di contatori.

Contatori aggregati
curl -s https://minervaai-steel.vercel.app/api/stats
# { "stats": { "flights": 9241, "sats": 2043, "cctv": 2117,
#              "weather": 58, "nuclear": 191, "incidents": 412 },
#   "timestamp": "2026-07-29T12:00:00Z" }

Le lookup OSINT accettano ciascuna un solo soggetto, quindi si combinano facilmente in una pipeline:

Enumerazione passiva dei sottodomini
curl -s "https://minervaai-steel.vercel.app/api/osint/certs?domain=example.com" | jq -r '.subdomains[]'
Provalo prima di scrivere codice
Ogni endpoint GET nel riferimento qui sotto ha un pulsante Invia richiesta che lo esegue su questa istanza e mostra la risposta live.
Guida

Self-hosting

MinervaAI richiede Node 20+ e nessun database. Per un’istanza locale bastano tre comandi:

Sviluppo locale
git clone https://github.com/kurisuchanxxx/MinervaAI.git
cd osiris
npm install
npm run dev        # http://localhost:3000

Per una build di produzione, o per eseguire i controlli:

Build e test
npm run build && npm start
npm run lint
npm test           # vitest
npm run test:live  # includes tests that hit live upstream feeds

Nel repository sono inclusi un Dockerfile e un docker-compose.yml. All’interno il container resta sempre in ascolto sulla porta 3000; OSIRIS_PORT determina la porta dell’host su cui viene esposto.

Docker
cp .env.example .env
docker compose up -d
Guida

Configurazione

Copia .env.example in .env. Leggi quel file prima di compilare qualsiasi valore: la maggior parte delle chiavi elencate è riservata a sorgenti future e non viene usata dal codice attuale.

Lette dall’applicazione

SCANNER_URL / SCANNER_KEY
Punta al backend separato dello scanner RECON. SCANNER_KEY deve coincidere con OSIRIS_KEY di quel backend. Lasciale entrambe vuote per disattivare RECON: in quel caso /api/scanner restituisce 503, come previsto.
SDK_INGEST_KEY
Segreto condiviso per /api/sdk/ingest. L’endpoint è fail closed: finché non è impostata, l’ingest è disattivato e restituisce 503.
OSIRIS_TELEGRAM_CHANNELS
Nomi di canali Telegram pubblici separati da virgola (senza @) per il layer OSINT Telegram; sostituiscono il set predefinito.
OSIRIS_PORT
Porta dell’host su cui è esposta la UI. Il container resta sempre in ascolto sulla 3000.

Facoltative: solo per rate limit più alti

FIRMS_API_KEY, OPENSKY_CLIENT_ID, OPENSKY_CLIENT_SECRET, N2YO_API_KEY, AIS_API_KEY. Vengono usati i feed pubblici senza chiave, a meno che tu non modifichi il codice per preferire queste.

Gestione dei segreti
Genera i segreti con openssl rand -hex 32. Non fare mai commit di un .env compilato: nel version control va solo .env.example.
Guida

Guida all’interfaccia

La mappa occupa tutto il viewport e ogni controllo fluttua sopra di essa. I pannelli si attivano e disattivano invece di essere pagine a sé, così puoi comporre esattamente il quadro che ti serve e scartare il resto.

Pannello livelli
La barra a sinistra. Attiva e disattiva i singoli feed e contiene il selettore del tema.
Toolkit RECON
DNS, WHOIS, certificate transparency, arricchimento IP e ASN, verifica dei data breach, sanzioni, ricerca CVE, port scanning.
Feed intel
Un flusso continuo degli eventi in arrivo da tutti i feed attivi.
Dossier regionale
Clic destro sulla mappa per una sintesi composita di quel punto, da tutti i feed che lo coprono.
Grafo delle entità
Analisi dei collegamenti, espandendo un nodo alla volta nei suoi vicini.
Barra di stato
A sinistra i link alla community e alla documentazione, poi un ticker live di prezzi ed eventi sismici rilevanti.
Guida

Scorciatoie da tastiera

Premi ? in qualsiasi momento all’interno dell’applicazione per visualizzare questo elenco.

FAttiva/disattiva schermo intero
SCondividi vista corrente
LMostra/nascondi pannello livelli
MMostra/nascondi pannello mercati
IMostra/nascondi feed intel
RTorna alla vista globale
?Mostra l’aiuto
ESCChiudi pannelli / popup

In questa documentazione, ⌘K (o /) apre la ricerca da qualsiasi punto della pagina.

Riferimento API

Convenzioni

Tutte le route si trovano sotto /api, su qualunque origin serva l’applicazione. Le letture sono GET, le scritture sono POST con body JSON. Nessuna richiede autenticazione, tranne /api/sdk/ingest e /api/github-webhook.

Errori
In caso di errore viene restituito uno status non-2xx con una chiave `error`, spesso accompagnata da `detail` con il messaggio upstream. La maggior parte delle route fa da proxy verso terze parti, quindi considera normali i fallimenti upstream: controlla response.ok prima di leggere il body.
Caching
Ogni route imposta i propri TTL di Cache-Control: in genere 45–60s per i feed che cambiano rapidamente, fino a un giorno per i dati di riferimento statici. Un polling più frequente del TTL aggiunge solo carico. Quando una route indica refreshInterval, usalo.
Rate limit
I tre endpoint AI consentono 5 richieste al minuto per IP e oltre quella soglia restituiscono 429. Le altre route sono limitate indirettamente dalle rispettive sorgenti upstream.
Timestamp
Tutti i campi timestamp sono in formato ISO 8601, in UTC.
Uso responsabile
Lo scanner RECON e /api/osint/sweep generano traffico verso i target che indichi. Usali solo su infrastrutture di tua proprietà o per cui hai un’autorizzazione scritta a eseguire test. Le altre route OSINT sono passive e interrogano dataset di terze parti, non il soggetto stesso.
Riferimento API

Sistema

Liveness e contatori aggregati. Si possono interrogare periodicamente dal monitoraggio senza problemi.

Riferimento API

Aviazione e spazio

Aeromobili, oggetti orbitali ed eliofisica.

Riferimento API

Terra e ambiente

Feed sismici, incendi, dati atmosferici e immagini satellitari.

Riferimento API

Geopolitica

Zone di conflitto, linee del fronte, flussi di eventi e rischio per paese.

Riferimento API

Media e mercati

Aggregazione di notizie, trasmissioni in diretta e strumenti finanziari.

Riferimento API

Sorveglianza e infrastrutture

Reti di telecamere, infrastrutture fisse, traffico marittimo e proxy per tile e stream.

Riferimento API

Minacce cyber

Telemetria su vulnerabilità, attacchi e malware.

Riferimento API

Toolkit OSINT

Gli strumenti di lookup dietro il pannello RECON. Ogni route accetta un singolo soggetto e restituisce un risultato normalizzato, quindi si combinano bene negli script. Richiedono l’accesso: con il browser autenticato nel pannello RECON il cookie di sessione viene inviato automaticamente, altrimenti rispondono 401.

Riferimento API

Scanner Recon

Scansione attiva, delegata a un backend separato: il livello web non esegue mai scansioni direttamente. Richiede l’accesso a RECON (altrimenti 401).

Riferimento API

Grafo delle entità

Analisi dei collegamenti tra le entità emerse nel resto della piattaforma.

Riferimento API

Analisi AI

Correlazione basata su Gemini sui dati dei feed che fornisci. Tutti e tre sono POST e hanno un rate limit di 5 richieste al minuto per IP.

Riferimento API

SDK Polybolos

Invia entità da una piattaforma esterna al Common Operating Picture e ricevi in streaming il quadro unificato.

Riferimento API

Webhook

Hook in ingresso da servizi esterni.