Cusimanse

Stato: Beta — Framework di Ricerca e Kit di Runtime

Cusimanse è in fase di sviluppo attivo. Fai un fork, testalo, esegui gli esperimenti di riferimento, segnala bug e invia pull request. Aspettati che API, recipe, documentazione e integrazioni evolvano durante la beta.

Uso dell'IA e contributo responsabile: Cusimanse utilizza lo sviluppo assistito dall'IA e l'IA agentica come parte del suo framework di ricerca, della documentazione, dei flussi di analisi e del processo ingegneristico. L'output generato o assistito dall'IA non è automaticamente autorevole, sicuro, corretto, originale o adatto all'uso in produzione. I contributori sono responsabili della revisione, del test e della validazione delle modifiche assistite dall'IA prima dell'invio. Non fare affidamento su un sistema di IA come unica autorità per decisioni di sicurezza, autorizzazione, interpretazione delle prove o azioni critiche per la sicurezza. Usa Cusimanse solo per ricerche autorizzate, rispetta le leggi e le policy applicabili, proteggi le credenziali e i dati sensibili, e mantieni l'esecuzione entro i confini dichiarati dal progetto in termini di policy e di compute usa-e-getta. I contributi dovrebbero identificare chiaramente l'assistenza materiale dell'IA ove appropriato, preservare la responsabilità umana e seguire i test del repository, i requisiti di revisione e le aspettative di uso responsabile.

Ricerca di sicurezza dichiarativa, operata da agenti su compute usa-e-getta. I ricercatori dichiarano intento e requisiti; gli agenti pianificano, selezionano e analizzano; l'API di capability in Go e la policy decidono se e come l'esecuzione può avvenire.

Contratto → requisiti → handoff del prompt → agente → risoluzione delle capability → runtime Go → policy/approvazione → Lima/QEMU → strumentazione/workload → evidenze → analisi → verifica indipendente → report → conservazione → distruzione.

Indice

• Cos'è Cusimanse
• Architettura e confine di autorità
• Flusso di lavoro del ricercatore
• Libreria di prompt e handoff dell'agente
• Strumenti host e installazione
• Gateway
• Strumentazione
• Osservabilità
• Lima/QEMU e strumenti guest
• API di capability in Go e comandi
• Ruoli, Skill e ciclo di apprendimento
• Profili e requisiti
• Policy e sicurezza
• Evidenze e riproducibilità
• Esperimenti di riferimento
• Validazione e test di integrazione
• Crediti e comunità open source
• Mappa del repository

Cos'è Cusimanse

Livello	Responsabilità	Fonte di verità
Contratto	scopo, autorizzazione, ambito, accettazione	contracts/
Requisiti	OS, isolamento, workload, rete, strumentazione	recipes/experiments/
Libreria di prompt	handoff neutrale rispetto all'agente	prompts/experiments/
Guide per operatori	handoff tramite adattatore sottile	prompts/operators/
Profili	capability riutilizzabili e fidate	recipes/profiles/
Runtime	risoluzione, policy, ciclo di vita, confine di esecuzione	cmd/cusimanse/, internal/
Policy	autorità e approvazione	policies/, internal/policy/
Contenimento	compute usa-e-getta	recipes/lima/, Lima/QEMU
Evidenze	osservazioni, provenienza, verifica	runs/<session-id>/

L'agente non può creare profili fidati, espandere la policy, modificare recipe fidate o eseguire un workload non fidato direttamente sull'host.

Architettura e confine di autorità

1. Dichiarazione: contratto + requisiti YAML.
2. Handoff: prompt di esperimento condiviso più guida opzionale per l'operatore.
3. Pianificazione: Goose è l'operatore di riferimento nativo; altri agenti usano adattatori.
4. Risoluzione: Go risolve i requisiti rispetto ai profili registrati e fallisce in modo sicuro in caso di ambiguità.
5. Policy: Go valuta i gate di autorità e approvazione e verifica le decisioni.
6. Esecuzione: le capability operano Lima/QEMU e handler di workload fissi.
7. Evidenze: raccogli, calcola l'hash, verifica in modo indipendente, riporta, conserva, poi distruggi il compute usa-e-getta.

Regola di confine: l'agente decide quale ricerca svolgere; Cusimanse decide se e come può essere eseguita.

Flusso di lavoro del ricercatore

1. Contratto e requisiti

Scrivi contracts/<experiment>.md con domanda di ricerca, autorizzazione, ambito, criteri di accettazione e vincoli di sicurezza. Dichiara solo i requisiti in recipes/experiments/<experiment>.yaml.

Esempio:

requirements:
  execution: disposable
  os: linux
  workload: npm-threat
  network: localhost-only
  instrumentation: [process, syscall, filesystem, network]

2. Bootstrap e validazione deterministica

./scripts/install.sh
export PATH="$HOME/.local/bin:$HOME/go/bin:$PATH"
cusimanse doctor
cusimanse validate
cusimanse preflight
cusimanse policy validate
cusimanse test
cusimanse integration-test

3. Valida ed esegui la recipe Goose

goose recipe validate recipes/npm-threat-001/recipe.yaml
goose recipe validate recipes/subrecipes/evidence-analysis.yaml
goose recipe validate recipes/subrecipes/verification.yaml
goose recipe validate recipes/subrecipes/report.yaml
goose run --recipe ./recipes/npm-threat-001/recipe.yaml --interactive

La recipe dichiara esplicitamente l'estensione di piattaforma summon. Summon fornisce solo delega/orchestrazione; non autorizza l'esecuzione.

4. Risolvi e approva

cusimanse resolve npm-threat-001
cusimanse policy explain vm
cusimanse policy explain network
cusimanse policy check-all
cusimanse policy require vm --approved

5. Esegui e concludi

cusimanse --approved run npm-threat-001 <session-id>
cusimanse observability report <session-id>
cusimanse policy audit

Ciclo di vita: resolve → policy → provision → configure → instrument → execute → collect → verify → report → preserve → destroy.

Libreria di prompt e handoff dell'agente

Il prompt è un handoff, non un livello di autorità e non una seconda recipe.

prompts/experiments/<experiment>.md       handoff di ricerca condiviso
prompts/operators/<operator>.md           guida sottile per l'operatore
recipes/experiments/<experiment>.yaml     fonte di verità dei requisiti
recipes/<experiment>/recipe.yaml          recipe Goose/runtime
contracts/<experiment>.md                 fonte di autorizzazione/ambito