ZettelForge

L'unico sistema di memoria agentivo costruito per l'intelligence sulle minacce informatiche.

Quando un analista senior se ne va, se ne portano via due o tre anni di contesto — ambienti cliente, indagini precedenti, TTP degli attori, pattern di falsi positivi, ogni "aspetta, abbiamo già visto questo" conquistato a fatica. ZettelForge è un sistema di memoria agentivo costruito affinché il contesto resti al team.

Estrae CVE, attori di minaccia, IOC e tecniche ATT&CK da note degli analisti e report di minaccia, risolve alias (APT28 = Fancy Bear = STRONTIUM = Sofacy), costruisce un grafo della conoscenza STIX 2.1 e restituisce ogni indagine passata ai tuoi analisti — e a Claude Code tramite MCP — in linguaggio naturale. Funziona interamente in-process. Nessuna chiave API. Nessun cloud. Nessun dato lascia l'host.

Star · pip install zettelforge · Docs · ThreatRecall (hosted) · Changelog

v2.6.2 (2026-04-27): La web editor di configurazione include menu a tendina funzionanti per tutti i campi enum (provider LLM/embedding, livello di log, azione PII, formato di sintesi) e un pulsante Applica funzionante. Nuovo extra [crewai] espone ZettelForge come strumenti CrewAI — pip install zettelforge[crewai]. Changelog completo

Se ZettelForge si adatta a un flusso di lavoro CTI che gestisci, una stella è il segnale più rapido che vale la pena continuare a investire in questa categoria.

Il problema

Ogni SOC perde analisti. Quando se ne vanno, il contesto delle indagini, l'attribuzione degli attori e i pattern di falsi positivi specifici dell'ambiente scompaiono con loro. I loro sostituti riaprono gli stessi ticket, rileggono gli stessi report e ricostruiscono da zero gli stessi modelli mentali.

I sistemi di memoria AI generici non risolvono questo problema per i team di sicurezza. Non sanno distinguere APT28 da Fancy Bear, non sanno che CVE-2024-3094 è il backdoor di XZ Utils, non sanno analizzare Sigma o YARA e non hanno alcun concetto degli ID delle tecniche MITRE ATT&CK. Quando un analista CTI fornisce loro un anno di report di intelligence, ottengono una vaga ricerca semantica sulla cronologia delle chat.

ZettelForge è stato costruito per analisti che pensano in grafi di minaccia. Estrae automaticamente CVE, attori di minaccia, IOC e tecniche ATT&CK, risolve alias tra convenzioni di denominazione, costruisce un grafo della conoscenza con relazioni causali e recupera memorie utilizzando una ricerca ibrida consapevole dell'intento — tutto in-process, senza dipendenza da API esterne.

L'augmentazione della memoria colma il 33% del divario tra modelli piccoli e grandi nelle attività CTI (CTI-REALM, Microsoft 2026, usando GPT-4 come baseline del modello grande). Vedi il rapporto benchmark completo per metodologia e confronti.

Pipeline dei dati

Funzionalità

Estrazione di entità — Identifica automaticamente CVE, attori di minaccia, IOC (IP, domini, hash, URL, email), tecniche MITRE ATT&CK, campagne, set di intrusione, strumenti, persone, luoghi e organizzazioni. Regex + LLM NER con tipi STIX 2.1 in tutto.

Grafo della conoscenza — Le entità diventano nodi, la co-occorrenza diventa archi. LLM deduce triple causali ("APT28 usa Cobalt Strike"). Archi temporali e soppressione tengono traccia di come l'intelligence si evolve.

Risoluzione alias — APT28, Fancy Bear, Sofacy, STRONTIUM si risolvono tutte allo stesso nodo attore. Funziona automaticamente su memorizzazione e recupero.

