# Otzaria Crash Forensics Collector

כלי דיאגנוסטיקה מתקדם המיועד לאיסוף מידע עמוק אודות קריסות ותקלות באפליקציית Otzaria (אוצרייא).
הכלי אוסף מידע קריטי על סביבת המערכת, קבצי לוג, שאריות מהתקנות קודמות, וכן מאפשר מעקב בזמן אמת ללכידת קריסות (Crash Dumps) ומעקב עמוק (Deep Trace) לפתרון תקלות מורכבות. המידע נאסף, מצונזר (כדי להגן על פרטיות המשתמש), ונארז לקובץ ZIP יחיד שניתן לשלוח לצוות התמיכה או הפיתוח.

---

## 🚀 תכונות מרכזיות (Key Features)

* **מנוע איתור דינאמי (Discovery Engine):** הכלי מאתר אוטומטית התקנות פעילות, גם אם הן נמצאות במיקומים לא צפויים, על ידי מעקב אחר התהליכים הרצים במחשב, הרג'יסטרי, קיצורי דרך בשולחן העבודה, ובמקרה קיצון הפעלת `es.exe` (Everything) לחיפוש עמוק.
* **זיהוי שמות תהליך גמיש:** במצב `Watch` הכלי מזהה גם שמות ישנים/חלופיים כגון `otzaria`, `Otzaria` ו-`אוצריא`, אך מדלג על כלי האבחון עצמו ומפעיל את ProcDump לפי PID מדויק כדי למנוע לכידה שגויה של `OtzariaDiagnostics.exe`.
* **תאימות גרסאות:** תמיכה לאחור בגרסאות ישנות ובגרסת `migrationDB_V2` (זיהוי קבצי `library.db` הישנים לעומת `seforim.db` ו-`personal_notes.db` החדשים).
* **מצב השוואה (Compare Mode):** הכלי מייצר קובץ `summary.json` אחיד ברמת השורש, המאפשר להשוות סביבות של משתמשים בצורה יעילה (למשל השוואת מחשב קורס למחשב תקין).
* **שלושה מצבי פעולה (Modes):**
  * `Baseline` - איסוף מידע כללי, לוגים ושאריות התקנה (מומלץ לכל משתמש שחווה תקלות).
  * `Watch` - המתנה לקריסה של האפליקציה ויצירת קובץ Dump מלא לניתוח שגיאות (מצריך כלים חיצוניים).
  * `Deep` - הקלטה עמוקה של כלל תהליכי מערכת ההפעלה (WPR) ומעקב אחרי גישה לקבצים (Procmon).
* **ממשק משתמש גרפי מלא:** ריצת ה-EXE מציגה חלון סטטוס קבוע עם חיווי עבודה, לוג קצר, כפתור לסיום מעקב קריסה, כפתור לפתיחת תיקיית התוצאות בסיום, ואייקון באזור ההתראות שמאפשר לשחזר את החלון לאחר מזעור.
* **הגנה על פרטיות (Privacy):** סינון אוטומטי של שם המשתמש מכל נתיבי הקבצים, הלוגים וההגדרות שנאספים.
* **ניתוח שאריות התקנה (Upgrade Residue):** קריאת מפתחות רישום (Registry) לאיתור רשומות הסרה, וזיהוי כפילויות של קבצי הרצה או מסדי נתונים ישנים שעלולים להתנגש עם הגרסה הנוכחית (למשל כשל במיגרציה).
* **תמיכה בארכיטקטורות שונות:** מזהה אוטומטית ומפעיל את הכלים הייעודיים גם עבור מעבדי x64 סטנדרטיים וגם עבור מעבדי ARM64 החדשים (למשל Snapdragon X).

---

## 📂 מבנה התיקיות (Folder Structure)

