From ffa94bcbea0f601d3de204ca2fd0ea0cbb9c6364 Mon Sep 17 00:00:00 2001 From: TheWitness Date: Mon, 21 Sep 2026 16:05:09 -0400 Subject: [PATCH 1/2] docs: add Security & Quality Conventions to copilot-instructions.md --- .github/copilot-instructions.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ad27f2e..e278f3c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -147,3 +147,28 @@ Document all changes in `CHANGELOG.md`; use descriptive commit messages referenc - [Cacti Documentation](https://www.github.com/Cacti/documentation) - `README.md` for feature descriptions - `CHANGELOG.md` for version history + +## Security & Quality Conventions + +These conventions apply across the Cacti plugin fleet and should be followed whenever touching +existing code or adding new code, not just in dedicated cleanup passes: + +- **No hardcoded third-party hosts.** Never hardcode a third-party IP address, hostname, or URL + in plugin code (even for tooling/download helpers). Expose it as a plugin setting instead, with + secure-by-default values (e.g. an SSL-verification setting that defaults to verify-on). +- **Prepared statements over `db_qstr()`.** Build dynamic `WHERE` clauses using the + `$sql_where`/`$sql_params` prepared-statement pattern, not string concatenation via `db_qstr()`. +- **Use `html_escape_request_var()`.** Prefer it over the `html_escape(get_request_var(...))` call + chain. +- **Harden `unserialize()`.** Always pass `['allow_classes' => false]` as the second argument. +- **i18n text domain.** Every `__()`/`__esc()` call must include this plugin's text domain as the + final argument, except when deliberately comparing against a literal, untranslated Cacti-core + label. +- **Plugin table-creation API.** Use `api_plugin_db_table_create()`/`api_plugin_db_add_column()` + (from Cacti core's `lib/plugins.php`) instead of raw `CREATE TABLE`/`ALTER TABLE ... ADD COLUMN`. + Both are idempotent (safe no-ops when already applied), so the same call can run unconditionally + from both the install AND upgrade paths. +- **PHPDoc shape.** Every function gets a PHPDoc block: a one-line description, a blank comment + line, `@param` lines, a blank comment line, then `@return`. Infer parameter/return types from + actual usage; don't change the function's real type-hints in the same pass (let static analysis + flag mismatches separately). Skip vendored third-party library files. From 1dd8206d0244101c6751fbed7f02a9ef63dcf0aa Mon Sep 17 00:00:00 2001 From: TheWitness Date: Mon, 21 Sep 2026 23:07:57 -0400 Subject: [PATCH 2/2] docs: fix grammar (install and upgrade) --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e278f3c..7cb2f88 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -167,7 +167,7 @@ existing code or adding new code, not just in dedicated cleanup passes: - **Plugin table-creation API.** Use `api_plugin_db_table_create()`/`api_plugin_db_add_column()` (from Cacti core's `lib/plugins.php`) instead of raw `CREATE TABLE`/`ALTER TABLE ... ADD COLUMN`. Both are idempotent (safe no-ops when already applied), so the same call can run unconditionally - from both the install AND upgrade paths. + from both the install and upgrade paths. - **PHPDoc shape.** Every function gets a PHPDoc block: a one-line description, a blank comment line, `@param` lines, a blank comment line, then `@return`. Infer parameter/return types from actual usage; don't change the function's real type-hints in the same pass (let static analysis