Spezifikation: Custom Rules — Erstellung benutzerdefinierter Regeln

Zweck

Kunden in die Lage versetzen, eigene Erkennungsregeln zu erstellen, zu testen und auszurollen, ohne Kenntnisse des internen Formats, der Regex-Syntax oder der Architektur der Analyse-Engine zu benötigen.

1. Überblick

Drei sich ergänzende Werkzeuge

Werkzeug	Befehl	Funktion
Assistent	`--create-rule`	Schrittweise geführte Erstellung, ohne erforderliches technisches Vorwissen
Schnelltest	`--test-rule <id>`	Sofortige Rückmeldung zu einer Regel, ohne vollständigen Audit
Beispiele	`--init-rule --examples`	Lernen anhand von Beispielen (kommentierte .sca-Dateien)

Vorhandene Werkzeuge (bereits implementiert)

Werkzeug	Befehl	Funktion
Gerüst	`--init-rule <id>`	Erzeugt eine leere, vorbefüllte .sca-Datei
Validierung	`--rules-validate`	Validiert sämtliche Custom-Regeln (Syntax, Regex, Felder)
Auflistung	`--rules-list`	Zeigt alle geladenen Regeln an (builtin + custom)

2. Interaktiver Assistent (`--create-rule`)

2.1 Benutzer-Workflow

$ ./staticcodeaudit /mein/projekt --create-rule

  StaticCodeAudit — Regelerstellung

? Regelname (snake_case): detect_console_error

? Zielsprache:
  > python
    javascript
    java
    csharp
    php
    html
    yaml

