Update README.md
This commit is contained in:
parent
e3313dbc1b
commit
1d1435f36a
64
README.md
64
README.md
|
|
@ -24,7 +24,7 @@ ICEYOU watches your Windows machine while you're away. The moment any input, USB
|
|||
|
||||
## Quick Start
|
||||
|
||||
1. **Create a virtualenv** (recommended — opencv-contrib requires numpy < 2):
|
||||
1. **Create a virtualenv** (recommended - opencv-contrib requires numpy < 2):
|
||||
```powershell
|
||||
python -m venv .venv
|
||||
.\.venv\Scripts\Activate.ps1
|
||||
|
|
@ -62,10 +62,10 @@ ICEYOU watches your Windows machine while you're away. The moment any input, USB
|
|||
|---|---|
|
||||
| `Ctrl+Alt+L` | Force away mode + show whiteout immediately |
|
||||
| `Ctrl+Alt+U` | Re-show the whiteout password prompt (useful if it was hidden) |
|
||||
| `Ctrl+Alt+M` | **Toggle Monitoring** — Pause or resume monitoring (motion + intrusion detection) |
|
||||
| `Ctrl+Alt+S` | **Stop Monitoring** — Immediately pause motion recording and intrusion detection |
|
||||
| `Ctrl+Alt+M` | **Toggle Monitoring** - Pause or resume monitoring (motion + intrusion detection) |
|
||||
| `Ctrl+Alt+S` | **Stop Monitoring** - Immediately pause motion recording and intrusion detection |
|
||||
|
||||
Combos are configurable in `config.json → hotkeys` using pynput syntax (`<ctrl>+<shift>+<alt>+p`, etc.). Restart ICEYOU after editing.
|
||||
Combos are configurable in `config.json -> hotkeys` using pynput syntax (`<ctrl>+<shift>+<alt>+p`, etc.). Restart ICEYOU after editing.
|
||||
|
||||
**Automatic behavior**: When the user successfully unlocks the whiteout, monitoring is automatically **paused** (no more motion recording or intrusion detection). It will **automatically resume** the next time the machine idles for the configured timeout.
|
||||
|
||||
|
|
@ -92,15 +92,15 @@ Combos are configurable in `config.json → hotkeys` using pynput syntax (`<ctrl
|
|||
|
||||
## Intrusion Response Flow
|
||||
|
||||
1. **Detect** — Idle ≥ `idle_timeout_seconds` (or you pressed `Ctrl+Alt+L`) → away mode + whiteout up.
|
||||
2. **Trigger** — Any keyboard, mouse, USB, or camera-obscured event during away fires an intrusion:
|
||||
1. **Detect** - Idle ≥ `idle_timeout_seconds` (or you pressed `Ctrl+Alt+L`) -> away mode + whiteout up.
|
||||
2. **Trigger** - Any keyboard, mouse, USB, or camera-obscured event during away fires an intrusion:
|
||||
- Snapshot captured (saved to `snapshots/`)
|
||||
- `intrusion_detected` event logged
|
||||
- Email alert sent with photo
|
||||
- Whiteout stays up with the password / face-unlock prompt
|
||||
3. **Locked state** — `manual_lock` is set; ordinary activity **cannot** clear away mode. Only a correct unlock does.
|
||||
4. **Password gate** — Cannot be cancelled or closed. After `max_unlock_attempts` (default 3) wrong passwords, Windows workstation lock kicks in. When the user returns from the Windows lock screen the **ICEYOU whiteout is still there** — unlocking Windows alone is not enough.
|
||||
5. **Success** — Whiteout dismisses, failure counter resets, auto-away is snoozed briefly so you can work.
|
||||
3. **Locked state** - `manual_lock` is set; ordinary activity **cannot** clear away mode. Only a correct unlock does.
|
||||
4. **Password gate** - Cannot be cancelled or closed. After `max_unlock_attempts` (default 3) wrong passwords, Windows workstation lock kicks in. When the user returns from the Windows lock screen the **ICEYOU whiteout is still there** - unlocking Windows alone is not enough.
|
||||
5. **Success** - Whiteout dismisses, failure counter resets, auto-away is snoozed briefly so you can work.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -110,17 +110,17 @@ Every interaction with the unlock prompt is recorded:
|
|||
|
||||
- **Snapshot** of whoever is at the keyboard: `snapshots/snapshot_<timestamp>_unlock_<success|fail>_<password|face>.jpg`
|
||||
- **Structured log entry** appended to `events.log` (one JSON object per line):
|
||||
- `method` — `"password"` or `"face"`
|
||||
- `success` — boolean
|
||||
- `snapshot` — path to the photo
|
||||
- `entered` — **only on failed password attempts** — the literal text the intruder typed
|
||||
- `label`, `confidence` — for face attempts
|
||||
- `method` - `"password"` or `"face"`
|
||||
- `success` - boolean
|
||||
- `snapshot` - path to the photo
|
||||
- `entered` - **only on failed password attempts** - the literal text the intruder typed
|
||||
- `label`, `confidence` - for face attempts
|
||||
- **Email alert** (if `email.enabled`) with the snapshot attached:
|
||||
- Failed password attempts include the typed text in the body
|
||||
- Successful unlocks confirm but **never** include your real password
|
||||
- Auto face attempts (every 4 s) are silent (no log / no email) to avoid flooding. Only **manual** `Unlock by Face` clicks and **successful** matches are recorded.
|
||||
|
||||
If alerts aren't arriving: tray → **Send Test Email** (or `python test_email.py`). SMTP errors land in `events.log` as `email_failed`. Gmail → external-domain alerts often hit **Spam** — check there first and mark "Not spam" to whitelist.
|
||||
If alerts aren't arriving: tray -> **Send Test Email** (or `python test_email.py`). SMTP errors land in `events.log` as `email_failed`. Gmail -> external-domain alerts often hit **Spam** - check there first and mark "Not spam" to whitelist.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -133,15 +133,15 @@ Optional second unlock path next to the password.
|
|||
pip install --upgrade --force-reinstall opencv-contrib-python
|
||||
```
|
||||
|
||||
2. **Enroll** your face — multi-pose, multi-look:
|
||||
2. **Enroll** your face - multi-pose, multi-look:
|
||||
```powershell
|
||||
python face_enrollment.py --name owner
|
||||
python face_enrollment.py --camera 1 --list-cameras
|
||||
```
|
||||
The capture window cycles through 5 poses (straight, left, right, up, down). Controls:
|
||||
- **Click** the preview window — most reliable capture
|
||||
- **SPACE / ENTER / C** — capture (window must have focus)
|
||||
- Hold a steady face ≥ 2 s — auto-capture
|
||||
- **Click** the preview window - most reliable capture
|
||||
- **SPACE / ENTER / C** - capture (window must have focus)
|
||||
- Hold a steady face ≥ 2 s - auto-capture
|
||||
- **R** restart, **Q / ESC** quit
|
||||
|
||||
For glasses / headphones / hats, **re-run with the same `--name`** so LBPH learns all your looks under one identity. Each session appends to `faces/<label>/capture_NN.png` and re-trains `faces/model.yml`.
|
||||
|
|
@ -159,14 +159,14 @@ Optional second unlock path next to the password.
|
|||
}
|
||||
```
|
||||
|
||||
- `confidence_threshold` — **lower = stricter** (LBPH distance). 50 = very strong, 70 = balanced, 85 = lenient. Tune based on the `conf=…` value shown on misses.
|
||||
- `allowed_labels` — list of enrolled identities allowed to unlock. `null` = any enrolled label.
|
||||
- `auto_attempt` — background tries every `attempt_interval_seconds` while the whiteout is up.
|
||||
- `confidence_threshold` - **lower = stricter** (LBPH distance). 50 = very strong, 70 = balanced, 85 = lenient. Tune based on the `conf=…` value shown on misses.
|
||||
- `allowed_labels` - list of enrolled identities allowed to unlock. `null` = any enrolled label.
|
||||
- `auto_attempt` - background tries every `attempt_interval_seconds` while the whiteout is up.
|
||||
|
||||
While the whiteout is shown:
|
||||
- Auto-attempts run silently every 4 s (default).
|
||||
- The **Unlock by Face** button lets you trigger a manual attempt (this is logged + emailed; auto attempts are not).
|
||||
- Face failures do **not** count toward the 3-strike OS-lock — only typed passwords do, so a bad camera angle can never lock you out.
|
||||
- Face failures do **not** count toward the 3-strike OS-lock - only typed passwords do, so a bad camera angle can never lock you out.
|
||||
|
||||
**Status hint**: failed face attempts show `Face not recognised (best=<label>, conf=<value>)` on the whiteout. If you consistently see `conf` slightly above your threshold, either raise the threshold or enroll more samples.
|
||||
|
||||
|
|
@ -174,7 +174,7 @@ While the whiteout is shown:
|
|||
|
||||
## Camera Tamper Detection
|
||||
|
||||
When the whiteout is active, ICEYOU periodically samples the camera (default every 12 s). If the frame mean brightness or pixel variance drops below thresholds (lens covered, sticker over webcam, etc.), it immediately triggers full lockdown — email alert + OS workstation lock — **without** waiting for input. Configure in `config.json → camera_obscured_detection`.
|
||||
When the whiteout is active, ICEYOU periodically samples the camera (default every 12 s). If the frame mean brightness or pixel variance drops below thresholds (lens covered, sticker over webcam, etc.), it immediately triggers full lockdown - email alert + OS workstation lock - **without** waiting for input. Configure in `config.json -> camera_obscured_detection`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -186,11 +186,11 @@ While the whiteout is up, [src/iceyou/motion_recorder.py](src/iceyou/motion_reco
|
|||
- Pops a system-tray notification ("Motion event saved: motion_…avi").
|
||||
- Does **not** trigger an email (snapshots + unlock attempts already cover that).
|
||||
|
||||
Recording starts on `WhiteScreen.show()` and stops on `WhiteScreen.hide()` — there is no recording when ICEYOU is not in the locked state.
|
||||
Recording starts on `WhiteScreen.show()` and stops on `WhiteScreen.hide()` - there is no recording when ICEYOU is not in the locked state.
|
||||
|
||||
**Viewing clips post-authentication:** the tray menu has a **View Motion Clips** item that opens the `motion_clips/` folder in Explorer. While the whiteout is up the escape-key hook prevents the intruder from reaching the tray icon, so this item is effectively post-authentication. Once you unlock, right-click the tray icon and pick **View Motion Clips** to review.
|
||||
|
||||
Config (`config.json → motion_recording`):
|
||||
Config (`config.json -> motion_recording`):
|
||||
|
||||
```jsonc
|
||||
"motion_recording": {
|
||||
|
|
@ -221,11 +221,11 @@ Disable with `"block_escape_keys": false` if needed (e.g. development). The hook
|
|||
|
||||
**Hard limits (Windows-enforced, cannot be intercepted from user mode):**
|
||||
|
||||
- `CTRL+ALT+DEL` — Secure Attention Sequence is kernel-enforced. An intruder can still reach the security screen → Task Manager → kill `python.exe`.
|
||||
- `CTRL+ALT+DEL` - Secure Attention Sequence is kernel-enforced. An intruder can still reach the security screen -> Task Manager -> kill `python.exe`.
|
||||
- Hard power off, pulling the keyboard.
|
||||
- Logging in as a different Windows user.
|
||||
|
||||
To harden against CTRL+ALT+DEL → Task Manager, run as Administrator and set the registry value `HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\System\DisableTaskMgr = 1 (DWORD)`. ICEYOU does **not** apply this automatically because it's a system-wide setting affecting every program.
|
||||
To harden against CTRL+ALT+DEL -> Task Manager, run as Administrator and set the registry value `HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\System\DisableTaskMgr = 1 (DWORD)`. ICEYOU does **not** apply this automatically because it's a system-wide setting affecting every program.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -294,9 +294,9 @@ To harden against CTRL+ALT+DEL → Task Manager, run as Administrator and set th
|
|||
| No tray icon | Make sure `python main.py` is running; check `events.log` for startup errors. |
|
||||
| Email alerts not arriving | Check Spam folder. Use **Send Test Email** in tray (or `python test_email.py`). Look for `email_failed` in `events.log`. |
|
||||
| Face unlock never matches | Status line shows `conf=<value>`. Either raise `confidence_threshold` in `config.json` or re-enroll with more samples / better lighting / same accessories you're wearing now. |
|
||||
| Password field clears mid-typing | Already fixed — input while the whiteout is up is treated as challenge, not re-intrusion. Pull latest `monitor.py` + `white_screen.py`. |
|
||||
| Tk error `Tcl_AsyncDelete: async handler deleted by the wrong thread` | Already fixed — `WhiteScreen` uses a persistent Tk root on a dedicated thread. |
|
||||
| Tk error `can't set fullscreen attribute… override-redirect flag is set` | Already fixed — `WhiteScreen` sizes to screen via `geometry()` instead of `-fullscreen`. |
|
||||
| Password field clears mid-typing | Already fixed - input while the whiteout is up is treated as challenge, not re-intrusion. Pull latest `monitor.py` + `white_screen.py`. |
|
||||
| Tk error `Tcl_AsyncDelete: async handler deleted by the wrong thread` | Already fixed - `WhiteScreen` uses a persistent Tk root on a dedicated thread. |
|
||||
| Tk error `can't set fullscreen attribute… override-redirect flag is set` | Already fixed - `WhiteScreen` sizes to screen via `geometry()` instead of `-fullscreen`. |
|
||||
| `numpy<2` conflict with `opencv-contrib-python` | Use the recommended `.venv` virtualenv. |
|
||||
| Antivirus flags ICEYOU | Low-level keyboard hooks trigger heuristics. Whitelist the project folder. |
|
||||
|
||||
|
|
@ -316,7 +316,7 @@ ICEYOU/
|
|||
├── motion_clips/ 5s-before + event + 5s-after AVI clips from the whiteout
|
||||
├── faces/
|
||||
│ ├── model.yml Trained LBPH model
|
||||
│ ├── labels.json Label id → name map
|
||||
│ ├── labels.json Label id -> name map
|
||||
│ └── <label>/capture_NN.png Enrolled photos per identity
|
||||
└── src/iceyou/
|
||||
├── tray_app.py System tray + wiring
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user