```text
CrashForensicsCollector/
│
├── RunCollector.bat             <- קובץ ההפעלה הראשי למשתמשי קצה
├── Collect-Diagnostics.ps1      <- הליבה של הכלי ב-PowerShell
├── config.json                  <- הגדרות נתיבים, התנהגות ותצורת איסוף
├── README.md                    <- מסמך זה
│
├── Modules/                     <- מודולים נפרדים המבצעים את עבודת האיסוף
│   ├── AppSnapshot.psm1
│   ├── Bundle.psm1
│   ├── Core.psm1
│   ├── CrashWatcher.psm1
│   ├── DeepTrace.psm1
│   ├── EventLogs.psm1
│   ├── GuiStatus.psm1
│   ├── Questionnaire.psm1
│   └── SystemSnapshot.psm1
│
├── Tools/                       <- תיקייה לכלים חיצוניים (Sysinternals)
│   ├── es.exe                   (חיפוש מהיר 'Everything' - לטובת מנוע ה-Discovery)
│   ├── procdump.exe             (חובה למצב Watch)
│   ├── procdump64.exe           (חובה למצב Watch - x64)
│   ├── procdump64a.exe          (חובה למצב Watch - ARM64)
│   ├── procmon.exe              (מומלץ למצב Deep)
│   ├── procmon64.exe            (מומלץ למצב Deep - x64)
│   ├── procmon64a.exe           (מומלץ למצב Deep - ARM64)
│   ├── zstd.exe                 (אופציונלי - דחיסה מהירה של Dump/Deep)
│   ├── zstd32.exe               (אופציונלי - אם מפיצים גם 32-bit וגם 64-bit)
│   ├── zstd64.exe               (אופציונלי - מומלץ ל-x64)
│   └── zstd64a.exe              (אופציונלי בלבד - build עצמאי ל-ARM64, לא asset רשמי)
│
└── Output/                      <- תוצרי האיסוף נשמרים כאן בקבצי ZIP
```

---

## 🛠️ דרישות מוקדמות והכנות (Prerequisites & Setup)

