michaelschiemer/docs/guides/security.md

# Sicherheits-Anleitung

Diese Anleitung erklärt die Sicherheitsfunktionen des Frameworks und wie Sie sie effektiv nutzen können, um Ihre Anwendung zu schützen.

## Überblick über die Sicherheitsarchitektur

Das Framework bietet eine mehrschichtige Sicherheitsarchitektur, die verschiedene Schutzmaßnahmen auf verschiedenen Ebenen implementiert:

1. **Eingabevalidierung**: Validierung aller Benutzereingaben, um Injection-Angriffe zu verhindern.
2. **Ausgabebereinigung**: Automatische Bereinigung von Ausgaben, um Cross-Site Scripting (XSS) zu verhindern.
3. **CSRF-Schutz**: Schutz vor Cross-Site Request Forgery.
4. **Authentifizierung**: Flexible Authentifizierungsmechanismen.
5. **Autorisierung**: Rollenbasierte und fähigkeitsbasierte Zugriffskontrolle.
6. **Web Application Firewall (WAF)**: Integrierte WAF zum Schutz vor gängigen Angriffen.
7. **Sicherheitsheader**: Automatische Konfiguration von Sicherheitsheadern.
8. **Sichere Konfiguration**: Sichere Standardeinstellungen und Best Practices.

## Eingabevalidierung

Die Eingabevalidierung ist die erste Verteidigungslinie gegen Injection-Angriffe. Das Framework bietet ein leistungsstarkes Validierungssystem, das in der [Validierungs-Anleitung](validation.md) ausführlich beschrieben wird.

### Beispiel für die Validierung von Benutzereingaben

```php
public function store(Request $request): Response
{
    $this->validate($request, [
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users,email',
        'password' => 'required|string|min:8',
        'website' => 'nullable|url',
        'age' => 'nullable|integer|min:18',
    ]);
    
    // Die Validierung wurde bestanden, fahren Sie mit der Speicherung fort
    $user = User::create($request->only(['name', 'email', 'password']));
    
    return $this->redirect('/users')->with('success', 'Benutzer erstellt');
}
```

### Schutz vor SQL-Injection

Das Framework verwendet parametrisierte Abfragen und Prepared Statements, um SQL-Injection-Angriffe zu verhindern:

```php
// Sicher: Verwendung von parametrisierten Abfragen
$users = DB::table('users')
    ->where('email', $request->input('email'))
    ->get();

// Sicher: Verwendung des Query Builders
$users = User::where('email', $request->input('email'))->get();

// Sicher: Verwendung von Prepared Statements
$statement = DB::prepare('SELECT * FROM users WHERE email = ?');
$statement->execute([$request->input('email')]);
$users = $statement->fetchAll();
```

## Ausgabebereinigung

### Automatische Bereinigung in Views

Das Framework bereinigt automatisch alle Ausgaben in Views, um XSS-Angriffe zu verhindern:

```php
<!-- Sicher: Automatische Bereinigung -->
<div><?= $user->name ?></div>

<!-- Unsicher: Rohe Ausgabe ohne Bereinigung (nur verwenden, wenn Sie sicher sind, dass der Inhalt vertrauenswürdig ist) -->
<div><?= raw($user->html_content) ?></div>
```

### Manuelle Bereinigung

Sie können auch manuell Daten bereinigen:

```php
use App\Framework\Security\Sanitizer;

// Text bereinigen
$cleanText = Sanitizer::clean($input);

// HTML bereinigen (entfernt gefährliche Tags und Attribute)
$cleanHtml = Sanitizer::cleanHtml($input);

// URL bereinigen
$cleanUrl = Sanitizer::cleanUrl($input);
```

## CSRF-Schutz

Das Framework bietet automatischen Schutz vor Cross-Site Request Forgery (CSRF) für alle Formulare und AJAX-Anfragen.

### CSRF-Token in Formularen

```php
<form method="POST" action="/users">
    <?= csrf_field() ?>
    <input type="text" name="name">
    <button type="submit">Speichern</button>
</form>
```

Die `csrf_field()`-Funktion generiert ein verstecktes Eingabefeld mit einem CSRF-Token:

```html
<input type="hidden" name="_token" value="random-token-here">
```

### CSRF-Token in AJAX-Anfragen

```javascript
// Mit jQuery
$.ajax({
    url: '/users',
    type: 'POST',
    data: {
        name: 'John Doe',
        _token: '<?= csrf_token() ?>'
    }
});

// Mit Fetch API
fetch('/users', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-TOKEN': '<?= csrf_token() ?>'
    },
    body: JSON.stringify({
        name: 'John Doe'
    })
});
```

