django-log-formatter-asim 1.2.0a0__py3-none-any.whl → 1.3.0__py3-none-any.whl

django_log_formatter_asim/events/__init__.py

@@ -1,2 +1,7 @@
-from .authentication import log_authentication
-from .file_activity import log_file_activity
+from .account_management import LogAccountManagement
+from .authentication import LogAuthentication
+from .file_activity import LogFileActivity
+
+log_account_management = LogAccountManagement()
+log_authentication = LogAuthentication()
+log_file_activity = LogFileActivity()

django_log_formatter_asim/events/account_management.py

@@ -0,0 +1,133 @@
+import datetime
+import json
+from enum import Enum
+from typing import Optional
+from typing import TypedDict
+
+from django.http import HttpRequest
+
+from .common import Activity
+from .common import Client
+from .common import LoggedInUser
+from .common import Result
+from .common import Server
+from .common import Severity
+
+
+class FileActivityEvent(str, Enum):
+    UserCreated = "UserCreated"
+    UserDeleted = "UserDeleted"
+    UserModified = "UserModified"
+    UserLocked = "UserLocked"
+    UserUnlocked = "UserUnlocked"
+    UserDisabled = "UserDisabled"
+    UserEnabled = "UserEnabled"
+    PasswordChanged = "PasswordChanged"
+    PasswordReset = "PasswordReset"
+    GroupCreated = "GroupCreated"
+    GroupDeleted = "GroupDeleted"
+    GroupModified = "GroupModified"
+    UserAddedToGroup = "UserAddedToGroup"
+    UserRemovedFromGroup = "UserRemovedFromGroup"
+    GroupEnumerated = "GroupEnumerated"
+    UserRead = "UserRead"
+    GroupRead = "GroupRead"
+
+
+class Account(TypedDict, total=False):
+    """Dictionary to represent details of the account management event."""
+
+    """
+    If a user was managed, the username of that user
+    """
+    username: Optional[str]
+    """If a group was managed, the name of the group."""
+    group: Optional[str]
+    """
+    If the Account Management event is one of the following.
+
+    - UserModified
+    - GroupModified
+
+    Details of the property which was changed, in the form:
+        ("propertyName", "oldValue", "newValue")
+    """
+    changed: tuple[str, str, str]
+
+
+class LogAccountManagement(Activity):
+    Event = FileActivityEvent
+    Result = Result
+    Severity = Severity
+
+    def __call__(
+        self,
+        request: HttpRequest,
+        event: Event,
+        account: Account,
+        result: Result,
+        user: Optional[LoggedInUser] = None,
+        server: Optional[Server] = None,
+        client: Optional[Client] = None,
+        severity: Optional[Severity] = None,
+        time_generated: Optional[datetime.datetime] = None,
+        result_details: Optional[str] = None,
+        message: Optional[str] = None,
+    ):
+        self._log_account_management(
+            request,
+            event,
+            account,
+            result,
+            {} if user == None else user,
+            {} if server == None else server,
+            {} if client == None else client,
+            time_generated or datetime.datetime.now(tz=datetime.timezone.utc),
+            severity,
+            result_details,
+            message,
+        )
+
+    def _log_account_management(
+        self,
+        request: HttpRequest,
+        event: Event,
+        account: Account,
+        result: Result,
+        user: LoggedInUser,
+        server: Server,
+        client: Client,
+        event_created: datetime.datetime,
+        severity: Optional[Severity] = None,
+        result_details: Optional[str] = None,
+        message: Optional[str] = None,
+    ):
+        log = {
+            "EventSchema": "UserManagement",
+            "EventSchemaVersion": "0.1.1",
+            "EventType": event,
+        }
+        log.update(
+            self._activity_fields(
+                request, event_created, result, server, client, severity, result_details, message
+            )
+        )
+
+        if "username" in user:
+            log["ActorUsername"] = user["username"]
+        elif hasattr(request, "user") and request.user.username:
+            log["ActorUsername"] = request.user.username
+
+        if "username" in account:
+            log["TargetUsername"] = account["username"]
+
+        if "group" in account:
+            log["GroupName"] = account["group"]
+
+        if "changed" in account:
+            (propertyName, previousPropertyValue, newPropertyName) = account["changed"]
+            log["UpdatedPropertyName"] = propertyName
+            log["PreviousPropertyValue"] = previousPropertyValue
+            log["NewPropertyValue"] = newPropertyName
+
+        print(json.dumps(log), flush=True)

django_log_formatter_asim/events/authentication.py

@@ -1,6 +1,5 @@
 import datetime
 import json
-import os
 from enum import Enum
 from hashlib import sha3_512
 from typing import Literal
@@ -9,14 +8,11 @@ from typing import TypedDict
 
 from django.http import HttpRequest
 
-from django_log_formatter_asim.ecs import _get_container_id
-
+from .common import Activity
 from .common import Client
 from .common import Result
 from .common import Server
 from .common import Severity
-from .common import _default_severity
-from .common import _get_client_ip_address
 
 
 class AuthenticationEvent(str, Enum):
@@ -62,164 +58,133 @@ class AuthenticationUser(TypedDict, total=False):
     sessionId: Optional[str]
 
 
