Initial commit
This commit is contained in:
167
docs/CLAUDE.md
Normal file
167
docs/CLAUDE.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This is a Windows remote administration toolkit designed for configuring and managing a specific Windows machine (PC-74269 at 192.168.88.112) from macOS/Linux systems. The toolkit provides automated scripts for system debloating, application installation, security configuration, and diagnostics.
|
||||
|
||||
## Architecture Pattern
|
||||
|
||||
**Dual-Script Architecture**: Each functionality consists of two files:
|
||||
- `.ps1` - PowerShell script that runs on the target Windows machine
|
||||
- `.sh` - macOS/Linux shell wrapper that uploads and executes the PowerShell script via SSH
|
||||
|
||||
**Execution Flow**:
|
||||
1. Shell script uses `sshpass` + `scp` to upload PowerShell script to target
|
||||
2. Executes PowerShell script remotely via SSH with `powershell -NoProfile -ExecutionPolicy Bypass`
|
||||
3. Output is simultaneously displayed and logged to `logs/` with timestamps
|
||||
|
||||
## Key Commands
|
||||
|
||||
### Prerequisites
|
||||
```bash
|
||||
# Install sshpass (required for all operations)
|
||||
brew install hudochenkov/sshpass/sshpass
|
||||
```
|
||||
|
||||
### System Reconnaissance
|
||||
```bash
|
||||
./recon.sh # Complete system inventory (15 sections)
|
||||
./verify-ai-removed.sh # Verify Windows AI components removed
|
||||
./verify-debloat.sh # Verify Win11Debloat changes applied
|
||||
```
|
||||
|
||||
### Core System Configuration
|
||||
```bash
|
||||
./firewall-allow-ssh.sh # Enable permanent SSH access
|
||||
./activate-windows.sh # Activate Windows via KMS
|
||||
./remove-windows-ai.sh # Remove Windows AI/Copilot components
|
||||
./win11debloat.sh # Remove bloatware and disable telemetry
|
||||
```
|
||||
|
||||
### Application Management
|
||||
```bash
|
||||
./install-thunderbird.sh # Install Thunderbird email client
|
||||
./setup-thunderbird.sh # Configure IMAP/SMTP (edit thunderbird-config.json first)
|
||||
./install-telegram.sh # Install Telegram for target user
|
||||
```
|
||||
|
||||
### Diagnostics and Tools
|
||||
```bash
|
||||
./install-nirsoft.sh # Install 16 NirSoft diagnostic tools
|
||||
./nirsoft-dump.sh # Collect and package system diagnostic data
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
All scripts support connection overrides:
|
||||
```bash
|
||||
HOST=192.168.x.x USER_NAME=foo PASS='xxx' ./script.sh
|
||||
MODE=Apply|Revert ./remove-windows-ai.sh # AI removal modes
|
||||
TARGET_USER=someone ./apply-ui-to-user.sh # UI settings target
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### `win11debloat-config.json`
|
||||
Configuration for Win11Debloat operations. Uses schema with `Tweaks`, `Deployment`, and `Apps` sections. All tweak names must exist in Win11Debloat's `Config/Features.json` or they'll be rejected as "no importable data".
|
||||
|
||||
### `thunderbird-config.json`
|
||||
Email account configuration for Thunderbird setup. Supports IMAP/SMTP with various providers (Gmail, Outlook, iCloud, custom servers).
|
||||
|
||||
### `nirsoft-config.json`
|
||||
Defines the 16 NirSoft diagnostic tools to install, their download URLs, and installation paths.
|
||||
|
||||
## Important Gotchas
|
||||
|
||||
1. **PowerShell Encoding**: Chinese Windows systems read UTF-8 scripts as CP950 without BOM. Scripts automatically add UTF-8 BOM to downloaded PowerShell files.
|
||||
|
||||
2. **Firewall Persistence**: Windows firewall profiles reset on reboot. The firewall script creates permanent rules and enables all profiles.
|
||||
|
||||
3. **Thunderbird Profiles**: Thunderbird 72+ uses `[Install<HASH>]` sections in profiles.ini, not `Default=1`. Setup script handles this correctly.
|
||||
|
||||
4. **Win11Debloat Scope**: Silent mode only applies UI settings to the executing user. Use `apply-ui-to-user.sh` to sync settings to other users.
|
||||
|
||||
5. **Registry Paths**: Many "common knowledge" registry paths for Windows settings are incorrect. Always verify actual paths used by tools.
|
||||
|
||||
## Logging and Output
|
||||
|
||||
- All operations create timestamped logs in `logs/` directory
|
||||
- Format: `{operation}-{host}-{timestamp}.log`
|
||||
- Diagnostic dumps saved to `dumps/` directory as ZIP files
|
||||
- Scripts provide real-time output while simultaneously logging
|
||||
|
||||
## Remote Target Requirements
|
||||
|
||||
- Windows machine with OpenSSH Server enabled on port 22
|
||||
- Default credentials: `Admin@192.168.88.112` / `P@ssw0rd!`
|
||||
- Target must be accessible from execution environment
|
||||
- PowerShell 5.1 required (not PowerShell 7/Core)
|
||||
|
||||
## Connection Methods
|
||||
|
||||
This toolkit supports two connection methods with different strengths:
|
||||
|
||||
### SSH Method (Stable, for Large Scripts)
|
||||
- ✅ Proven stability and reliability
|
||||
- ✅ Handles large scripts (>3KB) without issues
|
||||
- ✅ File upload capabilities via `scp`
|
||||
- ✅ All existing `.sh` scripts use this method
|
||||
- ⏱️ Execution time: ~22 seconds for recon
|
||||
- Requires OpenSSH Server on target Windows machine
|
||||
|
||||
### WinRM Method (Fast, for Quick Tasks)
|
||||
- ⚡ **1.9x faster execution** (12s vs 22s for recon)
|
||||
- ✅ Native Windows remote management
|
||||
- ✅ Better PowerShell integration and error handling
|
||||
- ✅ Structured logging and real-time output
|
||||
- ⚠️ Limited by command line length for large scripts
|
||||
- Requires WinRM service configuration on target
|
||||
|
||||
```bash
|
||||
# SSH method (reliable for large scripts)
|
||||
./recon.sh
|
||||
|
||||
# WinRM method (faster for small tasks)
|
||||
python3 test_simple_winrm.py
|
||||
python3 benchmark_ssh_vs_winrm.py
|
||||
|
||||
# Smart method selection
|
||||
python3 smart_executor.py script.ps1
|
||||
```
|
||||
|
||||
## WinRM Setup and Usage
|
||||
|
||||
### Prerequisites for WinRM
|
||||
```bash
|
||||
# Install Python WinRM library
|
||||
pip3 install pywinrm
|
||||
|
||||
# Generate WinRM wrapper scripts
|
||||
python3 generate_winrm_wrappers.py
|
||||
```
|
||||
|
||||
### WinRM Configuration Scripts
|
||||
- `check-winrm.sh` - Verify WinRM configuration status
|
||||
- `enable-winrm.sh` - Configure WinRM service for remote access
|
||||
- `fix-winrm.sh` - Fix common WinRM connectivity issues
|
||||
- `test_winrm_python.py` - Test WinRM connectivity with Python
|
||||
- `winrm_executor.py` - Core WinRM execution framework
|
||||
|
||||
### WinRM Target Requirements
|
||||
- WinRM service running on port 5985 (HTTP) or 5986 (HTTPS)
|
||||
- `Enable-PSRemoting -Force` executed on target
|
||||
- Firewall rules enabled for Windows Remote Management
|
||||
- For HTTP: `AllowUnencrypted=true` in WinRM configuration
|
||||
|
||||
## Recommended Execution Order
|
||||
|
||||
For new machines, follow this sequence:
|
||||
1. `firewall-allow-ssh.sh` - Ensure permanent SSH access
|
||||
2. `enable-winrm.sh` - Configure WinRM (if using WinRM method)
|
||||
3. `recon.sh` or `recon-winrm.py` - System inventory
|
||||
4. `activate-windows.sh` - Windows activation
|
||||
5. AI removal + reboot + verification
|
||||
6. Win11Debloat + reboot + verification
|
||||
7. Application installations
|
||||
8. Account management (rename/hide should be done last)
|
||||
Reference in New Issue
Block a user