Skip to content

Commit

Permalink
Merge pull request #5143 from kobotoolbox/TASK-1054-improve-al-docume…
Browse files Browse the repository at this point in the history 
…ntation

Improve audit log endpoint documentation
  • Loading branch information
@noliveleger
noliveleger authored Oct 9, 2024
2 parents c86d193 + d7a2320 commit 1c12337
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 19 deletions.
8 changes: 2 additions & 6 deletions kobo/apps/audit_log/tests/test_one_time_auth.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,13 +133,13 @@ def side_effect(request):
'kpi.authentication.OPOAuth2Authentication.authenticate',
'kobo.apps.openrosa.libs.authentication.BasicAuthentication.authenticate',
)
def test_any_auth_for_submissions(self, authetication_method):
def test_any_auth_for_submissions(self, authentication_method):
"""
Test most one-time authenticated submissions result in a submission access log
"""

with patch(
authetication_method,
authentication_method,
return_value=(TestOneTimeAuthentication.user, 'something'),
):
# assume the submission works, we don't actually care
Expand All @@ -161,10 +161,6 @@ def test_any_auth_for_submissions(self, authetication_method):
def test_digest_auth_for_submissions(self):
"""
Test digest-authenticated submissions result in a submission access log
=======
Test digest authentications for submissions result in an audit log being created
with the 'Submission' type
>>>>>>> main
"""

def side_effect(request):
Expand Down
146 changes: 133 additions & 13 deletions kobo/apps/audit_log/views.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ class AuditLogViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
"""
Audit logs
Lists the actions performed (delete, update, create) by users.
Lists actions performed by users.
Only available for superusers.
<span class='label label-warning'>For now, only `DELETE`s are logged</span>
Expand All @@ -29,23 +29,89 @@ class AuditLogViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
> Response 200
> {
> "count": 1,
> "count": 2,
> "next": null,
> "previous": null,
> "results": [
> {
> "app_label": "foo",
> "model_name": "bar",
> "user": "http://kf.kobo.local/users/kobo_user/",
> "user": "http://kf.kobo.local/api/v2/users/kobo_user/",
> "user_uid": "u12345",
> "action": "delete",
> "date_created": "2024-10-01T00:01:00Z",
> "log_type": "asset-management",
> }
> },
> {
> "app_label": "kobo_auth",
> "model_name": "user",
> "user": "http://kf.kobo.local/api/v2/users/another_user/",
> "user_uid": "u12345",
> "username": "another_user",
> "action": "auth",
> "metadata": {
> "source": "Firefox (Ubuntu)",
> "auth_type": "Digest",
> "ip_address": "1.2.3.4"
> },
> "date_created": "2024-10-01T00:00:00Z",
> "log_type": "access"
> },
> ]
> }
Results from this endpoint can be filtered by a Boolean query specified in the
`q` parameter.
**Filterable fields:**
1. app_label
2. model_name
3. action
a. Available actions:
i. create
ii. delete
iii. in-trash
iv. put-back
v. remove
vi. update
vii. auth
4. log_type
a. Available log types:
i. access
ii. project-history
iii. data-editing
iv. submission-management
v. user-management
vi. asset-management
5. date_created
6. user_uid
7. user__*
a. user__username
b. user__email
c. user__is_superuser
8. metadata__*
a. metadata__asset_uid
b. metadata__auth_type
c. some logs may have additional filterable fields in the metadata
**Some examples:**
1. All deleted submissions<br>
Expand All @@ -63,6 +129,9 @@ class AuditLogViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
5. All deleted submissions submitted after a specific date **and time**<br>
`/api/v2/audit-logs/?q=action:delete AND date_created__gte:"2022-11-15 20:34"`
6. All authentications from superusers<br>
`api/v2/audit-logs/?q=action:auth AND user__is_superuser:True
*Notes: Do not forget to wrap search terms in double-quotes if they contain spaces
(e.g. date and time "2022-11-15 20:34")*
Expand Down Expand Up @@ -94,7 +163,7 @@ class AllAccessLogViewSet(AuditLogViewSet):
Lists all access logs for all users. Only available to superusers.
Submissions will be grouped together by hour
Submissions will be grouped together by user by hour
<pre class="prettyprint">
<b>GET</b> /api/v2/access-logs/
Expand All @@ -117,15 +186,15 @@ class AllAccessLogViewSet(AuditLogViewSet):
> "username": "admin",
> "metadata": {
> "source": "Firefox (Ubuntu)",
> "auth_type": "Digest",
> "auth_type": "digest",
> "ip_address": "172.18.0.6"
> },
> "date_created": "2024-08-19T16:48:58Z",
> },
> {
> "user": "http://localhost/api/v2/users/admin/",
> "user_uid": "u12345",
> "username": "admin",
> "user": "http://localhost/api/v2/users/someuser/",
> "user_uid": "u5678",
> "username": "someuser",
> "metadata": {
> "auth_type": "submission-group",
> },
Expand All @@ -135,8 +204,59 @@ class AllAccessLogViewSet(AuditLogViewSet):
> ]
> }
This endpoint can be filtered and paginated the same as the /audit-logs endpoint
Results from this endpoint can be filtered by a Boolean query
specified in the `q` parameter.
**Filterable fields:**
1. date_created
2. user_uid
3. user__*
a. user__username
b. user__email
c. user__is_superuser
4. metadata__*
a. metadata__auth_type
available auth types:
i. django-loginas
ii. token
iii. digest
iv. basic
v. submission-group
vi. kpi.backends.ModelBackend
vii. authorized-application
viii. oauth2
ix. unknown
b. metadata__source
c. metadata__ip_address
d. metadata__initial_user_uid
e. metadata__initial_user_username
f. metadata__authorized_app_name
This endpoint can be paginated with 'offset' and 'limit' parameters, eg
> curl -X GET https://[kpi-url]/access-logs/?offset=100&limit=50
"""

queryset = AccessLog.objects.with_submissions_grouped().order_by('-date_created')
Expand All @@ -152,12 +272,12 @@ class AccessLogViewSet(AuditLogViewSet):
Submissions will be grouped together by hour
<pre class="prettyprint">
<b>GET</b> /api/v2/access-logs/me
<b>GET</b> /api/v2/access-logs/me/
</pre>
> Example
>
> curl -X GET https://[kpi-url]/access-logs/me
> curl -X GET https://[kpi-url]/access-logs/me/
> Response 200
Expand Down Expand Up @@ -191,7 +311,7 @@ class AccessLogViewSet(AuditLogViewSet):
> }
This endpoint can be paginated with 'offset' and 'limit' parameters, eg
> curl -X GET https://[kpi-url]/access-logs/me?offset=100&limit=50
> curl -X GET https://[kpi-url]/access-logs/me/?offset=100&limit=50
will return entries 100-149
Expand Down

0 comments on commit 1c12337

Please sign in to comment.