django-log-formatter-asim 1.0.0__py3-none-any.whl → 1.1.0a1__py3-none-any.whl

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/events/authentication.py

@@ -0,0 +1,179 @@
+import datetime
+import json
+from enum import Enum
+from typing import Literal
+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
+
+
+class AuthenticationEvent(str, Enum):
+    Logon = "Logon"
+    Logoff = "Logoff"
+
+
+class AuthenticationLoginMethod(str, Enum):
+    UsernamePassword = "Username & Password"
+    StaffSSO = "Staff-SSO"
+    UKGOVSSO = "UK.GOV-SSO"
+    ExternalIDP = "External IdP"
+
+
+class AuthenticationUser(TypedDict):
+    """Dictionary to represent properties of the users session."""
+
+    """What type of role best describes this Authentication event."""
+    role: Optional[
+        Literal[
+            "Regular",
+            "Machine",
+            "Admin",
+            "System",
+            "Application",
+            "Service Principal",
+            "Service",
+            "Anonymous",
+            "Other",
+        ]
+    ]
+    """
+    A unique identifier for the user.
+
+    Defaults to the logged in Django User.username if not provided.
+    """
+    username: Optional[str]
+    """
+    A unique identifier for this authentication session if one exists.
+
+    Defaults to the Django Sessions session key if not provided.
+    """
+    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
+                        - Server hostname
+    :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 "hostname" in server:
+        log["DvcHostname"] = server["hostname"]
+    elif hasattr(request, "environ") and "SERVER_NAME" in request.environ:
+        log["DvcHostname"] = request.environ["SERVER_NAME"]
+
+    if "ip_address" in client:
+        log["SrcIpAddr"] = client["ip_address"]
+    elif hasattr(request, "environ") and "REMOTE_ADDR" in request.environ:
+        log["SrcIpAddr"] = request.environ.get("REMOTE_ADDR")
+
+    if "role" in user:
+        log["ActorUserType"] = user["role"]
+
+    if "sessionId" in user:
+        log["ActorSessionId"] = user["sessionId"]
+    elif request.session.session_key:
+        log["ActorSessionId"] = request.session.session_key
+
+    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_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"

django_log_formatter_asim/events/common.py

@@ -0,0 +1,42 @@
+from enum import Enum
+from typing import Optional
+from typing import TypedDict
+
+
+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]
+
+
+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

django_log_formatter_asim/events/file_activity.py

@@ -0,0 +1,197 @@
+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
+
+
+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
+                        - 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 hasattr(request, "environ") and "SERVER_NAME" in request.environ:
+        log["DvcHostname"] = request.environ["SERVER_NAME"]
+
+    if "ip_address" in client:
+        log["SrcIpAddr"] = client["ip_address"]
+    elif hasattr(request, "environ") and "REMOTE_ADDR" in request.environ:
+        log["SrcIpAddr"] = request.environ.get("REMOTE_ADDR")
+
+    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.0.0.dist-info → django_log_formatter_asim-1.1.0a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-log-formatter-asim
-Version: 1.0.0
+Version: 1.1.0a1
 Summary: Formats Django logs in ASIM format.
 License: MIT
 Author: Department for Business and Trade Platform Team
@@ -16,7 +16,6 @@ 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: pre-commit (>=3.5.0,<4.0.0)
 Description-Content-Type: text/markdown
 
 # Django ASIM log formatter

django_log_formatter_asim-1.1.0a1.dist-info/RECORD

@@ -0,0 +1,9 @@
+django_log_formatter_asim/__init__.py,sha256=i-7HqYE5s3hjmHLh4TTzLpEdgr5N22msFEQw16Pe_EI,7867
+django_log_formatter_asim/events/__init__.py,sha256=th8AEFNM-J5lNlO-d8Lk465jXqplE3IoTwj4DlscwYo,92
+django_log_formatter_asim/events/authentication.py,sha256=Nkgv-c_pNhwS8C1QYj0M3zH_cz2QJQqopzcMRhTv7Ls,6242
+django_log_formatter_asim/events/common.py,sha256=4P3lb-rfxv_4Vf2DfW-Mi3Sq7rIWqF_tGK8mPPCUMco,1039
+django_log_formatter_asim/events/file_activity.py,sha256=bKDpZcoBUePTeKCDPqLToGc8CA85_aXTw1c8KXoRLq0,6741
+django_log_formatter_asim-1.1.0a1.dist-info/LICENSE,sha256=dP79lN73--7LMApnankTGLqDbImXg8iYFqWgnExGkGk,1090
+django_log_formatter_asim-1.1.0a1.dist-info/METADATA,sha256=Fz6KC4Ai4jr3yq-Q1PDCtl0cp9mGlor0buzMCmh9J9s,5535
+django_log_formatter_asim-1.1.0a1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+django_log_formatter_asim-1.1.0a1.dist-info/RECORD,,

{django_log_formatter_asim-1.0.0.dist-info → django_log_formatter_asim-1.1.0a1.dist-info}/WHEEL

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

django_log_formatter_asim-1.0.0.dist-info/RECORD

@@ -1,5 +0,0 @@
-django_log_formatter_asim/__init__.py,sha256=i-7HqYE5s3hjmHLh4TTzLpEdgr5N22msFEQw16Pe_EI,7867
-django_log_formatter_asim-1.0.0.dist-info/LICENSE,sha256=dP79lN73--7LMApnankTGLqDbImXg8iYFqWgnExGkGk,1090
-django_log_formatter_asim-1.0.0.dist-info/METADATA,sha256=Gmn92QLejMsh63aivEaeqLfOKfnGl-9Hw5MPO-YC5KQ,5576
-django_log_formatter_asim-1.0.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-django_log_formatter_asim-1.0.0.dist-info/RECORD,,