Dokumentation

Sicherheit und Verifikation

Unterstützte Versionen

Sicherheitskorrekturen gibt es für das neueste veröffentlichte Release, aktuell v0.4.1. Der unveröffentlichte main-Branch wird laufend getestet, ist aber kein unterstützter Release-Kanal. Pinne produktive Installationen auf einen unveränderlichen Tag und prüfe Prüfsumme und Build-Provenienz. greppy hat keinen Self-Updater: Du aktualisierst bewusst, über geprüfte Release-Artefakte.

So entsteht ein Release

Ein Release entsteht nur, wenn auf dem exakten Release-Commit alles Folgende grün ist:

  • CI;
  • CodeQL;
  • das Security-Audit der Rust-Abhängigkeiten;
  • das Reproduzierbarkeits-Audit der Task-Bank;
  • das Qualitäts-Gate für die Zusammenfassungen;
  • Code-Signing und Notarisierung.

Jedes Paket kommt mit einem SBOM (*.spdx.json). Pakete, SBOMs, Build-Umgebungen und das Trainingsprotokoll des Qwen-Modells tragen eine SLSA-Build-Provenienz-Attestation von GitHub. Agent-Benchmarks laufen fortlaufend als Diagnose und blockieren nie das Release, das gerade geprüft wird. Siehe Benchmarks und Paper.

Release prüfen

Die erwartete Identität ist das Repository metric-space-ai/greppy, der Signer-Workflow .github/workflows/release.yml und der Commit, auf den der Release-Tag zeigt. Lade die Prüfsummen, das Release-Manifest und das Paket für deine Plattform in ein leeres Verzeichnis:

version=v0.4.1
asset=greppy-macos-arm64.pkg   # oder greppy-linux-x86_64.deb / greppy-linux-x86_64.rpm
mkdir "greppy-$version" && cd "greppy-$version"
gh release download "$version" --repo metric-space-ai/greppy \
  -p SHA256SUMS -p RELEASE-ASSETS.json -p "$asset"

1. Prüfsumme

shasum -a 256 -c --ignore-missing SHA256SUMS   # Linux: sha256sum --check --ignore-missing SHA256SUMS

RELEASE-ASSETS.json: OK
greppy-macos-arm64.pkg: OK

SHA256SUMS deckt alle 15 übrigen Assets ab: Pakete, ihre SHA-256-Dateien und SBOMs, das Manifest RELEASE-ASSETS.json, die Build-Umgebungen, den Modell-Herkunftsbericht und das Qwen-Trainingsprotokoll. --ignore-missing prüft die Dateien, die du geladen hast.

2. Manifest

RELEASE-ASSETS.json ist der maschinenlesbare Vertrag über die exakten Dateinamen, ihre Rollen und SHA-256-Werte. Prüfe, dass dein Paket als package dieses Tags gelistet ist:

jq -r --arg a "$asset" '.tag, (.assets[] | select(.name == $a) | "\(.role) \(.sha256)")' RELEASE-ASSETS.json

v0.4.1
package 1040391f1e23a71d7a21c33eb5d2e9343d002fc6f44743e466fa086ee8295d86

3. Build-Provenienz

Die Attestation bindet die SHA-256 des Pakets an Repository, Workflow und Quell-Commit. --source-digest verlangt genau den Commit, auf den der Release-Tag zeigt; RELEASE-ASSETS.json nennt denselben Commit als git_commit.

commit=$(gh api "repos/metric-space-ai/greppy/commits/$version" --jq .sha)
gh attestation verify "$asset" \
  --repo metric-space-ai/greppy \
  --signer-workflow metric-space-ai/greppy/.github/workflows/release.yml \
  --source-digest "$commit" \
  --deny-self-hosted-runners

Loaded digest sha256:1040391f1e23a71d7a21c33eb5d2e9343d002fc6f44743e466fa086ee8295d86 for file://greppy-macos-arm64.pkg
Loaded 1 attestation from GitHub API

