backupchecks/TODO-audit-logging.md

TODO: Audit Logging Uitbreiding - Vervolg

Branch: v20260206-10-audit-logging-expansion Datum: 2026-02-07 Status: Deel 1 compleet, deel 2 nog te doen

---

✅ Wat is al gedaan (Deel 1)

Model & Database

• ✅ Model hernoemd: AdminLog → AuditLog
• ✅ Database migratie toegevoegd: migrate_rename_admin_logs_to_audit_logs()
  • Hernoemt tabel admin_logs → audit_logs
  • Idempotent en veilig
• ✅ Backwards compatibility: AdminLog = AuditLog alias

Code Updates

• ✅ admin_logging.py: log_admin_event() → log_audit_event() (met alias)
• ✅ routes_core.py: Updated naar AuditLog
• ✅ routes_shared.py: Updated naar AuditLog
• ✅ Gecommit en gepusht naar Gitea

---

🔄 Wat moet nog (Deel 2)

1. UI Updates

Bestand: containers/backupchecks/src/templates/main/logging.html

Te wijzigen:

• Page title: "Admin Activity" → "System Audit Log" of "Activity Log"
• Breadcrumb indien aanwezig

Huidige code zoeken naar:

<h1>Admin Activity</h1>
<!-- of -->
<title>Admin Activity</title>

---

2. Settings Logging Toevoegen

Locatie: containers/backupchecks/src/backend/app/main/routes_settings.py

Routes die logging nodig hebben:

A. General Settings (/settings/general POST)

# Na regel waar settings worden opgeslagen
# Voeg toe na db.session.commit()

from ..admin_logging import log_audit_event
import json

# Track wat er gewijzigd is
changes = {}
if old_value != new_value:
    changes['setting_name'] = {'old': old_value, 'new': new_value}

if changes:
    log_audit_event(
        event_type="settings_general",
        message=f"Updated {len(changes)} general setting(s)",
        details=json.dumps(changes, indent=2)
    )

Settings om te tracken:

• ui_timezone
• require_daily_dashboard_visit
• is_sandbox_environment
• Andere SystemSettings velden

B. Mail Settings (/settings/mail POST)

log_audit_event(
    event_type="settings_mail",
    message="Updated mail settings",
    details=json.dumps({
        'imap_server': settings.imap_server,
        'auto_import_enabled': settings.auto_import_enabled,
        # etc.
    }, indent=2)
)

C. Autotask Settings (/settings/autotask POST)

log_audit_event(
    event_type="settings_autotask",
    message="Updated Autotask integration settings",
    details=json.dumps({
        'url': settings.autotask_url,
        'username': settings.autotask_username,
        # NIET het wachtwoord loggen!
        'enabled': settings.autotask_enabled
    }, indent=2)
)

BELANGRIJK: Wachtwoorden NOOIT loggen in details!

---

3. Export Logging Toevoegen

A. Customers Export (/customers/export)

Huidige code: routes_customers.py regel ~421

Toevoegen:

# Voor return Response(...)
from ..admin_logging import log_audit_event

log_audit_event(
    event_type="export_customers",
    message=f"Exported {len(items)} customers to CSV",
    details=f"format=CSV, count={len(items)}"
)

B. Jobs Export (/settings/jobs/export)

Huidige code: routes_settings.py regel ~207

Toevoegen:

# Voor return send_file(...)
log_audit_event(
    event_type="export_jobs",
    message=f"Exported jobs configuration",
    details=json.dumps({
        'format': 'JSON',
        'schema': 'approved_jobs_export_v1',
        'customers_count': len(payload['customers']),
        'jobs_count': len(payload['jobs'])
    }, indent=2)
)

---

4. Import Logging Toevoegen

A. Customers Import (/customers/import)

Huidige code: routes_customers.py regel ~448

Toevoegen:

# Na db.session.commit()
log_audit_event(
    event_type="import_customers",
    message=f"Imported customers from CSV",
    details=json.dumps({
        'format': 'CSV',
        'created': created,
        'updated': updated,
        'skipped': skipped
    }, indent=2)
)

B. Jobs Import (/settings/jobs/import)

