emcp-tools-mapping/docs/07-SYSTEM-OPS.md

07 — System Ops: Filesystem, Base de Dados, WP-CLI, Security Scanner, Performance Analyzer

Fonte: leitura directa do código-fonte emcp-tools v3.12.1 (build Free), instalado em emanuelalmeida.pt (/home/ealmeida/emanuelalmeida.pt/wp-content/plugins/emcp-tools/), 19-08-2026. Cruzado com docs/00-ARQUITECTURA.md (arquitectura geral, cadeia de arranque, emcp_tools_register_ability()) e skill://emcp-tools (postura de segurança ao vivo nos 3 sites do ecossistema, mecanismo do deny-list incremental).

Estes são os grupos de MAIOR RISCO do plugin. Todas as 6 tools de filesystem que mutam estado, todas as 6 de base de dados que mutam estado, e as 4 de WP-CLI (incluindo as duas de só leitura, get-wp-cli-job/list-wp-cli-jobs) fazem parte dos 131 slugs desligados por omissão em emanuelalmeida.pt/starter.descomplicar.pt (ver skill://emcp-tools §2.1/§2.2). Security Scanner e Performance Analyzer são as únicas duas ferramentas deste documento que ficam activas por omissão — são estritamente de leitura, nunca escrevem nada.

Todos os grupos deste documento registam-se sempre (não dependem de Elementor activo, nem de nenhum módulo opcional) — são chamados directamente em EMCP_Tools_Ability_Registrar::register_groups(), fora de qualquer bloco condicional if ( class_exists(...) ) ou if ( $elementor_active ). A única coisa que os torna "inúteis" num site com config por omissão é estarem no deny-list aplicado por EMCP_Tools_Plugin::filter_disabled_tools() (ver doc 00 §3).

---

1. Filesystem

Classe de abilities: EMCP_Tools_Filesystem_Abilities (includes/abilities/class-filesystem-abilities.php) Condição de registo: sempre activo (chamado sem guarda em register_groups()). permission_callback (todas as 6 tools): current_user_can( 'manage_options' ) — mesmo as de leitura, porque read-file/search-files podem expor segredos de config de outros ficheiros do site.

Tool	input_schema (resumo)	O que faz	Readonly / Destructive
read-file	path (string, required), offset (int, 1-based), limit (int)	Lê um ficheiro dentro de ABSPATH. Limite de 5 MB (MAX_READ_BYTES); recusa binários (devolve {binary:true} em vez do conteúdo); recusa wp-config.php (is_read_protected); suporta slice por linhas via offset/limit.	readonly / não destrutivo
list-directory	path (opt, default raiz), recursive (bool, profundidade máx. 5, cap 2000 entradas)	Lista entradas (nome/path/tipo/size/mtime) de um directório dentro de ABSPATH.	readonly
search-files	query (string, required), path (opt), extensions (array de string), max_results (int, default 200, tecto 500)	Grep de substring (case-sensitive) recursivo por uma árvore; ignora ficheiros >5 MB e wp-config.php; devolve {file, line, text} capado a 300 chars por match.	readonly
write-file	path, content (ambos required)	Cria ou sobrescreve um ficheiro. Faz backup do existente primeiro; recusa wp-config.php/.htaccess; limite 5 MB (MAX_WRITE_BYTES); requer writes_allowed() (capability edit_files + !DISALLOW_FILE_EDIT); invalida OPcache se .php; grava no change ledger unificado.	não readonly, destrutivo — desligado por omissão
edit-file	path, old_string, new_string (required), replace_all (bool)	Substituição exacta de string (old_string deve corresponder exactamente uma vez, a menos que replace_all). Backup, mesmo gate de escrita, mesma protecção de ficheiros, mesmo registo no ledger.	destrutivo — desligado por omissão
delete-file	path (required), confirm (bool)	Apaga um ficheiro. Exige confirm:true; backup antes de apagar; mesmo gate de escrita e protecção.	destrutivo — desligado por omissão

Guard: EMCP_Tools_Filesystem_Guard

Ficheiro: includes/class-filesystem-guard.php. Comentário do próprio ficheiro: "This is the security boundary for the filesystem tools. resolve_path() is the one chokepoint that makes 'inside the WordPress install only' true."

Constantes: MAX_READ_BYTES = 5242880 (5 MB), MAX_WRITE_BYTES = 5242880 (5 MB), BACKUP_DIR = 'emcp-fs-backups'.

• resolve_path( string $path, ?string $root = null ) — o chokepoint único. $root por omissão ABSPATH (parâmetro só existe para testes). Rejeita path vazio ou com byte NUL. Detecta se é absoluto (começa por /, \, ou C:\-like via regex). Constrói o candidato (absoluto tal-e-qual, ou rtrim($root) . '/' . ltrim($path)). Faz realpath(); se o próprio alvo não existir ainda (caso de escrita nova), resolve o directório pai com realpath() e reconstrói parent/basename. Compara o prefixo do caminho resolvido contra realpath($root): tem de ser exactamente igual ou começar por root . DIRECTORY_SEPARATOR — nunca um simples strpos, para evitar que /var/www/site-evil passe por prefixo de /var/www/site. Devolve WP_Error('outside_root') se escapar.
• is_protected( string $abs ) — lista de basenames escrita/eliminação-protegidos: wp-config.php, .htaccess (case-insensitive), filtrável via emcp_tools_fs_protected_paths.
• is_read_protected( string $abs ) — lista de basenames leitura-protegidos: só wp-config.php — .htaccess fica de fora porque não é um segredo, comentário explícito no código: "wp-config.php carries the DB credentials and auth salts; .htaccess is not a secret so it stays readable." Filtrável via emcp_tools_fs_read_protected_paths — um admin pode adicionar .env, ficheiros de chave, etc. Nota importante: as duas listas são deliberadamente diferentes (escrita ⊃ leitura) — não é o mesmo array reutilizado.
• backup_name( rel, timestamp ) — pure: nome de ficheiro sanitizado <timestamp>-<path-com-/-substituído-por-\->, caracteres fora de A-Za-z0-9._- viram -.
• is_utf8( content ) — pure: byte NUL ou falha em preg_match('//u', $content) → binário.
• check_writes( can_edit_files, disallow_file_edit ) — pure: combina a capability edit_files com a constante DISALLOW_FILE_EDIT.
• writes_allowed() — wrapper live: current_user_can('edit_files') && !(defined(DISALLOW_FILE_EDIT) && DISALLOW_FILE_EDIT).
• to_relative( abs ) — inverso de resolve_path para display/log (relativo a ABSPATH, slashes normalizados).
• backup( abs ) — copia o ficheiro-alvo para wp-content/uploads/emcp-fs-backups/<timestamp>-<path-flat> antes de qualquer write/edit/delete. Cria .htaccess (Require all denied) + index.html vazio no directório de backups na primeira utilização (bloqueia acesso web directo aos backups). Devolve '' quando o ficheiro-fonte ainda não existe (é uma criação, não um overwrite) — nesse caso o rollback ficheiro-a-ficheiro é do tipo 'file-create' em vez de 'file-backup'.
• log() — @deprecated 3.10.0, no-op. Auditoria foi migrada para o change ledger unificado (EMCP_Tools_Change_Log/EMCP_Tools_Change_Recorder::record_file(), documentado no doc 05) — class-filesystem-abilities.php::record_fs_change() monta a entrada do ledger com rollback do tipo file-backup/file-create e chama o recorder directamente.

Efeito colateral extra em cada escrita/edição/eliminação de .php: invalidate_php_opcache() chama opcache_invalidate($abs, true) — sem isto, o pedido seguinte podia executar bytecode cached obsoleto em vez do ficheiro recém-alterado.

Storage: backups em wp-content/uploads/emcp-fs-backups/ (protegido de acesso web via .htaccess). Registo de mudanças no change ledger unificado (ver doc 05) — nenhum log próprio separado.

---

2. Base de dados directa

Classe de abilities: EMCP_Tools_Database_Abilities (includes/abilities/class-database-abilities.php) Condição de registo: sempre activo. permission_callback (todas as 6 tools): current_user_can( 'manage_options' ).

Tool	input_schema (resumo)	O que faz	Readonly / Destructive
list-tables	(sem input)	Lista tabelas via information_schema.TABLES — nome, table_rows estimado, tamanho em bytes (data_length + index_length).	readonly
describe-table	table (string, required)	Valida o nome contra EMCP_Tools_Database_Guard::valid_table() e corre DESCRIBE; devolve colunas/tipos/keys.	readonly
query	sql (string, required), limit (int, default/tecto MAX_ROWS=1000)	Corre SQL de leitura validado por is_read_only_sql(). Recusa também leitura das tabelas users/usermeta mesmo em modo SELECT (query_touches_protected), apontando para list-users/get-user em vez disso.	readonly
insert-row	table, data (objecto) — ambos required	$wpdb->insert() parametrizado. Recusa tabelas protegidas. Regista no ledger (rollback.type = db-before-image, op = insert).	destrutivo — desligado por omissão
update-rows	table, data, where (todos objecto) — required	Exige where não-vazio (nunca um UPDATE sem condição). Captura before_image() (snapshot das linhas afectadas, cap 500) antes de $wpdb->update(). Recusa tabelas protegidas.	destrutivo — desligado por omissão
delete-rows	table, where (required), confirm (bool)	Exige confirm:true + where não-vazio. before_image() antes de $wpdb->delete(). Recusa tabelas protegidas.	destrutivo — desligado por omissão

Guard: EMCP_Tools_Database_Guard

Ficheiro: includes/class-database-guard.php. Comentário: "is_read_only_sql() is the safety boundary for the flexible read path." Constantes: MAX_ROWS = 1000, BEFORE_IMAGE_CAP = 500.

• normalize_sql( string $sql ) — pure, scanner char-a-char (não regex — evita problemas de backtracking/ReDoS em SQL longo). Substitui todo o comentário (--, #, /* */) por um espaço, todo o literal de string ('...'/"...", com escapes de backslash e duplicação de quote reconhecidos) por '', e todo o identificador entre backticks por ``. Não trata /*! ... */ (comentários executáveis do MySQL) — esses são rejeitados antes mesmo de chamar normalize_sql.
• is_read_only_sql( string $sql ) — a gate real, em cadeia:
  1. Se $sql contém /*! → rejeita de imediato. Comentário: "MySQL executes the body of /! ... ​/ executable comments, so we cannot safely strip-and-trust."
  2. normalize_sql() + trim().
  3. Multi-statement: qualquer ; que não seja o único carácter final (depois de rtrim) → rejeita.
  4. Vectores de acesso a ficheiros — regex /\b(into\s+outfile|into\s+dumpfile|load_file\s*\(|load\s+data\b)/i. Nota deliberada no código: sem \b a fechar — porque load_file( termina em (, e ( seguido de outro não-word-char não tem word boundary; um \b final deixaria passar LOAD_FILE por engano.
  5. Primeira palavra tem de ser uma de SELECT/SHOW/DESCRIBE/DESC/EXPLAIN/WITH.
  6. Denylist da frase inteira: INSERT|UPDATE|DELETE|REPLACE|MERGE|DROP|TRUNCATE|ALTER|CREATE|RENAME|GRANT|REVOKE|HANDLER|CALL|LOCK|UNLOCK|PREPARE|EXECUTE|INTO — como comentários/literais já foram removidos por normalize_sql, isto só apanha keywords reais (não texto dentro de uma string).
• valid_table( string $table ) — nomes de tabela não podem ser parametrizados em SQL (?/%s só serve para valores), por isso resolve contra SHOW TABLES ao vivo e devolve o nome real exacto (preserva case) ou WP_Error('unknown_table').
• table_is_protected/is_protected( $table ) — tabelas protegidas por omissão: $wpdb->users, $wpdb->usermeta, filtrável via emcp_tools_db_protected_tables.
• query_touches_tables/query_touches_protected( $sql ) — o análogo do lado da leitura: remove backticks, normaliza (comentários/strings fora), e testa se algum nome de tabela protegida aparece como identificador real com word boundaries (wp_users_backup não corresponde a wp_users). Aplicado ao tool query para bloquear leitura directa de password hashes/tokens de sessão via SELECT * FROM wp_users.
• before_image( $table, $where ) — SELECT * com condições de igualdade AND (parametrizado via $wpdb->prepare), LIMIT 500, chamado antes de update/delete.
• log() — @deprecated 3.10.0, no-op; ledger via EMCP_Tools_Change_Recorder::record_db().

Storage: nenhum armazenamento próprio — escreve directamente nas tabelas alvo via $wpdb; before-images e rollback vão para o change ledger unificado (blob store para snapshots grandes, ver doc 05).

---

3. WP-CLI (execução + jobs assíncronos)

Classe de abilities: EMCP_Tools_WPCLI_Abilities (includes/abilities/class-wpcli-abilities.php) Condição de registo: sempre activo. Todas as 4 tools deste grupo fazem parte dos 131 slugs desligados por omissão (skill://emcp-tools §2.1) — incluindo as duas de puro leitura (get-wp-cli-job/list-wp-cli-jobs), ao contrário de outros grupos onde read/write têm gates separadas. Provavelmente porque estas duas só fazem sentido em conjunto com run/dispatch. permission_callback (todas as 4): current_user_can( 'manage_options' ).

Comentário do cabeçalho do ficheiro, citado por ser exactamente o resumo de risco correcto: "Risk notice. WP-CLI is powerful and, via the shell path, is effectively command execution. The tool is confined by a command blocklist (no eval, eval-file, shell, raw db query, config writes, package install, or arbitrary PHP flags), ships disabled-by-default, is admin-gated, and audit-logs runs."

Tool	input_schema (resumo)	O que faz	Readonly / Destructive
run-wp-cli	command (string, required, sem wp inicial), timeout (int, default 60, tecto 300)	Corre um comando WP-CLI síncrono. Devolve stdout/stderr/exit_code. Executa in-process (WP_CLI::runcommand) se este pedido já corre dentro de um processo WP-CLI (transporte stdio), ou via shell (proc_open com um binário wp configurado) se ligado por HTTP.	destrutivo (por defeito de anotação — pode invocar qualquer subcomando não bloqueado) — desligado por omissão
dispatch-wp-cli	command (required), timeout (int, default 900, conselho até 86400)	Corre como job detached em background (para migrações/bulk tasks longas). Requer o caminho shell disponível — não é possível fazer detach de um comando in-process. Devolve job_id.	destrutivo — desligado por omissão
get-wp-cli-job	job_id (string, required)	Devolve estado do job (running/completed/failed), exit_code, stdout/stderr (tail capado).	readonly (anotação) — mesmo assim desligado por omissão
list-wp-cli-jobs	(sem input)	Lista jobs recentes (metadata apenas, sem stdout/stderr completos).	readonly (anotação) — mesmo assim desligado por omissão

Cada execução (run e dispatch) é registada no change ledger, mas não é reversível — comentário explícito no código: "not reversible — commands have no before-image".

Validator: EMCP_Tools_WPCLI_Validator

Ficheiro: includes/wpcli/class-wpcli-validator.php. A gate de segurança do grupo inteiro. Comentário do cabeçalho: "Args are always passed to the runner as an array (never interpolated into a shell string), so metacharacters in values are inert; this validator blocks the command surface that would let an operator run arbitrary PHP, raw SQL, or arbitrary shell."

• BLOCKED_COMMANDS = eval, eval-file, shell, server — comandos WP-CLI que dão execução de PHP arbitrário, shell interactivo, ou arrancam um servidor web embutido.
• BLOCKED_SUBCOMMANDS (pares comando subcomando) = db query, db cli, db import, db export, db reset, db drop, db clean, config set, config delete, config edit, package install, package update, package uninstall, cli update, cli cmd-dump, cli info. Note-se: db query/db cli/etc. é redundante em parte com a gate própria da ability database (§2), mas é defesa em profundidade — um agente não pode contornar o guard de SQL via WP-CLI.
• BLOCKED_FLAG_PREFIXES = --exec, --require (carregam PHP arbitrário), --path, --ssh, --http (retargeting do WP-CLI para outro install/servidor — poderia escapar do site actual), --prompt (ficaria pendurado à espera de input interactivo), --user=0.
• validate( $command ): trim(); rejeita \r/\n (anti-injecção de linha); remove prefixo "wp " tolerado; tokeniza; varre TODOS os tokens contra os prefixos de flag bloqueados (stripos, case-insensitive, por prefixo — não exact-match); identifica a "command word" = primeiro token não-flag (não começa por -) e o subcommand = segundo token não-flag; rejeita se o comando isolado ou o par comando+subcomando estiverem nas listas. Todas as três listas são filtráveis (emcp_tools_wpcli_blocked_commands, _blocked_subcommands, _blocked_flags).
• tokenize( $command ): tokenizador consciente de aspas (single/double quotes). Fora de aspas, um backslash é literal (friendly para paths Windows tipo C:\wp\wp-cli.phar). Dentro de aspas duplas, só \" e \\ são escapes reconhecidos; dentro de aspas simples, nada é escapado. Devolve WP_Error('wpcli_unterminated_quote') se uma aspa não fechar.

Runner: EMCP_Tools_WPCLI_Runner

Ficheiro: includes/wpcli/class-wpcli-runner.php. OUTPUT_CAP = 262144 (256 KB) por stream, truncado com "…[output truncated]".

• is_cli_context() — defined('WP_CLI') && WP_CLI && class_exists('\WP_CLI') — true se este pedido já corre dentro de um processo WP-CLI (o caso normal deste ecossistema, que liga via SSH+STDIO a wp mcp-adapter serve, ver doc 00 e skill://emcp-tools).
• base_command() — o binário wp configurado, ordem de prioridade: constante EMCP_TOOLS_WPCLI_COMMAND > option emcp_tools_wpcli_command > filtro emcp_tools_wpcli_command.
• shell_available() — proc_open existe, base_command() não vazio, e proc_open não está em disable_functions do php.ini.
• run( $command, $timeout=60 ) — valida via Validator::validate(); se is_cli_context() → run_in_process() usa WP_CLI::runcommand($cmd, ['return'=>'all','exit_error'=>false,'launch'=>false,'parse'=>false]) — corre dentro do mesmo processo PHP, sem fork/exec. Senão, se shell_available() → run_shell().
• run_shell() — proc_open($argv_array, ...). Comentário do código, crucial: "PHP 7.4+: an array command is executed WITHOUT a shell — arguments are passed verbatim, so no metacharacter can be interpreted." $argv = base_argv() + tokens + ['--path=' . ABSPATH, '--no-color']. Poll não-bloqueante (stream_set_blocking(false)), timeout com proc_terminate($proc, 9) (SIGKILL) se ultrapassar deadline (timed_out=true, exit_code=124), drena pipes no fim.

Jobs assíncronos: EMCP_Tools_WPCLI_Jobs

Ficheiro: includes/wpcli/class-wpcli-jobs.php. KEEP = 50 job dirs mantidos (mais antigos são apagados por prune(), por filemtime).

• dir() — wp-content/uploads/emcp-wpcli-jobs/, criado + protegido na primeira utilização com .htaccess (Require all denied\nDeny from all) + index.php silencioso.
• Estrutura por job (<id>/, $id = gmdate('Ymd-His') . '-' . substr(md5(uniqid()),0,6)):
  • meta.json — {id, command, timeout, status, created, started, finished, exit_code, user}; status transita queued → running → (completed|failed).
  • stdout.log / stderr.log — streams capturados.
  • run.sh (POSIX) ou run.bat (Windows) — launcher gerado, com o comando completo já montado via escapeshellarg() por token (implode(' ', array_map('escapeshellarg', $argv))) — a escaping fica de fora do proc_open/popen de spawn.
  • exit_code — ficheiro escrito pelo launcher quando o comando termina — é a fonte de verdade para o estado terminal (não um polling do processo pai).
• dispatch( $command, $timeout=900 ) — requer shell_available() (impossível fazer detach de algo já in-process); valida; prune(); grava meta.json inicial; spawn() lança o launcher detached — POSIX: proc_open(['sh','-c', 'nohup sh run.sh > /dev/null 2>&1 &'], ...); Windows: popen('cmd /c start /B "" cmd /c run.bat', 'r'). O processo pai não espera — retorna job_id de imediato com status='running'.
• get( $id ) — sanitiza $id (regex [^a-z0-9-] removido); lê meta.json; deriva o estado terminal do ficheiro exit_code se existir (0 = completed, !=0 = failed); devolve tail() do stdout/stderr (capado a OUTPUT_CAP, prefixo "…[output truncated]" — mostra o fim do log, não o início).
• all() — todos os jobs (glob(GLOB_ONLYDIR)), ordenados por created desc, sem stdout/stderr completos.
• spawn() — vale a pena ler: gera o run.sh/run.bat completo primeiro (incluindo redirecção de stdout/stderr/exit_code), depois só lança um shell trivial que executa esse ficheiro — separa completamente a lógica de "o que corre" da lógica de "como fica detached".

Storage: wp-content/uploads/emcp-wpcli-jobs/<job-id>/ (protegido de acesso web).

---

4. Security & Malware Scanner

Classe de abilities: EMCP_Tools_Security_Abilities (includes/abilities/class-security-abilities.php) Condição de registo: sempre activo. scan-security está ACTIVA por omissão (não faz parte do deny-list — a única categoria deste documento com essa distinção, junto com analyze-performance). permission_callback: current_user_can( 'manage_options' ).

Tool	input_schema (resumo)	O que faz	Readonly / Destructive
scan-security	checks (array de enum malware/integrity/hardening/software, opt — omitir corre as 4), deep (bool, default false), max_files (int, default 2000, tecto 20000), max_seconds (int, default 20, tecto 120)	Corre até 4 audits e devolve {summary:{score 0-100, grade A-F, counts}, sections:{malware,integrity,hardening,software}, scan_meta, top_recommendations}. deep=false cobre só uploads/ + plugins activos + tema activo; deep=true cobre toda a wp-content/ (mais lento).	readonly, destructive=false, idempotent=true — activa por omissão

Orchestrator: EMCP_Tools_Security_Scanner

Ficheiro: includes/security/class-security-scanner.php. CRITICAL_WEIGHT=20, WARNING_WEIGHT=5, CATEGORY_CRIT_CAP=60 (o penalty de criticals satura a 60 por categoria — impede que uma categoria sozinha com muitos criticals leve o score a zero), TOP_RECS=8.

• Construção LAZY dos 4 audits — só instanciados na primeira scan() que de facto precisa deles. Decisão de design explícita (comentário completo citado em §4.1 abaixo, ligado ao issue #100): registar a tool não pode instanciar o motor de audit, porque o registo de abilities corre em cada carregamento de página de admin e cada pedido REST.
• resolve_checks( $requested ) — pure: normaliza para o subset válido em ordem canónica; vazio/tudo-inválido → todos os 4.
• scan( $input ) — corre os checks pedidos, agrega findings, summarize().
• summarize( $findings ) — pure: conta por status (critical/warning/pass/info); penalty por categoria — cat_crit_pen[cat] = min(60, soma_de_20_por_cada_critical_nessa_categoria); score = 100 - soma(penalties_por_categoria) - (nº_warnings * 5), clamp [0,100]; grade A(≥90)/B(≥80)/C(≥70)/D(≥60)/F(resto).
• group_by_category — agrupa em 4 secções fixas.
• rank_recommendations — críticos primeiro, depois warnings, corta a 8, formato "[label] recomendação".

Value object: EMCP_Tools_Security_Finding

Ficheiro: includes/security/class-security-finding.php. Uma única factory pure: make( id, category, label, status, value, message, recommendation='' ) → array uniforme. status ∈ pass|warning|critical|info; recommendation deve ser não-vazio quando status != 'pass'.

4.1 Audit — Malware (EMCP_Tools_Security_Malware_Audit)

Ficheiro: includes/security/class-security-malware-audit.php. MAX_FILE_BYTES=2MB (ficheiros maiores são saltados), MAX_LINE_BYTES=64KB (cap por linha alimentada às regex — guarda anti-ReDoS/backtrack-limit; o comentário explica: linhas longas fazem preg_match devolver false silenciosamente ao atingir pcre.backtrack_limit, mascarando um hit real), MAX_FILES=2000/CEILING=20000, TIME_BUDGET=20s/CEILING=120s, SNIPPET_LEN=120, MAX_FINDINGS_PER_FILE=5.

• scan_code( code, relpath, in_uploads ) — pure: corre 5 regras de assinatura linha a linha (ver abaixo); nunca devolve mais de 5 achados por ficheiro; o value de cada finding é {location: "path:line", snippet} — nunca o conteúdo completo do ficheiro.
• is_misplaced_php( relpath ) — PHP executável dentro de uploads/ (extensões php/phtml/php3-7/phps/pht).
• is_trivial_php( code ) — pure, usa token_get_all() para distinguir um index.php "Silence is golden" (só T_OPEN_TAG/CLOSE_TAG/WHITESPACE/COMMENT/DOC_COMMENT) de PHP com código real — evita falsos positivos em guardas de directório vazias.
• is_excluded( relpath, prefixes ) — exclui a própria pasta de instalação do plugin (via EMCP_TOOLS_DIR) + o directório sandbox gerido (EMCP_Tools_Sandbox_Paths::relative_base()), para o scanner não se auto-detectar como malware.
• run( deep, max_files, max_seconds ) — scan_roots(deep): false → uploads/ + plugins activos + tema activo/pai; true → toda a wp-content/. Percorre com RecursiveIteratorIterator + FOLLOW_SYMLINKS, mas valida que o caminho resolvido continua dentro de ABSPATH (bloqueia escape de symlink). Ficheiro PHP executável sob uploads/ com código real (não trivial) gera um achado crítico dedicado malware_uploads_php antes de correr as 5 regras normais.

🏆 O achado mais importante deste ficheiro (citação literal, comentário do autor):

As assinaturas de malware (eval, assert, create_function, base64_decode, gzinflate, system, exec, shell_exec, c99shell, r57shell, b374k, phpspy, WSO, etc.) NÃO estão escritas de forma literal no ficheiro-fonte — estão fragmentadas em signature_tokens() como concatenações ('ev' . 'al'), reunidas em runtime via expand()/strtr(). Comentário do autor no código:

"This class is a malware scanner, so its rules have to name the exact functions and webshell handles that host-level scanners (Imunify360, maldet, Wordfence, ModSecurity) hunt for. Spelled out intact, this file reads as a c99-style webshell and gets quarantined or zeroed in place. require_once then still succeeds (the path exists) but the class is never declared, which used to fatal every wp-admin page and REST request (issue #100)."

"Splitting the tokens means no intact signature ever sits on disk. The patterns compiled below are byte-identical to the originals, so detection behaviour is unchanged. Keep any new signature split the same way."

Este é o motivo directo por trás tanto da construção lazy no orchestrator (§4, issue #100) como desta fragmentação de tokens: um scanner de malware do próprio host identificava literalmente este ficheiro como um webshell e colocava-o em quarentena/zerava-o, partindo o site inteiro (a classe deixava de existir mas o require_once continuava a "ter sucesso" silenciosamente — o registo de abilities engolia a excepção mas o servidor MCP ficava sem esta tool).

As 5 regras de assinatura:

1. malware_eval_obfuscation (critical) — eval/assert/create_function envolvendo um decoder (base64_decode/gzinflate/gzuncompress/str_rot13/strrev/convert_uudecode).
2. malware_request_eval (critical) — eval/assert/system/exec/passthru/ shell_exec/popen/proc_open recebendo directamente $_GET/POST/REQUEST/COOKIE/SERVER — o backdoor RCE clássico.
3. malware_command_exec (warning; critical se in_uploads) — qualquer chamada de shell_exec/passthru/proc_open/popen/system/exec isolada.
4. malware_webshell_marker (critical) — strings de webshells conhecidos (FilesMan, c99shell, r57shell, b374k, phpspy, WSO<versão>shell).
5. malware_long_base64 (warning) — blob de 260+ chars base64-like (payload escondido).

4.2 Audit — Integrity (EMCP_Tools_Security_Integrity_Audit)

Ficheiro: includes/security/class-security-integrity-audit.php.

• diff( checksums, hasher ) — pure: compara o manifesto de checksums oficial do wordpress.org (md5 por ficheiro core-relative) contra o hash real via hash_equals() (timing-safe); ficheiro em falta → warning('integrity_missing'); hash não bate → critical('integrity_modified').
• run() — usa a função core get_core_checksums($wp_version, $locale) (wp-admin/includes/update.php); exclui tudo em wp-content/ (não faz parte dos checksums oficiais de core). Se a API estiver inacessível (offline) devolve um único finding info com api.ok=false — degrada graciosamente em vez de falhar todo o scan.

4.3 Audit — Hardening (EMCP_Tools_Security_Hardening_Audit)

Ficheiro: includes/security/class-security-hardening-audit.php. FETCH_TIMEOUT=8s.

7 checks, cada evaluate_*() pure, run() gathers live + UM loopback GET reutilizado para dois checks (headers + generator meta):

Check	Pass	Warning/Critical
harden_file_edit	DISALLOW_FILE_EDIT definido true	editor de ficheiros do admin ligado
harden_debug_display	WP_DEBUG_DISPLAY off	warning se on em produção; info noutro ambiente
harden_admin_user	sem user admin	username_exists('admin')
harden_xmlrpc	XML-RPC desligado	xmlrpc.php existe + filtro xmlrpc_enabled true
harden_https	scheme de home_url() é https	qualquer outro
harden_security_headers	X-Frame-Options + X-Content-Type-Options + Strict-Transport-Security + Content-Security-Policy todos presentes	falta pelo menos um (via 1 loopback GET a home_url('/'))
harden_version_disclosure	sem readme.html nem meta generator no HTML	qualquer um presente

4.4 Audit — Software (EMCP_Tools_Security_Software_Audit)

Ficheiro: includes/security/class-security-software-audit.php. MAX_ABANDONED_LOOKUPS=30 (orçamento de chamadas plugins_api ao vivo por scan), ABANDONED_CACHE_TTL=43200 (12h, transient por-slug).

Checks: core desactualizado, plugins/temas desactualizados (um finding por item), plugins inactivos (contagem — info, não warning), plugins abandonados/removidos do directório wordpress.org — via plugins_api('plugin_information', ['slug'=>$slug]) e o campo $info->closed. O resultado (closed/open) fica em cache num transient emcp_sec_abandoned_<md5(slug)> durante 12h; um WP_Error (plugin premium não no wp.org, ou API em baixo) não é marcado nem colocado em cache — retenta no próximo scan. Slugs já em cache não contam para o orçamento de 30 chamadas ao vivo — só chamadas realmente feitas são limitadas.

---

5. Performance Analyzer

Classe de abilities: EMCP_Tools_Performance_Abilities (includes/abilities/class-performance-abilities.php) Condição de registo: sempre activo. analyze-performance está ACTIVA por omissão (igual a scan-security). permission_callback: current_user_can( 'manage_options' ).

Tool	input_schema (resumo)	O que faz	Readonly / Destructive
analyze-performance	url (uri, opt — página deste site, hosts externos rejeitados), post_id (int, opt — ignorado se url definido), include_page_fetch (bool, default true — false corre só server/DB), deep_assets (bool, reservado, ainda não implementado)	Sem url/post_id analisa a frontpage. Devolve {target, summary{score,grade,counts}, sections, page_fetch, top_recommendations}.	readonly, destructive=false, idempotent=true — activa por omissão

Orchestrator: EMCP_Tools_Performance_Analyzer

Ficheiro: includes/performance/class-performance-analyzer.php. CRITICAL_WEIGHT=15, WARNING_WEIGHT=4, TOP_RECS=8 (pesos diferentes do Security Scanner — mais leve, sem cap por categoria).

• analyze( $input ) — resolve_target() primeiro (url|post_id|frontpage); corre sempre o server audit; corre o page audit condicionalmente (include_page_fetch); combina findings; summarize() + group_by_category().
• resolve_target( $input ) — valida que url está no mesmo host que home_url() via validate_same_host() (pure) — protecção anti-SSRF/anti-scan-de-outro-site logo à entrada.
• summarize( $findings ) — pure: score = 100 - (critical*15) - (warning*4), sem cap por categoria (diferente do Security Scanner); grade A-F igual.
• group_by_category — 5 secções fixas: server, database, config, page, assets.

Value object: EMCP_Tools_Performance_Finding

Ficheiro: includes/performance/class-performance-finding.php. Idêntico em forma ao Security_Finding — factory pure make(id, category, label, status, value, message, recommendation='').

5.1 Audit — Server (EMCP_Tools_Performance_Server_Audit)

Ficheiro: includes/performance/class-performance-server-audit.php. Todo in-process, sem HTTP. MIN_MEMORY_BYTES=128MB, AUTOLOAD_WARN=1MB/CRIT=3MB, PLUGIN_WARN_COUNT=40, REVISIONS_WARN_COUNT=1000, TOP_TABLES=5, TOP_AUTOLOAD_OPTIONS=5.

11 checks pure+live: versão PHP (≥8.2 pass, ≥8.0 warning, senão critical), memory_limit (≥128MB pass, -1=ilimitado=pass, senão warning), OPcache activo, object cache persistente (wp_using_ext_object_cache()), biblioteca de imagem (Imagick ou GD), WP_DEBUG em produção (warning) vs outros ambientes (info), contagem de plugins activos (>40 → warning), revisões de posts (>1000 → warning, COUNT(*) WHERE post_type='revision'), backlog de cron overdue >5min (via _get_cron_array()), tamanho de opções autoload (SUM(LENGTH(option_value)) WHERE autoload IN ('yes','on','auto') — nota: cobre as 3 variantes de valor da coluna autoload, não só 'yes'; devolve top 5 maiores), tamanho da base de dados (SUM(data_length+index_length) de information_schema.TABLES, top 5 tabelas maiores).

5.2 Audit — Page (EMCP_Tools_Performance_Page_Audit)

Ficheiro: includes/performance/class-performance-page-audit.php. 1 loopback HTTP fetch + parsing DOM. Não executa JS — análise de HTML/headers, não Core Web Vitals reais. FETCH_TIMEOUT=10s, MAX_HTML_BYTES=2MB (cap de parsing), MAX_REDIRECTS=3, RESPONSE_WARN_MS=800, HTML_WARN_BYTES=500KB, RENDER_BLOCK_WARN=5.

• fetch( $url, $timeout=10 ) — segue redirects manualmente (redirection=0 em cada wp_remote_get, loop até MAX_REDIRECTS) em vez de delegar no redirection nativo do wp_remote_get. Motivo: cada hop precisa de ser revalidado contra o host de origem (safe_redirect_target()) — um redirect para outro host é recusado, não seguido.
• safe_redirect_target( location, current_url, origin_host ) — resolve Location relativo contra o URL actual (scheme+host), depois testa se o host de destino == origin_host (case-insensitive); devolve '' se sair do host. Guarda anti-SSRF explícita: um atacante não pode fazer o site "chutar" outro host arbitrário através de um redirect 301/302 configurado maliciosamente numa página que este tool analisa.
• analyze( $fetched, $deep_assets ) — pure. Se o fetch falhou → 1 finding warning e degrada graciosamente (server/DB continuam reportados normalmente). Se OK: http_status (200=pass), response_time (>800ms=warning), html_size (>500KB=warning), compression (gzip/br em content-encoding), cache_headers (Cache-Control/Expires/X-Cache presentes), depois parse_dom() com DOMDocument (libxml_use_internal_errors para engolir HTML malformado) + asset_findings(): render-blocking (<link rel=stylesheet> no <head> + <script> síncrono no <head> sem async/defer, warning se >5), asset_counts (info), image_lazy_loading (contagem de <img> sem loading="lazy", info), third_party (domínios de <link>/<script src> diferentes do host analisado, info).

Storage: nenhum armazenamento próprio para nenhum dos dois audits — tudo calculado ao vivo e devolvido na resposta; nada persistido em disco/BD (excepto os transients de cache do audit de software do Security Scanner, que é um documento diferente — §4.4).

---

Blueprint para réplica

Copiar quase 1:1 (código já correcto, difícil de reproduzir sem reintroduzir bugs)

1. EMCP_Tools_Filesystem_Guard::resolve_path() — o chokepoint de confinamento a ABSPATH. A lógica de comparação de prefixo (=== OU strpos($real, $root . DIRECTORY_SEPARATOR) === 0, nunca um strpos simples) evita a classe de bugs "/var/www/site-evil passa como prefixo de /var/www/site". O tratamento de caminhos que ainda não existem (resolver o pai com realpath para permitir criar um ficheiro novo) é subtil e vale a pena copiar tal-e-qual.
2. A distinção is_protected (write) vs is_read_protected (read) — não são a mesma lista. .htaccess pode ser lido mas não escrito/apagado; wp-config.php não pode nem sequer ser lido. Uma réplica que use uma única lista "protected" para tudo está a proteger a menos (deixa ler segredos) ou a mais (bloqueia leitura de .htaccess, que é inofensiva e útil de auditar).
3. Padrão "backup antes de escrever, directório de backups bloqueado a acesso web" — .htaccess Require all denied + index.html vazio no directório de backups, gerado on-demand na primeira escrita. Simples e eficaz; copiar tal-e-qual.
4. EMCP_Tools_Database_Guard::normalize_sql() + is_read_only_sql() — o scanner char-a-char que neutraliza comentários/strings/identificadores antes de testar keywords é sofisticado e já tem dois bugs de "quase-passou" documentados directamente nos comentários do código (o truque /*! do MySQL, e o cuidado de não pôr \b a fechar no regex de LOAD_FILE(). Reimplementar do zero arrisca reintroduzir exactamente estes dois bugs já corrigidos aqui.
5. valid_table() a resolver contra SHOW TABLES ao vivo em vez de confiar no input — nomes de tabela não podem ser parametrizados em SQL preparado, por isso a única forma segura de os validar é confirmá-los contra uma lista real.
6. EMCP_Tools_WPCLI_Validator — a combinação de blocklist de comandos/subcomandos/flags + tokenizador consciente de aspas (com as regras específicas de escaping por tipo de aspa, e o comportamento "backslash literal fora de aspas" para paths Windows) é bem pensada e testada. Copiar a estrutura (3 listas filtráveis + tokenizer) quase tal-e-qual.
7. O princípio "argv array, nunca string interpolada" em WPCLI_Runner::run_shell() e WPCLI_Jobs::spawn() — mesmo quando o spawn() monta uma string via implode(' ', array_map('escapeshellarg', $argv)) para o ficheiro launcher, cada TOKEN individual passa primeiro por escapeshellarg(); nunca há concatenação directa de input do utilizador numa string de shell. Esta é a regra arquitectural mais importante de todo este documento — qualquer tool nova que precise de invocar um processo externo deve seguir o mesmo padrão.
8. A técnica de fragmentação de assinaturas do malware scanner (signature_tokens() + expand()) — o achado mais interessante de todo o ficheiro: se uma réplica alguma vez escrever o seu próprio scanner de malware, tem de aplicar a mesma técnica ou arrisca ser confundida com o próprio malware que procura, por scanners de host (Imunify360, maldet, Wordfence). Ver citação completa em §4.1.
9. Performance_Page_Audit::fetch() / safe_redirect_target() — seguir redirects manualmente em vez de delegar no parâmetro redirection do wp_remote_get, revalidando o host em cada hop. Este padrão é reutilizável para qualquer futura tool "analisar um URL deste site" (ex. um crawler de sitemap) — nunca confiar que o WordPress core segue redirects de forma segura para este caso de uso.

Simplificar

1. O caminho "shell" completo de WP-CLI (binário wp configurável via option/constante, proc_open HTTP, jobs em background detached) é infraestrutura pesada que só é necessária quando o servidor MCP é alcançado por HTTP puro (sem contexto WP-CLI). Neste ecossistema, os 3 servidores MCP já ligam via SSH+STDIO a wp mcp-adapter serve (ver doc 00 e skill://emcp-tools) — ou seja, is_cli_context() é sempre verdadeiro e o caminho run_in_process() cobre 100% da utilização real. Uma réplica focada neste padrão de deployment pode eliminar inteiramente o caminho shell + jobs detached (WPCLI_Runner::run_shell, toda a classe WPCLI_Jobs) e ficar só com WP_CLI::runcommand(..., launch=false) — muito menos superfície de ataque e código para manter, sem perder funcionalidade no cenário real de uso.
2. Security_Finding/Performance_Finding são factories triviais de um único método — copiar tal-e-qual sem redesenho, não há aqui nada a simplificar mais.
3. O cap CATEGORY_CRIT_CAP=60 por categoria no Security Scanner é razoável mas arbitrário — uma réplica pode adoptar o mesmo valor sem re-derivar a heurística, ou simplesmente usar o scoring mais simples do Performance Analyzer (sem cap) se a diferenciação por categoria não for um requisito.

Deixar de fora (ou adiar)

1. deep_assets no Performance Analyzer — está no schema como "reserved", nunca chegou a ser implementado neste build. Não vale a pena reservar espaço para uma feature que o próprio vendor não implementou em 12 versões (since 3.0.0).

Gotchas não óbvios a não esquecer

• Invalidação de OPcache após escrever/apagar .php (opcache_invalidate($abs, true)) — é fácil esquecer este passo numa réplica e ter bugs "a alteração não teve efeito" reportados como falsos negativos de teste.
• O deny-list incremental (doc 00 §8) é a camada EXTERNA de defesa; os guards deste documento são a camada INTERNA. Mesmo que uma réplica não implemente um deny-list configurável, TODAS as gates internas aqui documentadas (confinamento de path, validação de SQL, blocklist de WP-CLI, confirm:true obrigatório em deletes) devem ser mantidas — são a última linha de defesa se o deny-list for mal configurado (ver o achado crítico de descomplicar.pt no skill://emcp-tools §8.2, onde o deny-list externo falhou completamente e só as gates internas — que continuam a existir mas não bastam sozinhas quando a tool está "activa" — teriam impedido o pior).
• get-wp-cli-job/list-wp-cli-jobs são readonly e mesmo assim ficam desligados por omissão em bloco com run/dispatch — é uma escolha deliberada de UX/segurança (não faz sentido dar acesso a resultados de jobs sem dar acesso a criá-los), mas quebra o padrão "read sempre activo, write desligado" que domina o resto do plugin. Documentar esta excepção explicitamente numa réplica para não ser "corrigida" por engano.
• A construção lazy dos audits de segurança não é só uma optimização de performance — é uma medida de resiliência anti-fatal-error (issue #100). Qualquer réplica que registe abilities em cada wp_abilities_api_init (que corre em TODO pedido admin/REST) deve tratar a construção de qualquer dependência pesada/frágil da mesma forma: lazy, e sempre com um try/catch a envolver o registo global (ver EMCP_Tools_Ability_Registrar::register_all() no doc 00, que já faz exactamente isto ao nível do registrador inteiro).

---

Fonte

Leitura directa (19-08-2026) de: includes/abilities/class-filesystem-abilities.php, includes/class-filesystem-guard.php, includes/abilities/class-database-abilities.php, includes/class-database-guard.php, includes/abilities/class-wpcli-abilities.php, includes/wpcli/class-wpcli-runner.php, includes/wpcli/class-wpcli-validator.php, includes/wpcli/class-wpcli-jobs.php, includes/abilities/class-security-abilities.php, includes/security/class-security-scanner.php, includes/security/class-security-malware-audit.php, includes/security/class-security-hardening-audit.php, includes/security/class-security-software-audit.php, includes/security/class-security-integrity-audit.php, includes/security/class-security-finding.php, includes/abilities/class-performance-abilities.php, includes/performance/class-performance-analyzer.php, includes/performance/class-performance-server-audit.php, includes/performance/class-performance-page-audit.php, includes/performance/class-performance-finding.php.

Cruzado com includes/abilities/class-ability-registrar.php (condições de registo — todos os 5 grupos deste documento registam-se sem guarda condicional, fora do bloco if ($elementor_active)) e com docs/00-ARQUITECTURA.md + skill://emcp-tools (contexto de arquitectura geral e postura de deny-list ao vivo nos 3 sites do ecossistema).