Recupero ibrido — Somiglianza vettoriale (fastembed a 768 dimensioni, ONNX) + traversata del grafo (BFS sugli archi del grafo della conoscenza), ponderata per classificazione dell'intento. Cinque tipi di intento: fattuale, temporale, relazionale, esplorativo, causale.

Evoluzione della memoria — Con evolve=True, la nuova intelligence viene confrontata con la memoria esistente. LLM decide AGGIUNGI, AGGIORNA, ELIMINA o NESSUNA OPERAZIONE. L'intelligence obsoleta viene sostituita. Le contraddizioni vengono risolte. I duplicati vengono saltati.

Sintesi RAG — Sintetizza risposte attraverso tutte le memorie memorizzate con il formato direct_answer.

In-process per architettura — fastembed (ONNX) per gli embedding, llama-cpp-python per l'inferenza LLM locale opzionale, SQLite + LanceDB per l'archiviazione e Ollama su localhost per impostazione predefinita. Non sono richieste chiavi API esterne. L'accesso alla rete in uscita può avvenire al primo avvio quando vengono scaricati i modelli di embedding/LLM; dopo il precaricamento dei modelli, può funzionare completamente offline (anche su host con aria-gap).

Registrazione audit in schema OCSF — Ogni operazione emette un evento strutturato nel formato Open Cybersecurity Schema Framework. Cosa fare con il flusso di log (SIEM, archivio WORM, niente) dipende da te.

Avvio rapido

Ciao mondo in 30 secondi (nessun LLM richiesto)

pip install zettelforge

from zettelforge import MemoryManager

mm = MemoryManager()

# Memorizza CTI -- entità (CVE, attori, ID ATT&CK, IOC) estratte tramite regex
mm.remember("APT28 usa Cobalt Strike per movimento laterale tramite T1021")
mm.remember("APT28 (Fancy Bear) prende di mira appaltatori della difesa NATO con spear-phishing")
mm.remember("CVE-2024-3094 è il backdoor di XZ Utils (CVSS 10.0) che colpisce sshd")

# Il recupero combina ricerca vettoriale + grafo; la risoluzione alias entra in azione (Fancy Bear -> APT28)
for note in mm.recall("Quali strumenti usa Fancy Bear?", k=3):
    print(f"[{note.metadata.tier}] {note.content.raw}")

Funziona con un pip install pulito, senza servizi esterni. Gli embedding vengono eseguiti in-process tramite fastembed (modello ONNX ~80MB scaricato alla prima chiamata). MemoryManager() scrive su ~/.amem/ per impostazione predefinita; sovrascrivi con ZETTELFORGE_DATA_DIR o tramite config. Una copia eseguibile si trova in examples/quickstart.py.

Aggiungi un LLM per sintesi e estrazione più ricca

ollama pull qwen3.5:9b && ollama serve

# Con Ollama in esecuzione, synthesize() restituisce un riepilogo reale tra le note memorizzate
answer = mm.synthesize("Riassumi le TTP note di APT28")
print(answer["synthesis"]["answer"])
# Il NER LLM in background arricchisce anche le note memorizzate con entità aggiuntive

ZettelForge rileva automaticamente Ollama. Per usare un provider diverso (local llama-cpp, litellm per oltre 100 provider, mock per test), vedi Configurazione. Senza LLM, synthesize() restituisce comunque una risposta strutturata ma il campo answer è un segnaposto di fallback — solo remember e recall producono risultati utili in modalità solo pip.

Evoluzione della memoria

# Arriva nuova intelligence -- evolve=True abilita l'evoluzione della memoria:
# LLM estrae fatti, li confronta con le note esistenti, decide AGGIUNGI/AGGIORNA/ELIMINA/NESSUNA OPERAZIONE
mm.remember(
    "APT28 ha cambiato tattica. Hanno abbandonato DROPBEAR e ora sfruttano dispositivi periferici.",
    domain="cti",
    evolve=True,   # la nota APT28 esistente viene sostituita, non duplicata
)

Come funziona

