OrenSegal/audit

Führe einen gegnerischen Audit dieser Codebase durch und schließe ihn ab. Berichte und liefere zuerst aus; ändere Quellcode nur mit --fix oder wenn der Benutzer Korrekturen auswählt.

Du bist der Gegner. Jede Linse stellt eine Frage aus einem anderen Blickwinkel: Welche Eingabe, welches Timing, welcher Benutzer oder Angreifer bringt diesen Code dazu, eine falsche Antwort zu geben, Daten zu verlieren, Daten preiszugeben oder den Benutzer zu blockieren?

Dieser Ordner enthält alles, was der Audit braucht. Löse diese Pfade relativ zum Verzeichnis dieser Datei auf:

• lenses/<linse>.md: eine pro Linse. Ihre Zeile Fires: sagt, wann die Linse läuft (always oder when <bedingung>). Jeder Prüfpunkt ist entweder unbedingt (wird immer beantwortet) oder mit (when <bedingung>) markiert (wird nur beantwortet, wenn die Bedingung zutrifft, sonst als nicht anwendbar geschlossen). Dann das Artefakt, das die Linse produziert, und ihre Done-Zeile.
• scripts/scan.py: erstellt einen Fingerabdruck des Repos, leitet Linsen weiter und listet die eigenen Analysewerkzeuge des Projekts auf, die ausgeführt werden sollen. scripts/signals.tsv: alle Erkennungs- und Seed-Muster; scripts/tools.tsv: alle bekannten Analysewerkzeuge. Ein Projekt fügt eigene Zeilen in docs/agents/audit-signals.tsv hinzu.
• scripts/verify.py: überprüft die Ergebnisdateien gegen die Lens-Dateien. scripts/cochange.sh: Dateien, die sich zusammen ändern.
• DELIVER.md: Übergabenotizen, die Audit-Karte und ihre Tickets.
• UNTANGLE.md: das strukturelle Refactoring, für --untangle und für strukturelle Tickets.

1. Umfang

• Argumente: ein Pfad (Standard: Repo-Wurzel); --lens a,b um nur diese auszuführen; --since REF um das zu auditieren, was sich seit einem Referenzpunkt geändert hat (ein PR-Base oder der Commit des letzten Audits); --fix; --untangle [area|ticket] um direkt zu UNTANGLE.md zu springen; --out VERZ (Standard: .audit/).
• Wenn keine Antwort eintreffen kann (CI, claude -p), bleiben unbeantwortete Fragen in HANDOFF.md als offene Fragen stehen, die Auslieferung erfolgt nur an den lokalen Tracker und der Quellcode bleibt unberührt, es sei denn, ein Ticket steht in der approved:-Zeile.
• Erstelle das Ausgabeverzeichnis mit einer .gitignore-Datei, die * enthält, sodass der Audit keine verfolgte Datei berührt. Wenn ein neuer Durchlauf startet (niemals bei Wiederaufnahme), verschiebe zuerst die Dateien RUN.md, REPORT.md und findings/ eines früheren Durchlaufs nach <ausgabe>/history/<sein Datum>/, damit der neue Durchlauf ihn vergleichen kann.
• Fortsetzen: wenn <ausgabe>/HANDOFF.md existiert, fahre ab seiner next-Phase fort, wobei die Dateien des Durchlaufs unverändert bleiben. Tickets auf seiner approved:-Zeile sind ohne erneute Rückfrage für Quellcode-Änderungen freigegeben; bearbeite das erste Ticket an der Front, ein Ticket pro Sitzung, wie in DELIVER.md beschrieben. Jedes andere Ticket geht zuerst zurück zum Benutzer. Wenn ein früherer Durchlauf in history/ existiert, biete --since <sein Commit> an und übernimm refuted.md weiter.

Jede untenstehende Phase endet damit, dass <ausgabe>/HANDOFF.md neu geschrieben wird, wie DELIVER.md es beschreibt.

2. Scan und Aufklärung

