Maintenance Scripts & CLI Tools
Relevant source files
The following files were used as context for generating this wiki page:
The maintenance and CLI infrastructure of the IT Management System is centralized within the scripts/ directory. This module serves as a comprehensive toolbox for system administrators and developers, providing utilities for database maintenance, security auditing, automated testing, and administrative overrides. These tools are designed to ensure system integrity, multi-tenant isolation, and performance across the legacy PHP 7.4 environment.
The tools are categorized by their primary execution environment: Browser (HTML UI/Reports), CLI (Terminal/CI), or CLI-only (safety-critical or automated scripts). Access to these scripts is strictly controlled via session authentication, authorized IP filtering (e.g., 127.0.0.1), or specific maintenance tokens.
Sources: scripts/scripts.php:123-140, scripts/AGENT_NOTES.md:4-15, README.md:167-175
Execution Architecture and Access Control
Scripts within the system utilize a dual-access model. When executed via a browser, they typically render HTML reports or interactive UIs. When run via the Command Line Interface (CLI), they provide plain-text output and exit codes suitable for Continuous Integration (CI) pipelines.
Access Validation Logic
To bypass standard session redirects during CLI execution, scripts must define the ITM_CLI_SCRIPT constant. For browser access, scripts require either an active login session or a valid ITM_MAINTENANCE_TOKEN provided via the ?token= query parameter or the X-ITM-Maintenance-Token header.
Sources: scripts/scripts.php:2-3, scripts/scripts.php:125-130, scripts/AGENT_NOTES.md:12-14
The following diagram illustrates the initialization and access flow for scripts:
Diagram shows the conditional logic used to determine execution context and authorization levels.
Sources: scripts/scripts.php:1-5, scripts/AGENT_NOTES.md:12-15
Core Maintenance Categories
Security Auditing
The system includes specialized static analysis and runtime testing scripts to maintain the security posture of the application.
- CSRF Coverage:
check_csrf_coverage.phpscans POST handlers to ensure data mutation is protected by CSRF guards. - SQL Injection:
check_sql_injection_coverage.phpperforms static scanning for direct queries near user input, whiletest_sql_injection.phpprovides a JSON sandbox for signature detection. - Multi-tenant Leaks:
check_multi_tenant_leaks.phpensures that SQL queries and inserts on scoped tables correctly includecompany_idfilters.
Sources: scripts/scripts.php:248-310, wiki/Security.md:5-15, README.md:173-182
Database Management
Scripts are provided to handle schema verification, health monitoring, and data normalization.
- Health Analysis:
analyze_database_health.phprunsANALYZE TABLEon all base tables to identify corruption or performance issues. - Schema Verification:
verify_database_schema.phpcompares the live database againstdatabase.sqlto detect missing tables or structural drift. - Normalization:
normalize_database_sql_created_at.phpandupdate_all_created_at.phpare used to synchronize timestamps across seed data and live rows.
Sources: scripts/scripts.php:328-410, wiki/Security.md:20-35, README.md:188-202
Automated Testing (QA Runner)
The module_browser_qa_runner.php is the central engine for full-module Quality Assurance. It automates a sequence of operations across all modules for multiple companies.
Sources: scripts/scripts.php:615-645, scripts/api.php:107-110
| Step | Operation | Description |
|---|---|---|
| 1 | Preflight | Validates environment and session credentials. |
| 2 | Clear/Seed | Clears existing table data and inserts fresh sample rows. |
| 3 | CRUD Cycle | Executes Add, Edit, Bulk Delete, and Single Delete operations. |
| 4 | Export/Import | Verifies Excel/JSON export and subsequent re-import integrity. |
| 5 | Report Build | Generates a Markdown summary and XLSX log via module_browser_qa_build_report.php. |
Sources: scripts/scripts.php:615-660, scripts/api.php:105-115
Administrative and Developer Tools
Login Bypass and Session Hijacking
For rapid development and automated UI testing (e.g., via Playwright), the bypass_login.php script allows a developer to establish an authenticated Admin session directly from the CLI. This script generates a PHPSESSID, unlocks the Vault for the Passwords module, and adjusts file permissions so the web server can read the CLI-generated session.
Sources: scripts/scripts.php:735-745, scripts/AGENT_NOTES.md:46-70
Sequence diagram illustrating the administrative session establishment process.
Sources: scripts/AGENT_NOTES.md:46-65, scripts/scripts.php:735-740
Automated UI Capture
Python-based scripts utilizing Playwright are used to capture system state and document module interfaces.
take_screenshots_modules.py: Captures key states of all modules.take_screenshots_passwords.py: Specifically targets the encrypted Passwords and Bookmarks modules.
Sources: scripts/scripts.php:751-765, scripts/AGENT_NOTES.md:28-32
API Documentation Utility
The scripts/api.php file serves as a live documentation generator. It dynamically collects information about JSON endpoints, module import handlers, and authentication requirements.
- Endpoint Detection: It identifies modules that support the
import_excel_rowspayload used bytable-tools.js. - Authentication Model: Documents the requirement for session-based authentication + CSRF tokens rather than JWT.
Sources: scripts/api.php:15-60, scripts/api.php:128-145, README.md:155-165
Conclusion
The scripts directory provides the necessary infrastructure to manage the application's lifecycle beyond simple web interactions. By combining static analysis, automated QA runners, and administrative CLI tools, the project maintains high standards of data isolation and security in a multi-tenant environment. Developers are encouraged to use the smoke_test.sh and idfs_sync_human_test.php scripts as primary gates before submitting any structural changes.
Sources: scripts/scripts.php:123-145, scripts/AGENT_NOTES.md:75-80, wiki/Security.md:1-10