-def log_authentication(
-    request: HttpRequest,
-    event: AuthenticationEvent,
-    result: Result,
-    login_method: AuthenticationLoginMethod,
-    user: Optional[AuthenticationUser] = None,
-    server: Optional[Server] = None,
-    client: Optional[Client] = None,
-    severity: Optional[Severity] = None,
-    time_generated: Optional[datetime.datetime] = None,
-    result_details: Optional[str] = None,
-    message: Optional[str] = None,
-):
-    """
-    Log an ASIM Authentication Event to standard output.
-
-    :param request: django.http.HttpRequest object which initiated this Authentication request
-                    from which the following data will be logged if available
-                        - Django Authentication systems current username
-                        - Django Session middlewares Session Key
-                        - Client IP address
-                        - URL requested by the client
-                        - Server domain name
-    :param event: What authentication action was attempted, either "Logon" or "Logoff"
-    :param result: What outcome did the action have, either "Success", "Failure", "Partial", "NA"
-    :param login_method: What authentication mechanism was being used, one of:
-                        - "Username & Password"
-                        - "Staff-SSO"
-                        - "UK.GOV-SSO"
-                        - "External IdP"
-    :param user: Dictionary containing information on the subject of this Authentication event
-                 see AuthenticationUser class for more details.
-    :param server: Dictionary containing information on the server servicing this Authentication event
-                   see Server class for more details.
-    :param client: Dictionary containing information on the client performing this Authentication event
-                   see Client class for more details.
-    :param severity: Optional severity of the event, defaults to "Informational", otherwise one of:
-                        - "Informational"
-                        - "Low"
-                        - "Medium"
-                        - "High"
-    :param time_generated: Optional datetime for when the event happened, otherwise datetime.now
-    :param result_details: Optional string describing any details associated with the events outcome.
-                           This field is typically populated when the result is a failure.
-    :param message: Optional string describing the reason why the log was generated.
-
-    See also: https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-authentication
-    """
-
-    _log_authentication(
-        request,
-        event,
-        result,
-        login_method,
-        user={} if user == None else user,
-        server={} if server == None else server,
-        client={} if client == None else client,
-        event_created=time_generated or datetime.datetime.now(tz=datetime.timezone.utc),
-        severity=severity,
-        result_details=result_details,
-        message=message,
-    )
-
-
-def _log_authentication(
-    request: HttpRequest,
-    event: AuthenticationEvent,
-    result: Result,
-    login_method: AuthenticationLoginMethod,
-    user: AuthenticationUser,
-    server: Server,
-    client: Client,
-    event_created: datetime.datetime,
-    severity: Optional[Severity] = None,
-    result_details: Optional[str] = None,
-    message: Optional[str] = None,
-):
-    log = {
-        "EventStartTime": event_created.isoformat(),
-        "EventSeverity": severity or _default_severity(result),
-        "EventOriginalType": _event_code(event, result),
-        "EventType": event,
-        "EventResult": result,
-        "LogonMethod": login_method,
-        "EventSchema": "Authentication",
-        "EventSchemaVersion": "0.1.4",
-    }
-
-    if "domain_name" in server:
-        log["HttpHost"] = server["domain_name"]
-    elif "HTTP_HOST" in request.META:
-        log["HttpHost"] = request.get_host()
-
-    if "service_name" in server:
-        log["TargetAppName"] = server["service_name"]
-    elif os.environ.get("COPILOT_APPLICATION_NAME") and os.environ.get("COPILOT_SERVICE_NAME"):
-        app_name = f"{os.environ['COPILOT_APPLICATION_NAME']}-{os.environ['COPILOT_SERVICE_NAME']}"
-        log["TargetAppName"] = app_name
-
-    if container_id := _get_container_id():
-        log["TargetContainerId"] = container_id
-
-    if "ip_address" in client:
-        log["SrcIpAddr"] = client["ip_address"]
-    elif client_ip := _get_client_ip_address(request):
-        log["SrcIpAddr"] = client_ip
-
-    if "requested_url" in client:
-        log["TargetUrl"] = client["requested_url"]
-    elif "HTTP_HOST" in request.META:
-        log["TargetUrl"] = request.scheme + "://" + request.get_host() + request.get_full_path()
-
-    if "role" in user:
-        log["TargetUserType"] = user["role"]
-
-    if "sessionId" in user:
-        log["TargetSessionId"] = _cryptographically_hash(user["sessionId"])
-    elif hasattr(request, "session") and request.session.session_key:
-        log["TargetSessionId"] = _cryptographically_hash(request.session.session_key)
-
-    if "username" in user:
-        log["TargetUsername"] = user["username"]
-    elif hasattr(request, "user") and request.user.username:
-        log["TargetUsername"] = request.user.username
-
-    if result_details:
-        log["EventResultDetails"] = result_details
-
-    if message:
-        log["EventMessage"] = message
-
-    if "ip_address" in server:
-        log["DvcIpAddr"] = server["ip_address"]
-
-    print(json.dumps(log), flush=True)
-
-
-log_authentication.Event = AuthenticationEvent
-log_authentication.Result = Result
-log_authentication.LoginMethod = AuthenticationLoginMethod
-log_authentication.Severity = Severity
-
-
-def _cryptographically_hash(data: Optional[str]) -> Optional[str]:
-    if data is None:
-        return None
-    return sha3_512(data.encode("UTF-8")).hexdigest()
-
-
-def _event_code(event: AuthenticationEvent, result: Result) -> str:
-    if event == AuthenticationEvent.Logon:
-        if result == Result.Success:
-            return "001a"
-        elif result == Result.Failure:
-            return "001b"
-    elif event == AuthenticationEvent.Logoff:
-        if result == Result.Success:
-            return "001c"
-        elif result == Result.Failure:
-            return "001d"
-    return "001"
+class LogAuthentication(Activity):
+    Event = AuthenticationEvent
+    Result = Result
+    LoginMethod = AuthenticationLoginMethod
+    Severity = Severity
+
+    def __call__(
+        self,
+        request: HttpRequest,
+        event: AuthenticationEvent,
+        result: Result,
+        login_method: AuthenticationLoginMethod,
+        user: Optional[AuthenticationUser] = None,
+        server: Optional[Server] = None,
+        client: Optional[Client] = None,
+        severity: Optional[Severity] = None,
+        time_generated: Optional[datetime.datetime] = None,
+        result_details: Optional[str] = None,
+        message: Optional[str] = None,
+    ):
+        """
+        Log an ASIM Authentication Event to standard output.
+
+        :param request: django.http.HttpRequest object which initiated this Authentication request
+                        from which the following data will be logged if available
+                            - Django Authentication systems current username
+                            - Django Session middlewares Session Key
+                            - Client IP address
+                            - URL requested by the client
+                            - Server domain name
+        :param event: What authentication action was attempted, either "Logon" or "Logoff"
+        :param result: What outcome did the action have, either "Success", "Failure", "Partial", "NA"
+        :param login_method: What authentication mechanism was being used, one of:
+                            - "Username & Password"
+                            - "Staff-SSO"
+                            - "UK.GOV-SSO"
+                            - "External IdP"
+        :param user: Dictionary containing information on the subject of this Authentication event
+                    see AuthenticationUser class for more details.
+        :param server: Dictionary containing information on the server servicing this Authentication event
+                    see Server class for more details.
+        :param client: Dictionary containing information on the client performing this Authentication event
+                    see Client class for more details.
+        :param severity: Optional severity of the event, defaults to "Informational", otherwise one of:
+                            - "Informational"
+                            - "Low"
+                            - "Medium"
+                            - "High"
+        :param time_generated: Optional datetime for when the event happened, otherwise datetime.now
+        :param result_details: Optional string describing any details associated with the events outcome.
+                            This field is typically populated when the result is a failure.
+        :param message: Optional string describing the reason why the log was generated.
+
+        See also: https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-authentication
+        """
+
+        self._log_authentication(
+            request,
+            event,
+            result,
+            login_method,
+            user={} if user == None else user,
+            server={} if server == None else server,
+            client={} if client == None else client,
+            event_created=time_generated or datetime.datetime.now(tz=datetime.timezone.utc),
+            severity=severity,
+            result_details=result_details,
+            message=message,
+        )
+
+    def _log_authentication(
+        self,
+        request: HttpRequest,
+        event: AuthenticationEvent,
+        result: Result,
+        login_method: AuthenticationLoginMethod,
+        user: AuthenticationUser,
+        server: Server,
+        client: Client,
+        event_created: datetime.datetime,
+        severity: Optional[Severity] = None,
+        result_details: Optional[str] = None,
+        message: Optional[str] = None,
+    ):
+        log = {
+            "EventOriginalType": self._event_code(event, result),
+            "EventType": event,
+            "LogonMethod": login_method,
+            "EventSchema": "Authentication",
+            "EventSchemaVersion": "0.1.4",
+        }
+
+        log.update(
+            self._activity_fields(
+                request, event_created, result, server, client, severity, result_details, message
+            )
+        )
+
+        if "role" in user:
+            log["TargetUserType"] = user["role"]
+
+        if "sessionId" in user:
+            log["TargetSessionId"] = self._cryptographically_hash(user["sessionId"])
+        elif hasattr(request, "session") and request.session.session_key:
+            log["TargetSessionId"] = self._cryptographically_hash(request.session.session_key)
+
+        if "username" in user:
+            log["TargetUsername"] = user["username"]
+        elif hasattr(request, "user") and request.user.username:
+            log["TargetUsername"] = request.user.username
+
+        print(json.dumps(log), flush=True)
+
+    def _cryptographically_hash(self, data: Optional[str]) -> Optional[str]:
+        if data is None:
+            return None
+        return sha3_512(data.encode("UTF-8")).hexdigest()
+
+    def _event_code(self, event: AuthenticationEvent, result: Result) -> str:
+        if event == AuthenticationEvent.Logon:
+            if result == Result.Success:
+                return "001a"
+            elif result == Result.Failure:
+                return "001b"
+        elif event == AuthenticationEvent.Logoff:
+            if result == Result.Success:
+                return "001c"
+            elif result == Result.Failure:
+                return "001d"
+        return "001"