The following policy criteria will be enforced:
- Predicate type must match:..................... https://slsa.dev/provenance/v1
- Source Repository Owner URI must match:........ https://github.com/metric-space-ai
- Source Repository URI must match:.............. https://github.com/metric-space-ai/greppy
- Source repo digest digest must match:.......... 7e6e6ed7d95a48dc7637ba5d406e7a724e589d77
- Subject Alternative Name must match regex:..... ^https://github.com/metric-space-ai/greppy/.github/workflows/release.yml
- OIDC Issuer must match:........................ https://token.actions.githubusercontent.com
- Action workflow Runner Environment must match : github-hosted

✓ Verification succeeded!
…

Mit greppy-linux-x86_64.deb endet derselbe Befehl ebenso mit ✓ Verification succeeded!.

Installiere kein Release, wenn eine dieser Prüfungen scheitert: Manifest, Prüfsumme, Signatur oder Attestation.

Die Release-Webseite lädt ihre Asset-Liste nachträglich, ein reiner HTML-Abruf zeigt deshalb nur die „Source code“-Links. Maßgeblich sind die API und RELEASE-ASSETS.json:

gh release view v0.4.1 --repo metric-space-ai/greppy --json assets --jq '.assets[].name'

macOS: Signatur und Notarisierung

Das .pkg ist mit einem Developer-ID-Installer-Zertifikat signiert und von Apple notarisiert; das Notarisierungsticket ist angeheftet. Gatekeeper stuft es als „Notarized Developer ID“ ein.

pkgutil --check-signature "$asset"
spctl --assess --type install --verbose=4 "$asset"
xcrun stapler validate "$asset"

$ pkgutil --check-signature greppy-macos-arm64.pkg
Package "greppy-macos-arm64.pkg":
   Status: signed by a developer certificate issued by Apple for distribution
   Notarization: trusted by the Apple notary service
   Signed with a trusted timestamp on: 2026-10-07 16:46:15 +0000
   Certificate Chain:
    1. Developer ID Installer: Michael Welsch (2HS27B8739)
…
    2. Developer ID Certification Authority
…
    3. Apple Root CA
…
$ spctl --assess --type install --verbose=4 greppy-macos-arm64.pkg
greppy-macos-arm64.pkg: accepted
source=Notarized Developer ID
$ xcrun stapler validate greppy-macos-arm64.pkg
…
The validate action worked!

Die installierte CLI trägt eine Developer-ID-Signatur mit Hardened Runtime. Nach einer Installation mit dem Installer liegt sie unter ~/.local/share/greppy/versions/v0.4.1/bin/, mit --system unter /Applications/GreppyWorkspaceFS.app/Contents/Resources/bin/:

cd ~/.local/share/greppy/versions/v0.4.1/bin
codesign --verify --strict --verbose=2 greppy
codesign --display --verbose=4 greppy 2>&1 | grep -E '^(Authority|TeamIdentifier)='

greppy: valid on disk
greppy: satisfies its Designated Requirement
Authority=Developer ID Application: Michael Welsch (2HS27B8739)
Authority=Developer ID Certification Authority
Authority=Apple Root CA
TeamIdentifier=2HS27B8739

Eine einzelne Mach-O-Datei kann kein Notarisierungsticket tragen; das Ticket sitzt am .pkg. spctl --assess --type execute lehnt die CLI deshalb mit „the code is valid but does not seem to be an app“ ab. Das ist erwartet und kein Defekt.

Die GitHub-Attestation belegt die Identität von Repository und Workflow. Die Apple-Prüfung belegt unabhängig davon das Vertrauen der Plattform. Der angezeigte Zertifikatsname ist eine Diagnose und ersetzt nicht die an das Repository gebundene Attestation.

Schwachstelle melden