1. **מערכת הפעלה:** Windows 10 או Windows 11.
2. **כלים חיצוניים (Sysinternals):**
   מטעמי אבטחת מידע, הכלי **אינו** מוריד קבצי הרצה מהאינטרנט בזמן אמת.
   כדי להשתמש במצבי `Watch` או `Deep`, חובה להוריד את הכלים הבאים מאתר Microsoft ולמקם אותם בתיקיית `Tools/`:
   * [ProcDump](https://learn.microsoft.com/en-us/sysinternals/downloads/procdump) - חלץ את הקבצים `procdump.exe`, `procdump64.exe`, ו-`procdump64a.exe` אל תוך התיקייה.
   * [Process Monitor (Procmon)](https://learn.microsoft.com/en-us/sysinternals/downloads/procmon) - חלץ את הקבצים המתאימים לתיקייה.
   * **Everything CLI (`es.exe`)** - במקרה שיש תקלה בזיהוי נתיב התוכנה, הכלי משתמש ב-`es.exe` כאמצעי הצלה לחיפוש עמוק ומהיר. (יש להניח את `es.exe` בתיקיית `Tools`).
   * **Zstandard (`zstd`)** - אופציונלי אך מומלץ כאשר נאספים Dumps או Deep traces גדולים. הורידו את חבילת Windows הרשמית מ-[Zstandard releases](https://github.com/facebook/zstd/releases). אם מפיצים גם 32-bit וגם 64-bit באותה תיקיית `Tools`, מומלץ לשנות שמות: `zstd64.exe` עבור ה-build של win64 ו-`zstd32.exe` עבור ה-build של win32. ב-Windows ARM64 אין כרגע asset רשמי מוכן; הכלי ינסה קודם build ARM64 אם סיפקתם כזה, ואז ייפול חזרה ל-`zstd64.exe` או `zstd.exe` דרך emulation.

*(הערה: ניתן להריץ את מצב ה-`Baseline` גם ללא כלים אלו, וללא הרשאות ניהול מיוחדות).*

---

## 🖱️ הוראות הפעלה למשתמש קצה (End-User Usage)

ישנן שתי דרכים מומלצות למשתמשי קצה להריץ את הכלי:

### דרך 1: שימוש בחבילת ה-EXE (מומלץ)
אם קיבלתם תיקייה המכילה את `OtzariaDiagnostics.exe`:
1. פשוט לחצו עליו פעמיים.
2. ייתכן שתקפוץ חלונית בקרת חשבון משתמש (UAC). אשרו אותה.
3. במסך שיפתח, לחצו על המצב הרצוי (לרוב "רגיל - איסוף מידע בסיסי").
4. ענו על השאלון הקצר שיוצג בחלון פופ-אפ.
5. בזמן האיסוף יישאר פתוח חלון סטטוס. אם מזערתם אותו, ניתן להחזיר אותו באמצעות לחיצה כפולה על אייקון `Otzaria Diagnostics` באזור ההתראות.
6. במצב `Watch`, פתחו את אוצריא רק אחרי שהחלון מציג שהוא ממתין לתהליך. שחזרו את התקלה או סגרו את אוצריא בכוח כדי ש-ProcDump ילכוד Dump. אם אין קריסה או שאוצריא תקועה ועדיין פתוחה, לחצו על `Finish and create ZIP`; הכלי ייצור Dump ידני של אוצריא לפני יצירת ה-ZIP.
7. במצב `Deep`, הכלי מתחיל קודם את Procmon/WPR, ורק אז ממתין לאוצריא עם ProcDump. פתחו את אוצריא אחרי שהסטטוס מציין ש-Deep trace מקליט, שחזרו את התקלה, ואז הכלי יעצור את Procmon/WPR ויצור ZIP בסיום. אם אין קריסה, לחצו `Finish and create ZIP` כדי ליצור Dump ידני ולסיים. אין צורך להתחיל Procmon ידנית אחרי הקריסה.
8. בסיום התהליך, קובץ ה-ZIP שלכם ייווצר על **שולחן העבודה** בתיקייה בשם `OtzariaDiagnosticsOutput`. חלון הסיום יישאר פתוח עד שתסגרו אותו, וניתן ללחוץ על `Open folder` כדי לפתוח מיד את התיקייה שבה נמצא ה-ZIP.

### דרך 2: שימוש בתיקיית המקור (קובץ ה-BAT)
אם אתם משתמשים בתיקיית הקוד הגולמי:
1. היכנסו לתיקיית `CrashForensicsCollector`.
2. לחצו פעמיים על **`RunCollector.bat`**.
3. ייתכן שתקפוץ חלונית בקרת חשבון משתמש (UAC). אשרו אותה.
4. ייפתח אותו ממשק גרפי כמו ב-EXE, כולל חלון הסטטוס הקבוע, שחזור מהמגש וכפתור `Open folder` בסיום.
5. בסיום, קובץ ה-ZIP יופיע בתיקיית `Output` הנמצאת ליד קובץ ה-BAT, אלא אם הוגדר `-OutputDir` אחר.

---

## 🔨 קימפול לקובץ EXE
על מנת להפוך את הסקריפט לקובץ הרצה נוח, הכנו סקריפט אוטומטי המשתמש במודול `ps2exe`:
1. הריצו את הקובץ `CompileToExe.bat` כמנהל.
2. הסקריפט יתקין אוטומטית את הסביבה הנדרשת וייצור קובץ בשם `OtzariaDiagnostics.exe` שמציג ממשק גרפי למשתמשים.
3. יש להפיץ את `OtzariaDiagnostics.exe` יחד עם `config.json`, תיקיית `Modules`, ותיקיית `Tools`. קובץ ה-EXE אינו מטמיע את המודולים והכלים החיצוניים לתוכו.

> חשוב: קבצי PowerShell שמכילים עברית (`.ps1`/`.psm1`) צריכים להישמר כ-`UTF-8 with BOM`. ב-Windows PowerShell/PS2EXE, UTF-8 ללא BOM עלול להיטען כקידוד ANSI ולגרום לשגיאות parsing או טקסט משובש.

---

## 💻 שימוש מתקדם משורת הפקודה (CLI Usage)

מפתחים או אנשי System יכולים להפעיל את הסקריפט ישירות מ-PowerShell כדי לקבל שליטה מלאה על הפרמטרים:

```powershell
# הפעלת איסוף בסיסי
.\Collect-Diagnostics.ps1 -Mode Baseline

# הפעלת מעקב קריסה עבור שם תהליך ספציפי
.\Collect-Diagnostics.ps1 -Mode Watch -ProcessName "otzaria.exe"

# הפעלת מעקב עמוק
.\Collect-Diagnostics.ps1 -Mode Deep

# הפעלת ריצת ניסיון (בדיקת הגדרות ונתיבים ללא איסוף מידע)
.\Collect-Diagnostics.ps1 -Mode Baseline -PreviewOnly

# ביטול צנזור שם המשתמש (למקרי צורך פנימיים בלבד)
.\Collect-Diagnostics.ps1 -Mode Baseline -RedactUserName:$false
```

### פרמטרים נתמכים ב-CLI
* `-Mode`: בחירת המצב (`Baseline`, `Watch`, `Deep`). ברירת מחדל: `Baseline`.
* `-CaseLabel`: תיוג המקרה (`Crash`, `NoCrash`, `Unknown`). ברירת מחדל: `Unknown`.
* `-ProcessName`: דריסת שם התהליך אחריו הכלי עוקב. במצב `Watch` הכלי ינסה קודם התאמה מדויקת, ואז התאמה לפי aliases של שם התהליך, ולבסוף יפעיל ProcDump לפי PID מדויק. כלי האבחון עצמם, כגון Procmon ו-ProcDump, מוחרגים מהזיהוי.
* `-ConfigPath`: נתיב מותאם אישית לקובץ ההגדרות. ברירת מחדל: `.\config.json`.
* `-NoDump`: ביטול יצירת קובץ ה-Dump במצבי Watch/Deep.
* `-NoDeepTrace`: מונע הפעלה של Trace עמוק למרות הפעלת המצב (עוקף את ההגדרה ב-config).
* `-PreviewOnly`: הצגת משתני הריצה ועצירת התהליך מבלי לבצע פעולות.
* `-RedactUserName`: שליטה על מנגנון הפיכת שם המשתמש ל-`<redacted>`. (כברירת מחדל נלקח מ-`config.json`).
* `-OutputDir`: הגדרת נתיב פלט חלופי לקבצי ה-ZIP.
* `-GuiMode`: הפעלת ממשק חלונות קופצים (GUI) בעברית, במקום אינטראקציה בטקסט מסוף. (מופעל אוטומטית בקובץ ה-EXE המקומפל).

### בדיקת איכות קוד (Lint)
הפרויקט משתמש ב-`PSScriptAnalyzer` עם הגדרות קבועות בקובץ `PSScriptAnalyzerSettings.psd1`.
להרצה מקומית:

```powershell
.\RunLint.ps1
```

### בדיקת Smoke קבועה
בדיקות פיתוח של הקולקטור צריכות להישמר בתיקייה הקבועה `TestOutput`, שאינה נכנסת ל-Git.
להרצת בדיקת Baseline לא-אינטראקטיבית:

```powershell
.\RunSmokeTest.ps1
```

הסקריפט יריץ את `Collect-Diagnostics.ps1` עם `-OutputDir .\TestOutput`, יוודא שנוצר `summary.json`, וייכשל אם `Success` אינו `true` או אם נרשמו שגיאות ב-`internal\errors.json`.

---

## ⚙️ קובץ ההגדרות (config.json)

קובץ ה-`config.json` שולט על ההתנהגות המפורטת של הכלי.
**דגשים:**
* מומלץ להשתמש במשתני מערכת כמו `%APPDATA%`, `%LOCALAPPDATA%` ו-`%SystemDrive%` כדי שהנתיבים יהיו גמישים ויתאימו לכל מחשב.
* המערך `KnownLegacyPaths` מגדיר היכן לחפש "שאריות" של גרסאות אוצרייא ישנות (נתיבי מערכת שהיו בשימוש בגרסאות פייתון או אלטקרון בעבר).
* `ProcessNameAliases` ו-`ExeFileNameAliases` מגדירים שמות תהליך חלופיים לאפליקציה, למשל `otzaria`, `Otzaria` ו-`אוצריא`. הם משמשים לזיהוי גרסאות ישנות או חדשות בלי ללכוד בטעות את `OtzariaDiagnostics.exe`.
* `MsInfo32TimeoutSeconds` ו-`DxDiagTimeoutSeconds` קובעים כמה זמן להמתין לכלי האבחון החיצוניים של Windows לפני שממשיכים הלאה. כך גם אם `msinfo32` או `dxdiag` נתקעים, הקולקטור ממשיך לסיכום וליצירת ZIP חלקי.
* המערך `VersionProfiles` מגדיר נתיבים ייחודיים לגרסאות שונות. למשל, במקרה של `MigrationDB_V2` מצופה לראות קבצי נתונים בשם `seforim.db` או `personal_notes.db`, לעומת `library.db` ההיסטורי.
* ההגדרה `CollectEventDays` קובעת כמה ימים אחורה לשלוף לוגים מתוך ה-Event Viewer של Windows.
* `EnableHangDumpByDefault`: מוסיף ל-ProcDump לכידת Hang של חלון שלא מגיב.
* `EnableManualDumpOnFinish`: כאשר לוחצים `Finish and create ZIP` ואוצריא עדיין רצה, הכלי יוצר Dump ידני לפני סיום המעקב.
* `ProcDumpCpuThresholdPercent` ו-`ProcDumpCpuThresholdSeconds`: מאפשרים להוסיף Dump לפי CPU גבוה. ערך `0` מכבה את הטריגר.
* `ProcDumpMemoryThresholdMB`: מאפשר Dump לפי שימוש זיכרון גבוה. ערך `0` מכבה את הטריגר.
* `DeepTraceToolTimeoutSeconds`: מגביל כמה זמן להמתין לפקודות WPR/Procmon נקודתיות במצב Deep כדי שכלי חיצוני תקוע לא ימנע יצירת ZIP.
* `ProcmonConvertToCsv`: כאשר `true`, הכלי ינסה להמיר את `procmon.pml` ל-`procmon.csv` לאחר עצירה נקייה של Procmon. אם Procmon לא נסגר נקי, ההמרה תידלג כדי למנוע חלונות שגיאה של Process Monitor.
* `BundleUseZstdForHeavyFiles`: כאשר `true`, קבצים כבדים כגון `.dmp`, `.etl`, ו-`.pml` יידחסו קודם עם `zstd` אם נמצא כלי מתאים בתיקיית `Tools`.
* `BundleHeavyFileThresholdMB`: סף הגודל שממנו קובץ נחשב כבד ומטופל במסלול zstd/fallback. ברירת מחדל: `100`.
* `BundleZstdLevel`: רמת הדחיסה של zstd. ברירת מחדל: `1`, לטובת איזון מהיר בין זמן דחיסה לגודל.
* `BundleZipCompressionLevel`: רמת הדחיסה הרגילה של קבצים קטנים בתוך ה-ZIP. ברירת מחדל: `Fastest`.

---

## 📦 אילו נתונים הכלי אוסף?

כל קובץ ZIP (`CASE-YYYYMMDD-GUID.zip`) יכיל את המבנה הבא:
* `summary.json` - קובץ "מצב השוואה" (Compare Mode) המספק מידע אחיד, שטוח וקריא-מכונה עבור אוטומציות השוואה בין סביבות עבודה. מתעד האם היו תקלות מיגרציה, סוג התקנה וסטטוס רכיבים.
* `manifest.json` - קובץ מטא-דאטה מרוכז שמתאר את מצב ההתקנה, גרסאות, חומרת המחשב וסיכום כללי של התיק.
* `summary.txt` - תקציר קריא לבני אדם של המידע.
* `questionnaire.json` - התשובות והפירוט שסיפק המשתמש בשאלון האינטראקטיבי לגבי אופי התקלה.
* **תיקיית `system`** - מידע מקיף על חומרת המחשב. כולל: מעבד, כרטיס מסך, נפח כוננים (`disk.json`), משתני סביבה, רשימת תהליכים מצונזרת, וכן פלטים של כלי הדיאגנוסטיקה המובנים של ווינדוס (`msinfo32.nfo` ו- `dxdiag.txt`).
* **תיקיית `app`** - קבצי תצורה ומידע של אפליקציית אוצרייא (Otzaria). כולל: חתימות (Hashes) של קבצי ההתקנה לווידוא תקינות, מידע על מסד הנתונים, רשימת תוספים (Plugins), ובדיקת הרשאות קריאה/כתיבה (ACL - `permissions.txt`). **לא נאסף מידע פרטי**.
* **תיקיית `logs`** - מרוכזים כאן כלל הלוגים:
  * `app_logs` - העתקים מצונזרים של קבצי הלוג האחרונים של אוצרייא.
  * `events` - ייצוא של שגיאות קריטיות וקריסות (Event Viewer) של מערכת ההפעלה מ-14 הימים האחרונים.
* **תיקיית `upgrade`** - תוצרי סריקה ב-Registry ובהארד-דיסק לאיתור "שאריות" והתנגשויות מגרסאות ישנות שהותקנו בעבר.
* **תיקיית `crash`** (במצב Watch/Deep) - לכידת קבצי זיכרון (Process Dump) בעת קריסה, סגירת תהליך, Hang, או סיום ידני באמצעות `Finish`. ProcDump מופעל מול PID מדויק של אפליקציית אוצרייא כדי למנוע לכידה של כלי האבחון עצמו. אם `zstd` זמין, קבצי Dump גדולים עשויים להופיע בתוך ה-ZIP כ-`.dmp.zst`; פותחים אותם עם `zstd -d file.dmp.zst`.
* **תיקיית `deep`** (במצב Deep) - קבצי הרישום של מעקב התהליכים העמוק (WPR ו-Procmon). קבצי `.etl` או `.pml` גדולים עשויים להיארז כ-`.zst` מאותה סיבה.
* **תיקיית `internal`** - נתוני טלמטריה על ריצת סקריפט הדיאגנוסטיקה עצמו (קובץ לוג, זמני ריצה `timeline.json`, ושגיאות תוכנה).

---

**פותח עבור פרויקט אוצרייא.**
לדיווח על תקלות או תרומת קוד, אנא פנו למאגר המרכזי.