django_log_formatter_asim/events/common.py

@@ -1,9 +1,23 @@
+import datetime
+import os
 from enum import Enum
 from typing import Optional
 from typing import TypedDict
 
 from django.http import HttpRequest
 
+from django_log_formatter_asim.ecs import _get_container_id
+
+
+class LoggedInUser(TypedDict, total=False):
+    """
+    A unique identifier for the user.
+
+    Defaults to the logged in Django User.username if not provided.
+    """
+
+    username: Optional[str]
+
 
 class Result(str, Enum):
     Success = "Success"
@@ -51,13 +65,67 @@ class Server(TypedDict, total=False):
     service_name: Optional[str]
 
 
-def _default_severity(result: Result) -> Severity:
-    return Severity.Informational if result == Result.Success else Severity.Medium
-
-
-def _get_client_ip_address(request: HttpRequest) -> Optional[str]:
-    # Import here as ipware uses settings
-    from ipware import get_client_ip
-
-    client_ip, _ = get_client_ip(request)
-    return client_ip
+class Activity:
+    def _activity_fields(
+        self,
+        request: HttpRequest,
+        event_created: datetime.datetime,
+        result: Result,
+        server: Server,
+        client: Client,
+        severity: Optional[Severity],
+        result_details: Optional[str],
+        message: Optional[str],
+    ):
+        log = {
+            "EventStartTime": event_created.isoformat(),
+            "EventSeverity": severity or self._default_severity(result),
+            "EventResult": result,
+        }
+
+        if "domain_name" in server:
+            log["HttpHost"] = server["domain_name"]
+        elif "HTTP_HOST" in request.META:
+            log["HttpHost"] = request.get_host()
+
+        if "service_name" in server:
+            log["TargetAppName"] = server["service_name"]
+        elif os.environ.get("COPILOT_APPLICATION_NAME") and os.environ.get("COPILOT_SERVICE_NAME"):
+            app_name = (
+                f"{os.environ['COPILOT_APPLICATION_NAME']}-{os.environ['COPILOT_SERVICE_NAME']}"
+            )
+            log["TargetAppName"] = app_name
+
+        if container_id := _get_container_id():
+            log["TargetContainerId"] = container_id
+
+        if "ip_address" in client:
+            log["SrcIpAddr"] = client["ip_address"]
+        elif client_ip := self._get_client_ip_address(request):
+            log["SrcIpAddr"] = client_ip
+
+        if "requested_url" in client:
+            log["TargetUrl"] = client["requested_url"]
+        elif "HTTP_HOST" in request.META:
+            log["TargetUrl"] = request.scheme + "://" + request.get_host() + request.get_full_path()
+
+        if result_details:
+            log["EventResultDetails"] = result_details
+
+        if message:
+            log["EventMessage"] = message
+
+        if "ip_address" in server:
+            log["DvcIpAddr"] = server["ip_address"]
+
+        return log
+
+    def _default_severity(sef, result: Result) -> Severity:
+        return Severity.Informational if result == Result.Success else Severity.Medium
+
+    def _get_client_ip_address(self, request: HttpRequest) -> Optional[str]:
+        # Import here as ipware uses settings
+        from ipware import get_client_ip
+
+        client_ip, _ = get_client_ip(request)
+        return client_ip

