django-log-formatter-asim 1.1.0a0__tar.gz → 1.1.0a2__tar.gz

{django_log_formatter_asim-1.1.0a0 → django_log_formatter_asim-1.1.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-log-formatter-asim
-Version: 1.1.0a0
+Version: 1.1.0a2
 Summary: Formats Django logs in ASIM format.
 License: MIT
 Author: Department for Business and Trade Platform Team
@@ -16,6 +16,7 @@ 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"
+Requires-Dist: django-ipware (>=7.0.1,<8.0.0)
 Description-Content-Type: text/markdown
 
 # Django ASIM log formatter

{django_log_formatter_asim-1.1.0a0 → django_log_formatter_asim-1.1.0a2}/django_log_formatter_asim/__init__.py

@@ -1,8 +1,9 @@
 import json
 import logging
+import os
 from datetime import datetime
+from datetime import timezone
 from importlib.metadata import distribution
-import os
 
 import ddtrace
 from ddtrace.trace import tracer
@@ -70,7 +71,7 @@ class ASIMRootFormatter:
 
     def get_log_dict(self):
         record = self.record
-        log_time = datetime.utcfromtimestamp(record.created).isoformat()
+        log_time = datetime.fromtimestamp(record.created, timezone.utc).isoformat()
         log_dict = {
             # Event fields...
             "EventMessage": record.getMessage(),
@@ -200,14 +201,6 @@ class ASIMRequestFormatter(ASIMRootFormatter):
             http_user_agent = request.META.get("HTTP_USER_AGENT", None)
         return http_user_agent
 
-    def _get_ip_address(self, request):
-        # Import here as ipware uses settings
-        from ipware import get_client_ip
-
-        client_ip, is_routable = get_client_ip(request)
-        return client_ip or "Unknown"
-
-
 ASIM_FORMATTERS = {
     "root": ASIMRootFormatter,
     "django.request": ASIMRequestFormatter,

django_log_formatter_asim-1.1.0a2/django_log_formatter_asim/events/__init__.py

@@ -0,0 +1,2 @@
+from .authentication import log_authentication
+from .file_activity import log_file_activity

django_log_formatter_asim-1.1.0a0/django_log_formatter_asim/events.py → django_log_formatter_asim-1.1.0a2/django_log_formatter_asim/events/authentication.py

@@ -1,22 +1,23 @@
 import datetime
 import json
-import sys
 from enum import Enum
 from typing import Literal
 from typing import Optional
 from typing import TypedDict
 
+from django.http import HttpRequest
 
-class AuthenticationType(str, Enum):
-    Logon = "Logon"
-    Logoff = "Logoff"
+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 AuthenticationResult(str, Enum):
-    Success = "Success"
-    Partial = "Partial"
-    Failure = "Failure"
-    NA = "NA"
+class AuthenticationEvent(str, Enum):
+    Logon = "Logon"
+    Logoff = "Logoff"
 
 
 class AuthenticationLoginMethod(str, Enum):
@@ -26,34 +27,6 @@ class AuthenticationLoginMethod(str, Enum):
     ExternalIDP = "External IdP"
 
 
-class Severity(str, Enum):
-    Informational = "Informational"
-    Low = "Low"
-    Medium = "Medium"
-    High = "High"
-
-
-class AuthenticationServer(TypedDict):
-    """Dictionary to represent properties of the HTTP Server."""
-
-    """
-    A unique identifier for the server which serviced the Authentication event.
-
-    Defaults to the WSGI SERVER_NAME field if not provided.
-    """
-    hostname: Optional[str]
-    """Internet Protocol Address of the server serving this request."""
-    ipAddr: Optional[str]
-
-
-class AuthenticationClient(TypedDict):
-    """Dictionary to represent properties of the HTTP Client."""
-
-    """Internet Protocol Address of the client making the Authentication
-    event."""
-    ipAddr: Optional[str]
-
-
 class AuthenticationUser(TypedDict):
     """Dictionary to represent properties of the users session."""
 
@@ -86,13 +59,13 @@ class AuthenticationUser(TypedDict):
 
 
 def log_authentication(
-    request,
-    type: AuthenticationType,
-    result: AuthenticationResult,
+    request: HttpRequest,
+    event: AuthenticationEvent,
+    result: Result,
     login_method: AuthenticationLoginMethod,
     user: Optional[AuthenticationUser] = None,
-    server: Optional[AuthenticationServer] = None,
-    client: Optional[AuthenticationClient] = None,
+    server: Optional[Server] = None,
+    client: Optional[Client] = None,
     severity: Optional[Severity] = None,
     time_generated: Optional[datetime.datetime] = None,
     result_details: Optional[str] = None,
@@ -106,8 +79,9 @@ def log_authentication(
                         - Django Authentication systems current username
                         - Django Session middlewares Session Key
                         - Client IP address
+                        - URL requested by the client
                         - Server hostname
-    :param type: What authentication action was attempted, either "Logon" or "Logoff"
+    :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"
@@ -117,9 +91,9 @@ def log_authentication(
     :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 AuthenticationServer class for more details.
+                   see Server class for more details.
     :param client: Dictionary containing information on the client performing this Authentication event
-                   see AuthenticationClient class for more details.
+                   see Client class for more details.
     :param severity: Optional severity of the event, defaults to "Informational", otherwise one of:
                         - "Informational"
                         - "Low"
@@ -141,64 +115,72 @@ def log_authentication(
 
     event_created = time_generated or datetime.datetime.now(tz=datetime.timezone.utc)
 
-    event = {
+    log = {
         "EventCreated": event_created.isoformat(),  # TODO: Should this really be EventCreated, or TimeGenerated
-        "DvcHostname": server.get("hostname", request.environ.get("SERVER_NAME")),
         "EventSeverity": severity or _default_severity(result),
-        "EventOriginalType": _event_code(type, result),
-        "SrcIpAddr": client.get("ipAddr", request.environ.get("REMOTE_ADDR")),
-        "EventType": type,
+        "EventOriginalType": _event_code(event, result),
+        "EventType": event,
         "EventResult": result,
         "LogonMethod": login_method,
         "EventSchema": "Authentication",
         "EventSchemaVersion": "0.1.4",
     }
 
+    if "hostname" in server:
+        log["DvcHostname"] = server["hostname"]
+    elif "SERVER_NAME" in request.META:
+        log["DvcHostname"] = request.META["SERVER_NAME"]
+
+    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 "SERVER_NAME" in request.META:
+        log["TargetUrl"] = request.scheme + "://" + request.get_host() + request.get_full_path()
+
     if "role" in user:
-        event["ActorUserType"] = user["role"]
+        log["ActorUserType"] = user["role"]
 
     if "sessionId" in user:
-        event["ActorSessionId"] = user["sessionId"]
+        log["ActorSessionId"] = user["sessionId"]
     elif request.session.session_key:
-        event["ActorSessionId"] = request.session.session_key
+        log["ActorSessionId"] = request.session.session_key
 
     if "username" in user:
-        event["ActorUserName"] = user["username"]
+        log["ActorUsername"] = user["username"]
     elif request.user.username:
-        event["ActorUserName"] = request.user.username
+        log["ActorUsername"] = request.user.username
 
     if result_details:
-        event["EventResultDetails"] = result_details
+        log["EventResultDetails"] = result_details
 
     if message:
-        event["EventMessage"] = message
+        log["EventMessage"] = message
 
-    if "ipAddr" in server:
-        event["DvcIpAddr"] = server["ipAddr"]
+    if "ip_address" in server:
+        log["DvcIpAddr"] = server["ip_address"]
 
-    sys.stdout.write(json.dumps(event) + "\n")
-    sys.stdout.flush()
+    print(json.dumps(log), flush=True)
 
 
-log_authentication.Type = AuthenticationType
-log_authentication.Result = AuthenticationResult
+log_authentication.Event = AuthenticationEvent
+log_authentication.Result = Result
 log_authentication.LoginMethod = AuthenticationLoginMethod
 log_authentication.Severity = Severity
 
 
-def _default_severity(result):
-    return Severity.Informational if result == AuthenticationResult.Success else Severity.Medium
-
-
-def _event_code(type, result):
-    if type == AuthenticationType.Logon:
-        if result == log_authentication.Result.Success:
+def _event_code(event: AuthenticationEvent, result: Result) -> str:
+    if event == AuthenticationEvent.Logon:
+        if result == Result.Success:
             return "001a"
-        elif result == AuthenticationResult.Failure:
+        elif result == Result.Failure:
             return "001b"
-    elif type == AuthenticationType.Logoff:
-        if result == AuthenticationResult.Success:
+    elif event == AuthenticationEvent.Logoff:
+        if result == Result.Success:
             return "001c"
-        elif result == AuthenticationResult.Failure:
+        elif result == Result.Failure:
             return "001d"
     return "001"

django_log_formatter_asim-1.1.0a2/django_log_formatter_asim/events/common.py

@@ -0,0 +1,54 @@
+from enum import Enum
+from typing import Optional
+from typing import TypedDict
+
+from django.http import HttpRequest
+
+
+class Result(str, Enum):
+    Success = "Success"
+    Partial = "Partial"
+    Failure = "Failure"
+    NA = "NA"
+
+
+class Severity(str, Enum):
+    Informational = "Informational"
+    Low = "Low"
+    Medium = "Medium"
+    High = "High"
+
+
+class Client(TypedDict):
+    """Dictionary to represent properties of the HTTP Client."""
+
+    """Internet Protocol Address of the client making the Authentication
+    event."""
+    ip_address: Optional[str]
+    """URL requested by the client."""
+    requested_url: Optional[str]
+
+
+class Server(TypedDict):
+    """Dictionary to represent properties of the HTTP Server."""
+
+    """
+    A unique identifier for the server which serviced the Authentication event.
+
+    Defaults to the WSGI SERVER_NAME field if not provided.
+    """
+    hostname: Optional[str]
+    """Internet Protocol Address of the server serving this request."""
+    ip_address: 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

django_log_formatter_asim-1.1.0a2/django_log_formatter_asim/events/file_activity.py

@@ -0,0 +1,204 @@
+import datetime
+import json
+import os
+from enum import Enum
+from typing import Optional
+from typing import TypedDict
+
+from django.http import HttpRequest
+
+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 FileActivityEvent(str, Enum):
+    FileAccessed = "FileAccessed"
+    FileCreated = "FileCreated"
+    FileModified = "FileModified"
+    FileDeleted = "FileDeleted"
+    FileRenamed = "FileRenamed"
+    FileCopied = "FileCopied"
+    FileMoved = "FileMoved"
+    FolderCreated = "FolderCreated"
+    FolderDeleted = "FolderDeleted"
+    FolderMoved = "FolderMoved"
+    FolderModified = "FolderModified"
+
+
+class FileActivityFile(TypedDict):
+    """Dictionary to represent properties of the target file."""
+
+    """
+    The full, normalized path of the target file, including the folder or location,
+    the file name, and the extension.
+    """
+    path: str
+    """
+    The name of the target file, without a path or a location, but with an
+    extension if available. This field should be similar to the final element in
+    the TargetFilePath field.
+
+    Defaults to extracting the name based off the path if not provided.
+    """
+    name: Optional[str]
+    """
+    The target file extension.
+
+    Defaults to extracting the extension based off the path if not provided.
+    """
+    extension: Optional[str]
+    """
+    The Mime, or Media, type of the target file.
+
+    Allowed values are listed in the IANA Media Types repository.
+    """
+    content_type: Optional[str]
+    """The SHA256 value of the target file."""
+    sha256: Optional[str]
+    """The size of the target file in bytes."""
+    size: Optional[int]
+
+
+class FileActivityUser(TypedDict):
+    """
+    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,
+    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 hostname
+    :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 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
+    """
+    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 = {
+        "EventSchema": "FileEvent",
+        "EventSchemaVersion": "0.2.1",
+        "EventType": event,
+        "EventResult": result,
+        "EventCreated": event_created.isoformat(),  # TODO: Should this really be EventCreated, or TimeGenerated
+        "EventSeverity": severity or _default_severity(result),
+        "TargetFilePath": file["path"],
+    }
+
+    if "name" in file:
+        log["TargetFileName"] = file["name"]
+    else:
+        log["TargetFileName"] = os.path.basename(file["path"])
+
+    if "extension" in file:
+        log["TargetFileExtension"] = file["extension"]
+    else:
+        file_name_parts = list(filter(None, log["TargetFileName"].split(".", 1)))
+        if len(file_name_parts) > 1:
+            log["TargetFileExtension"] = file_name_parts[1]
+
+    if "content_type" in file:
+        log["TargetFileMimeType"] = file["content_type"]
+
+    if "sha256" in file:
+        log["TargetFileSHA256"] = file["sha256"]
+
+    if "size" in file:
+        log["TargetFileSize"] = file["size"]
+
+    if "hostname" in server:
+        log["DvcHostname"] = server["hostname"]
+    elif "SERVER_NAME" in request.META:
+        log["DvcHostname"] = request.META["SERVER_NAME"]
+
+    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 "SERVER_NAME" in request.META:
+        log["TargetUrl"] = request.scheme + "://" + request.get_host() + request.get_full_path()
+
+    if "username" in user:
+        log["ActorUsername"] = user["username"]
+    elif request.user.username:
+        log["ActorUsername"] = 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_file_activity.Event = FileActivityEvent
+log_file_activity.Result = Result
+log_file_activity.Severity = Severity

{django_log_formatter_asim-1.1.0a0 → django_log_formatter_asim-1.1.0a2}/pyproject.toml

@@ -3,7 +3,7 @@ line-length = 100
 
 [tool.poetry]
 name = "django-log-formatter-asim"
-version = "1.1.0a0"
+version = "1.1.0a2"
 description = "Formats Django logs in ASIM format."
 authors = ["Department for Business and Trade Platform Team <sre-team@digital.trade.gov.uk>"]
 license = "MIT"
@@ -19,12 +19,13 @@ django = [
     { version = ">=3,<6", python = ">=3.10,<4" },
 ]
 ddtrace = "^3.2.1"
+django-ipware = "^7.0.1"
 
 [tool.poetry.group.dev.dependencies]
 pre-commit = "^3.5.0"
 pytest = "^7.4.3"
 tox = "^4.11.3"
-freezegun = "^1.2.2"
+freezegun = "^1.5.2"
 pytest-django = "^4.7.0"
 importlib-metadata = "^6.8.0"