Ogni chiamata remember() attiva una pipeline:

1. Estrazione di entità — regex + LLM NER identifica CVE, set di intrusione, attori di minaccia, strumenti, campagne, tecniche ATT&CK, IOC (IPv4, dominio, URL, MD5/SHA1/SHA256, email), persone, luoghi, organizzazioni, eventi, attività e riferimenti temporali (19 tipi)
2. Aggiornamento del grafo della conoscenza — le entità diventano nodi, la co-occorrenza diventa archi, LLM deduce triple causali
3. Embedding vettoriale — fastembed a 768 dimensioni (ONNX, in-process, 7ms/embed) memorizzato in LanceDB
4. Controllo di sostituzione — il rilevamento di sovrapposizione di entità segna le note obsolete come sostituite
5. Scrittura a doppio flusso — il percorso veloce restituisce in ~45ms; l'arricchimento causale viene delegato a un worker in background

Ogni chiamata recall() combina due strategie di recupero:

1. Somiglianza vettoriale — ricerca semantica sugli embedding
2. Traversata del grafo — BFS sugli archi del grafo della conoscenza, valutato per distanza di salto
3. Instradamento dell'intento — query classificata come fattuale/temporale/relazionale/causale/esplorativa, pesi regolati per tipo
4. Riordinamento con cross-encoder — ms-marco-MiniLM riordina i risultati finali per pertinenza

Usa ZettelForge in Claude Desktop in 60 secondi

pip install zettelforge

Crea o modifica .claude.json nella radice del tuo progetto (o ~/.claude/.claude.json per accesso globale):

{
  "mcpServers": {
    "zettelforge": {
      "command": "python3",
      "args": ["-m", "zettelforge.mcp"]
    }
  }
}

Se ZettelForge è installato in un ambiente virtuale, usa il percorso completo di quell'interprete Python:

{
  "mcpServers": {
    "zettelforge": {
      "command": "/home/user/.venvs/zettelforge/bin/python",
      "args": ["-m", "zettelforge.mcp"]
    }
  }
}

Avvia Claude Code e verifica che gli strumenti siano disponibili:

claude
# All'interno della sessione, chiedi: "Quali strumenti hai a disposizione da zettelforge?"

Sette strumenti sono esposti: zettelforge_remember, zettelforge_recall, zettelforge_synthesize, zettelforge_entity, zettelforge_graph, zettelforge_stats e zettelforge_sync (richiede pacchetto enterprise). Vedi il riferimento protocollo MCP per schemi completi, esempi di richiesta/risposta JSON-RPC, codici di errore e il ciclo di vita lazy-singleton. Per risoluzione dei problemi, percorsi virtualenv e test manuali degli strumenti, vedi set-up-mcp-server.

Benchmark

Valutato rispetto a benchmark accademici pubblicati:

La colonna Punteggio riporta le misurazioni di ZettelForge eseguite con modelli ospitati da Ollama, con un'eccezione: la riga LOCOMO è stata misurata nuovamente alla v2.1.1 utilizzando un giudice cloud Ollama per la valutazione (non generazione locale). Vedi il rapporto benchmark completo per metodologia specifica del benchmark, cronologia delle versioni e configurazione del giudice per suite.

Regole di rilevamento come memoria (Sigma + YARA)

Le regole Sigma e YARA sono primitive di memoria di prima classe. Analizza, convalida e importa una regola e i suoi tag diventano archi del grafo: tecniche MITRE ATT&CK, CVE, alias di attori di minaccia, strumenti e famiglie di malware si risolvono rispetto alla stessa ontologia di ogni altra nota. Un supertipo DetectionRule condiviso porta i sottotipi SigmaRule e YaraRule, quindi un singolo UUID di regola è indirizzabile in entrambi i formati.