Führe python3 scripts/scan.py <pfad> [--since REF] [--lens a,b] > <ausgabe>/SCAN.md aus, sodass SCAN.md die rohe Ausgabe des Skripts ist: Stacks, Pakete, welche Linsen feuern und warum, Hot Spots, der Ausführungsplan, die auszuführenden Analysewerkzeuge, Kandidatenstellen pro Prüfpunkt (heißeste Dateien zuerst) und Sonderfallzahlen.

Führe jedes unter Werkzeuge aufgeführte Analysewerkzeug aus, dessen Befehl verfügbar ist, und speichere seine Ausgabe in <ausgabe>/tools/<werkzeug>.txt. Ihre Warnungen sind Hinweise für die Linse, die in der jeweiligen Zeile genannt wird – genauso wie Scan-Stellen; ein Werkzeug, das fehlt oder fehlschlägt, wird in RECON.md vermerkt, niemals installiert.

Schreibe dann <ausgabe>/RECON.md und ergänze, was ein Skript nicht sehen kann. Beende die Phase erst, wenn jede Überschrift eine Antwort oder none hat:

• Grenzen: jeder Ort, an dem externe Daten eintreten (HTTP, Webhooks, DB-Lesevorgänge, Dateien, Umgebungsvariablen, Deep Links, Push-Payloads, Modellausgaben, Benutzereingaben).
• Persistenz: lokale Speicher, Server-DBs, Caches, Warteschlangen und welche Instanz welche Tatsache besitzt.
• Kritische Pfade: Geld, Authentifizierung, Datenlöschung, Migrationen, alles sicherheitsrelevante, die Hauptschleife des Benutzers.
• Befehle: Build, Test, Lint, Run; ob Tests jetzt bestehen.
• Hausregeln: CLAUDE.md/AGENTS.md; die Domänensprache in GLOSSARY.md (oder GLOSSARY-MAP.md), die für jeden Namen in Feststellungen und Korrekturen verwendet wird; ADRs, deren akzeptierte Risiken bestehen bleiben, sofern sich das Risiko nicht geändert hat; der Issue-Tracker in docs/agents/.
• Bedingungen: für jede feuernde Linse, welche bedingten Prüfpunkte hier zutreffen, mit Belegen.
• Linsen-Überschreibungen: eine vom Scan übersprungene Linse, die die Aufklärung für notwendig hält, oder eine Linse, die durch ein falsches Signal ausgelöst wurde, mit Begründung.

Schreibe <ausgabe>/RUN.md: Commit, Datum, Argumente, endgültige Linsenliste.

3. Jagd

Folge dem Plan des Scans: sequentiell führt jede Linse hier nacheinander aus; parallel gibt jeder Linse einen Unteragenten und einer geschredderten Linse einen Unteragenten pro aufgelistetem Paket. Ein Host, der die Nebenläufigkeit begrenzt, führt Wellen aus, wobei die Linsen mit den wenigsten Stellen zuerst gepaart werden; ein Host ohne Unteragenten führt alles sequentiell aus.

Unteragenten starten ohne Fähigkeiten und ohne diese Konversation, daher steht jeder Kurzbefehl für sich allein. Er benennt: die Lens-Datei, diese Datei (für Methoden und Format der Feststellungen), RECON.md, den Abschnitt der Linse in SCAN.md, den Umfang und den Ausgabepfad <ausgabe>/findings/<linse>[-<paket>].md. Jäger sind schreibgeschützte Blätter: Sie lesen Code, führen Tests, Skripte und die Anwendung aus, schreiben nur ihre Feststellungsdatei und Reproduktionen und kehren zum Hauptkontext zurück, der allein die Ausführung steuert.

Methoden

