# StaticCodeAudit — Benutzerhandbuch

## Inhaltsverzeichnis

1. [Schnellstart](#1-schnellstart)
2. [CLI-Referenz](#2-cli-referenz)
3. [Projektkonfiguration](#3-projektkonfiguration-auditconfigjson)
4. [Bericht anpassen](#4-bericht-anpassen)
5. [Falsch-positive unterdrücken](#5-falsch-positive-unterdrücken)
6. [Eigene Regeln](#6-eigene-regeln)
7. [CI/CD-Integration](#7-cicd-integration)
8. [Exportformate](#8-exportformate)

---

## 1. Schnellstart

### Erste Prüfung — keine Konfiguration erforderlich

```bash
./staticcodeaudit-windows-x64.exe /pfad/zu/ihrem/projekt
```

Der Bericht wird in `docs/audit-reports/` im Projektverzeichnis gespeichert.
Öffnen Sie `SCA-REPORT-*.html` in einem beliebigen Browser.

### Projektkonfiguration initialisieren (empfohlen)

```bash
./staticcodeaudit-windows-x64.exe /pfad/zu/ihrem/projekt --init
```

Erstellt `audit.config.json` im Projektstamm mit allen verfügbaren Optionen,
vorausgefüllt und kommentiert. Einmalig konfigurieren, beliebig oft ausführen.

### Lizenzstatus prüfen

```bash
./staticcodeaudit-windows-x64.exe --license-info
```

---

## 2. CLI-Referenz

Der Binärname enthält auf Ihrem System den Plattformsuffix
(z. B. `staticcodeaudit-windows-x64.exe`). Alle Beispiele verwenden `./staticcodeaudit-windows-x64.exe`.

### Scan-Optionen

| Option | Beschreibung | Standard |
|--------|-------------|---------|
| `project_path` | Pfad zum zu prüfenden Projekt | `.` (aktuelles Verzeichnis) |
| `--lang` | Sprache für Bericht und Konsole: `fr`, `en`, `es`, `de` | `en` |
| `--version` | Version ausgeben und beenden | — |
| `--license-info` | Lizenzstatus anzeigen und beenden | — |
| `--no-cache` | Regel-Kompilierungs-Cache deaktivieren (vollständiger Rebuild) | off |
| `--no-incremental` | Inkrementelle Analyse deaktivieren (alle Dateien neu scannen) | off |
| `--no-parallel` | Paralleles Scannen deaktivieren (sequenziell erzwingen) | off |

### Ausgabeoptionen

| Option | Beschreibung |
|--------|-------------|
| `--fail-on-high` | Exit-Code 1 bei HOHEN/KRITISCHEN Befunden (CI/CD-Gate) |
| `--sarif` | SARIF-2.1.0-Datei zusätzlich zum HTML-Bericht erzeugen |
| `--sbom` | CycloneDX-1.5-SBOM erzeugen (Abhängigkeitsinventar) |
| `--with-logs` | Konsolenausgabe in `.log`-Datei speichern |
| `--quiet` | Stiller Modus — nur Fehler und das Endergebnis werden ausgegeben |

### Client-Funktionen

| Option | Beschreibung |
|--------|-------------|
| `--init` | `audit.config.json` interaktiv erstellen oder bearbeiten |
| `--create-rule` | Assistenten zur Erstellung einer eigenen Regel starten |
| `--custom-rules-match` | Prüfen, ob alle eigenen Regeln Test-Fixtures besitzen |
| `--with-tests` | Unit-Tests des Projekts automatisch erkennen und ausführen |
| `--with-deps` | Sicherheits-Scan der Abhängigkeiten ausführen (`pip-audit`, `npm audit`) |

### Häufige Aufrufe

```bash
# Bericht auf Deutsch
./staticcodeaudit-windows-x64.exe /pfad/projekt --lang=de

# Prüfung + SARIF-Export (GitHub / GitLab)
./staticcodeaudit-windows-x64.exe /pfad/projekt --sarif

# Prüfung + Abhängigkeitsscan
./staticcodeaudit-windows-x64.exe /pfad/projekt --with-deps

# Prüfung + Unit-Tests
./staticcodeaudit-windows-x64.exe /pfad/projekt --with-tests

# Stiller Modus für Skripte
./staticcodeaudit-windows-x64.exe /pfad/projekt --quiet

# CI-Pipeline bei HOHEN oder KRITISCHEN Befunden abbrechen
./staticcodeaudit-windows-x64.exe /pfad/projekt --fail-on-high

# Vollständige Kombination für CI
./staticcodeaudit-windows-x64.exe /pfad/projekt --sarif --fail-on-high --quiet --lang=de

# Konsolenausgabe in Log-Datei speichern
./staticcodeaudit-windows-x64.exe /pfad/projekt --with-logs
```

---

## 3. Projektkonfiguration (`audit.config.json`)

Legen Sie `audit.config.json` im Stamm des zu prüfenden Projekts ab.
Erzeugen Sie eine vorausgefüllte Vorlage mit `--init` oder erstellen Sie die Datei manuell.

### Minimales Beispiel

```json
{
  "project": {
    "name": "Meine API",
    "version": "2.0"
  },
  "languages": ["python", "javascript"],
  "paths": {
    "include": ["src/", "api/"],
    "exclude": ["node_modules/", ".venv/", "*.min.js"]
  },
  "reports": {
    "output_dir": "docs/audit-reports",
    "language": "de"
  }
}
```

### Sprachen

Steuert, welche Regelsätze aktiviert werden.

| Wert | Gescannte Dateien |
|------|------------------|
| `python` | `.py` |
| `javascript` | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs` |
| `html` | `.html`, `.htm` |
| `java` | `.java` |
| `csharp` | `.cs` |
| `php` | `.php`, `.inc` |
| `yaml` | `.yml`, `.yaml` (CI/CD-Regeln — Kategorie `cicd` aktivieren) |

### Pfade

```json
"paths": {
  "include": ["src/", "app/", "lib/"],
  "exclude": [
    "node_modules/",
    "vendor/",
    ".venv/",
    "__pycache__/",
    "*.min.js",
    "dist/"
  ]
}
```

`include` listet zu scannende Ordner (relativ zum Projektstamm).
`exclude` unterstützt Ordnernamen, relative Pfade und Glob-Muster.

### Kategorien

Jede Kategorie kann unabhängig aktiviert oder deaktiviert werden. `weight` steuert
den Beitrag zum Gesundheits-Score (1 = gering, 5 = hoch).

```json
"categories": {
  "security":      { "enabled": true,  "weight": 3 },
  "architecture":  { "enabled": true,  "weight": 2 },
  "ui":            { "enabled": true,  "weight": 1 },
  "ux":            { "enabled": true,  "weight": 1 },
  "maintenance":   { "enabled": true,  "weight": 1 },
  "dependencies":  { "enabled": false, "weight": 2 },
  "cicd":          { "enabled": false, "weight": 2 }
}
```

Aktivieren Sie `dependencies` für automatische `pip-audit`/`npm-audit`-Scans.
Aktivieren Sie `cicd` für die Prüfung von GitHub-Actions-/GitLab-CI-Pipelines
(erfordert `yaml` in `languages`).

### Berichte

```json
"reports": {
  "output_dir":   "docs/audit-reports",
  "history_dir":  "docs/audit-reports/audit-datas",
  "max_history":  10,
  "language":     "de"
}
```

`language` steuert die Berichtssprache unabhängig von `--lang`
(die CLI-Option hat Vorrang, wenn beide gesetzt sind).
`max_history` ist die Anzahl vergangener Prüfungen für die Trend-Diagramme.

### Berichtsaufbewahrung

```json
"retention": {
  "mode":      "count",
  "max_count": 20,
  "max_days":  90
}
```

| `mode`-Wert | Verhalten |
|-------------|----------|
| `"count"` | Die `max_count` neuesten Berichte behalten |
| `"days"` | Berichte älter als `max_days` Tage löschen |
| `"both"` | Beide Regeln anwenden |
| `null` | Keine automatische Löschung (Standard) |

### Schwellenwerte

```json
"thresholds": {
  "max_high":       0,
  "max_medium":     10,
  "min_health":     80,
  "health_good":    90,
  "health_warning": 70
}
```

### Test-Integration

```json
"tests": {
  "enabled":   true,
  "tests_dir": "tests/",
  "command":   "python -m pytest {tests_dir} -v --tb=short"
}
```

Aktivieren mit `--with-tests`. `{tests_dir}` wird zur Laufzeit ersetzt.

---

## 4. Bericht anpassen

### Corporate Identity

```json
"brand": {
  "tool_name":     "StaticCodeAudit",
  "company_name":  "Acme GmbH",
  "prefix":        "SCA",
  "logo":          "assets/logo.svg",
  "primary_color": "#1e3a5f",
  "accent_color":  "#2c5282",
  "website_url":   "https://acme.example.de"
}
```

`logo` akzeptiert einen Pfad relativ zum Projektstamm oder einen absoluten Pfad.
Unterstützte Formate: SVG, PNG, JPG.

### Berichts-Header

```json
"project": {
  "name":        "Acme Backend",
  "version":     "3.1",
  "description": "REST-API — Zahlungsabwicklungsdienst"
}
```

### Ausgabeverzeichnis

```json
"reports": {
  "output_dir": "docs/audit-reports"
}
```

Das Verzeichnis wird automatisch erstellt. Berichte werden benannt:
`SCA-REPORT-YYYY-MM-DD-HH-MM.html`.

---

## 5. Falsch-positive unterdrücken

### Methode 1 — Inline-Kommentar

Fügen Sie `# sca-ignore` am Ende der markierten Zeile ein, um alle Regeln zu unterdrücken:

```python
password = hashlib.md5(token).hexdigest()  # sca-ignore
```

Um nur eine bestimmte Regel zu unterdrücken:

```python
password = hashlib.md5(token).hexdigest()  # sca-ignore:weak_hash
```

Funktioniert in Python-, JavaScript-, TypeScript-, Java-, C#- und PHP-Dateien.

### Methode 2 — Konfigurationsdatei (dauerhaft)

```json
"rules": {
  "suppress": [
    {
      "rule": "weak_hash",
      "file": "src/legacy/auth.py",
      "reason": "MD5 wird nur als Cache-Schlüssel ohne Sicherheitsbezug verwendet"
    },
    {
      "rule": "console.log",
      "file": "src/debug/logger.js"
    }
  ]
}
```

### Methode 3 — Deaktivierte Regeln (global)

```json
"rules": {
  "disabled": ["TODO/FIXME", "console.log", "hardcoded_secret"]
}
```

Deaktivierte Regeln erscheinen in keinem Bericht. Mit Vorsicht verwenden.

---

## 6. Eigene Regeln

Schreiben Sie projektspezifische Regeln, ohne die eingebauten Regeln zu ändern.
Eigene Regeln werden in `custom-rules/` neben dem Binär gespeichert
und durch Updates nie überschrieben.

### Assistenten starten

```bash
./staticcodeaudit-windows-x64.exe /pfad/projekt --create-rule
```

Der Assistent führt durch: Regelname, Kategorie, Zielsprache, Schweregrad,
Erkennungsmuster, Beschreibungen in 4 Sprachen und Korrekturbeispiele.
Erneutes Ausführen von `--create-rule` bei einer vorhandenen Regel öffnet den Editor vorausgefüllt.

### Regelabdeckung prüfen

```bash
./staticcodeaudit-windows-x64.exe /pfad/projekt --custom-rules-match
```

---

## 7. CI/CD-Integration

### GitHub Actions

```yaml
- name: Static Code Audit
  run: |
    chmod +x ./staticcodeaudit-linux-x64
    ./staticcodeaudit-linux-x64 . --sarif --fail-on-high --quiet
  continue-on-error: false

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: docs/audit-reports/SCA-REPORT-*.sarif
```

### GitLab CI

```yaml
sca:
  script:
    - chmod +x ./staticcodeaudit-linux-x64
    - ./staticcodeaudit-linux-x64 . --sarif --fail-on-high --quiet
  artifacts:
    reports:
      sast: docs/audit-reports/SCA-REPORT-*.sarif
```

### Exit-Codes

| Code | Bedeutung |
|------|----------|
| `0` | Prüfung erfolgreich |
| `1` | HOHE/KRITISCHE Befunde erkannt (nur mit `--fail-on-high`) |
| `2` | Konfigurationsfehler oder fehlende Pflichtdatei |

---

## 8. Exportformate

### HTML (immer erzeugt)

Interaktiver Bericht mit Diagrammen, Schweregrad-Aufschlüsselung, Trendverlauf
und Behebungshinweisen je Befund. Im Browser öffnen — kein Server erforderlich.

Speicherort: `docs/audit-reports/SCA-REPORT-YYYY-MM-DD-HH-MM.html`

### SARIF 2.1.0

```bash
./staticcodeaudit-windows-x64.exe /pfad/projekt --sarif
```

Unterstützt von GitHub Code Scanning, GitLab SAST, VS Code (SARIF-Viewer-Erweiterung),
Azure DevOps, SonarQube und Checkmarx.

Speicherort: `docs/audit-reports/SCA-REPORT-YYYY-MM-DD-HH-MM.sarif`

### CycloneDX SBOM

```bash
./staticcodeaudit-windows-x64.exe /pfad/projekt --sbom
```

Software Bill of Materials im CycloneDX-1.5-JSON-Format. Listet alle erkannten
Abhängigkeiten mit Versionsinformationen — nützlich für Supply-Chain-Audits,
Compliance-Nachweise und Lizenzinventarisierung.

Speicherort: `docs/audit-reports/SCA-SBOM-YYYY-MM-DD-HH-MM.json`

> Die Verfügbarkeit von SARIF und SBOM hängt von Ihrem Lizenz-Tier ab.
> Wenden Sie sich an support@codefixture.com für Details.

---

*StaticCodeAudit von CodeFixture — Building Trust in Every Line.*
Support: support@codefixture.com