Le regole Sigma vengono convalidate rispetto allo schema JSON SigmaHQ fornito. Le regole YARA vengono analizzate con plyara e verificate rispetto allo standard di metadati YARA CCCS (livelli: strict, warn, non_cccs). L'importazione è idempotente — reimportare una regola invariata restituisce la nota originale tramite un source_ref con hash del contenuto.

from zettelforge import MemoryManager
from zettelforge.sigma import ingest_rule as ingest_sigma
from zettelforge.yara import ingest_rule as ingest_yara

mm = MemoryManager()
ingest_sigma("rules/proc_creation_win_office_macro.yml", mm)
ingest_yara("rules/webshell_china_chopper.yar", mm, tier="warn")

# Importazione bulk da SigmaHQ o un repository di regole privato
python -m zettelforge.sigma.ingest /path/to/sigma/rules/
python -m zettelforge.yara.ingest /path/to/yara/rules/ --tier warn

# Verifica CI fixture -- analizza + convalida, nessuna scrittura
python -m zettelforge.sigma.ingest rules/ --dry-run

Un spiegatore di regole LLM (zettelforge.detection.explainer.explain) produce un riepilogo JSON strutturato — intento, campi chiave, note di evasione, ipotesi di falsi positivi — per qualsiasi DetectionRule. Viene eseguito in modo sincrono su richiesta in v1; il collegamento alla coda di arricchimento asincrono è previsto per v1.1. Limitato in frequenza tramite ZETTELFORGE_EXPLAIN_RPM (default 60 chiamate/minuto).

Riferimenti: Specifica Sigma, Regole SigmaHQ, CCCS YARA, Documentazione YARA.

Integrazioni

ATHF (Agentic Threat Hunting Framework)

Importa le cacce completate di ATHF nella memoria di ZettelForge. Le tecniche MITRE e gli IOC vengono estratti e collegati nel grafo della conoscenza.

python examples/athf_bridge.py /path/to/hunts/
# 12 caccia(e) analizzata(e)
# Importate 12/12 cacce in ZettelForge

Vedi examples/athf_bridge.py.

ThreatRecall (Hosted)

ThreatRecall è la distribuzione commerciale di ZettelForge con estensioni enterprise abilitate. È offerto come SaaS gestito per impostazione predefinita, con distribuzioni on-premise self-hosted opzionali e con aria-gap per ambienti classificati. Componenti aggiuntivi enterprise:

• Backend TypeDB STIX 2.1 — ontologia con vincoli di schema e regole di inferenza
• Sincronizzazione OpenCTI — sincronizzazione bidirezionale con la tua istanza OpenCTI
• Autenticazione multi-tenant — OAuth/JWT con isolamento dei dati per tenant
• Generazione di regole Sigma — regole di rilevamento da IOC estratti (in arrivo)

Il SaaS si distribuisce in minuti senza infrastruttura da mantenere. La versione self-hosted viene fornita come bundle distribuibile per ambienti in cui l'uscita di rete verso l'esterno è limitata o proibita.

Unisciti alla lista d'attesa — stiamo attualmente onboardando partner di progettazione.

Configurazione

Vedi config.default.yaml per tutte le opzioni.

Contribuire

Vedi CONTRIBUTING.md per la configurazione di sviluppo.

Licenza

MIT — Vedi LICENSE.

Realizzato da Patrick Roland — LinkedIn | Direttore dei Servizi SOC, Summit 7 Systems | Veterano della Marina Nucleare | CISSP, CCP (Professionista CMMC 2.0)

Supporta il Progetto

ZettelForge è con licenza MIT. Metti una stella al repo, apri issue e invia PR — tutti i contributi sono benvenuti.

Riconoscimenti

• Ispirato da Zettelkasten e A-Mem (NeurIPS 2025)
• Pipeline a due fasi ispirata da Mem0
• Schema STIX 2.1 informato da typedb-cti
• Confrontato con LOCOMO (ACL 2024) e CTIBench (NeurIPS 2024)
• LanceDB | fastembed | Pydantic | TypeDB