Huidige code: routes_settings.py regel ~263

Is al deels aanwezig, maar uitbreiden:

# Na db.session.commit()
log_audit_event(
    event_type="import_jobs",
    message="Imported jobs configuration",
    details=json.dumps({
        'format': 'JSON',
        'schema': payload.get('schema'),
        'customers_created': created_customers,
        'customers_updated': updated_customers,
        'jobs_created': created_jobs,
        'jobs_updated': updated_jobs
    }, indent=2)
)

---

5. Changelog Updaten

Bestand: docs/changelog-claude.md

BELANGRIJK: De datum is nu 2026-02-07, niet 2026-02-06!

Toevoegen aan de changelog:

## [2026-02-07]

### Changed
- Renamed AdminLog to AuditLog for better semantic clarity:
  - **Model**: AdminLog → AuditLog (backwards compatible alias maintained)
  - **Table**: admin_logs → audit_logs (automatic migration)
  - **Function**: log_admin_event() → log_audit_event() (alias provided)
  - Better reflects purpose as comprehensive audit trail for both user and system events

### Added
- Expanded audit logging for critical operations:
  - **Settings Changes**: Now logs all changes to General, Mail, Autotask, and Navigation settings
    - Tracks which settings changed (old value → new value)
    - Excludes sensitive data (passwords)
  - **Export Operations**: Logs when users export data
    - Customers export (CSV): count and format
    - Jobs export (JSON): schema version, customer/job counts
  - **Import Operations**: Logs when users import data
    - Customers import (CSV): created/updated/skipped counts
    - Jobs import (JSON): schema version, all operation counts
  - All logging uses event_type for filtering and includes detailed JSON in details field
  - Maintains 7-day retention policy
  - No performance impact (async logging)

---

📝 Implementatie Tips

Settings Changes Detecteren

Voor elke setting die je wilt tracken:

# Voor de save
old_value = settings.some_setting

# Na form processing
new_value = form.some_setting.data

# Track change
if old_value != new_value:
    changes['some_setting'] = {
        'old': str(old_value),
        'new': str(new_value)
    }

JSON Serialization

Gebruik json.dumps() voor details:

import json

details = json.dumps({
    'key': 'value',
    'count': 123
}, indent=2)

Event Types

Consistent naming:

• settings_general
• settings_mail
• settings_autotask
• export_customers
• export_jobs
• import_customers
• import_jobs

---

🎯 Volgende Stappen (Morgen)

1. UI updaten (logging.html page title)
2. Settings logging implementeren (General, Mail, Autotask)
3. Export logging implementeren (Customers, Jobs)
4. Import logging implementeren (Customers, Jobs)
5. Changelog updaten met correcte datum 2026-02-07
6. Testen of logging werkt
7. Committen en pushen

---

🔍 Test Checklist

Na implementatie testen:

• Wijzig general setting → check /logging
• Wijzig mail setting → check /logging
• Wijzig Autotask setting → check /logging
• Export customers → check /logging
• Export jobs → check /logging
• Import customers → check /logging
• Import jobs → check /logging
• Check of user naam correct is
• Check of details field JSON bevat
• Check of event_type correct is

---

📂 Belangrijke Bestanden

containers/backupchecks/src/backend/app/
├── admin_logging.py              # log_audit_event() functie
├── models.py                      # AuditLog model
├── migrations.py                  # migrate_rename_admin_logs_to_audit_logs()
└── main/
    ├── routes_settings.py         # Settings routes (toevoegen logging)
    ├── routes_customers.py        # Customer export/import (toevoegen logging)
    ├── routes_core.py             # Logging page
    └── routes_shared.py           # _log_admin_event() wrapper

containers/backupchecks/src/templates/main/
└── logging.html                   # UI update (page title)

docs/
└── changelog-claude.md            # Changelog (datum 2026-02-07!)

---

⚠️ Let Op!

1. Wachtwoorden NOOIT loggen in details veld
2. Datum in changelog: 2026-02-07 (niet 06!)
3. Event types consistent houden (lowercase, underscore)
4. JSON format voor details veld (makkelijk te parsen)
5. Backwards compatibility behouden (aliases)