django_log_formatter_asim/events/file_activity.py

@@ -7,14 +7,12 @@ from typing import TypedDict
 
 from django.http import HttpRequest
 
-from django_log_formatter_asim.ecs import _get_container_id
-
+from .common import Activity
 from .common import Client
+from .common import LoggedInUser
 from .common import Result
 from .common import Server
 from .common import Severity
-from .common import _default_severity
-from .common import _get_client_ip_address
 
 
 class FileActivityEvent(str, Enum):
@@ -71,186 +69,146 @@ class FileActivityFile(FileActivityFileBase, total=False):
     size: Optional[int]
 
 
-class FileActivityUser(TypedDict, total=False):
-    """
-    A unique identifier for the user.
-
-    Defaults to the logged in Django User.username if not provided.
-    """
-
-    username: Optional[str]
-
-
-def log_file_activity(
-    request: HttpRequest,
-    event: FileActivityEvent,
-    result: Result,
-    file: FileActivityFile,
-    source_file: Optional[FileActivityFile] = None,
-    user: Optional[FileActivityUser] = None,
-    server: Optional[Server] = None,
-    client: Optional[Client] = None,
-    severity: Optional[Severity] = None,
-    time_generated: Optional[datetime.datetime] = None,
-    result_details: Optional[str] = None,
-    message: Optional[str] = None,
-):
-    """
-    Log an ASIM File Event to standard output.
-
-    :param request: django.http.HttpRequest object which initiated this Authentication request
-                    from which the following data will be logged if available
-                        - Django Authentication systems current username
-                        - Client IP address
-                        - URL requested by the client
-                        - Server domain name
-    :param event: What File Event action was attempted, one of:
-                        - FileAccessed
-                        - FileCreated
-                        - FileModified
-                        - FileDeleted
-                        - FileRenamed
-                        - FileCopied
-                        - FileMoved
-                        - FolderCreated
-                        - FolderDeleted
-                        - FolderMoved
-                        - FolderModified
-    :param result: What outcome did the action have, either "Success", "Failure", "Partial", "NA"
-    :param file: Dictionary containing information on the target of this File event see
-                 FileActivityFile for more details.
-    :param source_file: Dictionary containing information on the source of this File event,
-                        this MUST be used for a FileRenamed, FileMoved, FileCopied, FolderMoved
-                        operation. See FileActivityFile for more details.
-    :param user: Dictionary containing information on the logged in users username.
-    :param server: Dictionary containing information on the server servicing this File event
-                   see Server class for more details.
-    :param client: Dictionary containing information on the client performing this File event
-                   see Client class for more details.
-    :param severity: Optional severity of the event, defaults to "Informational", otherwise one of:
-                        - "Informational"
-                        - "Low"
-                        - "Medium"
-                        - "High"
-    :param time_generated: Optional datetime for when the event happened, otherwise datetime.now
-    :param result_details: Optional string describing any details associated with the events outcome.
-                           This field is typically populated when the result is a failure.
-    :param message: Optional string describing the reason why the log was generated.
-
-    See also: https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-file-event
-    """
-
-    _log_file_activity(
-        request,
-        event,
-        result,
-        file,
-        source_file,
-        user={} if user == None else user,
-        server={} if server == None else server,
-        client={} if client == None else client,
-        event_created=time_generated or datetime.datetime.now(tz=datetime.timezone.utc),
-        severity=severity,
-        result_details=result_details,
-        message=message,
-    )
-
-
-def _log_file_activity(
-    request: HttpRequest,
-    event: FileActivityEvent,
-    result: Result,
-    file: FileActivityFile,
-    source_file: Optional[FileActivityFile],
-    user: FileActivityUser,
-    server: Server,
-    client: Client,
-    event_created: datetime.datetime,
-    severity: Optional[Severity] = None,
-    result_details: Optional[str] = None,
-    message: Optional[str] = None,
-):
-    log = {
-        "EventSchema": "FileEvent",
-        "EventSchemaVersion": "0.2.1",
-        "EventType": event,
-        "EventResult": result,
-        "EventStartTime": event_created.isoformat(),
-        "EventSeverity": severity or _default_severity(result),
-    }
-
-    log.update(_generate_file_attributes(file, "Target"))
-    if source_file:
-        log.update(_generate_file_attributes(source_file, "Src"))
-
-    if "domain_name" in server:
-        log["HttpHost"] = server["domain_name"]
-    elif "HTTP_HOST" in request.META:
-        log["HttpHost"] = request.get_host()
-
-    if "service_name" in server:
-        log["TargetAppName"] = server["service_name"]
-    elif os.environ.get("COPILOT_APPLICATION_NAME") and os.environ.get("COPILOT_SERVICE_NAME"):
-        app_name = f"{os.environ['COPILOT_APPLICATION_NAME']}-{os.environ['COPILOT_SERVICE_NAME']}"
-        log["TargetAppName"] = app_name
-
-    if container_id := _get_container_id():
-        log["TargetContainerId"] = container_id
-
-    if "ip_address" in client:
-        log["SrcIpAddr"] = client["ip_address"]
-    elif client_ip := _get_client_ip_address(request):
-        log["SrcIpAddr"] = client_ip
-
-    if "requested_url" in client:
-        log["TargetUrl"] = client["requested_url"]
-    elif "HTTP_HOST" in request.META:
-        log["TargetUrl"] = request.scheme + "://" + request.get_host() + request.get_full_path()
-
-    if "username" in user:
-        log["TargetUsername"] = user["username"]
-    elif hasattr(request, "user") and request.user.username:
-        log["TargetUsername"] = request.user.username
-
-    if result_details:
-        log["EventResultDetails"] = result_details
-
-    if message:
-        log["EventMessage"] = message
-
-    if "ip_address" in server:
-        log["DvcIpAddr"] = server["ip_address"]
-
-    print(json.dumps(log), flush=True)
-
-
-def _generate_file_attributes(file: FileActivityFile, prefix: str) -> dict:
-    log = {prefix + "FilePath": file["path"]}
-
-    if "name" in file:
-        log[prefix + "FileName"] = file["name"]
-    else:
-        log[prefix + "FileName"] = os.path.basename(file["path"])
-
-    if "extension" in file:
-        log[prefix + "FileExtension"] = file["extension"]
-    else:
-        file_name_parts = list(filter(None, log[prefix + "FileName"].split(".", 1)))
-        if len(file_name_parts) > 1:
-            log[prefix + "FileExtension"] = file_name_parts[1]
-
-    if "content_type" in file:
-        log[prefix + "FileMimeType"] = file["content_type"]
-
-    if "sha256" in file:
-        log[prefix + "FileSHA256"] = file["sha256"]
-
-    if "size" in file:
-        log[prefix + "FileSize"] = file["size"]
-
-    return log
-
-
-log_file_activity.Event = FileActivityEvent
-log_file_activity.Result = Result
-log_file_activity.Severity = Severity
+class LogFileActivity(Activity):
+    Event = FileActivityEvent
+    Result = Result
+    Severity = Severity
+
+    def __call__(
+        self,
+        request: HttpRequest,
+        event: FileActivityEvent,
+        result: Result,
+        file: FileActivityFile,
+        source_file: Optional[FileActivityFile] = None,
+        user: Optional[LoggedInUser] = None,
+        server: Optional[Server] = None,
+        client: Optional[Client] = None,
+        severity: Optional[Severity] = None,
+        time_generated: Optional[datetime.datetime] = None,
+        result_details: Optional[str] = None,
+        message: Optional[str] = None,
+    ):
+        """
+        Log an ASIM File Event to standard output.
+
+        :param request: django.http.HttpRequest object which initiated this Authentication request
+                        from which the following data will be logged if available
+                            - Django Authentication systems current username
+                            - Client IP address
+                            - URL requested by the client
+                            - Server domain name
+        :param event: What File Event action was attempted, one of:
+                            - FileAccessed
+                            - FileCreated
+                            - FileModified
+                            - FileDeleted
+                            - FileRenamed
+                            - FileCopied
+                            - FileMoved
+                            - FolderCreated
+                            - FolderDeleted
+                            - FolderMoved
+                            - FolderModified
+        :param result: What outcome did the action have, either "Success", "Failure", "Partial", "NA"
+        :param file: Dictionary containing information on the target of this File event see
+                    FileActivityFile for more details.
+        :param source_file: Dictionary containing information on the source of this File event,
+                            this MUST be used for a FileRenamed, FileMoved, FileCopied, FolderMoved
+                            operation. See FileActivityFile for more details.
+        :param user: Dictionary containing information on the logged in users username.
+        :param server: Dictionary containing information on the server servicing this File event
+                    see Server class for more details.
+        :param client: Dictionary containing information on the client performing this File event
+                    see Client class for more details.
+        :param severity: Optional severity of the event, defaults to "Informational", otherwise one of:
+                            - "Informational"
+                            - "Low"
+                            - "Medium"
+                            - "High"
+        :param time_generated: Optional datetime for when the event happened, otherwise datetime.now
+        :param result_details: Optional string describing any details associated with the events outcome.
+                            This field is typically populated when the result is a failure.
+        :param message: Optional string describing the reason why the log was generated.
+
+        See also: https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-file-event
+        """
+
+        self._log_file_activity(
+            request,
+            event,
+            result,
+            file,
+            source_file,
+            user={} if user == None else user,
+            server={} if server == None else server,
+            client={} if client == None else client,
+            event_created=time_generated or datetime.datetime.now(tz=datetime.timezone.utc),
+            severity=severity,
+            result_details=result_details,
+            message=message,
+        )
+
+    def _log_file_activity(
+        self,
+        request: HttpRequest,
+        event: FileActivityEvent,
+        result: Result,
+        file: FileActivityFile,
+        source_file: Optional[FileActivityFile],
+        user: LoggedInUser,
+        server: Server,
+        client: Client,
+        event_created: datetime.datetime,
+        severity: Optional[Severity] = None,
+        result_details: Optional[str] = None,
+        message: Optional[str] = None,
+    ):
+        log = {
+            "EventSchema": "FileEvent",
+            "EventSchemaVersion": "0.2.1",
+            "EventType": event,
+        }
+
+        log.update(
+            self._activity_fields(
+                request, event_created, result, server, client, severity, result_details, message
+            )
+        )
+
+        log.update(self._generate_file_attributes(file, "Target"))
+        if source_file:
+            log.update(self._generate_file_attributes(source_file, "Src"))
+
+        if "username" in user:
+            log["TargetUsername"] = user["username"]
+        elif hasattr(request, "user") and request.user.username:
+            log["TargetUsername"] = request.user.username
+
+        print(json.dumps(log), flush=True)
+
+    def _generate_file_attributes(self, file: FileActivityFile, prefix: str) -> dict:
+        log = {prefix + "FilePath": file["path"]}
+
+        if "name" in file:
+            log[prefix + "FileName"] = file["name"]
+        else:
+            log[prefix + "FileName"] = os.path.basename(file["path"])
+
+        if "extension" in file:
+            log[prefix + "FileExtension"] = file["extension"]
+        else:
+            file_name_parts = list(filter(None, log[prefix + "FileName"].split(".", 1)))
+            if len(file_name_parts) > 1:
+                log[prefix + "FileExtension"] = file_name_parts[1]
+
+        if "content_type" in file:
+            log[prefix + "FileMimeType"] = file["content_type"]
+
+        if "sha256" in file:
+            log[prefix + "FileSHA256"] = file["sha256"]
+
+        if "size" in file:
+            log[prefix + "FileSize"] = file["size"]
+
+        return log

