Audit Logging
=============

The Vulnerability Scanner includes a comprehensive audit logging system to track critical actions performed by users and administrators, as well as significant system events.

Architecture
------------

Audit logging is implemented via the ``audit_logs`` database table and a set of helper functions in the backend.

- **Storage**: MariaDB table ``audit_logs``.
- **Mechanism**: Explicit calls to ``create_audit_log`` in route handlers.
- **Context**: Captures User ID, Email, IP Address, Event Type, Target (ID/Type), and a JSON payload of Details.

Event Types
-----------

The following event types are currently logged:

User Management
^^^^^^^^^^^^^^^
- ``USER_LOGIN``: Successful user login.
- ``USER_LOGIN_FAILED``: Failed login attempt.
- ``USER_CREDENTIAL_CHANGE``: User changed their password.
- ``ADMIN_UPDATE_USER_PROFILE``: Admin updated a user's details.

Contact & Network Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- ``CONTACT_PERSON_CREATE``: New contact person created.
- ``CONTACT_PERSON_UPDATE``: Contact person details updated.
- ``CONTACT_PERSON_DELETE``: Contact person deleted.
- ``CSV_IMPORT_CONTACTS``: Bulk import of contacts via CSV.
- ``IP_TRANSFER``: IP responsibility transferred between contacts.
- ``IP_REMOVE_SELF``: User removed their own IP assignment.
- ``CIDR_REMOVE_SELF``: User removed their own CIDR assignment.
- ``ADMIN_REMOVE_IP``: Admin removed an IP from a contact.
- ``ADMIN_REMOVE_CIDR``: Admin removed a CIDR from a contact.
- ``ADMIN_REMOVE_USER_IP``: Admin removed an IP from a user.
- ``ADMIN_TRANSFER_USER_IP``: Admin transferred an IP between users.

File & Scan Operations
^^^^^^^^^^^^^^^^^^^^^^
- ``REPORT_UPLOAD_QUEUED``: A report file was uploaded for processing.
- ``REPORT_DOWNLOAD``: Admin downloaded a report file.
- ``SCAN_DOWNLOAD``: XML scan file downloaded.
- ``SCAN_DELETE``: Scan record deleted.
- ``SCAN_TIMER_RESET``: Retention timer for a scan was reset.
- ``QUARANTINE_DOWNLOAD``: Quarantined file downloaded.
- ``QUARANTINE_RESTORE``: Quarantined file restored.
- ``QUARANTINE_DELETE``: Quarantined file deleted.
- ``MANUAL_PARSE``: Manual trigger of file parsing.

Configuration
^^^^^^^^^^^^^
- ``EMAIL_TEMPLATE_CREATE``: New email template created.
- ``EMAIL_TEMPLATE_UPDATE``: Email template updated.
- ``EMAIL_TEMPLATE_DELETE``: Email template deleted.

Notification
^^^^^^^^^^^^
- ``NOTIFICATION_SENT_MANUAL``: Admin manually triggered report notifications.

Database Schema
---------------

See :doc:`database_schema` for the full schema definition.

Logging Helper
--------------

.. code-block:: python

    from crud.audit_logs import create_audit_log
    from schemas.audit_log import AuditLogCreate

    create_audit_log(
        db,
        AuditLogCreate(
            user_id=user.id,
            user_email=user.email,
            event_type="EVENT_NAME",
            target_id="123",
            target_type="resource",
            details={"key": "value"},
            ip_address="1.2.3.4"
        )
    )