? Wonach soll im Code gesucht werden?
  Geben Sie den zu erkennenden Text oder das Pattern ein.
  Beispiele: "TODO", "console.error", "SELECT.*FROM.*WHERE"
  > console.error(

? Suchbereich:
  > Jede Zeile einzeln (line)
    Fenster von 4 Zeilen (context-4)
    Fenster von 6 Zeilen (context-6)

? Schweregrad:
  > LOW — Bewährte Praxis, vorgeschlagene Verbesserung
    MEDIUM — Problem, das in angemessener Frist behoben werden sollte
    HIGH — Kritisches Problem, sofort zu beheben

? Muss die Datei ein bestimmtes Pattern enthalten?
  (Vorbedingung — leer lassen, um zu überspringen)
  > 

? Darf die Datei NICHT enthalten?
  (Ausschluss — leer lassen, um zu überspringen)
  > 

? Kurzbeschreibung (Englisch): Residual console.error call
? Kurzbeschreibung (Französisch): Appel console.error residuel
? Risiko (Englisch): Error logging in production exposes internal state.
? Lösung (Englisch): Remove console.error or use a proper logging framework.

  Vorschau der Regel:

  rule detect_console_error
    language  javascript
    severity  LOW

    match
      pattern  console\.error\(
      scope    line
    end

    message
      en "Residual console.error call"
      fr "Appel console.error residuel"
    end
  end

? Diese Regel anlegen? (J/n): J

  Regel angelegt: audit-rules/detect_console_error.sca
  Validiert: 1 pattern, scope line, LOW

  Nächste Schritte:
  1. Testen Sie sie: ./staticcodeaudit /mein/projekt --test-rule detect_console_error
  2. Führen Sie den vollständigen Audit aus, um diese Regel in den Bericht aufzunehmen

2.2 Verhalten des Assistenten

Automatisches Regex-Escaping

Der Kunde tippt reinen Text. Der Assistent escaped die regex-spezifischen Sonderzeichen automatisch:

Eingabe des Kunden	Erzeugte Regex	Erläuterung
`console.error(`	`console\.error\(`	Punkt und Klammer escaped
`System.out.println`	`System\.out\.println`	Punkte escaped
`SELECT.*FROM`	`SELECT.*FROM`	`.*` als beabsichtigt erkannt
`\bfoo\b`	`\bfoo\b`	Regex-Konstrukt erhalten

Escaping-Regeln:

Die Zeichen (, ), [, ], {, }, ., +, ?, ^, $, |, \ werden automatisch escaped
AUSGENOMMEN, der Kunde verwendet explizite Regex-Konstrukte: .*, .+, \s, \w, \d, \b, [...], (a|b)
Der Assistent erkennt diese Konstrukte und behält sie unverändert bei
Im Zweifelsfall fragt der Assistent: "Das sieht nach einer Regex aus. So verwenden? (J/n)"

Validierung in Echtzeit

Jede Antwort wird unmittelbar validiert:

Name: [a-z][a-z0-9_]* — andernfalls Fehlermeldung und erneute Abfrage
Pattern: wird als Regex kompiliert — bei Fehler wird die Fehlermeldung angezeigt und erneut abgefragt
Schweregrad: Auswahl aus den 3 Werten — keine freie Eingabe

Erweiterter Modus (optional)

Wenn der Kunde --create-rule --advanced eingibt, erscheinen zusätzliche Fragen:

Confidence (0-100, Standardwert 80)
Pattern-not (Ausschluss-Pattern — "NICHT erkennen, wenn diese Zeile enthält ...")
Codebase-Scope (für requires — Prüfung über die Gesamtheit der Dateien, nicht datei-weise)
CWE/OWASP-Metadaten (Konformität)

2.3 Fehlerbehandlung

Situation	Verhalten
Name bereits vergeben	"Dieser Name existiert bereits. Wählen Sie einen anderen Namen."
Ungültige Regex	"Pattern ungültig: [Fehler]. Korrigieren Sie es oder geben Sie einfachen Text ein."
Strg+C	"Abgebrochen. Es wurde keine Datei angelegt."
Fehlendes Verzeichnis audit-rules/	Wird automatisch angelegt

3. Schnelltest (`--test-rule <id>`)

3.1 Benutzer-Workflow

$ ./staticcodeaudit /mein/projekt --test-rule detect_console_error

  Test der Regel 'detect_console_error' an 42 Dateien ...

  src/components/App.jsx:18      — console.error("Failed to load", err);
  src/utils/api.js:67            — console.error(response.statusText);
  src/utils/api.js:102           — console.error("Network error:", e);

  3 Findings in 2 Dateien erkannt (0.2s)

3.2 Verhalten

Lädt AUSSCHLIESSLICH die angeforderte Regel (keine builtin, keine anderen custom)
Scannt die Dateien der entsprechenden Sprache in paths.include
Zeigt jedes Finding an: Datei, Zeile, Code
Kein HTML-Bericht, keine Baseline, kein JSON-Export
Misst die Ausführungszeit
Exit-Code: 0 bei mindestens 1 Finding, 1 bei 0 Findings

3.3 Optionen

Option	Verhalten
`--test-rule <id>`	Testet die Regel in `audit-rules/`
`--test-rule <id> --file src/app.py`	Testet an einer einzelnen Datei
`--test-rule <id> --verbose`	Zeigt zusätzlich gescannte Dateien ohne Treffer an

3.4 Fehlerfälle

Situation	Verhalten
Regel nicht gefunden	"Regel 'xxx' in audit-rules/ nicht gefunden. Verfügbare Regeln: ..."
Ungültige Regel	Zeigt die Validierungsfehler an (wie --rules-validate)
0 Dateien der Sprache	"Keine .py-Datei in den konfigurierten Pfaden gefunden."

4. Kommentierte Beispiele (`--init-rule --examples`)

4.1 Installation

$ ./staticcodeaudit /mein/projekt --init-rule --examples

  5 Beispiele in audit-rules/_examples/ installiert
    01_simple_pattern.sca       — Erkennung eines einfachen Schlüsselworts
    02_multiline_context.sca    — Pattern über mehrere Zeilen
    03_file_condition.sca       — match + requires (Kombination)
    04_exclusion_pattern.sca    — Erkennen, sofern nicht safe
    05_requires_only.sca        — Reine Datei-Bedingung

    Führen Sie aus: ./staticcodeaudit /mein/projekt --rules-validate
    um zu prüfen, dass die Beispiele gültig sind.

4.2 Inhalt der Beispiele

01_simple_pattern.sca

Erkennt console.log() in JavaScript.
Einfachstes Format: ein Pattern auf einer einzigen Zeile.

02_multiline_context.sca

Erkennt .execute(f"...") in Python über 4 Zeilen (scope context-4).
Das Schlüsselwort "with" fügt eine AND-Bedingung im selben Fenster hinzu.

03_file_condition.sca

Kombiniert match + requires: erkennt Flask() ausschließlich in
Dateien, die CSRFProtect nicht importieren.
Das Finding bezieht sich auf die genaue Zeile von Flask(), nicht auf Zeile 1.

04_exclusion_pattern.sca

Erkennt hashlib.md5() AUSSER wenn "usedforsecurity=False" vorhanden ist.
Das Schlüsselwort "pattern-not" schließt Zeilen aus, die das sichere Pattern enthalten.

05_requires_only.sca

Ein eigenständiger requires-Block (ohne match) erzeugt ein Finding auf File-Level (Zeile 1).
Erkennt Django-Dateien mit MIDDLEWARE, aber ohne HSTS.

5. Tier-basiertes Gating (Lizenz)

Tier	Eigene Regeln	Funktionen
Demo	0	Keine eigenen Regeln
Solo	20 regex	`--create-rule`, `--test-rule`, `--rules-validate`
Team	100 regex + 30 taint	Wie Solo + erweiterte Beispiele
Enterprise	Unbegrenzt	Alles + verschlüsselte Regeln