{django_log_formatter_asim-1.2.0a0.dist-info → django_log_formatter_asim-1.3.0.dist-info}/METADATA

@@ -1,21 +1,21 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: django-log-formatter-asim
-Version: 1.2.0a0
+Version: 1.3.0
 Summary: Formats Django logs in ASIM format.
 License: MIT
+License-File: LICENSE
 Author: Department for Business and Trade Platform Team
 Author-email: sre-team@digital.trade.gov.uk
-Requires-Python: >=3.9,<4
+Requires-Python: >=3.10,<4
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: ddtrace (>=3.2.1,<4.0.0)
-Requires-Dist: django (>=3,<5) ; python_version == "3.9"
-Requires-Dist: django (>=3,<6) ; python_version >= "3.10" and python_version < "4"
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: ddtrace (>=3.2.1,<5)
+Requires-Dist: django (>=4.2,<7)
 Requires-Dist: django-ipware (>=7.0.1,<8.0.0)
 Description-Content-Type: text/markdown
 
@@ -77,6 +77,101 @@ LOGGING = {
 In this example we assign the ASIM formatter to a `handler` and ensure both `root` and `django` loggers use this `handler`.
 We then set `propagate` to `False` on the `django` logger, to avoid duplicating logs at the root level.
 
+### Settings
+
+`DLFA_LOG_PERSONALLY_IDENTIFIABLE_INFORMATION` - the formatter checks this setting to see if personally identifiable information should be logged. If this is not set to true, only the user's id is logged.
+
+`DLFA_TRACE_HEADERS` - used for defining custom zipkin headers, the defaults is `("X-Amzn-Trace-Id")`, but for applications hosted in GOV.UK PaaS you should use `("X-B3-TraceId", "X-B3-SpanId")`. If you are running your application in both places side by side during migration, the following should work in your Django settings:
+
+```python
+from dbt_copilot_python.utility import is_copilot
+
+if is_copilot():
+   DLFA_TRACE_HEADERS = ("X-B3-TraceId", "X-B3-SpanId")
+```
+
+`DLFA_INCLUDE_RAW_LOG` - By default the original unformatted log is not included in the ASIM formatted log. You can enable that by setting this to `True` and it will be included in `AddidtionalFields.RawLog`.
+
+> [!WARNING]
+> Setting `DLFA_INCLUDE_RAW_LOG` to `True` will cause additional private fields to be output to your logs.
+> This could include secrets, such as AWS Access Keys, private HTTP Request data, or personally identifiable information.
+> This setting is not recommended for a production environment.
+
+### Serialisation behaviour
+
+The package provides one `logging.Formatter` class, `ASIMFormatter` which routes log messages to a serialiser
+which generates a python dict which the formatter converts to a JSON string and prints to standard output.
+
+It has a generic serialiser called `ASIMRootFormatter` and a custom serlializer for log messages where the
+logger is `django.request`.
+
+``` python
+    ASIM_FORMATTERS = {
+        "root": ASIMRootFormatter,
+        "django.request": ASIMRequestFormatter,
+    }
+```
+
+#### ASIMRootFormatter
+
+This serialiser outputs the following ASIM fields.
+
+- `EventSchema` = `ProcessEvent`
+- `ActingAppType` = `Django`
+- `AdditionalFields[DjangoLogFormatterAsimVersion]`
+- `EventSchemaVersion`
+- `EventMessage`
+- `EventCount`
+- `EventStartTime`
+- `EventEndTime`
+- `EventType`
+- `EventResult`
+- `EventSeverity`
+- `EventOriginalSeverity`
+
+Additionally, the following DataDog fields where available:
+
+- `dd.trace_id`
+- `dd.span_id`
+- `env`
+- `service`
+- `version`
+
+
+#### ASIMRequestFormatter
+
+This serialiser outputs the following ASIM fields in addition to the ones from ASIMRootFormatter.
+It is coupled to the datastructure provided by the `django.request` logger.
+The `django.request` logger only outputs requests where the response code is 4xx/5xx.
+
+- `SrcIpAddr` and `IpAddr`
+- `SrcPortNumber`
+- `SrcUserId` and `SrcUsername`
+- `HttpUserAgent`
+- `AdditionalFields["TraceHeaders"][trace_header_name]` - See `DLFA_TRACE_HEADERS` setting for more information.
+
+#### Creating a custom serialiser
+
+If you wish to create your own ASIM serialiser, you can inherit from `ASIMRootFormatter` and call
+`super().get_log_dict()` to get the base level logging data for augmentation:
+
+``` python
+    class MyASIMFormatter(ASIMRootFormatter):
+        def get_log_dict(self):
+            log_dict = super().get_log_dict()
+
+            # Customise logger event
+
+            return log_dict
+```
+
+This serialiser can then be added to `ASIM_FORMATTERS`...
+
+```python
+ASIM_FORMATTERS["my_logger"] = MyASIMFormatter
+```
+
+
 ### ASIM Events
 
 The events mostly follow the Microsoft schema but have been tailored to Department of Business and Trade needs.
@@ -127,48 +222,114 @@ log_authentication(
 }
 ```
 
-### Settings
+#### File Activity event
 
-`DLFA_LOG_PERSONALLY_IDENTIFIABLE_INFORMATION` - the formatter checks this setting to see if personally identifiable information should be logged. If this is not set to true, only the user's id is logged.
+Following the [ASIM File Event Schema](https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-file-event).
 
-`DLFA_TRACE_HEADERS` - used for defining custom zipkin headers, the defaults is `("X-Amzn-Trace-Id")`, but for applications hosted in GOV.UK PaaS you should use `("X-B3-TraceId", "X-B3-SpanId")`. If you are running your application in both places side by side during migration, the following should work in your Django settings:
+```python
+# Example usage
+from django_log_formatter_asim.events import log_file_activity
 
-`DLFA_INCLUDE_RAW_LOG` - By default the original unformatted log is not included in the ASIM formatted log. You can enable that by setting this to `True` and it will be included in `AddidtionalFields.RawLog`.
+log_file_activity(
+    request,
+    event=log_file_activity.Event.FileCopied,
+    result=log_file_activity.Result.Success,
+    file={
+        "path": "/tmp/copied.txt",
+        "content_type": "text/plain",
+        "extension": "txt",
+        "name": "copied.txt",
+        "sha256": "6798b7a132f37a0474002dec538ec52bdcd5f7b76e49e52c8a3d2016ca8d1d18",
+        "size": 14,
+    },
+    # source_file is only necessary if the event is one of FileRenamed, FileMoved, FileCopied, FolderMoved
+    source_file={
+        "path": "/tmp/original.txt",
+        "content_type": "text/plain",
+        "extension": "txt",
+        "name": "original.txt",
+        "sha256": "6798b7a132f37a0474002dec538ec52bdcd5f7b76e49e52c8a3d2016ca8d1d18",
+        "size": 14,
+    },
+)
 
-```python
-from dbt_copilot_python.utility import is_copilot
+# Example JSON printed to standard output
+{
+    # Values provided as arguments
+    "EventType": "FileCopied",
+    "EventResult": "Success",
 
-if is_copilot():
-   DLFA_TRACE_HEADERS = ("X-B3-TraceId", "X-B3-SpanId")
-```
+    "TargetFilePath": "/tmp/copied.txt",
+    "TargetFileName": "copied.txt",
+    "TargetFileExtension": "txt",
+    "TargetFileMimeType": "text/plain",
+    "TargetFileSHA256": "6798b7a132f37a0474002dec538ec52bdcd5f7b76e49e52c8a3d2016ca8d1d18",
+    "TargetFileSize": 14,
 
-### Formatter classes
+    "SrcFilePath": "/tmp/original.txt",
+    "SrcFileName": "original.txt",
+    "SrcFileExtension": "txt",
+    "SrcFileMimeType": "text/plain",
+    "SrcFileSHA256": "6798b7a132f37a0474002dec538ec52bdcd5f7b76e49e52c8a3d2016ca8d1d18",
+    "SrcFileSize": 14,
 
-``` python
-    ASIM_FORMATTERS = {
-        "root": ASIMSystemFormatter,
-        "django.request": ASIMRequestFormatter,
-    }
-```
+    # Calculated / Hard coded fields
+    "EventStartTime": "2025-07-30T11:05:09.406460+00:00",
+    "EventSchema": "FileEvent",
+    "EventSchemaVersion": "0.2.1",
+    "EventSeverity": "Informational",
 
-The default class for other loggers is:
+    # Taken from Django HttpRequest object
+    "HttpHost": "WebServer.local",
+    "SrcIpAddr": "192.168.1.101",
+    "TargetUrl": "https://WebServer.local/steel",
+    "TargetUsername": "Adrian"
 
-``` python
-    ASIMSystemFormatter
+    # Taken from DBT Platform environment variables
+    "TargetAppName": "export-analytics-frontend",
+}
 ```
 
-### Creating a custom `logging.Formatter`
+#### Account Management event
 
-If you wish to create your own ASIM formatter, you can inherit from ASIMSystemFormatter and call _get_event_base to get the base level logging data for use in augmentation:
+Following the [ASIM User Management Schema](https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-user-management).
 
-``` python
-    class ASIMSystemFormatter(ASIMFormatterBase):
-        def get_event(self):
-            logger_event = self._get_event_base()
 
-            # Customise logger event
+```python
+# Example usage
+from django_log_formatter_asim.events import log_account_management
+
+log_account_management(
+    request,
+    event=log_account_management.Event.UserCreated,
+    result=log_account_management.Result.Success,
+    account={
+        "username": "Roger",
+    },
+)
+
+# Example JSON printed to standard output
+{
+    # Values provided as arguments
+    "EventType": "UserCreated",
+    "EventResult": "Success",
+    "TargetUsername": "Roger",
 
-            return logger_event
+    # Calculated / Hard coded fields
+    "EventStartTime": "2025-07-30T11:05:09.406460+00:00",
+    "EventSchema": "UserManagement",
+    "EventSchemaVersion": "0.1.1",
+    "EventSeverity": "Informational",
+
+    # Taken from Django HttpRequest object
+    "HttpHost": "WebServer.local",
+    "SrcIpAddr": "192.168.1.101",
+    "TargetUrl": "https://WebServer.local/admin/create-user",
+    "ActorUsername": "Adrian"
+
+    # Taken from DBT Platform environment variables
+    "TargetAppName": "export-analytics-frontend",
+}
 ```
 
 ## Dependencies
@@ -203,6 +364,8 @@ Or, run `poetry run tox` in the root directory to run all tests for multiple Pyt
 
 ### Publishing
 
+Create a pull request to update the [CHANGELOG.md](./CHANGELOG.md) and also create a [create a release in GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) for your new version.
+
 1. Acquire API token from [Passman](https://passman.ci.uktrade.digital/secret/cc82a3f7-ddfa-4312-ab56-1ff8528dadc8/).
    - Request access from the SRE team.
    - _Note: You will need access to the `platform` group in Passman._

django_log_formatter_asim-1.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+django_log_formatter_asim/__init__.py,sha256=ftbSWdejSnWK_MpT3RSfTgcs3E-661FM-e3ugnoiBqA,7133
+django_log_formatter_asim/ecs.py,sha256=SSg3A5pfS5E-Hm7AXQnN1RrtXclgq07oSBxPCRn5gDg,536
+django_log_formatter_asim/events/__init__.py,sha256=K78BzhkNJpI2AdpaiMmf9FrBQTurEdBFX1Xx2hy-TGg,270
+django_log_formatter_asim/events/account_management.py,sha256=k6uPs9XcchCW2G3lcbdeXviSVWjJ4pK52mrYekwSLVQ,3936
+django_log_formatter_asim/events/authentication.py,sha256=8Kn5_8WF-DunmgpqWPVhaNh3k1qYVCwLbQ2I7WPmHj8,6966
+django_log_formatter_asim/events/common.py,sha256=CWC6Bo3R7yOY7NElJb1jxcD1el72Hl4CBZhFYgT0tIs,3874
+django_log_formatter_asim/events/file_activity.py,sha256=hTscMhGyaYVsLzqMcw-aQB5ks4G2VpB9Pkw63LwxqaI,7793
+django_log_formatter_asim-1.3.0.dist-info/METADATA,sha256=vfA4S1Y9OBBoXh-ZL0hf1Ui__MzWhg-rrjPofEyzZZE,12579
+django_log_formatter_asim-1.3.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+django_log_formatter_asim-1.3.0.dist-info/licenses/LICENSE,sha256=dP79lN73--7LMApnankTGLqDbImXg8iYFqWgnExGkGk,1090
+django_log_formatter_asim-1.3.0.dist-info/RECORD,,

{django_log_formatter_asim-1.2.0a0.dist-info → django_log_formatter_asim-1.3.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.3
+Generator: poetry-core 2.2.1
 Root-Is-Purelib: true
 Tag: py3-none-any

django_log_formatter_asim-1.2.0a0.dist-info/RECORD

@@ -1,10 +0,0 @@
-django_log_formatter_asim/__init__.py,sha256=ftbSWdejSnWK_MpT3RSfTgcs3E-661FM-e3ugnoiBqA,7133
-django_log_formatter_asim/ecs.py,sha256=SSg3A5pfS5E-Hm7AXQnN1RrtXclgq07oSBxPCRn5gDg,536
-django_log_formatter_asim/events/__init__.py,sha256=th8AEFNM-J5lNlO-d8Lk465jXqplE3IoTwj4DlscwYo,92
-django_log_formatter_asim/events/authentication.py,sha256=WUHSllqTKTLnEdRlLn2SqCn3YR1_AKPA3y8Gm22CyIY,7808
-django_log_formatter_asim/events/common.py,sha256=-QjR9QPkMDqD3nXPiukAJvm8qjUt2LwzhL_zN5ae_t0,1702
-django_log_formatter_asim/events/file_activity.py,sha256=h8xlY0ABDCejAVnRMJ0aeWdNJZpu_54et1squMEfSM8,8755
-django_log_formatter_asim-1.2.0a0.dist-info/LICENSE,sha256=dP79lN73--7LMApnankTGLqDbImXg8iYFqWgnExGkGk,1090
-django_log_formatter_asim-1.2.0a0.dist-info/METADATA,sha256=ofAaVdlWggllH93apSQg16S0ZHaPmF1xd27APovOirc,7428
-django_log_formatter_asim-1.2.0a0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-django_log_formatter_asim-1.2.0a0.dist-info/RECORD,,