django-log-formatter-asim 0.0.6__tar.gz → 1.1.0__tar.gz

{django_log_formatter_asim-0.0.6 → django_log_formatter_asim-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: django-log-formatter-asim
-Version: 0.0.6
+Version: 1.1.0
 Summary: Formats Django logs in ASIM format.
 License: MIT
 Author: Department for Business and Trade Platform Team
@@ -12,9 +12,11 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: django (>=3,<5) ; python_version >= "3.9" and python_version < "3.10"
+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)
+Requires-Dist: django-ipware (>=7.0.1,<8.0.0)
 Description-Content-Type: text/markdown
 
 # Django ASIM log formatter
@@ -23,8 +25,6 @@ The library formats Django logs in [ASIM format](https://learn.microsoft.com/en-
 
 Mapping to the format may not be complete, but best effort has been made to create logical field mappings.
 
-If you need to amend the mapping, you can implement a custom formatter.
-
 ## Installation
 
 ``` shell
@@ -33,7 +33,16 @@ pip install django-log-formatter-asim
 
 ## Usage
 
-Using in a Django logging configuration:
+This package provides the following ASIM functionality:
+
+- A Python [logging.Formatter] implementation.
+- A module of functions `django_log_formatter_asim.events` which generate ASIM event log entries.
+
+[logging.Formatter]: https://docs.python.org/3/library/logging.html#formatter-objects
+
+### `logging.Formatter` setup
+
+Using the formatter in a Django logging configuration:
 
 ``` python
 from django_log_formatter_asim import ASIMFormatter
@@ -64,15 +73,61 @@ 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. 
 
-## Dependencies
+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.
 
-This package uses [Django IPware](https://github.com/un33k/django-ipware) for IP address capture.
+### ASIM Events
 
-This package is compatible with [Django User Agents](https://pypi.org/project/django-user-agents) which, when used, will enhance logged user agent information.
+The events mostly follow the Microsoft schema but have been tailored to Department of Business and Trade needs.
+
+Events are designed for simple integrate into your Django app.
+Each will take additional information from the [Django HttpRequest object][django-request].
+
+[django-request]: https://docs.djangoproject.com/en/5.2/ref/request-response/#httprequest-objects
+
+#### Authentication event
 
-## Settings
+Following the [ASIM Authentication Schema](https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-authentication).
+
+```python
+# Example usage
+from django_log_formatter_asim.events import log_authentication
+
+log_authentication(
+    request,
+    event=log_authentication.Event.Logoff,
+    result=log_authentication.Result.Success,
+    login_method=log_authentication.LoginMethod.UsernamePassword,
+)
+
+# Example JSON printed to standard output
+{
+    # Values provided as arguments
+    "EventType": "Logoff",
+    "EventResult": "Success",
+    "LogonMethod": "Username & Password",
+
+    # Calculated / Hard coded fields
+    "EventStartTime": "2025-07-02T08:15:20+00:00",
+    "EventSeverity": "Informational",
+    "EventOriginalType": "001c",
+    "EventSchema": "Authentication",
+    "EventSchemaVersion": "0.1.4",
+
+    # Taken from Django HttpRequest object
+    "HttpHost": "WebServer.local",
+    "SrcIpAddr": "192.168.1.101",
+    "TargetUrl": "https://WebServer.local/steel",
+    "TargetSessionId": "def456",
+    "TargetUsername": "Adrian"
+
+    # Taken from DBT Platform environment variables
+    "TargetAppName": "export-analytics-frontend",
+}
+```
+
+### 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.
 
@@ -87,7 +142,7 @@ if is_copilot():
    DLFA_TRACE_HEADERS = ("X-B3-TraceId", "X-B3-SpanId")
 ```
 
-## Formatter classes
+### Formatter classes
 
 ``` python
     ASIM_FORMATTERS = {
@@ -102,7 +157,7 @@ The default class for other loggers is:
     ASIMSystemFormatter
 ```
 
-## Creating a custom formatter
+### Creating a custom `logging.Formatter`
 
 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:
 
@@ -116,6 +171,12 @@ If you wish to create your own ASIM formatter, you can inherit from ASIMSystemFo
             return logger_event
 ```
 
+## Dependencies
+
+This package uses [Django IPware](https://github.com/un33k/django-ipware) for IP address capture.
+
+This package is compatible with [Django User Agents](https://pypi.org/project/django-user-agents) which, when used, will enhance logged user agent information.
+
 ## Contributing to the `django-log-formatter-asim` package
 
 ### Getting started

{django_log_formatter_asim-0.0.6 → django_log_formatter_asim-1.1.0}/README.md

@@ -4,8 +4,6 @@ The library formats Django logs in [ASIM format](https://learn.microsoft.com/en-
 
 Mapping to the format may not be complete, but best effort has been made to create logical field mappings.
 
-If you need to amend the mapping, you can implement a custom formatter.
-
 ## Installation
 
 ``` shell
@@ -14,7 +12,16 @@ pip install django-log-formatter-asim
 
 ## Usage
 
-Using in a Django logging configuration:
+This package provides the following ASIM functionality:
+
+- A Python [logging.Formatter] implementation.
+- A module of functions `django_log_formatter_asim.events` which generate ASIM event log entries.
+
+[logging.Formatter]: https://docs.python.org/3/library/logging.html#formatter-objects
+
+### `logging.Formatter` setup
+
+Using the formatter in a Django logging configuration:
 
 ``` python
 from django_log_formatter_asim import ASIMFormatter
@@ -45,15 +52,61 @@ 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. 
 
-## Dependencies
+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.
 
-This package uses [Django IPware](https://github.com/un33k/django-ipware) for IP address capture.
+### ASIM Events
 
-This package is compatible with [Django User Agents](https://pypi.org/project/django-user-agents) which, when used, will enhance logged user agent information.
+The events mostly follow the Microsoft schema but have been tailored to Department of Business and Trade needs.
+
+Events are designed for simple integrate into your Django app.
+Each will take additional information from the [Django HttpRequest object][django-request].
+
+[django-request]: https://docs.djangoproject.com/en/5.2/ref/request-response/#httprequest-objects
+
+#### Authentication event
 
-## Settings
+Following the [ASIM Authentication Schema](https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-authentication).
+
+```python
+# Example usage
+from django_log_formatter_asim.events import log_authentication
+
+log_authentication(
+    request,
+    event=log_authentication.Event.Logoff,
+    result=log_authentication.Result.Success,
+    login_method=log_authentication.LoginMethod.UsernamePassword,
+)
+
+# Example JSON printed to standard output
+{
+    # Values provided as arguments
+    "EventType": "Logoff",
+    "EventResult": "Success",
+    "LogonMethod": "Username & Password",
+
+    # Calculated / Hard coded fields
+    "EventStartTime": "2025-07-02T08:15:20+00:00",
+    "EventSeverity": "Informational",
+    "EventOriginalType": "001c",
+    "EventSchema": "Authentication",
+    "EventSchemaVersion": "0.1.4",
+
+    # Taken from Django HttpRequest object
+    "HttpHost": "WebServer.local",
+    "SrcIpAddr": "192.168.1.101",
+    "TargetUrl": "https://WebServer.local/steel",
+    "TargetSessionId": "def456",
+    "TargetUsername": "Adrian"
+
+    # Taken from DBT Platform environment variables
+    "TargetAppName": "export-analytics-frontend",
+}
+```
+
+### 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.
 
@@ -68,7 +121,7 @@ if is_copilot():
    DLFA_TRACE_HEADERS = ("X-B3-TraceId", "X-B3-SpanId")
 ```
 
-## Formatter classes
+### Formatter classes
 
 ``` python
     ASIM_FORMATTERS = {
@@ -83,7 +136,7 @@ The default class for other loggers is:
     ASIMSystemFormatter
 ```
 
-## Creating a custom formatter
+### Creating a custom `logging.Formatter`
 
 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:
 
@@ -97,6 +150,12 @@ If you wish to create your own ASIM formatter, you can inherit from ASIMSystemFo
             return logger_event
 ```
 
+## Dependencies
+
+This package uses [Django IPware](https://github.com/un33k/django-ipware) for IP address capture.
+
+This package is compatible with [Django User Agents](https://pypi.org/project/django-user-agents) which, when used, will enhance logged user agent information.
+
 ## Contributing to the `django-log-formatter-asim` package
 
 ### Getting started

{django_log_formatter_asim-0.0.6 → django_log_formatter_asim-1.1.0}/django_log_formatter_asim/__init__.py

@@ -1,10 +1,15 @@
 import json
 import logging
 from datetime import datetime
+from datetime import timezone
 from importlib.metadata import distribution
 
+import ddtrace
+from ddtrace.trace import tracer
 from django.conf import settings
 
+from .ecs import _get_container_id
+
 
 class ASIMRootFormatter:
     def __init__(self, record):
@@ -25,9 +30,36 @@ class ASIMRootFormatter:
 
         return copied_dict
 
+    def _get_first_64_bits_of(self, trace_id):
+        # See https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces/python/#no-standard-library-logging
+        return str((1 << 64) - 1 & trace_id)
+
+    def _datadog_trace_dict(self):
+        event_dict = {}
+
+        span = tracer.current_span()
+        trace_id, span_id = (
+            (self._get_first_64_bits_of(span.trace_id), span.span_id)
+            if span
+            else (None, None)
+        )
+
+        # add ids to structlog event dictionary
+        event_dict["dd.trace_id"] = str(trace_id or 0)
+        event_dict["dd.span_id"] = str(span_id or 0)
+
+        # add the env, service, and version configured for the tracer
+        event_dict["env"] = ddtrace.config.env or ""
+        event_dict["service"] = ddtrace.config.service or ""
+        event_dict["version"] = ddtrace.config.version or ""
+
+        event_dict["container_id"] = _get_container_id()
+
+        return event_dict
+
     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(),
@@ -48,6 +80,8 @@ class ASIMRootFormatter:
             },
         }
 
+        log_dict.update(self._datadog_trace_dict())
+
         if getattr(settings, "DLFA_INCLUDE_RAW_LOG", False):
             return self.get_log_dict_with_raw(log_dict)
 
@@ -155,14 +189,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.0/django_log_formatter_asim/ecs.py

@@ -0,0 +1,16 @@
+import os
+
+
+def _get_container_id():
+    """
+    The dockerId (container Id) is available via the metadata endpoint.
+
+    However, it looks like it is embedded in the metadata URL e.g.:
+    ECS_CONTAINER_METADATA_URI=http://169.254.170.2/v3/709d1c10779d47b2a84db9eef2ebd041-0265927825
+    See: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4-response.html
+    """
+
+    try:
+        return os.environ["ECS_CONTAINER_METADATA_URI"].split("/")[-1]
+    except (KeyError, IndexError):
+        return ""

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

@@ -0,0 +1,205 @@
+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 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):
+    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
+                        - 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 = {
+        "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"

django_log_formatter_asim-1.1.0/django_log_formatter_asim/events/common.py

@@ -0,0 +1,63 @@
+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."""
+
+    """
+    The FQDN that this server is listening to HTTP requests on. For example:
+        web.trade.gov.uk
+
+    Defaults to the WSGI HTTP_HOST field if not provided.
+    """
+    domain_name: Optional[str]
+    """Internet Protocol Address of the server serving this request."""
+    ip_address: Optional[str]
+    """
+    A unique (within DBT) identifier for the software running on the server.
+    For example: berry-auctions-frontend
+
+    Defaults to combining the environment variables COPILOT_APPLICATION_NAME and
+    COPILOT_SERVICE_NAME separated by a '-'.
+    """
+    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

django_log_formatter_asim-1.1.0/django_log_formatter_asim/events/file_activity.py

@@ -0,0 +1,215 @@
+import datetime
+import json
+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
+
+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 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 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,
+        "EventStartTime": event_created.isoformat(),
+        "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 "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)
+
+
+log_file_activity.Event = FileActivityEvent
+log_file_activity.Result = Result
+log_file_activity.Severity = Severity

{django_log_formatter_asim-0.0.6 → django_log_formatter_asim-1.1.0}/pyproject.toml

@@ -3,7 +3,7 @@ line-length = 100
 
 [tool.poetry]
 name = "django-log-formatter-asim"
-version = "0.0.6"
+version = "1.1.0"
 description = "Formats Django logs in ASIM format."
 authors = ["Department for Business and Trade Platform Team <sre-team@digital.trade.gov.uk>"]
 license = "MIT"
@@ -14,17 +14,18 @@ packages = [
 
 [tool.poetry.dependencies]
 python = ">=3.9,<4"
-pre-commit = "^3.5.0"
 django = [
     { version = ">=3,<5", python = ">=3.9,<3.10" },
     { 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"