### CSRF-Schutz deaktivieren

In einigen Fällen, wie z.B. bei API-Endpunkten, möchten Sie möglicherweise den CSRF-Schutz deaktivieren:

```php
// In der Middleware-Konfiguration
$middleware->except([
    CsrfMiddleware::class => [
        '/api/*'
    ]
]);
```

## Authentifizierung

Das Framework bietet ein flexibles Authentifizierungssystem, das verschiedene Authentifizierungsmethoden unterstützt.

### Benutzerauthentifizierung

```php
use App\Framework\Auth\Auth;

class LoginController extends Controller
{
    public function login(Request $request): Response
    {
        $this->validate($request, [
            'email' => 'required|email',
            'password' => 'required|string',
        ]);
        
        $credentials = $request->only(['email', 'password']);
        $remember = $request->input('remember', false);
        
        if (Auth::attempt($credentials, $remember)) {
            return $this->redirect('/dashboard');
        }
        
        return $this->back()->withErrors([
            'email' => 'Die angegebenen Anmeldeinformationen sind ungültig.',
        ]);
    }
    
    public function logout(): Response
    {
        Auth::logout();
        
        return $this->redirect('/');
    }
}
```

### Zugriff auf den authentifizierten Benutzer

```php
// Prüfen, ob ein Benutzer angemeldet ist
if (Auth::check()) {
    // Benutzer ist angemeldet
}

// Aktuellen Benutzer abrufen
$user = Auth::user();

// Benutzer-ID abrufen
$userId = Auth::id();
```

### Passwort-Hashing

Das Framework verwendet automatisch sichere Passwort-Hashing-Algorithmen:

```php
use App\Framework\Security\Hash;

// Passwort hashen
$hashedPassword = Hash::make('password');

// Passwort überprüfen
if (Hash::check('password', $hashedPassword)) {
    // Passwort ist korrekt
}

// Prüfen, ob ein Passwort neu gehasht werden muss
if (Hash::needsRehash($hashedPassword)) {
    $hashedPassword = Hash::make('password');
}
```

### Passwort-Zurücksetzung

Das Framework bietet auch Unterstützung für die Passwort-Zurücksetzung:

```php
use App\Framework\Auth\Password;

// Token für die Passwort-Zurücksetzung erstellen
$token = Password::createToken($user);

// E-Mail mit dem Token senden
Mail::send('emails.reset-password', [
    'token' => $token,
    'user' => $user
], function ($message) use ($user) {
    $message->to($user->email);
    $message->subject('Passwort zurücksetzen');
});

// Token überprüfen und Passwort zurücksetzen
$status = Password::reset($request->only(
    'email', 'password', 'password_confirmation', 'token'
), function ($user, $password) {
    $user->password = Hash::make($password);
    $user->save();
});
```

## Autorisierung

Das Framework bietet ein leistungsstarkes Autorisierungssystem, das rollenbasierte und fähigkeitsbasierte Zugriffskontrolle unterstützt.

### Rollenbasierte Zugriffskontrolle

```php
use App\Framework\Auth\Auth;

// Prüfen, ob der Benutzer eine bestimmte Rolle hat
if (Auth::user()->hasRole('admin')) {
    // Benutzer ist ein Administrator
}

// Prüfen, ob der Benutzer eine von mehreren Rollen hat
if (Auth::user()->hasAnyRole(['admin', 'editor'])) {
    // Benutzer ist entweder Administrator oder Editor
}

// Prüfen, ob der Benutzer alle angegebenen Rollen hat
if (Auth::user()->hasAllRoles(['admin', 'editor'])) {
    // Benutzer ist sowohl Administrator als auch Editor
}
```

### Fähigkeitsbasierte Zugriffskontrolle

```php
use App\Framework\Auth\Auth;

// Prüfen, ob der Benutzer eine bestimmte Fähigkeit hat
if (Auth::user()->can('edit-post', $post)) {
    // Benutzer kann den Beitrag bearbeiten
}

// Prüfen, ob der Benutzer eine Fähigkeit nicht hat
if (Auth::user()->cannot('delete-post', $post)) {
    // Benutzer kann den Beitrag nicht löschen
}

// Autorisierung erzwingen (wirft eine Exception, wenn nicht autorisiert)
Auth::user()->authorize('edit-post', $post);
```