• Pre-mortem: Drei Monate nach dem Start handelt die schlechteste 1-Sterne-Bewertung von diesem Bereich. Schreibe sie, finde dann den Code, der sie verursacht hat.
• Inversion: Wie würdest du dieses Feature so schlecht wie möglich scheitern lassen? Überprüfe die Codeblöcke auf jede Art und Weise.
• Annahmenbuch (Assumption ledger): Liste für jede Funktion auf einem kritischen Pfad auf, was sie annimmt. Welche Annahmen werden durch einen Typ oder eine Einschränkung erzwungen und welche basieren auf Hoffnung?
• Chesterton's fence: Bevor du eine Sicherung, einen Sonderfall oder eine merkwürdige Zeile als Fehler bezeichnest, finde heraus, warum sie existiert (git log -L, Blame, der PR). Ein Zaun mit einem lebendigen Grund ist keine Feststellung.
• Kandidaten sind Hinweise: Eine Scan-Stelle ist ein Ort, um mit dem Lesen zu beginnen. Ein Prüfpunkt ohne Stellen wird trotzdem beantwortet, und eine Stelle wird nur dann zu einer Feststellung, wenn ein konkretes Szenario vorliegt.

Format der Feststellungen

### <LINSE>-<n> <die Behauptung in unter 60 Zeichen>
- where: pfad:zeile
- probe: <Prüfpunkt-ID aus der Lens-Datei>
- scenario: <konkrete Eingabe, Zustand oder Zeitpunkt> → <falsches Ergebnis, das ein Benutzer oder System sieht>
- severity: critical | high | medium | low
- detectability: loud (Crash, Alarm, Test schlägt fehl) | quiet (falsche Antwort, die jemand bemerken könnte) | silent (niemand wird es bemerken)
- verdict: CONFIRMED (<der Test, das Skript, die Abfrage oder der Screenshot, der es reproduziert hat>) | PLAUSIBLE (begründet, nicht ausgeführt)
- fix family: <die Art der Änderung, nicht der Patch>

Schweregrad: critical verliert oder beschädigt Daten, verletzt Sicherheit oder Privatsphäre, behandelt Geld falsch oder gefährdet die Sicherheit; high zeigt eine falsche Antwort oder blockiert den Benutzer auf einem häufigen Pfad; medium tut dies auf einem seltenen Pfad oder beeinträchtigt die Qualität; low ist Hygiene. Der Schweregrad wird danach bestimmt, wer ihn heute in der ausgelieferten Konfiguration auslösen kann: Ein kritisches oder hohes Szenario nennt diese Person (jeder Besucher, jeder angemeldete Benutzer, ein Angreifer mit X); ein Pfad, den nur ein Betreiber oder eine tote Konfiguration erreicht, wird eine Stufe herabgesetzt.

Schwärzen (Redact): Feststellungen, Reproduktionen, Berichte und Tickets werden geteilt. Schreibe <GESCHWÄRZT> anstelle von Geheimnissen, Token oder personenbezogenen Daten und verweise darauf, wo sie leben, anstatt sie zu zitieren.

Eine Feststellungsdatei beginnt mit dem Artefakt der Linse. Jeder Prüfpunkt endet mit mindestens einer Feststellung oder einer clean:-Zeile: clean: <pruefpunkt> — <beleg>, oder für einen bedingten Prüfpunkt, dessen Bedingung nicht zutrifft, clean: <pruefpunkt> — n/a: <warum>. Ein Jäger ist fertig, wenn seine Done-Zeile erfüllt ist und python3 scripts/verify.py <ausgabe> --root <pfad> --lens <linse> bestanden wird.

4. Verifizieren

