Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions README-DE.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ System-Tray-Launcher für die drei Universal Mail Tools.
[![Tests: 90 bestanden](https://img.shields.io/badge/tests-90%20bestanden-brightgreen.svg)](tests/)
[![Sicherheit: Richtlinie](https://img.shields.io/badge/sicherheit-SECURITY.md-blue.svg)](SECURITY.md)
[![Sicherheits-SLA: 48h Reaktion](https://img.shields.io/badge/sicherheits--SLA-48h%20Reaktion-blue.svg)](SECURITY.md)
[![Datenschutz: 100% Local--First](https://img.shields.io/badge/datenschutz-100%25%20Local--First-blueviolet.svg)](SECURITY.md)
[![Datenschutzhinweis: Entwurf](https://img.shields.io/badge/datenschutz-hinweis%20entwurf-blue.svg)](docs/PRIVACY_POLICY_DRAFT.md)
[![Code-Stil: ruff](https://img.shields.io/badge/code--stil-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Dachverband: open-bricks](https://img.shields.io/badge/dachverband-open--bricks-blue.svg)](https://github.com/open-bricks)
[![LLM Ready](https://img.shields.io/badge/LLM--Ready-llms.txt-brightgreen.svg)](llms.txt)
Expand Down Expand Up @@ -66,6 +66,10 @@ MailProcessor sitzt im Windows-System-Tray und gibt per Rechtsklick Zugang zu:
- Autostart mit Windows (Registry-Eintrag)
- Zweisprachig: Deutsch / Englisch

### Daten- und Netzwerkumfang

MailProcessor speichert seine Launcher-Konfiguration auf dem Gerät. Startet der Benutzer im Einrichtungsassistenten einen Werkzeug-Download, fragt der Launcher Release-Metadaten bei GitHub ab und lädt das Release-Archiv des Werkzeugs herunter. Im geprüften Launcher-Quellstand wurde keine Telemetrie-Implementierung gefunden. Die separat gestarteten Mailwerkzeuge haben eigene Datenflüsse; dieser Befund beschreibt oder begrenzt deren Netzwerkverhalten nicht. Siehe den [Prüfentwurf der Datenschutzhinweise](docs/PRIVACY_POLICY_DRAFT.md).

## Systemarchitektur & Workflow

```mermaid
Expand Down Expand Up @@ -188,16 +192,16 @@ werden in [RELEASES.md](RELEASES.md#current-platform-scope-2026-08-26) nachverfo

## Governance & Laufzeit-Invarianten

Die folgenden Invarianten definieren die Betriebs- und Sicherheitsgarantien von MailProcessor:
Die folgenden Kennungen fassen beobachtetes Produktverhalten und Sicherheitsgrenzen zusammen:

| Invarianten-ID | Bezeichnung | Richtlinie / Standard | Verifikation & Garantie |
| Invarianten-ID | Bezeichnung | Richtlinie / Standard | Beobachtetes Verhalten |
|---|---|---|---|
| `INV-LOCAL-01` | **100% Local-First & Zero Egress** | Offline-Datenschutzstandard | Läuft vollständig auf dem lokalen System. Keine Telemetrie, keine Cloud-Weiterleitung, keine Speicherung von Mail-Inhalten, Passwörtern oder Zugangsdaten. |
| `INV-DATA-01` | **Daten- und Netzwerkumfang des Launchers** | Beobachtetes Quellverhalten | Launcher-Einstellungen werden lokal gespeichert. Vom Benutzer gestartete Werkzeug-Downloads kontaktieren GitHub Releases; separat gestartete Werkzeuge haben eigene Datenflüsse. Im geprüften Launcher-Quellstand wurde keine Telemetrie-Implementierung gefunden. |
| `INV-NOELEV-02` | **Keine Rechteerweiterung (RunAsInvoker)** | Windows Least-Privilege-Prinzip | Läuft ausnahmslos als Standardbenutzer ohne UAC-Elevation (`runAsInvoker`). |
| `INV-ZIPSLIP-03` | **Zip-Slip-Schutz gegen Pfadüberquerung** | CWE-22 Sicherheitsstandard | GitHub-Release-Downloads validieren alle Archivpfade vor dem Entpacken, um Verzeichnisüberquerungen auszuschließen. |
| `INV-CFGISO-04` | **Lokale AppData-Isolation** | Windows AppData Konvention | Konfiguration liegt isoliert unter `%LOCALAPPDATA%\MailProcessor\config.json`. Keine Registry-Verschmutzung außer dem optionalen Benutzer-Autostart. |
| `INV-PROCLIF-05` | **Sicherer Subprozess-Lebenszyklus** | Saubere Prozess-Entkopplung | Startet Universal Mail Tools als losgelöste unprivilegierte Subprozesse (`subprocess.Popen`), wodurch Blockaden des Trays verhindert werden. |
| `INV-REDACT-06` | **Deterministische Snapshot-Anonymisierung** | Datenminimierung | Der `mailprocessor-suite-v1.json`-Export bereinigt benutzerspezifische absolute Pfade für den sicheren Offline-Austausch. |
| `INV-REDACT-06` | **Pfadhinweise im Snapshot** | Datenverarbeitung | Der Export ersetzt Pfade unter lokalen Datenwurzeln; andere Pfade können die letzten ein oder zwei Ordnernamen enthalten. Prüfe die Datei vor dem Teilen. |
| `INV-OSPAR-07` | **Plattform-Smoke-Vertrag** | Multi-OS Quelltext-Integrität | Primäre Ziellaufzeit ist Windows Desktop Tray; Multi-OS-Matrix prüft Quelltext-Kompatibilität unter Ubuntu und macOS. |
| `INV-SLA-08` | **Sicherheitsreaktions- & Triage-SLA** | Responsible Disclosure | 48-Stunden-Reaktions-SLA und 5-Werktage-Triage über `[email protected]` und GitHub Security Advisories. |

Expand Down
14 changes: 9 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ System tray launcher for the three Universal Mail Tools.
[![Tests: 90 passed](https://img.shields.io/badge/tests-90%20passed-brightgreen.svg)](tests/)
[![Security: Policy](https://img.shields.io/badge/security-SECURITY.md-blue.svg)](SECURITY.md)
[![Security SLA: 48h Response](https://img.shields.io/badge/security%20SLA-48h%20response-blue.svg)](SECURITY.md)
[![Privacy: 100% Local--First](https://img.shields.io/badge/privacy-100%25%20Local--First-blueviolet.svg)](SECURITY.md)
[![Privacy notice: draft](https://img.shields.io/badge/privacy-notice%20draft-blue.svg)](docs/PRIVACY_POLICY_DRAFT.md)
[![Code Style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Umbrella: open-bricks](https://img.shields.io/badge/umbrella-open--bricks-blue.svg)](https://github.com/open-bricks)
[![LLM Ready](https://img.shields.io/badge/LLM--Ready-llms.txt-brightgreen.svg)](llms.txt)
Expand Down Expand Up @@ -66,6 +66,10 @@ MailProcessor sits in the Windows system tray and gives you one-click access to:
- Windows autostart (registry entry)
- Bilingual: German / English

### Data and network scope

MailProcessor stores its launcher configuration on the device. When a user starts a tool download in the setup wizard, the launcher requests release metadata from GitHub and downloads that tool's release archive. No telemetry implementation was found in the reviewed launcher source. The separately launched mail tools have their own data flows; this finding does not describe or limit their network behavior. See the [launcher privacy notice draft](docs/PRIVACY_POLICY_DRAFT.md).

## System Architecture & Workflow

```mermaid
Expand Down Expand Up @@ -185,16 +189,16 @@ tracked in [RELEASES.md](RELEASES.md#current-platform-scope-2026-08-26).

## Governance & Runtime Invariants

The following invariants define the operational and security guarantees of MailProcessor:
The following identifiers summarize observed product behavior and security boundaries:

| Invariant ID | Name | Standard / Policy | Verification & Guarantee |
| Invariant ID | Name | Standard / Policy | Observed behavior |
|---|---|---|---|
| `INV-LOCAL-01` | **100% Local-First & Zero Egress** | Offline Privacy Standard | Operates entirely on the local machine. No telemetry, no background analytics, no cloud relay, and zero storage of email content, passwords, or credentials. |
| `INV-DATA-01` | **Launcher data and network scope** | Observed source behavior | Launcher configuration is stored locally. User-started tool downloads contact GitHub Releases; separately launched tools have their own data flows. No telemetry implementation was found in the reviewed launcher source. |
| `INV-NOELEV-02` | **Non-Elevation & RunAsInvoker** | Windows Least Privilege | Runs exclusively as standard unprivileged user. Never requests UAC elevation (`runAsInvoker`). |
| `INV-ZIPSLIP-03` | **Zip-Slip Traversal Defense** | CWE-22 Security Standard | Tool downloads from GitHub releases validate archive member paths to prevent directory traversal attacks before extraction. |
| `INV-CFGISO-04` | **Local AppData Isolation** | Windows AppData Convention | Configuration is isolated under `%LOCALAPPDATA%\MailProcessor\config.json`. No registry pollution except optional per-user autostart entry. |
| `INV-PROCLIF-05` | **Safe Subprocess Lifecycle** | Clean Process Separation | Launches Universal Mail Tools via detached unprivileged subprocesses (`subprocess.Popen`) preventing parent tray lockups or cascaded crashes. |
| `INV-REDACT-06` | **Deterministic Snapshot Redaction** | Data Minimization | `mailprocessor-suite-v1.json` exports redact machine-specific absolute paths to protect user privacy in shared or offline bug reports. |
| `INV-REDACT-06` | **Snapshot path hints** | Data handling | The export replaces local data-root paths; other paths may retain the last one or two folder names. Review the file before sharing. |
| `INV-OSPAR-07` | **Cross-Platform Source Smoke Contract** | Multi-OS Integrity | Primary product surface is Windows Desktop Tray; multi-platform smoke test matrix verifies source-level compatibility across Ubuntu and macOS. |
| `INV-SLA-08` | **Security Response & Triage SLA** | Responsible Disclosure | 48-hour response SLA and 5-business-day triage commitment through `[email protected]` and GitHub Security Advisories. |

Expand Down
26 changes: 16 additions & 10 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,22 @@ melden Sie diese bitte verantwortungsvoll:
- `[email protected]`
- `[email protected]`

### Verbindliche Sicherheitsgarantien (Invarianten)
### Laufzeitverhalten und Datenumfang

- **Local-First & Zero-Egress:** MailProcessor speichert keine E-Mail-Inhalte, Passwörter,
Tokens oder IMAP-Zugangsdaten. Alle Operationen laufen lokal auf dem Rechner des Nutzers.
- **Daten- und Netzwerkumfang des Launchers:** MailProcessor speichert seine Launcher-Konfiguration
lokal. Wenn Benutzer im Einrichtungsassistenten einen Werkzeug-Download starten, fragt der Launcher
GitHub-Release-Metadaten ab und lädt das Archiv herunter. Im geprüften Launcher-Quellstand wurde
keine Telemetrie-Implementierung gefunden. Separat gestartete Werkzeuge haben eigene Datenflüsse;
dieser Befund beschreibt oder begrenzt deren Netzwerkverhalten nicht.
- **Unprivilegierter User-Mode (Non-Elevation):** MailProcessor benötigt und verlangt keine
Administratorrechte. Autostart wird ausschließlich im aktuellen Benutzerkontext
(`HKCU\Software\Microsoft\Windows\CurrentVersion\Run`) verwaltet.
- **Zip-Slip- & Pfadtraversierungs-Schutz:** Heruntergeladene Release-Archive werden vor dem
Entpacken strikt auf Pfadtraversierung (CWE-22) validiert, sodass keine Dateien außerhalb
des vorgesehenen Tool-Ordners abgelegt werden können.
- **Isolierte Konfiguration:** Konfigurationsdaten werden im lokalen Benutzerdatenverzeichnis
(`%LOCALAPPDATA%\MailProcessor\config.json`) gehalten. Snapshot-Exporte redigieren lokale
Pfade und enthalten keinerlei geheime Informationen.
(`%LOCALAPPDATA%\MailProcessor\config.json`) gehalten. Snapshot-Exporte ersetzen lokale
Pfadwurzeln; andere Pfade können die letzten Ordnernamen enthalten. Vor dem Teilen prüfen.

### Reaktionszeit

Expand Down Expand Up @@ -68,19 +71,22 @@ If you discover a security vulnerability or concern in MailProcessor, please rep
- `[email protected]`
- `[email protected]`

### Core Security Invariants
### Runtime Behavior and Data Scope

- **Local-First & Zero-Egress:** MailProcessor does not store email contents, passwords,
tokens, or IMAP credentials. It operates 100% locally with zero cloud telemetry.
- **Launcher data and network scope:** MailProcessor stores its launcher configuration locally.
When a user starts a tool download in the setup wizard, the launcher requests GitHub release
metadata and downloads the archive. No telemetry implementation was found in the reviewed
launcher source. Separately launched tools have their own data flows; this finding does not
describe or limit their network behavior.
- **Non-Elevation (User Mode):** MailProcessor runs unprivileged in standard user mode.
Autostart entries are registered exclusively under the user scope
(`HKCU\Software\Microsoft\Windows\CurrentVersion\Run`).
- **Zip-Slip & Path Traversal Guard:** Downloaded release archives are strictly validated
against path traversal (CWE-22) before extraction, preventing any file writes outside the
designated tool target directory.
- **Isolated Configuration:** Configuration data is stored in the local user directory
(`%LOCALAPPDATA%\MailProcessor\config.json`). Snapshot exports redact local paths and
contain zero secrets.
(`%LOCALAPPDATA%\MailProcessor\config.json`). Snapshot exports replace local data-root paths;
other paths may retain trailing folder names. Review an export before sharing it.

### Response Time

Expand Down
43 changes: 43 additions & 0 deletions SUPPORT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# MailProcessor Support

**Source basis:** MailProcessor 0.1.0, reviewed at commit b5be8f20c5ec6fb519c40c4892b47f15e08c9be8 (2026-10-03).

## English

For ordinary usage questions and reproducible MailProcessor problems, use the public issue tracker:

https://github.com/doc-bricks/MailProcessor/issues

Please include, when known:

- MailProcessor version and whether you use a source checkout or a downloaded build. The current source declares version 0.1.0 in pyproject.toml and RELEASES.md. The versions displayed beside tray menu entries belong to the separate mail tools, not to MailProcessor.
- Windows version and relevant language setting.
- Short steps to reproduce, expected result, actual result, and the exact visible error text.
- Whether the issue concerns MailProcessor itself or one of the separately launched tools.

Do not post email addresses, mailbox names, message or attachment contents, passwords, tokens, private keys, or account exports. Do not attach config.json: it contains local tool paths. A MailProcessor snapshot redacts path roots but may retain trailing folder names; inspect it and remove identifying details before sharing. The launcher does not create an application log in the reviewed source.

For a security vulnerability, do not use a public issue. Consult SECURITY.md for the project's documented reporting options:
https://github.com/doc-bricks/MailProcessor/blob/main/SECURITY.md

The source repository does not promise a general support response time.

## Deutsch

Für allgemeine Nutzungsfragen und reproduzierbare Fehler in MailProcessor nutze bitte den öffentlichen Issue-Tracker:

https://github.com/doc-bricks/MailProcessor/issues

Gib, soweit bekannt, Folgendes an:

- MailProcessor-Version und ob du einen Quellcode-Checkout oder einen heruntergeladenen Build verwendest. Der aktuelle Quellstand nennt Version 0.1.0 in pyproject.toml und RELEASES.md. Versionsangaben neben Einträgen im Tray-Menü gehören zu den separaten Mailwerkzeugen, nicht zu MailProcessor.
- Windows-Version und relevante Spracheinstellung.
- Kurze Schritte zur Reproduktion, erwartetes und tatsächliches Ergebnis sowie den genauen sichtbaren Fehlertext.
- Ob der Fehler MailProcessor selbst oder eines der separat gestarteten Werkzeuge betrifft.

Veröffentliche keine E-Mail-Adressen, Postfachnamen, Nachrichten- oder Anhangsinhalte, Passwörter, Tokens, privaten Schlüssel oder Konto-Exporte. Hänge config.json nicht an: Sie enthält lokale Toolpfade. Ein MailProcessor-Snapshot kürzt Pfadwurzeln, kann aber die letzten Ordnernamen enthalten. Prüfe die Datei und entferne erkennbare persönliche Angaben, bevor du sie teilst. Im geprüften Quellstand legt der Launcher kein eigenes Anwendungsprotokoll an.

Melde Sicherheitslücken nicht öffentlich als Issue. Prüfe dafür die in SECURITY.md dokumentierten Meldewege:
https://github.com/doc-bricks/MailProcessor/blob/main/SECURITY.md

Der Quellstand verspricht keine allgemeine Support-Antwortzeit.
Loading
Loading