### Richtlinien definieren

Sie können Autorisierungsrichtlinien definieren, um komplexe Autorisierungslogik zu kapseln:

```php
use App\Framework\Auth\Policy;

class PostPolicy extends Policy
{
    public function view(User $user, Post $post): bool
    {
        return true; // Jeder kann Beiträge sehen
    }
    
    public function create(User $user): bool
    {
        return $user->hasRole('writer');
    }
    
    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id || $user->hasRole('editor');
    }
    
    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->user_id || $user->hasRole('admin');
    }
}
```

Registrieren Sie die Richtlinie:

```php
use App\Framework\Auth\Gate;

// In der Bootstrap-Datei
Gate::policy(Post::class, PostPolicy::class);
```

Verwenden Sie die Richtlinie:

```php
if (Auth::user()->can('update', $post)) {
    // Benutzer kann den Beitrag aktualisieren
}
```

### Autorisierung in Controllern

Sie können die Autorisierung auch direkt in Controllern verwenden:

```php
public function update(Request $request, int $id): Response
{
    $post = Post::find($id);
    
    if (!$post) {
        return $this->notFound('Beitrag nicht gefunden');
    }
    
    $this->authorize('update', $post);
    
    // Beitrag aktualisieren
    
    return $this->redirect('/posts')->with('success', 'Beitrag aktualisiert');
}
```

## Web Application Firewall (WAF)

Das Framework enthält eine integrierte Web Application Firewall (WAF), die Ihre Anwendung vor gängigen Angriffen schützt.

### WAF-Konfiguration

Die WAF ist standardmäßig aktiviert und kann in der Konfigurationsdatei `config/security.php` konfiguriert werden:

```php
return [
    'waf' => [
        'enabled' => true,
        'rules' => [
            'sql_injection' => true,
            'xss' => true,
            'command_injection' => true,
            'path_traversal' => true,
            'request_validation' => true,
        ],
        'whitelist' => [
            'ip' => [
                '127.0.0.1',
                '::1',
            ],
            'paths' => [
                '/api/webhook',
            ],
        ],
        'blacklist' => [
            'ip' => [
                // Blockierte IP-Adressen
            ],
            'user_agents' => [
                'Bad Bot',
            ],
        ],
        'rate_limiting' => [
            'enabled' => true,
            'max_requests' => 100,
            'time_window' => 60, // Sekunden
        ],
    ],
];
```

### Maschinelles Lernen für die Angriffserkennung

Die WAF verwendet auch maschinelles Lernen, um Anomalien zu erkennen und potenzielle Angriffe zu identifizieren:

```php
use App\Framework\Waf\MachineLearning\MachineLearningEngine;

// In einem Controller oder Service
$mlEngine = $this->container->get(MachineLearningEngine::class);
$anomalyScore = $mlEngine->detectAnomalies($request);

if ($anomalyScore > 0.8) {
    // Verdächtige Anfrage protokollieren oder blockieren
    $this->logger->warning('Verdächtige Anfrage erkannt', [
        'ip' => $request->ip(),
        'path' => $request->path(),
        'score' => $anomalyScore,
    ]);
}
```

## Sicherheitsheader

Das Framework konfiguriert automatisch wichtige Sicherheitsheader, um Ihre Anwendung zu schützen.

### Content Security Policy (CSP)

Die Content Security Policy schützt vor XSS-Angriffen, indem sie kontrolliert, welche Ressourcen geladen werden dürfen:

```php
use App\Framework\Security\ContentSecurityPolicy;

// In einem Middleware oder Controller
$csp = new ContentSecurityPolicy();
$csp->setDefaultSrc(['self'])
    ->setScriptSrc(['self', 'trusted-scripts.com'])
    ->setStyleSrc(['self', 'trusted-styles.com'])
    ->setImgSrc(['self', 'trusted-images.com'])
    ->setFontSrc(['self', 'trusted-fonts.com'])
    ->setConnectSrc(['self', 'api.trusted-domain.com'])
    ->setFrameSrc(['none'])
    ->setObjectSrc(['none'])
    ->setReportUri('/csp-report');

$response->headers->set('Content-Security-Policy', $csp->compile());
```

### Andere Sicherheitsheader

Das Framework setzt auch andere wichtige Sicherheitsheader:

```php
// In einem Middleware oder Controller
$response->headers->set('X-Content-Type-Options', 'nosniff');
$response->headers->set('X-Frame-Options', 'DENY');
$response->headers->set('X-XSS-Protection', '1; mode=block');
$response->headers->set('Referrer-Policy', 'strict-origin-when-cross-origin');
$response->headers->set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
```

## Sichere Konfiguration

### HTTPS erzwingen

Sie können HTTPS für Ihre Anwendung erzwingen:

```php
// In der Middleware-Konfiguration
$middleware->add(HttpsMiddleware::class);
```

### Sichere Cookies

Das Framework konfiguriert automatisch sichere Cookies:

```php
// In der Konfigurationsdatei config/session.php
return [
    'cookie' => [
        'secure' => true,
        'http_only' => true,
        'same_site' => 'lax',
    ],
];
```

### Sichere Datei-Uploads

Das Framework bietet Funktionen für sichere Datei-Uploads:

```php
use App\Framework\Security\FileValidator;

// In einem Controller
$this->validate($request, [
    'document' => 'required|file|mimes:pdf,doc,docx|max:10240',
]);

$file = $request->file('document');

// Zusätzliche Sicherheitsvalidierung
$validator = new FileValidator();
if (!$validator->isSafe($file)) {
    return $this->back()->withErrors([
        'document' => 'Die Datei ist möglicherweise schädlich.',
    ]);
}

// Datei speichern
$path = $file->store('documents');
```

## Sicherheitsprotokollierung und -überwachung

Das Framework bietet umfangreiche Protokollierung für Sicherheitsereignisse:

```php
use App\Framework\Security\SecurityLogger;

// In einem Controller oder Service
$securityLogger = $this->container->get(SecurityLogger::class);

// Sicherheitsereignis protokollieren
$securityLogger->log('authentication_failure', [
    'user_id' => $user->id,
    'ip' => $request->ip(),
    'user_agent' => $request->userAgent(),
]);
```

### Sicherheitsbenachrichtigungen

Sie können auch Benachrichtigungen für wichtige Sicherheitsereignisse konfigurieren:

```php
use App\Framework\Security\SecurityNotifier;

// In einem Controller oder Service
$securityNotifier = $this->container->get(SecurityNotifier::class);

// Benachrichtigung senden
$securityNotifier->notify('suspicious_login', [
    'user_id' => $user->id,
    'ip' => $request->ip(),
    'location' => $geoip->getLocation($request->ip()),
    'time' => now(),
]);
```

## Sicherheits-Checkliste

Hier ist eine Checkliste, um sicherzustellen, dass Ihre Anwendung sicher ist:

1. **Eingabevalidierung**: Validieren Sie alle Benutzereingaben.
2. **Ausgabebereinigung**: Bereinigen Sie alle Ausgaben, um XSS zu verhindern.
3. **CSRF-Schutz**: Verwenden Sie CSRF-Token in allen Formularen und AJAX-Anfragen.
4. **Authentifizierung**: Implementieren Sie sichere Authentifizierungsmechanismen.
5. **Autorisierung**: Implementieren Sie rollenbasierte und fähigkeitsbasierte Zugriffskontrolle.
6. **Sichere Passwörter**: Verwenden Sie sichere Passwort-Hashing-Algorithmen.
7. **HTTPS**: Erzwingen Sie HTTPS für Ihre Anwendung.
8. **Sichere Cookies**: Konfigurieren Sie sichere Cookies.
9. **Sicherheitsheader**: Setzen Sie wichtige Sicherheitsheader.
10. **Datei-Uploads**: Validieren Sie Datei-Uploads sorgfältig.
11. **Fehlerbehandlung**: Zeigen Sie keine sensiblen Informationen in Fehlermeldungen an.
12. **Protokollierung**: Protokollieren Sie Sicherheitsereignisse.
13. **Aktualisierungen**: Halten Sie das Framework und alle Abhängigkeiten aktuell.

## Weitere Informationen

- [Authentifizierungs-Anleitung](authentication.md): Erfahren Sie mehr über die Authentifizierungsfunktionen des Frameworks.
- [Autorisierungs-Anleitung](authorization.md): Erfahren Sie mehr über die Autorisierungsfunktionen des Frameworks.
- [WAF-Anleitung](../components/waf/index.md): Erfahren Sie mehr über die Web Application Firewall des Frameworks.
- [Validierungs-Anleitung](validation.md): Erfahren Sie mehr über die Validierungsfunktionen des Frameworks.
- [Architekturübersicht](../architecture/overview.md): Überblick über die Architektur des Frameworks.