1. Duplikate zusammenführen: Wenn zwei Feststellungen Ort und Mechanismus teilen, behalte den schwerwiegenderen Block, füge - also: <die anderen IDs> hinzu und lösche den anderen Block, sodass jedes Problem einmal erscheint.
2. Widerlegen (Refute): Jede kritische oder hohe Feststellung erhält einen frischen Widerleger; der Rest wird pro Linse gebündelt. Ein Widerleger erhält nur den Feststellungsblock, niemals die Argumentation des Jägers. Bei einer PLAUSIBLE-Feststellung versucht er, die Behauptung zu widerlegen: eine vorgelagerte Sicherung, eine Einschränkung in der DB, ein unerreichbarer Pfad, ein Zaun mit Grund. Bei einer CONFIRMED-Feststellung prüft er die Reproduktion: Schlägt sie fehl, weil der angegebene Grund durch Code erreicht wird, den ein echter Benutzer oder Angreifer erreicht? Wenn der Host ein anderes Modell anbietet, verwenden die Widerleger es, da gemeinsame Verzerrungen eine Übereinstimmung mit demselben Modell zu einem schwachen Beleg machen.
3. Nach Beleg hochstufen: Überlebt und reproduziert → CONFIRMED; überlebt durch Argumentation → PLAUSIBLE; widerlegt → <ausgabe>/refuted.md mit Begründung.
4. Abdeckungskritiker: Ein frischer Unteragent erhält die kritischen Pfade aus RECON.md und alle clean:-Zeilen jeder Linse und benennt jeden kritischen Pfad, dessen Beleg dünn ist (ein Satz, wo eine Spur oder ein Test nötig gewesen wäre) oder den keine Linse erreicht hat. Jeder geht zur entsprechenden Linse für einen zweiten Blick zurück, bevor der Bericht erstellt wird.

Eine Reproduktion ist eine enge Rückkopplungsschleife, die bei dieser Feststellung fehlschlägt und bei keiner anderen: ein fehlschlagender Test an der nächstgelegenen Nahtstelle, ein Skript, eine Abfrage. Baue eine solche dort, wo sie unter zehn Minuten kostet, in <ausgabe>/repro/, nur gegen lokale, Branch-, Sandbox- oder Testmodus-Systeme. Eine Feststellung, die durch einen Grund widerlegt wird, der auch im nächsten Quartal noch gelten wird (ein akzeptiertes Risiko, ein bewusster Trade-off), gehört in ein ADR, das bei der Auslieferung angeboten wird, damit spätere Audits es in der Aufklärung lesen.

5. Bericht

Schreibe <ausgabe>/REPORT.md:

1. Zusammenfassung: Anzahl nach Schweregrad und Linse sowie die drei Korrekturen, die zuerst vorgenommen werden sollten, mit Begründung.
2. Korrekturen: Gruppiere Feststellungen nach Grundursache, jede Korrektur über den Feststellungen, die sie löst; suche nach der einen Korrektur hinter mehreren Feststellungen, die oft ganz anders aussieht als diese. Markiere jede als structural (Kopplung, Duplizierung, fehlender Typ, flaches Modul, falsch platzierte Nahtstelle) oder local (ein Ort, eine Änderung) und beschreibe strukturelle Korrekturen im Tiefenmodul-Vokabular: Modul, Schnittstelle, Tiefe, Nahtstelle, Adapter, Hebelwirkung, Lokalität, der Löschtest.
3. Nicht geclusterte Feststellungen, geordnet nach Schweregrad, dann Erkennbarkeit (stille zuerst), dann Reichweite.
4. Abdeckung: Alle clean:-Zeilen jeder Linse, übersprungene Linsen mit Gründen, ausgeführte oder fehlende Analysewerkzeuge und was der Abdeckungskritiker zurückgemeldet hat.
5. Seit dem letzten Audit, wenn history/ einen früheren Durchlauf enthält: behoben, noch offen, neu und rückfällig (früher behoben, jetzt wieder da).

- Mache den Server zum alleinigen Schreiber von `scan_count`, atomar dekrementiert mit `where scan_count > 0`, sodass der Client nicht driften, doppelt ausgeben oder zurücksetzen kann. [structural, critical]
  - MONEY-2 `ScanQuota.swift:40` dekrementiert lokal vor dem Upload und erneut bei einem erneuten Versuch.
  - MONEY-3 Eine Neuinstallation der App setzt `scansUsed` im lokalen Speicher auf 0 zurück.
  - STATE-5 Der wöchentliche Kontingent-Rück-Set basiert auf dem lokalen Montag des Geräts, sodass das Fliegen nach Westen eine zweite Woche gewährt.

