Skip to content

Commit 813960b

Browse files
bmfmancinibmfmancini
authored
Github actions setup (#41)
* agents * Audit plugin CI workflow * Update plugin-ci-workflow.yml * Update plugin-ci-workflow.yml * Update plugin-ci-workflow.yml * Create copilot-instructions.md
1 parent 4425d52 commit 813960b

File tree

2 files changed

+325
-0
lines changed

2 files changed

+325
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Cacti Audit Plugin AI Instructions
2+
3+
## Architecture Overview
4+
This is a Cacti plugin that logs GUI and CLI activities to an audit trail. The plugin hooks into Cacti's event system to capture user actions.
5+
6+
**Core Components:**
7+
- [`setup.php`](../setup.php): Plugin lifecycle (install/uninstall/upgrade) and hook registration via `api_plugin_register_hook()`
8+
- [`audit.php`](../audit.php): Web UI for viewing/exporting/purging audit logs; handles actions via `switch(get_request_var('action'))`
9+
- [`audit_functions.php`](../audit_functions.php): Core logging logic in `audit_config_insert()` and page-specific data extraction in `audit_process_page_data()`
10+
- Database: Single `audit_log` table with columns: `page`, `user_id`, `action`, `ip_address`, `user_agent`, `event_time`, `post` (JSON), `object_data` (JSON)
11+
12+
**Data Flow:**
13+
1. Cacti triggers `config_insert` hook on POST requests → `audit_config_insert()` executes
14+
2. Function validates event via `audit_log_valid_event()`, sanitizes `$_POST`, removes passwords
15+
3. If `selected_items` present, `audit_process_page_data()` extracts object details from DB
16+
4. Event logged to `audit_log` table + optional external JSON file
17+
18+
## Critical Conventions
19+
20+
### Function Naming
21+
ALL functions MUST use `audit_` or `plugin_audit_` prefix to avoid namespace collisions with Cacti core.
22+
23+
### Input Handling (Security Critical)
24+
**NEVER** access `$_GET`/`$_POST` directly. Always use:
25+
- `get_request_var('name')` - for basic input
26+
- `get_filter_request_var('name')` - for validated/filtered input
27+
- `get_nfilter_request_var('name')` - for non-filtered input
28+
- `isset_request_var('name')` - to check existence
29+
30+
Example from [`audit.php`](../audit.php#L30):
31+
```php
32+
switch(get_request_var('action')) {
33+
case 'export':
34+
audit_export_rows();
35+
break;
36+
```
37+
38+
### Database Operations (Security Critical)
39+
**ALWAYS** use prepared statements, NEVER string concatenation:
40+
- `db_execute_prepared($sql, $params)` - for INSERT/UPDATE/DELETE
41+
- `db_fetch_assoc_prepared($sql, $params)` - for SELECT returning rows
42+
- `db_fetch_row_prepared($sql, $params)` - for single row
43+
- `db_fetch_cell($sql)` - only for queries without user input
44+
45+
Example from [`audit_functions.php`](../audit_functions.php#L210-L212):
46+
```php
47+
db_execute_prepared('INSERT INTO audit_log (page, user_id, action, ip_address, user_agent, event_time, post, object_data)
48+
VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
49+
array($page, $user_id, $action, $ip_address, $user_agent, $event_time, $post, $object_data));
50+
```
51+
52+
### Localization
53+
Wrap ALL user-facing strings in `__('String', 'audit')`. The second parameter `'audit'` is the text domain.
54+
55+
Example: `__('View Audit Log', 'audit')`
56+
57+
For plurals: `__('%d Months', 2, 'audit')`
58+
59+
### UI Structure
60+
- Use `top_header()` before and `bottom_footer()` after page content
61+
- Use `html_start_box()` / `html_end_box()` for content sections
62+
- Access Cacti config: `global $config;`
63+
64+
## Developer Workflows
65+
66+
### Testing Integration
67+
GitHub Actions runs tests against live Cacti install. See [`.github/workflows/plugin-ci-workflow.yml`](../.github/workflows/plugin-ci-workflow.yml):
68+
- Tests against PHP 8.1, 8.2, 8.3
69+
- Plugin must be in `cacti/plugins/audit` directory (NOT `plugin_audit`)
70+
- MySQL 8.0 service with user `cactiuser:cactiuser`, database `cacti`
71+
72+
### Localization Workflow
73+
```bash
74+
cd locales
75+
./build_gettext.sh
76+
```
77+
Requires `xgettext` (GNU gettext). Regenerates `po/cacti.pot` from all `__()` calls, then compiles `.po` → `.mo` files.
78+
79+
### Upgrades & Schema Changes
80+
When adding DB columns, update `audit_check_upgrade()` in [`setup.php`](../setup.php#L69-L100):
81+
```php
82+
db_execute('ALTER TABLE audit_log ADD COLUMN IF NOT EXISTS object_data LONGBLOB');
83+
```
84+
This runs on plugin version change detection.
85+
86+
## Hook System
87+
Hooks registered in `plugin_audit_install()`:
88+
- `config_insert` - Main logging trigger (fires on POST requests)
89+
- `poller_bottom` - Daily cleanup of old records based on retention setting
90+
- `config_arrays` - Inject menu items and configuration arrays
91+
- `config_settings` - Add admin settings page
92+
- `draw_navigation_text` - Define breadcrumb navigation
93+
- `replicate_out` - Table replication for remote pollers
94+
95+
## Key Files Reference
96+
- [`setup.php`](../setup.php) - Hook registration, table schema, upgrade logic
97+
- [`audit.php`](../audit.php) - UI controller with export/purge/getdata actions
98+
- [`audit_functions.php`](../audit_functions.php) - `audit_config_insert()` (main logger), `audit_process_page_data()` (extract object details)
99+
- [`locales/build_gettext.sh`](../locales/build_gettext.sh) - Translation builder
100+
- [`.github/workflows/plugin-ci-workflow.yml`](../.github/workflows/plugin-ci-workflow.yml) - Integration tests

‎.github/workflows/plugin-ci-workflow.yml‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# +-------------------------------------------------------------------------+
2+
# | Copyright (C) 2004-2025 The Cacti Group |
3+
# | |
4+
# | This program is free software; you can redistribute it and/or |
5+
# | modify it under the terms of the GNU General Public License |
6+
# | as published by the Free Software Foundation; either version 2 |
7+
# | of the License, or (at your option) any later version. |
8+
# | |
9+
# | This program is distributed in the hope that it will be useful, |
10+
# | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11+
# | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
12+
# | GNU General Public License for more details. |
13+
# +-------------------------------------------------------------------------+
14+
# | Cacti: The Complete RRDtool-based Graphing Solution |
15+
# +-------------------------------------------------------------------------+
16+
# | This code is designed, written, and maintained by the Cacti Group. See |
17+
# | about.php and/or the AUTHORS file for specific developer information. |
18+
# +-------------------------------------------------------------------------+
19+
# | http://www.cacti.net/ |
20+
# +-------------------------------------------------------------------------+
21+
22+
name: Plugin Integration Tests
23+
24+
on:
25+
push:
26+
branches:
27+
- main
28+
- develop
29+
pull_request:
30+
branches:
31+
- main
32+
- develop
33+
34+
jobs:
35+
integration-test:
36+
runs-on: ${{ matrix.os }}
37+
38+
strategy:
39+
fail-fast: false
40+
matrix:
41+
php: ['8.1', '8.2', '8.3']
42+
os: [ubuntu-latest]
43+
44+
services:
45+
mysql:
46+
image: mysql:8.0
47+
env:
48+
MYSQL_ROOT_PASSWORD: cactiroot
49+
MYSQL_DATABASE: cacti
50+
MYSQL_USER: cactiuser
51+
MYSQL_PASSWORD: cactiuser
52+
ports:
53+
- 3306:3306
54+
options: >-
55+
--health-cmd="mysqladmin ping"
56+
--health-interval=10s
57+
--health-timeout=5s
58+
--health-retries=3
59+
60+
name: PHP ${{ matrix.php }} Integration Test on ${{ matrix.os }}
61+
62+
steps:
63+
- name: Checkout Cacti
64+
uses: actions/checkout@v4
65+
with:
66+
repository: Cacti/cacti
67+
path: cacti
68+
69+
- name: Checkout audit Plugin
70+
uses: actions/checkout@v4
71+
with:
72+
path: cacti/plugins/audit
73+
74+
- name: Install PHP ${{ matrix.php }}
75+
uses: shivammathur/setup-php@v2
76+
with:
77+
php-version: ${{ matrix.php }}
78+
extensions: intl, mysql, gd, ldap, gmp, xml, curl, json, mbstring
79+
ini-values: "post_max_size=256M, max_execution_time=60, date.timezone=America/New_York"
80+
81+
- name: Check PHP version
82+
run: php -v
83+
84+
85+
- name: Run apt-get update
86+
run: sudo apt-get update
87+
88+
- name: Install System Dependencies
89+
run: sudo apt-get install -y apache2 snmp snmpd rrdtool fping libapache2-mod-php${{ matrix.php }}
90+
91+
- name: Start SNMPD Agent and Test
92+
run: |
93+
sudo systemctl start snmpd
94+
sudo snmpwalk -c public -v2c -On localhost .1.3.6.1.2.1.1
95+
96+
- name: Setup Permissions
97+
run: |
98+
sudo chown -R www-data:runner ${{ github.workspace }}/cacti
99+
sudo find ${{ github.workspace }}/cacti -type d -exec chmod 775 {} \;
100+
sudo find ${{ github.workspace }}/cacti -type f -exec chmod 664 {} \;
101+
sudo chmod +x ${{ github.workspace }}/cacti/cmd.php
102+
sudo chmod +x ${{ github.workspace }}/cacti/poller.php
103+
104+
- name: Create MySQL Config
105+
run: |
106+
echo -e "[client]\nuser = root\npassword = cactiroot\nhost = 127.0.0.1\n" > ~/.my.cnf
107+
cat ~/.my.cnf
108+
109+
- name: Initialize Cacti Database
110+
env:
111+
MYSQL_AUTH_USR: '--defaults-file=~/.my.cnf'
112+
run: |
113+
mysql $MYSQL_AUTH_USR -e 'CREATE DATABASE IF NOT EXISTS cacti;'
114+
mysql $MYSQL_AUTH_USR -e "CREATE USER IF NOT EXISTS 'cactiuser'@'localhost' IDENTIFIED BY 'cactiuser';"
115+
mysql $MYSQL_AUTH_USR -e "GRANT ALL PRIVILEGES ON cacti.* TO 'cactiuser'@'localhost';"
116+
mysql $MYSQL_AUTH_USR -e "GRANT SELECT ON mysql.time_zone_name TO 'cactiuser'@'localhost';"
117+
mysql $MYSQL_AUTH_USR -e "FLUSH PRIVILEGES;"
118+
mysql $MYSQL_AUTH_USR cacti < ${{ github.workspace }}/cacti/cacti.sql
119+
mysql $MYSQL_AUTH_USR -e "INSERT INTO settings (name, value) VALUES ('path_php_binary', '/usr/bin/php')" cacti
120+
121+
- name: Validate composer files
122+
run: |
123+
cd ${{ github.workspace }}/cacti
124+
if [ -f composer.json ]; then
125+
composer validate --strict || true
126+
fi
127+
128+
- name: Install Composer Dependencies
129+
run: |
130+
cd ${{ github.workspace }}/cacti
131+
if [ -f composer.json ]; then
132+
sudo composer install --prefer-dist --no-progress
133+
fi
134+
135+
- name: Create Cacti config.php
136+
run: |
137+
cat ${{ github.workspace }}/cacti/include/config.php.dist | \
138+
sed -r "s/localhost/127.0.0.1/g" | \
139+
sed -r "s/'cacti'/'cacti'/g" | \
140+
sed -r "s/'cactiuser'/'cactiuser'/g" | \
141+
sed -r "s/'cactiuser'/'cactiuser'/g" > ${{ github.workspace }}/cacti/include/config.php
142+
sudo chmod 664 ${{ github.workspace }}/cacti/include/config.php
143+
144+
145+
146+
- name: Configure Apache
147+
run: |
148+
cat << 'EOF' | sed 's#GITHUB_WORKSPACE#${{ github.workspace }}#g' > /tmp/cacti.conf
149+
<VirtualHost *:80>
150+
ServerAdmin webmaster@localhost
151+
DocumentRoot GITHUB_WORKSPACE/cacti
152+
153+
<Directory GITHUB_WORKSPACE/cacti>
154+
Options Indexes FollowSymLinks
155+
AllowOverride All
156+
Require all granted
157+
</Directory>
158+
159+
ErrorLog ${APACHE_LOG_DIR}/error.log
160+
CustomLog ${APACHE_LOG_DIR}/access.log combined
161+
</VirtualHost>
162+
EOF
163+
sudo cp /tmp/cacti.conf /etc/apache2/sites-available/000-default.conf
164+
sudo systemctl restart apache2
165+
166+
- name: Install Cacti via CLI
167+
run: |
168+
cd ${{ github.workspace }}/cacti
169+
sudo php cli/install_cacti.php --accept-eula --install --force
170+
171+
- name: Install Audit Plugin
172+
run: |
173+
cd ${{ github.workspace }}/cacti
174+
sudo php cli/plugin_manage.php --plugin=audit --install --enable
175+
176+
- name: Check PHP Syntax for Plugin
177+
run: |
178+
cd ${{ github.workspace }}/cacti/plugins/audit
179+
if find . -name '*.php' -exec php -l {} 2>&1 \; | grep -iv 'no syntax errors detected'; then
180+
echo "Syntax errors found!"
181+
exit 1
182+
fi
183+
184+
185+
- name: Run Cacti Poller
186+
run: |
187+
cd ${{ github.workspace }}/cacti
188+
sudo php poller.php --poller=1 --force --debug
189+
if ! grep -q "SYSTEM STATS" log/cacti.log; then
190+
echo "Cacti poller did not finish successfully"
191+
cat log/cacti.log
192+
exit 1
193+
fi
194+
195+
196+
- name: View Cacti Logs
197+
if: always()
198+
run: |
199+
if [ -f ${{ github.workspace }}/cacti/log/cacti.log ]; then
200+
echo "=== Cacti Log ==="
201+
sudo cat ${{ github.workspace }}/cacti/log/cacti.log
202+
fi
203+
204+
- name: enable audit plugin logging
205+
run: |
206+
cd ${{ github.workspace }}
207+
ENABLE_AUDIT_LOGGING="update settings set value = 'on' where name = 'audit_enabled' or name = 'audit_log_external';"
208+
mysql -u cactiuser -p'cactiuser' -h 127.0.0.1 cacti -e "$ENABLE_AUDIT_LOGGING"
209+
210+
- name: Run cli script to trigger audit log entry
211+
run: |
212+
cd ${{ github.workspace }}/cacti
213+
sudo php cli/add_device.php --description=test --ip=1
214+
215+
- name: check audit log entries
216+
run: |
217+
cd ${{ github.workspace }}
218+
AUDIT_LOG_COUNT=$(mysql -u cactiuser -p'cactiuser' -h 127.0.0.1 cacti -se "select count(*) from audit_log;")
219+
echo "Audit log entry count: $AUDIT_LOG_COUNT"
220+
if [ "$AUDIT_LOG_COUNT" -lt 1 ]; then
221+
echo "No audit log entries found!"
222+
exit 1
223+
fi
224+
225+

0 commit comments

Comments
 (0)