{"id":25566485,"url":"https://github.com/protostarship/win-system-guardian","last_synced_at":"2026-04-27T11:31:12.846Z","repository":{"id":276462402,"uuid":"929361673","full_name":"Protostarship/Win-System-Guardian","owner":"Protostarship","description":"SystemGuardian is a Windows service written in Python that acts as a comprehensive system monitoring and maintenance tool. It continuously monitors system event logs, registry health, and component status to detect and respond to potential issues before they cause system instability and crash the whole system (e.g. BSOD/GSOD).","archived":false,"fork":false,"pushed_at":"2025-02-09T10:13:08.000Z","size":62,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-01T11:40:23.709Z","etag":null,"topics":["bsod","gsod","insider-program","insiders","microsoft","python","service","services","windows","windows-10","windows-11","windows-insiders","windows-service","windowsinsiders"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Protostarship.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-08T11:20:23.000Z","updated_at":"2025-02-09T11:09:02.000Z","dependencies_parsed_at":"2025-05-25T02:08:23.789Z","dependency_job_id":"dcf26971-9ae3-43c8-a5b8-903815d53cd3","html_url":"https://github.com/Protostarship/Win-System-Guardian","commit_stats":null,"previous_names":["protostarship/win-system-guardian"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Protostarship/Win-System-Guardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protostarship%2FWin-System-Guardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protostarship%2FWin-System-Guardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protostarship%2FWin-System-Guardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protostarship%2FWin-System-Guardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Protostarship","download_url":"https://codeload.github.com/Protostarship/Win-System-Guardian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protostarship%2FWin-System-Guardian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32335295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bsod","gsod","insider-program","insiders","microsoft","python","service","services","windows","windows-10","windows-11","windows-insiders","windows-service","windowsinsiders"],"created_at":"2025-02-20T22:32:01.929Z","updated_at":"2026-04-27T11:31:12.830Z","avatar_url":"https://github.com/Protostarship.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SystemGuardian Service Documentation\n\n## Overview\nSystemGuardian is an advanced Windows service that provides automated system monitoring, protection, and recovery capabilities. It implements real-time component tracking, automatic recovery points, and intelligent event handling to maintain system stability and integrity.\n\n## Key Features\n- Real-time WMI-based event monitoring\n- Automated recovery point management\n- Registry state tracking and backup\n- Component integrity verification\n- Intelligent thread pool management\n- SQLite-based component and event tracking\n- Automated system restoration capabilities\n- Smart component isolation and quarantine\n\n## System Requirements\n\n### Hardware Requirements\n- Windows Operating System (Windows 10/11 recommended)\n- Minimum 4GB RAM\n- 1GB free disk space for recovery points\n\n### Software Prerequisites\n- Python 3.8 or higher\n- Required Python packages:\n```\nwin32serviceutil\nwmi\npsutil\nwin10toast\nsqlite3\n```\n\n## Directory Structure\n```\nC:/ProgramData/SystemGuardian/\n├── logs/                     # Rotating log files\n├── backups/                  # Registry and component backups\n├── recovery_points/          # System recovery points\n├── quarantine/               # Isolated components\n└── guardian.db               # SQLite database\n```\n\n## Database Schema\n\n### Components Table\n```sql\nCREATE TABLE components (\n    name TEXT PRIMARY KEY,\n    type TEXT,\n    path TEXT,\n    dependencies TEXT,\n    hash TEXT,\n    last_modified REAL,\n    status TEXT\n);\n```\n\n### Recovery Points Table\n```sql\nCREATE TABLE recovery_points (\n    timestamp REAL PRIMARY KEY,\n    components TEXT,\n    registry_backup TEXT,\n    description TEXT\n);\n```\n\n### Events Table\n```sql\nCREATE TABLE events (\n    id INTEGER PRIMARY KEY,\n    timestamp REAL,\n    type TEXT,\n    component TEXT,\n    description TEXT,\n    severity TEXT\n);\n```\n\n## Service Installation\n\n### Basic Installation\n```bash\npython SystemGuardian.py install\n```\n\n### Service Management\n- Start service\n```bash\npython SystemGuardian.py start\n```\n- Stop service\n```bash\npython SystemGuardian.py stop\n```\n- Update service\n```bash\npython SystemGuardian.py update\n```\n- Remove service\n```bash\npython SystemGuardian.py remove\n```\n## Recovery System\n\n### Recovery Points\n- Automatic creation before critical operations\n- Maximum retention: 5 recovery points\n- Includes:\n  - Full registry state\n  - Component database snapshot\n  - System state metadata\n\n### Recovery Point Creation\nRecovery points are automatically created:\n- At service startup\n- Before critical component modifications\n- Before component isolation\n- During service shutdown\n- On-demand via API\n\n### Recovery Point Restoration\n```python\n# Example restoration code\nguardian_service.restore_recovery_point(timestamp)\n```\n\n## Monitoring System\n\n### WMI Event Monitoring\n- Real-time event capture\n- Efficient event filtering\n- Resource-aware processing\n- Automated response triggers\n\n### Component Integrity\n- SHA-256 hash verification\n- Dependency validation\n- Path existence checking\n- Permission verification\n\n## Thread Management\n\n### Thread Pool\n- Maximum workers: 4\n- Automatic task distribution\n- Resource-aware scheduling\n- Graceful shutdown handling\n\n### Event Queue\n- Maximum size: 1000 events\n- FIFO processing\n- Overflow protection\n- Priority handling\n\n## Configuration\n\n### Service Configuration\n```python\nclass Config:\n    MAX_QUEUE_SIZE = 1000\n    MAX_THREADS = 4\n    MAX_RECOVERY_POINTS = 5\n    MAX_BACKUP_AGE_DAYS = 7\n    EVENT_CHECK_INTERVAL = 5\n    CACHE_UPDATE_INTERVAL = 3600\n    BACKUP_INTERVAL = 86400\n```\n\n### Registry Monitoring\nMonitored paths:\n```python\nCRITICAL_REG_PATHS = [\n    r\"SYSTEM\\CurrentControlSet\\Services\",\n    r\"SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Drivers32\",\n    r\"SYSTEM\\CurrentControlSet\\Control\\Class\"\n]\n```\n\n## Component Management\n\n### Component States\n- Active: Component running normally\n- Warning: Minor issues detected\n- Critical: Major problems identified\n- Isolated: Component quarantined\n- Recovered: Restored from backup\n\n### Isolation Process\n1. Create recovery point\n2. Backup component files\n3. Disable/stop component\n4. Update database status\n5. Notify administrator\n\n### Recovery Process\n1. Verify recovery point integrity\n2. Restore registry state\n3. Restore component files\n4. Validate restoration\n5. Update component status\n\n## Logging System\n\n### Log Rotation\n- Daily log files\n- Maximum size: 10MB\n- Retention: 5 files\n- Format: `guardian_YYYYMMDD.log`\n\n### Log Levels\n- INFO: Normal operations\n- WARNING: Potential issues\n- ERROR: Operation failures\n- CRITICAL: System failures\n\n## Performance Considerations\n\n### Resource Usage\n- CPU: \u003c5% average\n- Memory: ~100MB baseline\n- Disk: ~1GB for recovery points\n- Database: ~50MB typical\n\n### Optimization\n- Event batching\n- Efficient WMI queries\n- Thread pool management\n- Queue size limits\n\n## Security Features\n\n### Component Verification\n- File hash validation\n- Path verification\n- Permission checking\n- Dependency validation\n\n### Backup Security\n- Encrypted storage\n- Access control\n- Integrity verification\n- Secure deletion\n\n## Troubleshooting\n\n### Common Issues\n1. Service Start Failure\n   - Check database permissions\n   - Verify directory access\n   - Review WMI permissions\n   - Check log files\n\n2. Recovery Point Creation Failure\n   - Verify disk space\n   - Check backup directory permissions\n   - Review database connectivity\n   - Check registry access\n\n3. Component Isolation Issues\n   - Verify administrative rights\n   - Check component dependencies\n   - Review isolation logs\n   - Verify backup creation\n\n### Diagnostic Steps\n1. Check service status\n```powershell\nGet-Service SystemGuardian | Format-List *\n```\n\n2. Review recent logs\n```powershell\nGet-Content \"C:\\ProgramData\\SystemGuardian\\logs\\guardian_*.log\" -Tail 100\n```\n\n3. Check recovery points\n```sql\nSELECT * FROM recovery_points ORDER BY timestamp DESC LIMIT 5;\n```\n\n4. Verify component status\n```sql\nSELECT name, status FROM components WHERE status != 'Active';\n```\n\n## Best Practices\n\n### Maintenance\n1. Regular database cleanup\n2. Log rotation verification\n3. Recovery point validation\n4. Component status review\n\n### Monitoring\n1. Regular log review\n2. Performance tracking\n3. Resource usage monitoring\n4. Event pattern analysis\n\n### Backup Strategy\n1. Regular recovery point testing\n2. Backup retention management\n3. Storage space monitoring\n4. Integrity verification\n\n## Support and Updates\n\n### Update Process\n1. Stop service\n2. Backup database\n3. Update Python script\n4. Verify configuration\n5. Restart service\n\n### Health Checks\n1. Database integrity\n2. Recovery point validity\n3. Component status\n4. Resource usage\n\n## Error Codes and Troubleshooting\n\n### Common Error Codes\n- 1001: Database connection failure\n- 1002: Recovery point creation failed\n- 1003: Component isolation error\n- 1004: Registry backup failed\n- 1005: WMI monitoring error\n\n### Resolution Steps\nDetailed for each error code in the logs with specific troubleshooting procedures and recovery steps.\n\n\u003c**Windows 11 Home - Insider Preview build Production 09/02/25**\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotostarship%2Fwin-system-guardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprotostarship%2Fwin-system-guardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotostarship%2Fwin-system-guardian/lists"}