cschantz
7556342a58
Added comprehensive [MULTI_PANEL_ARCHITECTURE] section to REFDB_FORMAT.txt: - Control panel support status (cPanel/InterWorx/Plesk/standalone) - Critical path differences (docroot, logs, configs, DB prefixes) - Module classification system (Class A/B/C/D) - Refactoring progress tracker (33/38 = 87% complete) - Mandatory abstraction libraries (system-detect.sh, user-manager.sh) - Standard code patterns (log discovery, domain→user, API calls) - Common mistakes to avoid - Complete commit history for multi-panel work REFDB_FORMAT.txt is THE comprehensive developer documentation file (now 764 lines). This is the ONLY file Claude uses for development context across sessions.
765 lines
28 KiB
Plaintext
765 lines
28 KiB
Plaintext
################################################################################
|
|
# SERVER TOOLKIT - CLAUDE AI CONTEXT DATABASE
|
|
################################################################################
|
|
# OPTIMIZED FOR: Claude Code AI parsing and context loading
|
|
# LAST UPDATED: 2025-11-12
|
|
# VERSION: 2.1.0
|
|
# FORMAT: Structured key-value with hierarchical sections
|
|
################################################################################
|
|
|
|
[META]
|
|
version: 2.1.0
|
|
updated: 2025-11-12
|
|
status: production_ready
|
|
base_path: /root/server-toolkit
|
|
entry_point: launcher.sh
|
|
control_panels: cPanel, Plesk, InterWorx, Standalone
|
|
repository: https://git.mull.lol/cschantz/Linux-Server-Management-Toolkit.git
|
|
|
|
[STATUS_SNAPSHOT_2025_11_07]
|
|
# What works right now (production ready)
|
|
working:
|
|
- launcher.sh: Main menu with hierarchical structure, cleanup/reset
|
|
- modules/diagnostics/system-health-check.sh: 22-phase diagnostics with baseline tracking
|
|
- modules/security/bot-analyzer.sh: Threat scoring (0-100), CSF blocking, IP reputation
|
|
- modules/security/live-attack-monitor.sh: Real-time SOC dashboard
|
|
- modules/security/enable-cphulk.sh: cPHulk enablement with CSF whitelist import
|
|
- modules/security/ip-reputation-manager.sh: Centralized IP tracking
|
|
- modules/website/website-error-analyzer.sh: Intelligent error detection (filters bots)
|
|
- modules/website/500-error-tracker.sh: Fast 500 error diagnosis
|
|
- modules/website/wordpress-menu.sh: WordPress management submenu
|
|
- modules/website/wordpress/wordpress-cron-manager.sh: WP cron → system cron conversion
|
|
- modules/backup/acronis-*.sh: Complete Acronis Cyber Protect integration (16 scripts)
|
|
- modules/performance/mysql-query-analyzer.sh: Slow query detection
|
|
- modules/performance/hardware-health-check.sh: Hardware diagnostics
|
|
- lib/system-detect.sh: Auto-detect cPanel/Plesk/InterWorx, OS, web server, DB, PHP
|
|
- lib/user-manager.sh: User selection with arrow-key menus and search
|
|
- lib/reference-db.sh: 1-hour cache with cross-module intelligence
|
|
- lib/ip-reputation.sh: Centralized IP reputation tracking
|
|
|
|
# Recent additions (2025-11-05 to 2025-11-07)
|
|
recent_features:
|
|
- WordPress Cron Manager: Complete wp-cron → system cron conversion
|
|
- WordPress submenu structure: modules/website/wordpress/
|
|
- Cancel/back options: ALL user inputs now support cancellation
|
|
- Development guidelines: REFDB_FORMAT.txt (this file)
|
|
- Acronis backup integration: 16 scripts for complete agent management
|
|
- Website error analyzers: Intelligent bot filtering
|
|
|
|
# Not implemented yet
|
|
future:
|
|
- modules/wordpress/*: Plugin/theme managers, security hardening
|
|
- modules/monitoring/*: Additional monitoring tools
|
|
- modules/reporting/*: Report generation
|
|
|
|
[CRITICAL_DESIGN_RULES]
|
|
# DO NOT BREAK THESE - Latest standards as of 2025-11-07
|
|
|
|
bash_strict_mode: "set -eo pipefail" (NOT -euo - -u is too strict)
|
|
cancel_buttons: MANDATORY - Every menu must have "0) Cancel", every input must accept "0"
|
|
grep_pattern: Always add "|| true" to grep/find that might not match
|
|
unbound_vars: Use ${var:-} or ${var:-default} for potentially unbound variables
|
|
arithmetic: Use current=$((current + 1)) NOT ((current++))
|
|
output_suppression: NEVER use { } >/dev/null on critical functions (breaks variable assignment)
|
|
module_isolation: Modules run in subshells with cleared SYS_* environment
|
|
press_enter: ALWAYS call press_enter at end of scripts before exit
|
|
messaging: Use print_success, print_error, print_warning, print_info (NOT echo)
|
|
|
|
[CANCEL_BUTTON_STANDARD]
|
|
# MANDATORY as of 2025-11-07 - ALL scripts must support cancellation
|
|
|
|
menu_format: |
|
|
echo " 1) Option One"
|
|
echo " 2) Option Two"
|
|
echo " 0) Cancel and return to menu" # REQUIRED
|
|
echo ""
|
|
read -p "Select option: " choice
|
|
|
|
case $choice in
|
|
0)
|
|
echo "Operation cancelled."
|
|
press_enter
|
|
exit 0
|
|
;;
|
|
# ... other options
|
|
esac
|
|
|
|
text_input_format: |
|
|
echo -n "Enter value (or 0 to cancel): "
|
|
read -r value
|
|
|
|
if [ -z "$value" ] || [ "$value" = "0" ]; then
|
|
echo "Operation cancelled."
|
|
press_enter
|
|
exit 0
|
|
fi
|
|
|
|
rationale: Users must NEVER be trapped in a prompt - always provide escape route
|
|
|
|
[KEY_FILES_QUICK_MAP]
|
|
# Fast reference for file locations (updated 2025-11-07)
|
|
|
|
launcher.sh: Main entry point, menu system
|
|
Line 77-84: Subshell isolation for modules
|
|
Line 1262-1279: WordPress/website menu handler
|
|
|
|
README.md: User-facing documentation
|
|
|
|
REFDB_FORMAT.txt: THIS FILE - developer reference (keep updated!)
|
|
|
|
lib/common-functions.sh: Core utilities
|
|
print_banner(), print_success(), print_error(), print_warning(), print_info()
|
|
press_enter(), show_progress(), finish_progress()
|
|
|
|
lib/system-detect.sh: Auto-detection
|
|
Exports: SYS_CONTROL_PANEL, SYS_OS_TYPE, SYS_WEB_SERVER, etc.
|
|
Line 433-445: Auto-initialization with exec redirect
|
|
|
|
lib/user-manager.sh: User/domain selection
|
|
select_user_interactive() - Arrow-key menu with search (type S [text])
|
|
get_user_domains() - Domain detection for cPanel users
|
|
|
|
lib/reference-db.sh: Session intelligence (.sysref)
|
|
db_get_all_wordpress(), db_get_user_domains(), db_store_*()
|
|
1-hour TTL cache, cross-module data sharing
|
|
|
|
lib/ip-reputation.sh: Centralized IP tracking
|
|
is_known_bot(), should_filter_ip(), log_ip_threat()
|
|
|
|
modules/website/wordpress-menu.sh: WordPress submenu
|
|
Entry point for all WordPress management tools
|
|
|
|
modules/website/wordpress/wordpress-cron-manager.sh: WP cron conversion
|
|
Disable/enable wp-cron, add system cron jobs, staggered timing
|
|
|
|
config/settings.conf: User configuration
|
|
config/whitelist-ips.txt: IP whitelist
|
|
config/whitelist-user-agents.txt: User-Agent whitelist
|
|
|
|
[DIRECTORY_STRUCTURE_2025_11_07]
|
|
server-toolkit/
|
|
├── launcher.sh (main entry point)
|
|
├── README.md (user docs)
|
|
├── REFDB_FORMAT.txt (THIS FILE - developer reference)
|
|
├── config/
|
|
│ ├── settings.conf
|
|
│ ├── whitelist-ips.txt
|
|
│ └── whitelist-user-agents.txt
|
|
├── lib/
|
|
│ ├── common-functions.sh (print_*, press_enter, colors)
|
|
│ ├── system-detect.sh (SYS_* variables)
|
|
│ ├── user-manager.sh (select_user_interactive)
|
|
│ ├── reference-db.sh (db_* functions, .sysref)
|
|
│ ├── ip-reputation.sh (is_known_bot, log_ip_threat)
|
|
│ └── mysql-analyzer.sh (database utilities)
|
|
├── modules/
|
|
│ ├── security/
|
|
│ │ ├── bot-analyzer.sh ✓
|
|
│ │ ├── live-attack-monitor.sh ✓
|
|
│ │ ├── enable-cphulk.sh ✓
|
|
│ │ └── ip-reputation-manager.sh ✓
|
|
│ ├── website/
|
|
│ │ ├── website-error-analyzer.sh ✓
|
|
│ │ ├── 500-error-tracker.sh ✓
|
|
│ │ ├── wordpress-menu.sh ✓
|
|
│ │ └── wordpress/
|
|
│ │ └── wordpress-cron-manager.sh ✓
|
|
│ ├── backup/
|
|
│ │ ├── acronis-backup-manager.sh ✓
|
|
│ │ ├── acronis-trigger-backup.sh ✓
|
|
│ │ ├── acronis-agent-status.sh ✓
|
|
│ │ └── [13 more acronis scripts] ✓
|
|
│ ├── diagnostics/
|
|
│ │ └── system-health-check.sh ✓
|
|
│ ├── performance/
|
|
│ │ ├── mysql-query-analyzer.sh ✓
|
|
│ │ └── hardware-health-check.sh ✓
|
|
│ └── maintenance/
|
|
│ └── cleanup-toolkit-data.sh ✓
|
|
└── tools/
|
|
└── diagnostic-report.sh
|
|
|
|
[REFERENCE_DATABASE_FORMAT]
|
|
# .sysref file format - pipe-delimited session database
|
|
|
|
location: /root/server-toolkit/.sysref
|
|
timestamp: /root/server-toolkit/.sysref.timestamp
|
|
ttl: 3600 seconds (1 hour)
|
|
format: TYPE|field1|field2|field3|...
|
|
|
|
record_types:
|
|
SYS: System information
|
|
format: SYS|key|value|extra
|
|
example: SYS|CONTROL_PANEL|cpanel|11.130.0.15
|
|
|
|
USER: User accounts
|
|
format: USER|username|primary_domain|db_count|domain_count|disk_mb|home_dir
|
|
example: USER|pickledperil|pickledperil.com|1|3|82|/home/pickledperil
|
|
|
|
DB: Databases
|
|
format: DB|db_name|owner|primary_domain|size_mb|table_count
|
|
example: DB|pickledperil_wp_wt6lz|pickledperil|pickledperil.com|15.23|12
|
|
|
|
DOMAIN: Domain mappings (with HTTP/HTTPS status codes)
|
|
format: DOMAIN|domain|owner|doc_root|log_path|php_ver|is_primary|type|aliases|http_code|https_code|status_summary
|
|
example: DOMAIN|pickledperil.com|pickledperil|/home/pickledperil/public_html|/var/log/apache2/domlogs/pickledperil.com|ea-php81|yes|primary|www.pickledperil.com|200|200|200_OK
|
|
types: primary, addon, subdomain, alias, parked, remote
|
|
status_codes: 200, 301, 302, 403, 404, 500, 502, 503, timeout, 000
|
|
status_summary: 200_OK, REDIRECT, 403_FORBIDDEN, 404_NOT_FOUND, 500_ERROR, 502_BAD_GATEWAY, 503_UNAVAILABLE, TIMEOUT, UNREACHABLE, OTHER, skipped, remote_mx
|
|
|
|
WP: WordPress installations
|
|
format: WP|domain|owner|path|db_name|db_user|version|plugin_count|theme_count
|
|
example: WP|pickledperil.com|pickledperil|/home/pickledperil/public_html|pickledperil_wp_wt6lz|pickledperil_wp_user|6.8.3|1|3
|
|
|
|
HEALTH: Health check baselines
|
|
format: HEALTH|metric_name|value|date
|
|
examples:
|
|
HEALTH|MEMORY_TOTAL_MB|3776|2025-11-01
|
|
HEALTH|CPU_LOAD_1MIN|2.4|2025-11-01
|
|
HEALTH|DISK_USED_PERCENT|35|2025-11-01
|
|
|
|
query_functions:
|
|
db_get_user(username)
|
|
db_get_all_users()
|
|
db_get_user_databases(username)
|
|
db_get_user_domains(username)
|
|
db_get_all_wordpress()
|
|
db_store_wordpress(domain, owner, path, db_name, db_user, version, plugins, themes)
|
|
|
|
[MODULE_TEMPLATE]
|
|
# Standard template for creating new modules
|
|
|
|
file_location: /root/server-toolkit/modules/{category}/{name}.sh
|
|
|
|
template: |
|
|
#!/bin/bash
|
|
|
|
################################################################################
|
|
# Script Name
|
|
################################################################################
|
|
# Purpose: Description
|
|
# Features:
|
|
# - Feature 1
|
|
# - Feature 2
|
|
################################################################################
|
|
|
|
# Path resolution (adjust based on depth)
|
|
# modules/category/script.sh → ../../
|
|
# modules/category/sub/script.sh → ../../../
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
|
|
source "$SCRIPT_DIR/lib/common-functions.sh"
|
|
source "$SCRIPT_DIR/lib/system-detect.sh"
|
|
|
|
# Optional libraries (only if needed)
|
|
# source "$SCRIPT_DIR/lib/user-manager.sh"
|
|
# source "$SCRIPT_DIR/lib/reference-db.sh"
|
|
# source "$SCRIPT_DIR/lib/ip-reputation.sh"
|
|
|
|
# Root check
|
|
if [ "$EUID" -ne 0 ]; then
|
|
print_error "This script must be run as root"
|
|
exit 1
|
|
fi
|
|
|
|
# Main logic
|
|
clear
|
|
print_banner "Script Name"
|
|
|
|
echo ""
|
|
echo "Script functionality here..."
|
|
echo ""
|
|
|
|
# ALWAYS provide cancel option
|
|
echo " 0) Cancel and return to menu"
|
|
echo ""
|
|
read -p "Select option: " choice
|
|
|
|
case $choice in
|
|
0)
|
|
echo "Operation cancelled."
|
|
press_enter
|
|
exit 0
|
|
;;
|
|
# ... other options
|
|
esac
|
|
|
|
echo ""
|
|
print_success "Completed"
|
|
echo ""
|
|
press_enter
|
|
|
|
steps_to_add_module:
|
|
1: Create file in modules/{category}/{name}.sh
|
|
2: chmod +x the file
|
|
3: Add to launcher.sh in appropriate menu handler
|
|
4: Test directly: bash /root/server-toolkit/modules/category/script.sh
|
|
5: Test via launcher: bash /root/server-toolkit/launcher.sh
|
|
6: Commit to git
|
|
|
|
mandatory_checklist:
|
|
- [ ] Cancel option on ALL menus ("0) Cancel")
|
|
- [ ] Cancel option on ALL text inputs ("or 0 to cancel")
|
|
- [ ] press_enter() at end before exit
|
|
- [ ] Use print_* functions (not echo for status)
|
|
- [ ] Correct SCRIPT_DIR path resolution
|
|
- [ ] Root check if needed
|
|
- [ ] Error handling with proper exit codes
|
|
- [ ] Test with bash -n (syntax check)
|
|
|
|
[WORDPRESS_CRON_MANAGER]
|
|
# New feature added 2025-11-07
|
|
|
|
location: modules/website/wordpress/wordpress-cron-manager.sh
|
|
purpose: Convert WordPress wp-cron to real system cron jobs
|
|
|
|
features:
|
|
- Scan for all WordPress installations
|
|
- Disable wp-cron per domain/user/server-wide
|
|
- Add staggered system cron jobs (load distribution)
|
|
- Revert to wp-cron
|
|
- Check status
|
|
|
|
staggered_timing:
|
|
purpose: Distribute cron load across 15-minute window
|
|
pattern: Site 1=0,15,30,45 | Site 2=1,16,31,46 | Site 3=2,17,32,47
|
|
formula: minute = (offset % 15), offset increments per site
|
|
result: 300 sites = 20 sites per minute (manageable load)
|
|
|
|
wp-config_modification:
|
|
function: disable_wpcron_in_config()
|
|
location: Before "/* That's all, stop editing! */" comment (proper WordPress convention)
|
|
fallback: After <?php tag if "stop editing" not found
|
|
adds: define('DISABLE_WP_CRON', true);
|
|
safety: Removes existing entries first, backup created, verification, rollback on failure
|
|
format: User crontabs (crontab -u $user) not system crontab
|
|
|
|
domain_lookup_method:
|
|
# Fixed 2025-11-10 - Two-step lookup process
|
|
method_1: Check main_domain in /var/cpanel/userdata/*/main files (YAML: main_domain:)
|
|
method_2: Fallback to search domain-specific files for servername (YAML: servername:)
|
|
skip_files: "*.cache, */main, */cache, */cache.json"
|
|
rationale: cPanel stores main_domain in main files, servername in domain-specific files
|
|
|
|
cron_job_format: |
|
|
0,15,30,45 * * * * cd /home/user/public_html && /usr/bin/php -q wp-cron.php >/dev/null 2>&1
|
|
|
|
options:
|
|
1: Scan for WordPress installations
|
|
2: Disable wp-cron for specific domain
|
|
3: Disable wp-cron for specific user (all their WP sites)
|
|
4: Disable wp-cron server-wide (all WordPress sites)
|
|
5: Check wp-cron status
|
|
6: Re-enable wp-cron for specific domain
|
|
7: Re-enable wp-cron for specific user
|
|
8: Re-enable wp-cron server-wide
|
|
0: Return to menu (cancel)
|
|
|
|
[RECENT_COMMITS]
|
|
# Latest changes (2025-11-13)
|
|
|
|
commit: [pending]
|
|
date: 2025-11-13
|
|
title: Complete security intelligence overhaul - Live monitor 2.0
|
|
files: lib/bot-signatures.sh, lib/attack-patterns.sh, lib/ip-reputation.sh, modules/security/live-attack-monitor.sh
|
|
changes:
|
|
- Created lib/bot-signatures.sh (shared bot classification for 60+ bots)
|
|
- Created lib/attack-patterns.sh (shared attack detection for 7 attack types)
|
|
- Enhanced lib/ip-reputation.sh with ban tracking and CSF/iptables integration
|
|
- Updated IP reputation DB format to include BAN_COUNT and LAST_BAN fields
|
|
- Completely rewrote live-attack-monitor.sh as "Intelligence Mode"
|
|
- Added real-time threat scoring (0-100) using bot-analyzer algorithms
|
|
- Integrated IP reputation DB for known threat detection
|
|
- Added bot classification with color coding (green=legit, red=malicious)
|
|
- Implemented attack vector detection (SQL, XSS, RCE, Path Traversal, etc.)
|
|
- Created quick action blocking system with interactive menu
|
|
- Added batch IP blocking (select multiple IPs or auto-block score >= 80)
|
|
- Added ban tracking (shows how many times each IP was banned)
|
|
- CSF integration for temporary bans (1 hour default, auto-expires)
|
|
- iptables fallback with 'at' scheduler for auto-unblock
|
|
- Enhanced dashboard with 4 panels: Intelligence, Attack Vectors, Live Feed, Quick Actions
|
|
- Bot analyzer and live monitor now share intelligence via IP reputation DB
|
|
testing: All libraries tested, syntax verified
|
|
architecture: Bot analyzer learns → IP reputation DB stores → Live monitor queries
|
|
next: Test live monitor in production, update bot-analyzer to use shared libraries
|
|
|
|
commit: [pending]
|
|
date: 2025-11-13
|
|
title: Add HTTP/HTTPS status code checking to reference database
|
|
files: lib/reference-db.sh, REFDB_FORMAT.txt
|
|
changes:
|
|
- Created check_domain_status() function to test domain HTTP/HTTPS status
|
|
- Integrated status code checking into build_domains_section()
|
|
- Added 3 new fields to DOMAIN records: http_code, https_code, status_summary
|
|
- Status codes checked during database build (not during bot analysis)
|
|
- Progress display while checking domain status codes
|
|
- Improved status classification: 200_OK, REDIRECT, 403_FORBIDDEN, 404_NOT_FOUND, 500_ERROR, 502_BAD_GATEWAY, 503_UNAVAILABLE, TIMEOUT, UNREACHABLE
|
|
- Skip status checks for aliases/subdomains (inherit from parent)
|
|
- Remote MX domains marked as remote_mx (no status check)
|
|
testing: Domain status codes successfully stored in .sysref
|
|
next: Update bot-analyzer.sh to use status codes from .sysref instead of checking live
|
|
|
|
# Latest changes (2025-11-12)
|
|
|
|
commit: d5eb8c7
|
|
date: 2025-11-12
|
|
title: Fix ImunifyAV output parsing in malware scanner
|
|
files: modules/security/malware-scanner.sh
|
|
changes:
|
|
- Fixed incorrect scan result retrieval (was getting oldest scan instead of newest)
|
|
- Changed tail -1 to tail -n +2 | head -1 (skip header, get most recent scan)
|
|
- Extract TOTAL_MALICIOUS from scan result directly (field 12)
|
|
- Added number validation to ImunifyAV, ClamAV, and Maldet parsers
|
|
- Now correctly reports realistic file counts (e.g., 3997 files in 69s, not millions)
|
|
testing: Verified with actual ImunifyAV output - parsing works correctly
|
|
bug_ref: BUG_014
|
|
|
|
# Latest changes (2025-11-10)
|
|
|
|
commit: 172a115
|
|
date: 2025-11-10
|
|
title: Fix domain lookup in WordPress Cron Manager
|
|
files: modules/website/wordpress/wordpress-cron-manager.sh
|
|
changes:
|
|
- Fixed broken domain lookup (was only searching /var/cpanel/userdata/*/main for servername:)
|
|
- Added two-step lookup: main_domain in main files, then servername in domain files
|
|
- Applied fix to options 2, 5, 6 (all domain lookup locations)
|
|
- Skip cache files during search
|
|
testing: Verified with pickledperil.com - lookup now works correctly
|
|
|
|
# Latest changes (2025-11-07)
|
|
|
|
commit: 56776a1
|
|
title: Add cancel/back options to all user input prompts
|
|
files: website-error-analyzer.sh, 500-error-tracker.sh, wordpress-cron-manager.sh
|
|
changes: Added "0) Cancel" to all menus, "(or 0 to cancel)" to all inputs
|
|
|
|
commit: b9ce90c
|
|
title: Reorganize website management menu with WordPress subdirectory
|
|
files: launcher.sh, wordpress-menu.sh, wordpress-cron-manager.sh
|
|
changes: Created modules/website/wordpress/ subdirectory, WordPress submenu
|
|
|
|
commit: 4a1285d
|
|
title: Add revert functionality to WordPress Cron Manager
|
|
changes: Options 6,7,8 for reverting wp-cron changes
|
|
|
|
commit: e893171
|
|
title: Add safe wp-config.php modification with validation
|
|
changes: Created disable_wpcron_in_config() with backup/rollback
|
|
|
|
commit: c559bfe
|
|
title: Add WordPress Cron Manager with intelligent load distribution
|
|
changes: Initial WordPress cron manager implementation
|
|
|
|
[GIT_WORKFLOW]
|
|
# Standard git operations
|
|
|
|
check_status: git status
|
|
add_all: git add -A
|
|
commit_format: |
|
|
git commit -m "Brief summary (50 chars max)
|
|
|
|
Changes:
|
|
- Change 1
|
|
- Change 2
|
|
|
|
Tested:
|
|
✓ Test 1
|
|
✓ Test 2"
|
|
|
|
IMPORTANT: NEVER add Claude/AI signatures to commits
|
|
- NO "Generated with Claude Code"
|
|
- NO "Co-Authored-By: Claude"
|
|
- NO AI attribution of any kind
|
|
- Keep commits clean and professional
|
|
|
|
push: git push origin main
|
|
|
|
[BUGS_FIXED_HISTORY]
|
|
# Historical bug fixes - DO NOT REINTRODUCE
|
|
|
|
BUG_014: ImunifyAV scan results parsing incorrect
|
|
issue: Used tail -1 to get "last scan" but ImunifyAV lists newest first, so was getting oldest scan
|
|
issue: Was reading wrong/stale scan results showing unrealistic file counts
|
|
fix: Changed to tail -n +2 | head -1 (skip header, get first data line = newest scan)
|
|
fix: Extract TOTAL_MALICIOUS (field 12) directly from scan result instead of separate query
|
|
fix: Added validation to ensure parsed values are numbers
|
|
location: modules/security/malware-scanner.sh:673-692
|
|
tested: 2025-11-12 - Correctly shows 3997 files in 69s (not millions in seconds)
|
|
|
|
BUG_013: Brace redirection blocks variable assignment
|
|
fix: Use exec file descriptor manipulation instead of { } >/dev/null
|
|
location: lib/system-detect.sh:439-445
|
|
|
|
BUG_012: Cleanup not forcing fresh detection
|
|
fix: Unset all SYS_* vars, re-source libraries
|
|
location: launcher.sh:332-360
|
|
|
|
BUG_011: Duplicate menu display
|
|
fix: Suppress auto-init output with exec redirect
|
|
location: lib/system-detect.sh:433-445
|
|
|
|
BUG_010: System detection errors silently suppressed
|
|
fix: Removed 2>/dev/null || true on critical functions
|
|
location: lib/system-detect.sh:435
|
|
|
|
BUG_009: User list not displaying in selection
|
|
fix: Redirect display to stderr, only username to stdout
|
|
location: lib/user-manager.sh:330-408
|
|
|
|
BUG_008: Octal number error in timeline (hours 08/09)
|
|
fix: Strip leading zeros with 10#$hour
|
|
location: modules/security/bot-analyzer.sh:1154-1157
|
|
|
|
BUG_007: find -name pattern -o -name pattern syntax
|
|
fix: find \( -name "*.log" -o -name "*access*" \)
|
|
status: Feature disabled due to performance
|
|
|
|
BUG_006: Arithmetic operations causing exit
|
|
fix: Changed ((current++)) to current=$((current + 1))
|
|
files: Multiple locations
|
|
|
|
BUG_005: grep commands failing with set -e
|
|
fix: Added || true to ALL grep in pipes
|
|
files: lib/user-manager.sh, lib/reference-db.sh
|
|
|
|
[NEXT_PRIORITIES_2025_11_07]
|
|
|
|
immediate:
|
|
1: Test WordPress cron manager on production server with multiple WP sites
|
|
2: Create additional WordPress management tools (plugin/theme managers)
|
|
3: Document all features in README.md
|
|
|
|
short_term:
|
|
4: Implement Joomla/Drupal management menus (similar structure)
|
|
5: Add more monitoring dashboards
|
|
6: Expand reporting capabilities
|
|
|
|
long_term:
|
|
7: Email/Slack alert integration
|
|
8: Automated security scanning
|
|
9: Performance trend analysis
|
|
|
|
[TESTING_CHECKLIST]
|
|
|
|
before_commit:
|
|
- [ ] bash -n script.sh (syntax check)
|
|
- [ ] Test cancel buttons (enter 0 at every prompt)
|
|
- [ ] Test direct execution: bash /path/to/script.sh
|
|
- [ ] Test via launcher menu navigation
|
|
- [ ] Verify press_enter() at end
|
|
- [ ] Check error handling
|
|
- [ ] Confirm no debug output in production
|
|
|
|
after_commit:
|
|
- [ ] git status (verify clean)
|
|
- [ ] Test on fresh system (rm .sysref*)
|
|
- [ ] Update this file (REFDB_FORMAT.txt)
|
|
- [ ] Update README.md if user-facing feature
|
|
|
|
[FOR_NEW_CLAUDE_INSTANCES]
|
|
# Quick onboarding for new sessions
|
|
|
|
step1_read_this_section_first: |
|
|
You are maintaining the Server Management Toolkit.
|
|
This file (REFDB_FORMAT.txt) is your ONLY reference document.
|
|
README.md is for users, this file is for you.
|
|
|
|
step2_understand_current_state: |
|
|
Read [STATUS_SNAPSHOT_2025_11_07] to know what works.
|
|
Read [CRITICAL_DESIGN_RULES] - these are mandatory.
|
|
Read [CANCEL_BUTTON_STANDARD] - every script must have this.
|
|
|
|
step3_file_locations: |
|
|
Use [KEY_FILES_QUICK_MAP] to find things fast.
|
|
Use [DIRECTORY_STRUCTURE_2025_11_07] for overall layout.
|
|
|
|
step4_making_changes: |
|
|
Follow [MODULE_TEMPLATE] for new scripts.
|
|
Follow [GIT_WORKFLOW] for commits.
|
|
Check [TESTING_CHECKLIST] before committing.
|
|
|
|
step5_update_this_file: |
|
|
After making changes, update:
|
|
- [STATUS_SNAPSHOT_2025_11_07]
|
|
- [RECENT_COMMITS]
|
|
- [NEXT_PRIORITIES_2025_11_07]
|
|
- [META] updated date
|
|
|
|
critical_rules_never_break:
|
|
- Every menu MUST have "0) Cancel"
|
|
- Every text input MUST accept "0" to cancel
|
|
- Always call press_enter() at script end
|
|
- Use print_* functions not echo for status
|
|
- Add || true to grep/find that might not match
|
|
- Never use set -u (too strict)
|
|
- Never use { } >/dev/null on critical functions
|
|
|
|
[SHARED_RESOURCES]
|
|
|
|
ip_reputation:
|
|
file: lib/ip-reputation.sh
|
|
functions: is_known_bot(), should_filter_ip(), log_ip_threat()
|
|
purpose: Centralized IP tracking across all security modules
|
|
|
|
reference_database:
|
|
file: lib/reference-db.sh
|
|
storage: /root/server-toolkit/.sysref
|
|
ttl: 1 hour
|
|
purpose: Cross-module intelligence sharing (WordPress, domains, users, health)
|
|
|
|
user_manager:
|
|
file: lib/user-manager.sh
|
|
function: select_user_interactive("Prompt text")
|
|
features: Arrow-key menu, search (type S [text]), domain display
|
|
returns: $SELECTED_USER variable
|
|
|
|
common_functions:
|
|
file: lib/common-functions.sh
|
|
functions: print_banner(), print_success(), print_error(), print_warning(), print_info(), press_enter()
|
|
colors: GREEN, RED, YELLOW, CYAN, BOLD, NC (auto-disabled if not TTY)
|
|
|
|
[MULTI_PANEL_ARCHITECTURE]
|
|
# MAJOR REFACTORING: 2025-11-19
|
|
# Supporting cPanel, Plesk, InterWorx, and standalone Apache
|
|
|
|
status: 33/38 modules complete (87%)
|
|
updated: 2025-11-19
|
|
|
|
# Control Panel Support Levels
|
|
panels:
|
|
cpanel: Full support (primary platform)
|
|
interworx: In progress (phases 1-3 complete)
|
|
plesk: Partial support (needs expansion)
|
|
standalone: Basic support (no control panel)
|
|
|
|
# CRITICAL PATH DIFFERENCES (MUST MEMORIZE)
|
|
paths:
|
|
docroot:
|
|
cpanel: /home/USER/public_html
|
|
interworx: /home/USER/DOMAIN/html
|
|
plesk: /var/www/vhosts/DOMAIN/httpdocs
|
|
|
|
access_logs:
|
|
cpanel: /var/log/apache2/domlogs/DOMAIN
|
|
interworx: /home/USER/var/DOMAIN/logs/access_log
|
|
plesk: /var/www/vhosts/system/DOMAIN/logs/access_log
|
|
|
|
error_logs:
|
|
cpanel: /var/log/apache2/domlogs/DOMAIN-error_log
|
|
interworx: /home/USER/var/DOMAIN/logs/error_log
|
|
plesk: /var/www/vhosts/system/DOMAIN/logs/error_log
|
|
|
|
user_config:
|
|
cpanel: /var/cpanel/users/USER
|
|
interworx: /etc/httpd/conf.d/vhost_*.conf
|
|
plesk: plesk bin commands
|
|
|
|
domain_map:
|
|
cpanel: /etc/userdatadomains
|
|
interworx: vhost configs + SuexecUserGroup
|
|
plesk: plesk bin subscription --info
|
|
|
|
# CRITICAL DATABASE PREFIX PATTERN (MOST IMPORTANT!)
|
|
database_prefixes:
|
|
cpanel: username_dbname
|
|
interworx: first8charsOfDomain_dbname # NOT username!
|
|
plesk: no prefix
|
|
|
|
# Module Classification System
|
|
classes:
|
|
A: Panel-agnostic (7 modules) - No changes needed
|
|
B: System detection only (6 modules) - Use SYS_LOG_DIR
|
|
C: User/domain management (6 modules) - Complex refactoring
|
|
D: Panel-specific features (2 modules) - Conditional execution
|
|
Acronis: Backup suite (13 modules) - No changes needed
|
|
|
|
# Class C Refactoring Progress (4/6 complete)
|
|
class_c_complete:
|
|
- website-error-analyzer.sh (commit d657c8a)
|
|
- 500-error-tracker.sh (commit 93d4cf9)
|
|
- malware-scanner.sh (previous commit)
|
|
- optimize-ct-limit.sh (previous commit)
|
|
|
|
class_c_pending:
|
|
- wordpress-cron-manager.sh (33 /var/cpanel/userdata refs, 9 public_html refs)
|
|
- wordpress-menu.sh (needs audit)
|
|
|
|
# MANDATORY ABSTRACTION LIBRARIES
|
|
required_libraries:
|
|
system-detect.sh:
|
|
exports: SYS_CONTROL_PANEL, SYS_LOG_DIR, SYS_CONTROL_PANEL_VERSION
|
|
values: cpanel|interworx|plesk|standalone
|
|
usage: source at top of script, use in case statements
|
|
|
|
user-manager.sh:
|
|
get_user_info: Returns USER_EXISTS, PRIMARY_DOMAIN, ALL_DOMAINS, HOME_DIR
|
|
get_user_domains: Returns newline-separated domain list
|
|
get_user_databases: Returns database list for user
|
|
usage: NEVER grep /var/cpanel/users directly
|
|
|
|
# STANDARD CODE PATTERNS (COPY THESE)
|
|
patterns:
|
|
log_discovery: |
|
|
case "$SYS_CONTROL_PANEL" in
|
|
cpanel)
|
|
find "$SYS_LOG_DIR" -type f -name "*.com" 2>/dev/null
|
|
;;
|
|
interworx)
|
|
find /home/*/var/*/logs -type f -name "access_log" 2>/dev/null
|
|
;;
|
|
plesk)
|
|
find /var/www/vhosts/system/*/logs -type f -name "access_log" 2>/dev/null
|
|
;;
|
|
*)
|
|
[ -f "/var/log/httpd/access_log" ] && echo "/var/log/httpd/access_log"
|
|
;;
|
|
esac
|
|
|
|
domain_to_user: |
|
|
case "$SYS_CONTROL_PANEL" in
|
|
cpanel)
|
|
user=$(grep "^${domain}:" /etc/userdatadomains | cut -d: -f2 | awk -F'==' '{print $1}')
|
|
;;
|
|
interworx)
|
|
user=$(grep -l "ServerName ${domain}" /etc/httpd/conf.d/vhost_*.conf | \
|
|
xargs grep "SuexecUserGroup" | awk '{print $2}')
|
|
;;
|
|
plesk)
|
|
user=$(plesk bin subscription --info "$domain" | grep "Owner" | awk '{print $2}')
|
|
;;
|
|
esac
|
|
|
|
api_calls: |
|
|
if [ "$SYS_CONTROL_PANEL" = "cpanel" ]; then
|
|
whmapi1 some_command
|
|
else
|
|
print_warning "Feature requires cPanel"
|
|
return 1
|
|
fi
|
|
|
|
# COMMON MISTAKES TO AVOID
|
|
mistakes:
|
|
hardcoded_paths: NEVER use /var/log/apache2/domlogs or /home/user/public_html
|
|
cpanel_only_apis: NEVER use whmapi1/uapi without panel check
|
|
missing_source: Class B/C modules MUST source system-detect.sh AND user-manager.sh
|
|
fallback_paths: NO fallbacks - fail explicitly with clear message
|
|
userdata_grep: NEVER grep /var/cpanel/userdata or /var/cpanel/users
|
|
|
|
# Refactoring Commits
|
|
commits:
|
|
- Phase 1: user-manager.sh InterWorx support (819865b)
|
|
- Phase 2: bot-analyzer.sh + firewall detection (b86aa14)
|
|
- Phase 3: Security modules (0988224)
|
|
- Class B: Log directory refactoring (b770487)
|
|
- Class D: Panel version detection (8a2d9f5)
|
|
- website-error-analyzer.sh: Multi-panel (d657c8a)
|
|
- 500-error-tracker.sh: Multi-panel (93d4cf9)
|
|
- Documentation consolidation (fbce072)
|
|
|
|
[END]
|
|
# This file is the ONLY developer reference document.
|
|
# README.md is for users, this file is for developers (Claude).
|
|
# Keep this updated after every significant change.
|
|
# Last updated: 2025-11-19
|
|
################################################################################
|