Melde Schwachstellen vertraulich über GitHubs Ablauf Security › Report a vulnerability im greppy-Repository. Öffne kein öffentliches Issue für eine vermutete Schwachstelle, die Repository-Inhalte, Cache-Pfade, lokale Rechtegrenzen, das Laden von Modellen oder Backends oder den Daemon-Transport betrifft.

Gib die betroffene Version und Plattform an, die Schritte zur Reproduktion, die erwartete Auswirkung und ob lokaler Zugriff nötig ist. Die Maintainer bestätigen eine vollständige Meldung innerhalb von fünf Werktagen und stimmen die Veröffentlichung ab, sobald ein Fix bereitsteht. Die vollständige Richtlinie steht in SECURITY.md.

Sicherheitsgrenzen

  • greppy verarbeitet lokalen Quellcode und speichert indizierte Spans in einem lokalen SQLite-Cache. Code-Navigation sendet weder Code noch Modell-Prompts an einen Netzwerkdienst.
  • Der normale grep-Passthrough ruft das echte System-grep auf. Er öffnet keinen Index, lädt kein Modell und ändert keinen greppy-Cache.
  • Die Qwen-Zusammenfassungen sind nicht vertrauenswürdige Navigationshinweise und fehlen bei jedem Inferenz- oder Validierungsfehler.
  • Modelle und eingebettete CUDA-Artefakte werden nur in private, inhaltsadressierte Cache-Pfade entpackt und vor dem Laden geprüft. Release-Builds unterstützen keine externen Backend-Bibliotheken.
  • greppy installiert keine Treiber, Toolkits, Updates oder sonstige Software.
  • Agent-Workspaces sind lokale private Workspaces, keine Sicherheitsgrenze zwischen dem Agenten und deinen Repository-Inhalten. In dein Repository gelangt nur ein geprüfter finaler Vorschlag.
  • Tool-Subprozesse des Agenten sind beim Schreiben eingegrenzt (Seatbelt unter macOS, Landlock unter Linux). Lesen und Netzwerk bleiben offen, Umgebungsvariablen mit Zugangsdaten entfernt greppy.
  • Die Sockets der Inferenz-Daemons haben Modus 0600 in einem Verzeichnis pro Benutzer mit 0700 (/tmp/greppy-daemon-<uid>/).
  • Den Fernsteuerungs-Socket des Agenten kann jeder Prozess unter deinem Benutzer ansprechen, auch die Tool-Subprozesse des Agenten. Die Grenze ist dein Benutzerkonto, keine Rechtegrenze zwischen Agenten.

Härtung des Browser-Tools (Beta)

  • Die eingebettete Engine beachtet ihre HSTS-Preload-Liste schon bei der ersten Navigation.
  • SubtleCrypto ist abgeschaltet, solange die Engine von einem timing-anfälligen RSA-Pfad abhängt (RUSTSEC-2023-0071). crypto.getRandomValues und crypto.randomUUID bleiben verfügbar. Ein Regressionstest schlägt fehl, sobald es wieder eingeschaltet wird.
  • Sessions nutzen standardmäßig das Profil research (öffentliches Web); das Profil project erlaubt zusätzlich Loopback. LAN- und Cloud-Metadaten-Adressen bleiben gesperrt.
  • Geheimnisse übergibst du mit --from-env oder --value-stdin, nie auf der Kommandozeile. Seitentext wird als nicht vertrauenswürdige Eingabe eingezäunt.

Sensible Repositories

Setze GREPPY_STORE_DIR auf einen verschlüsselten oder flüchtigen, benutzerprivaten Ort, wenn Repository-Inhalte zusätzlichen Schutz im Ruhezustand brauchen. Gespeicherte Pfade prüfst du mit greppy cache status --json, verwaltete Daten entfernst du mit greppy cache clear --root DIR --yes oder greppy cache clear --all --yes. Siehe Lokale Daten, Datenschutz und Deinstallation.