Cusimanse

Status: Beta — Research Framework & Runtime Kit

Cusimanse wird aktiv weiterentwickelt. Forken Sie es, testen Sie es, führen Sie die Referenzexperimente aus, melden Sie Fehler und reichen Sie Pull Requests ein. Erwarten Sie, dass sich APIs, Rezepte, Dokumentation und Integrationen während der Beta-Phase weiterentwickeln.

KI-Nutzung und verantwortungsvolle Mitwirkung: Cusimanse nutzt KI-unterstützte Entwicklung und agentische KI als Teil seines Research-Frameworks, seiner Dokumentation, Analyse-Workflows und Engineering-Prozesse. KI-generierte oder KI-unterstützte Ergebnisse sind nicht automatisch autoritativ, sicher, korrekt, originell oder für den Produktionseinsatz geeignet. Mitwirkende sind dafür verantwortlich, KI-unterstützte Änderungen vor der Einreichung zu überprüfen, zu testen und zu validieren. Verlassen Sie sich nicht auf ein KI-System als alleinige Autorität für Sicherheitsentscheidungen, Autorisierung, Beweisinterpretation oder sicherheitskritische Aktionen. Verwenden Sie Cusimanse nur für autorisierte Forschung, respektieren Sie geltende Gesetze und Richtlinien, schützen Sie Anmeldedaten und sensible Daten und halten Sie die Ausführung innerhalb der vom Projekt erklärten Richtlinien- und Wegwerf-Compute-Grenzen. Beiträge sollten wesentliche KI-Unterstützung gegebenenfalls klar kennzeichnen, die menschliche Verantwortlichkeit wahren und die Tests, Review-Anforderungen und Erwartungen an die verantwortungsvolle Nutzung des Repositorys befolgen.

Deklarative, agentenbetriebene Sicherheitsforschung auf Wegwerf-Compute. Forschende erklären Absicht und Anforderungen; Agenten planen, wählen aus und analysieren; die Go-Capability-API und die Policy entscheiden, ob und wie eine Ausführung erfolgen darf.

Vertrag → Anforderungen → Prompt-Übergabe → Agent → Capability-Auflösung → Go-Runtime → Policy/Genehmigung → Lima/QEMU → Instrumentierung/Workload → Evidenz → Analyse → unabhängige Verifikation → Bericht → Bewahrung → Vernichtung.

Inhaltsverzeichnis

• Was Cusimanse ist
• Architektur und Autoritätsgrenze
• Workflow für Forschende
• Prompt-Bibliothek und Agenten-Übergabe
• Host-Tooling und Installation
• Gateways
• Instrumentierung
• Observability
• Lima/QEMU und Gast-Tooling
• Go-Capability-API und Befehle
• Rollen, Skills und Lernschleife
• Profile und Anforderungen
• Policy und Sicherheit
• Evidenz und Reproduzierbarkeit
• Referenzexperimente
• Validierung und Integrationstests
• Danksagungen und Open-Source-Community
• Repository-Übersicht

Was Cusimanse ist

Ebene	Verantwortlichkeit	Quelle der Wahrheit
Vertrag	Zweck, Autorisierung, Umfang, Abnahme	contracts/
Anforderungen	OS, Isolation, Workload, Netzwerk, Instrumentierung	recipes/experiments/
Prompt-Bibliothek	agentenneutrale Übergabe	prompts/experiments/
Operator-Leitfäden	schlanke Adapter-Übergabe	prompts/operators/
Profile	vertrauenswürdige wiederverwendbare Capabilities	recipes/profiles/
Runtime	Auflösung, Policy, Lebenszyklus, Ausführungsgrenze	cmd/cusimanse/, internal/
Policy	Autorität und Genehmigung	policies/, internal/policy/
Eindämmung	Wegwerf-Compute	recipes/lima/, Lima/QEMU
Evidenz	Beobachtungen, Provenienz, Verifikation	runs/<session-id>/

Der Agent kann keine vertrauenswürdigen Profile erstellen, die Policy erweitern, vertrauenswürdige Rezepte verändern oder einen nicht vertrauenswürdigen Workload direkt auf dem Host ausführen.

Architektur und Autoritätsgrenze

1. Deklaration: Vertrag + YAML-Anforderungen.
2. Übergabe: gemeinsamer Experiment-Prompt plus optionaler Operator-Leitfaden.
3. Planung: Goose ist der native Referenz-Operator; andere Agenten verwenden Adapter.
4. Auflösung: Go löst Anforderungen gegen registrierte Profile auf und schlägt bei Mehrdeutigkeit fehl (fail closed).
5. Policy: Go bewertet Autoritäts- und Genehmigungs-Gates und auditiert Entscheidungen.
6. Ausführung: Capabilities bedienen Lima/QEMU und feste Workload-Handler.
7. Evidenz: sammeln, hashen, unabhängig verifizieren, berichten, bewahren, dann Wegwerf-Compute vernichten.

Grenzregel: Der Agent entscheidet, welche Forschung betrieben wird; Cusimanse entscheidet, ob und wie sie ausgeführt werden darf.

Workflow für Forschende

1. Vertrag und Anforderungen

Schreiben Sie contracts/<experiment>.md mit Forschungsfrage, Autorisierung, Umfang, Abnahmekriterien und Sicherheitsbeschränkungen. Deklarieren Sie nur Anforderungen in recipes/experiments/<experiment>.yaml.

Beispiel:

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

2. Bootstrap und deterministische Validierung

./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. Goose-Rezept validieren und ausführen

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

Das Rezept deklariert explizit die Plattform-Erweiterung summon. Summon bietet nur Delegation/Orchestrierung; es autorisiert keine Ausführung.

4. Auflösen und genehmigen

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

5. Ausführen und abschließen

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

Lebenszyklus: resolve → policy → provision → configure → instrument → execute → collect → verify → report → preserve → destroy.

Prompt-Bibliothek und Agenten-Übergabe

Der Prompt ist eine Übergabe, keine Autoritätsebene und kein zweites Rezept.