167 lines
6.3 KiB
Markdown
167 lines
6.3 KiB
Markdown
# 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) |