feat: Add applet IAM audit event logging (#2057)

* feat: Add applet IAM audit event logging

Add audit event logging to applet-related endpoints:
- Applet create, delete, encryption update
- Transfer ownership initiate, accept, decline
- Invitation send (respondent, reviewer, manager, subject, shell account)
- Invitation accept (regular and private), decline
- Remove team member, change team member permissions
- Data retention and report configuration changes

* feat: add audit logging to delete_subject endpoint

* chore: fixed lint issues

* fix: Add null checks for invitation lookup in audit logging

* fix: logging subject_id for delete_subject audit event log

* chore: refactor access audit events

* fix: add user_target_email to shell account audit event

* chore: format invitations router to pass ruff check

* chore: add explanatory comments to silenced exceptions

These were suggestions made by github-security-bot

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

* fix: log granted roles on APPLET_ACCESS_GRANT action

* chore: resolve merge conflicts with dev

Author: adeiji

src/apps/applets/api/applets.py

@@ -4,6 +4,7 @@
 
 from fastapi import Body, Depends
 from firebase_admin.exceptions import FirebaseError
+from starlette.requests import Request
 from starlette.responses import Response as HTTPResponse
 
 from apps.activities.crud import ActivitiesCRUD
@@ -35,9 +36,10 @@
 from apps.applets.filters import AppletQueryParams, FlowItemHistoryExportQueryParams
 from apps.applets.service import AppletHistoryService, AppletService
 from apps.applets.service.applet_history import retrieve_applet_by_version, retrieve_versions
+from apps.audit import AuditEvent, EventAction, http_audit_fields, log
 from apps.authentication.deps import get_current_user
 from apps.shared.domain.response import Response, ResponseMulti
-from apps.shared.exception import NotFoundError
+from apps.shared.exception import BaseError, NotFoundError
 from apps.shared.link import convert_link_key
 from apps.shared.query_params import QueryParams, parse_query_params
 from apps.subjects.services import SubjectsService
@@ -124,17 +126,37 @@ async def applet_retrieve_by_key(
 
 async def applet_create(
     owner_id: uuid.UUID,
+    request: Request,
     user: User = Depends(get_current_user),
     schema: AppletCreate = Body(...),
     session=Depends(get_session),
 ) -> Response[public_detail.Applet]:
-    async with atomic(session):
-        await CheckAccessService(session, user.id).check_applet_create_access(owner_id)
-        has_editor = await UserAppletAccessCRUD(session).check_access_by_user_and_owner(
-            user_id=user.id, owner_id=owner_id, roles=[Role.EDITOR]
+    try:
+        async with atomic(session):
+            await CheckAccessService(session, user.id).check_applet_create_access(owner_id)
+            has_editor = await UserAppletAccessCRUD(session).check_access_by_user_and_owner(
+                user_id=user.id, owner_id=owner_id, roles=[Role.EDITOR]
+            )
+            manager_role = Role.EDITOR if has_editor else None
+            applet = await AppletService(session, owner_id).create(schema, user.id, manager_role)
+    except BaseError as e:
+        await log(
+            AuditEvent(
+                event_action=EventAction.APPLET_CREATE,
+                user_id=user.id,
+                **http_audit_fields(request, e),
+            )
+        )
+        raise
+
+    await log(
+        AuditEvent(
+            event_action=EventAction.APPLET_CREATE,
+            user_id=user.id,
+            curious_applet_id=[applet.id],
+            **http_audit_fields(request),
         )
-        manager_role = Role.EDITOR if has_editor else None
-        applet = await AppletService(session, owner_id).create(schema, user.id, manager_role)
+    )
     return Response(result=public_detail.Applet.model_validate(applet))
 
 
@@ -165,15 +187,36 @@ async def applet_update(
 
 async def applet_encryption_update(
     applet_id: uuid.UUID,
+    request: Request,
     user: User = Depends(get_current_user),
     schema: Encryption = Body(...),
     session=Depends(get_session),
 ) -> Response[public_detail.Encryption]:
-    async with atomic(session):
-        service = AppletService(session, user.id)
-        await service.exist_by_id(applet_id)
-        await CheckAccessService(session, user.id).check_applet_edit_access(applet_id)
-        await service.update_encryption(applet_id, schema)
+    try:
+        async with atomic(session):
+            service = AppletService(session, user.id)
+            await service.exist_by_id(applet_id)
+            await CheckAccessService(session, user.id).check_applet_edit_access(applet_id)
+            await service.update_encryption(applet_id, schema)
+    except BaseError as e:
+        await log(
+            AuditEvent(
+                event_action=EventAction.APPLET_ENCRYPTION_UPDATE,
+                user_id=user.id,
+                curious_applet_id=[applet_id],
+                **http_audit_fields(request, e),
+            )
+        )
+        raise
+
+    await log(
+        AuditEvent(
+            event_action=EventAction.APPLET_ENCRYPTION_UPDATE,
+            user_id=user.id,
+            curious_applet_id=[applet_id],
+            **http_audit_fields(request),
+        )
+    )
     return Response(result=public_detail.Encryption.model_validate(schema))
 
 
@@ -197,15 +240,36 @@ async def applet_duplicate(
 
 async def applet_set_report_configuration(
     applet_id: uuid.UUID,
+    request: Request,
     user: User = Depends(get_current_user),
     schema: AppletReportConfiguration = Body(...),
     session=Depends(get_session),
 ):
-    async with atomic(session):
-        service = AppletService(session, user.id)
-        await service.exist_by_id(applet_id)
-        await CheckAccessService(session, user.id).check_applet_edit_access(applet_id)
-        await service.set_report_configuration(applet_id, schema)
+    try:
+        async with atomic(session):
+            service = AppletService(session, user.id)
+            await service.exist_by_id(applet_id)
+            await CheckAccessService(session, user.id).check_applet_edit_access(applet_id)
+            await service.set_report_configuration(applet_id, schema)
+    except BaseError as e:
+        await log(
+            AuditEvent(
+                event_action=EventAction.APPLET_REPORT_UPDATE,
+                user_id=user.id,
+                curious_applet_id=[applet_id],
+                **http_audit_fields(request, e),
+            )
+        )
+        raise
+
+    await log(
+        AuditEvent(
+            event_action=EventAction.APPLET_REPORT_UPDATE,
+            user_id=user.id,
+            curious_applet_id=[applet_id],
+            **http_audit_fields(request),
+        )
+    )
 
 
 async def flow_report_config_update(
@@ -331,15 +395,36 @@ async def applet_version_changes_retrieve(
 
 async def applet_delete(
     applet_id: uuid.UUID,
+    request: Request,
     user: User = Depends(get_current_user),
     session=Depends(get_session),
 ):
-    async with atomic(session):
-        service = AppletService(session, user.id)
-        await service.exist_by_id(applet_id)
-        await CheckAccessService(session, user.id).check_applet_delete_access(applet_id)
-        respondents_device_ids = await AppletsCRUD(session).get_respondents_device_ids(applet_id)
-        await service.delete_applet_by_id(applet_id)
+    try:
+        async with atomic(session):
+            service = AppletService(session, user.id)
+            await service.exist_by_id(applet_id)
+            await CheckAccessService(session, user.id).check_applet_delete_access(applet_id)
+            respondents_device_ids = await AppletsCRUD(session).get_respondents_device_ids(applet_id)
+            await service.delete_applet_by_id(applet_id)
+    except BaseError as e:
+        await log(
+            AuditEvent(
+                event_action=EventAction.APPLET_DELETE,
+                user_id=user.id,
+                curious_applet_id=[applet_id],
+                **http_audit_fields(request, e),
+            )
+        )
+        raise
+
+    await log(
+        AuditEvent(
+            event_action=EventAction.APPLET_DELETE,
+            user_id=user.id,
+            curious_applet_id=[applet_id],
+            **http_audit_fields(request),
+        )
+    )
     try:
         await service.send_notification_to_applet_respondents(
             applet_id,
@@ -415,15 +500,36 @@ async def applet_link_delete(
 
 async def applet_set_data_retention(
     applet_id: uuid.UUID,
+    request: Request,
     schema: AppletDataRetention,
     user: User = Depends(get_current_user),
     session=Depends(get_session),
 ):
-    async with atomic(session):
-        service = AppletService(session, user.id)
-        await service.exist_by_id(applet_id)
-        await CheckAccessService(session, user.id).check_applet_retention_access(applet_id)
-        await service.set_data_retention(applet_id, schema)
+    try:
+        async with atomic(session):
+            service = AppletService(session, user.id)
+            await service.exist_by_id(applet_id)
+            await CheckAccessService(session, user.id).check_applet_retention_access(applet_id)
+            await service.set_data_retention(applet_id, schema)
+    except BaseError as e:
+        await log(
+            AuditEvent(
+                event_action=EventAction.APPLET_RETENTION_UPDATE,
+                user_id=user.id,
+                curious_applet_id=[applet_id],
+                **http_audit_fields(request, e),
+            )
+        )
+        raise
+
+    await log(
+        AuditEvent(
+            event_action=EventAction.APPLET_RETENTION_UPDATE,
+            user_id=user.id,
+            curious_applet_id=[applet_id],
+            **http_audit_fields(request),
+        )
+    )
 
 
 async def applet_retrieve_base_info(

src/apps/applets/tests/test_applet.py

@@ -28,6 +28,7 @@
 from apps.applets.domain.base import AppletReportConfigurationBase, Encryption
 from apps.applets.errors import AppletAlreadyExist, AppletVersionNotFoundError
 from apps.applets.service.applet import AppletService
+from apps.audit.enums import EventAction, EventOutcome
 from apps.shared.enums import Language
 from apps.shared.exception import NotFoundError
 from apps.shared.test.client import TestClient
@@ -1366,3 +1367,150 @@ async def test_editor_can_update_applet(
         assert response.status_code == http.HTTPStatus.OK, response.json()
         data = response.json()["result"]
         assert data["displayName"] == "Updated Name"
+
+    # ── Audit event tests ──
+
+    async def test_create_applet_audit_event(
+        self, client: TestClient, tom: User, applet_minimal_data: AppletCreate, mocker: MockerFixture
+    ):
+        audit_log = mocker.patch("apps.applets.api.applets.log")
+        client.login(tom)
+        response = await client.post(
+            self.applet_create_url.format(owner_id=tom.id),
+            data=applet_minimal_data,
+        )
+        assert response.status_code == http.HTTPStatus.CREATED
+        audit_log.assert_awaited_once()
+        event = audit_log.call_args[0][0]
+        assert event.event_action == EventAction.APPLET_CREATE
+        assert event.event_outcome == EventOutcome.SUCCESS
+        assert event.user_id == tom.id
+        assert event.curious_applet_id == [uuid.UUID(response.json()["result"]["id"])]
+
+    async def test_create_applet_audit_event_failure(
+        self, client: TestClient, lucy: User, bob: User, applet_minimal_data: AppletCreate, mocker: MockerFixture
+    ):
+        audit_log = mocker.patch("apps.applets.api.applets.log")
+        client.login(lucy)
+        response = await client.post(
+            self.applet_create_url.format(owner_id=bob.id),
+            data=applet_minimal_data,
+        )
+        assert response.status_code == http.HTTPStatus.FORBIDDEN
+        audit_log.assert_awaited_once()
+        event = audit_log.call_args[0][0]
+        assert event.event_action == EventAction.APPLET_CREATE
+        assert event.event_outcome == EventOutcome.FAILURE
+        assert event.user_id == lucy.id
+
+    async def test_delete_applet_audit_event(
+        self, client: TestClient, tom: User, applet_one: AppletFull, mocker: MockerFixture
+    ):
+        audit_log = mocker.patch("apps.applets.api.applets.log")
+        client.login(tom)
+        response = await client.delete(
+            self.applet_detail_url.format(pk=applet_one.id),
+        )
+        assert response.status_code == http.HTTPStatus.NO_CONTENT
+        audit_log.assert_awaited_once()
+        event = audit_log.call_args[0][0]
+        assert event.event_action == EventAction.APPLET_DELETE
+        assert event.event_outcome == EventOutcome.SUCCESS
+        assert event.user_id == tom.id
+        assert event.curious_applet_id == [applet_one.id]
+
+    async def test_delete_applet_audit_event_failure(
+        self, client: TestClient, tom: User, uuid_zero: uuid.UUID, mocker: MockerFixture
+    ):
+        audit_log = mocker.patch("apps.applets.api.applets.log")
+        client.login(tom)
+        response = await client.delete(
+            self.applet_detail_url.format(pk=uuid_zero),
+        )
+        assert response.status_code == http.HTTPStatus.NOT_FOUND
+        audit_log.assert_awaited_once()
+        event = audit_log.call_args[0][0]
+        assert event.event_action == EventAction.APPLET_DELETE
+        assert event.event_outcome == EventOutcome.FAILURE
+        assert event.user_id == tom.id
+
+    async def test_encryption_update_audit_event(
+        self,
+        client: TestClient,
+        tom: User,
+        applet_one_no_encryption: AppletFull,
+        encryption: Encryption,
+        mocker: MockerFixture,
+    ):
+        audit_log = mocker.patch("apps.applets.api.applets.log")
+        client.login(tom)
+        response = await client.post(
+            self.applet_set_encryption_url.format(pk=applet_one_no_encryption.id),
+            data=encryption,
+        )
+        assert response.status_code == http.HTTPStatus.OK
+        audit_log.assert_awaited_once()
+        event = audit_log.call_args[0][0]
+        assert event.event_action == EventAction.APPLET_ENCRYPTION_UPDATE
+        assert event.event_outcome == EventOutcome.SUCCESS
+        assert event.user_id == tom.id
+        assert event.curious_applet_id == [applet_one_no_encryption.id]
+
+    async def test_encryption_update_audit_event_failure(
+        self, client: TestClient, tom: User, applet_one: AppletFull, encryption: Encryption, mocker: MockerFixture
+    ):
+        audit_log = mocker.patch("apps.applets.api.applets.log")
+        client.login(tom)
+        response = await client.post(
+            self.applet_set_encryption_url.format(pk=applet_one.id),
+            data=encryption,
+        )
+        assert response.status_code == http.HTTPStatus.FORBIDDEN
+        audit_log.assert_awaited_once()
+        event = audit_log.call_args[0][0]
+        assert event.event_action == EventAction.APPLET_ENCRYPTION_UPDATE
+        assert event.event_outcome == EventOutcome.FAILURE
+        assert event.user_id == tom.id
+
+    async def test_report_configuration_audit_event(
+        self, client: TestClient, tom: User, applet_one: AppletFull, mocker: MockerFixture
+    ):
+        audit_log = mocker.patch("apps.applets.api.applets.log")
+        client.login(tom)
+        report_configuration = dict(
+            report_server_ip="ipaddress",
+            report_public_key="public key",
+            report_recipients=["recipient1"],
+            report_include_user_id=True,
+            report_include_case_id=True,
+            report_email_body="body",
+        )
+        response = await client.post(
+            self.applet_report_config_url.format(pk=applet_one.id),
+            report_configuration,
+        )
+        assert response.status_code == http.HTTPStatus.OK
+        audit_log.assert_awaited_once()
+        event = audit_log.call_args[0][0]
+        assert event.event_action == EventAction.APPLET_REPORT_UPDATE
+        assert event.event_outcome == EventOutcome.SUCCESS
+        assert event.user_id == tom.id
+        assert event.curious_applet_id == [applet_one.id]
+
+    async def test_data_retention_audit_event(
+        self, client: TestClient, tom: User, applet_one: AppletFull, mocker: MockerFixture
+    ):
+        audit_log = mocker.patch("apps.applets.api.applets.log")
+        client.login(tom)
+        data_retention = dict(period=30, retention="days")
+        response = await client.post(
+            f"{self.applet_list_url}/{applet_one.id}/retentions",
+            data_retention,
+        )
+        assert response.status_code == http.HTTPStatus.OK
+        audit_log.assert_awaited_once()
+        event = audit_log.call_args[0][0]
+        assert event.event_action == EventAction.APPLET_RETENTION_UPDATE
+        assert event.event_outcome == EventOutcome.SUCCESS
+        assert event.user_id == tom.id
+        assert event.curious_applet_id == [applet_one.id]