django-log-formatter-asim 1.1.0a4__py3-none-any.whl → 1.2.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,21 +1,18 @@
 import datetime
 import json
-import os
 from enum import Enum
+from hashlib import sha3_512
 from typing import Literal
 from typing import Optional
 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):
@@ -30,7 +27,7 @@ class AuthenticationLoginMethod(str, Enum):
     ExternalIDP = "External IdP"
 
 
-class AuthenticationUser(TypedDict):
+class AuthenticationUser(TypedDict, total=False):
     """Dictionary to represent properties of the users session."""
 
     """What type of role best describes this Authentication event."""
@@ -61,138 +58,133 @@ class AuthenticationUser(TypedDict):
     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
-    """
-    if user == None:
-        user = {}
-    if server == None:
-        server = {}
-    if client == None:
-        client = {}
-
-    event_created = time_generated or datetime.datetime.now(tz=datetime.timezone.utc)
-
-    log = {
-        "EventCreated": event_created.isoformat(),  # TODO: Should this really be EventCreated, or TimeGenerated
-        "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["ContainerId"] = 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"] = user["sessionId"]
-    elif request.session.session_key:
-        log["TargetSessionId"] = 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 _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"
@@ -19,7 +33,7 @@ class Severity(str, Enum):
     High = "High"
 
 
-class Client(TypedDict):
+class Client(TypedDict, total=False):
     """Dictionary to represent properties of the HTTP Client."""
 
     """Internet Protocol Address of the client making the Authentication
@@ -29,7 +43,7 @@ class Client(TypedDict):
     requested_url: Optional[str]
 
 
-class Server(TypedDict):
+class Server(TypedDict, total=False):
     """Dictionary to represent properties of the HTTP Server."""
 
     """
@@ -51,13 +65,67 @@ class Server(TypedDict):
     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