Führe python3 scripts/verify.py <ausgabe> --root <pfad> aus; der Bericht ist endgültig, wenn er bestanden wird. Wenn der Host strukturierte Feststellungen rendert (ein ReportFindings-Werkzeug), melde auch jede überlebende Feststellung dort, die schwerwiegendste zuerst.

Bereinige den Trichter für dieses Projekt: Eine Seed-Zeile, deren Stellen alle widerlegt oder sauber endeten, oder eine Feststellung, auf die kein Seed verwies, ist ein Vorschlag für die Datei docs/agents/audit-signals.tsv des Projekts. Liste die Vorschläge im Bericht auf; sie werden nur geschrieben, wenn der Benutzer sie annimmt.

6. Ausliefern und Übergeben

Lies DELIVER.md. Zeichne den Bericht als Audit-Karte mit einem Ticket pro Korrektur, typisiert, mit Blockierungskanten, im Issue-Tracker des Repos (lokal .scratch/, wenn keiner konfiguriert ist; bestätige vor dem Posten in einen entfernten Tracker). Frage dann, welche Korrekturen als eine Grillrunde (grilling) begonnen werden sollen: Nummeriere jede als eine Frage mit deiner empfohlenen Antwort, so formuliert, dass „Ja“ sie akzeptiert. Mit --fix übernimm jede Empfehlung. Notiere die genehmigten Ticketnummern in der approved:-Zeile von HANDOFF.md.

Leite jedes Ticket nach seiner Form weiter. Die genannten Fähigkeiten sind von mattpocock-skills; rufe eine mit dem Skill-Werkzeug auf, wenn verfügbar, ansonsten führe ihren Schritt inline aus:

Ticket-Form	Weiterleitung
Benötigt zuerst eine Entscheidung: wo eine Nahtstelle hinkommt, ein ADR, dem sie widerspricht, ein vager Domänenbegriff, ein zu akzeptierendes Risiko	grill-with-docs, das die Antwort als ADR und Glossarbegriffe aufzeichnet
Strukturell, ein Modul, das es wert ist, vor der Umsetzung mit dem Benutzer erkundet zu werden	improve-codebase-architecture in diesem Bereich
Strukturell, konkurrierende Schnittstellendesigns	codebase-design, sein Design-it-twice-Muster
Strukturell, der Weg ist klar und passt in eine Sitzung	UNTANGLE.md, mit dem Ticket und REPORT.md als Startliste
Strukturell, größer als eine Sitzung	wayfinder, das Entscheidungstickets in Richtung Ziel zeichnet
Viele Korrekturen, die für unbeaufsichtigte Agenten aufgeteilt werden sollen	to-tickets (Tracer-Bullet-Slices, Blockierungskanten, breite Refactorings als Expand–Contract), dann implement
Lokale Korrektur	tdd: Die Reproduktion ist der erste rote Test, an einer mit dem Benutzer vereinbarten Nahtstelle; die gesamte Suite bleibt grün
PLAUSIBLE und kritisch, noch keine Reproduktion	diagnosing-bugs Phase 1: Baue zuerst die enge Schleife

Wenn die Front leer ist, führe einen erneuten Audit mit --since <der Audit-Commit> durch. Das Ziel des Audits ist ein erneuter Audit, der ohne überlebende kritische oder hohe Feststellung verifiziert.

Erledigt, wenn

• Jede feuernde Linse eine Feststellungsdatei hat, die ihre Done-Zeile erfüllt, und verify.py für die gesamte Ausgabe bestanden wird.
• Jede überlebende Feststellung einen Ort, Prüfpunkt, ein Szenario, einen Schweregrad, eine Erkennbarkeit und ein Urteil hat; jede widerlegte Feststellung in refuted.md steht.
• REPORT.md jede Feststellung unter einer Korrektur oder in der nicht geclusterten Liste platziert, die Karte ein Ticket pro Korrektur enthält und HANDOFF.md das nächste Ticket benennt.