API - Audit Logs #3861

New Issue

OVERLORD · 2026-02-05T07:42:12+03:00

OVERLORD commented

2026-02-05 07:42:12 +03:00

Originally created by @ademxoy on GitHub (Jun 15, 2023).

Describe the feature you'd like

I would like to be able to get the audit logs using an API to transfer the data to splunk. Application & Splunk servers are in 2 different zones that does not allow access to database from Splunk or direct access from bookstack to splunk.

Describe the benefits this would bring to existing BookStack users

Audit logs one of the most important part of managing access and making sure all the information bookstack contains is safe. I would have helped if bookstack was written with Python or Go but I have no knowledge in PHP...

Can the goal of this request already be achieved via other means?

Yes, Database activities table can be dumped, ftp over to and then written into another server. It is just very clumsy.

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

Not using yet, just scoping

Additional context

There were a few other requests to transfer to csv, etc. In my case, bookstack contains sensitive data and almost every port is blocked by a firewall (including the database from outside).

Originally created by @ademxoy on GitHub (Jun 15, 2023). ### Describe the feature you'd like I would like to be able to get the audit logs using an API to transfer the data to splunk. Application & Splunk servers are in 2 different zones that does not allow access to database from Splunk or direct access from bookstack to splunk. ### Describe the benefits this would bring to existing BookStack users Audit logs one of the most important part of managing access and making sure all the information bookstack contains is safe. I would have helped if bookstack was written with Python or Go but I have no knowledge in PHP... ### Can the goal of this request already be achieved via other means? Yes, Database activities table can be dumped, ftp over to and then written into another server. It is just very clumsy. ### Have you searched for an existing open/closed issue? - [X] I have searched for existing issues and none cover my fundemental request ### How long have you been using BookStack? Not using yet, just scoping ### Additional context There were a few other requests to transfer to csv, etc. In my case, bookstack contains sensitive data and almost every port is blocked by a firewall (including the database from outside).

OVERLORD added the 🔨 Feature Request 🔩 API Request labels 2026-02-05 07:42:12 +03:00

OVERLORD closed this issue

2026-02-05 07:42:15 +03:00

OVERLORD commented

2026-02-05 07:42:22 +03:00

@ssddanbrown commented on GitHub (Jun 15, 2023):

Thanks for the request @ademxoy.
Should be relatively simple to add a single activities API endpoint for this, especially if we ignore non-admin user access, at least for initial implementation.

Can the goal of this request already be achieved via other means?

There is also webhooks, which can spit out anything that gets recorded to the audit log, but I appreciate that's quite a different form of data handling.

How long have you been using BookStack?
Not using yet, just scoping

I'll keep this issue open as it fits the platform while naturally following the path of matching UI abilities with the API, and existing other users may desire this also, but I generally like to increase our scope of core support to actual existing user need rather than potential/theoretical requirement.
Let me know if your usage becomes more of a reality and I'll adjust my desire to implement/support accordingly.

@ssddanbrown commented on GitHub (Jun 15, 2023): Thanks for the request @ademxoy. Should be relatively simple to add a single `activities` API endpoint for this, especially if we ignore non-admin user access, at least for initial implementation. > Can the goal of this request already be achieved via other means? There is also webhooks, which can spit out anything that gets recorded to the audit log, but I appreciate that's quite a different form of data handling. > How long have you been using BookStack? > Not using yet, just scoping I'll keep this issue open as it fits the platform while naturally following the path of matching UI abilities with the API, and existing other users may desire this also, but I generally like to increase our scope of core support to actual existing user need rather than potential/theoretical requirement. Let me know if your usage becomes more of a reality and I'll adjust my desire to implement/support accordingly.

OVERLORD commented

2026-02-05 07:42:24 +03:00

@ademxoy commented on GitHub (Jun 15, 2023):

This is actually in use; but I just wanted to give you the freedom to work on it whenever you have time. I understand the burden of an open source projects...

We export the database, import the database as read-only (using a read-only username to access to the database) to have a read-only version, export the activities right now. This only happens once a day.

Appreciate the support and the product!

@ademxoy commented on GitHub (Jun 15, 2023): This is actually in use; but I just wanted to give you the freedom to work on it whenever you have time. I understand the burden of an open source projects... We export the database, import the database as read-only (using a read-only username to access to the database) to have a read-only version, export the activities right now. This only happens once a day. Appreciate the support and the product!

OVERLORD commented

2026-02-05 07:42:29 +03:00

@ssddanbrown commented on GitHub (Jun 26, 2023):

Dev Notes

Some notes since I looked into doing this but it's getting late so not implementing right now, but don't want to loose my thoughts so recording here:

Need to decide what we do with entity_id and entity_type.
- We don't expose these elsewhere on the API, not sure I want to expose those names.
- We should expose these fields though to allow filtering by related type.
- For recycle bin we have deletable_type and id. Probably good to update this to something similar.
  - name? activitable sounds bad. Maybe loggable_type and id? Already use a loggable interface.
  - If we expand it here, should we update other activity types to have relation.
    - For those, Need to update related activity on delete?
Don't exposed updated_at, don't think that should ever be different. Remove column?
Is this the activities API or audit-log API?
- Existing endpoints more follow the UI naming, rather than DB naming, so currently siding to audit-log.
- "audit-log" Might be and awkward name for future non-admin activity usage, but probably better to optimize for the main desired use case we're specifically targeting here.

@ssddanbrown commented on GitHub (Jun 26, 2023): ### Dev Notes Some notes since I looked into doing this but it's getting late so not implementing right now, but don't want to loose my thoughts so recording here: - Need to decide what we do with `entity_id` and `entity_type`. - We don't expose these elsewhere on the API, not sure I want to expose those names. - We should expose these fields though to allow filtering by related type. - For recycle bin we have `deletable_type` and id. Probably good to update this to something similar. - name? `activitable` sounds bad. Maybe `loggable_type` and id? Already use a loggable interface. - If we expand it here, should we update other activity types to have relation. - For those, Need to update related activity on delete? - Don't exposed `updated_at`, don't think that should ever be different. Remove column? - Is this the activities API or audit-log API? - Existing endpoints more follow the UI naming, rather than DB naming, so currently siding to audit-log. - "audit-log" Might be and awkward name for future non-admin activity usage, but probably better to optimize for the main desired use case we're specifically targeting here.

OVERLORD commented

2026-02-05 07:42:33 +03:00

@bennyandresen commented on GitHub (Aug 8, 2023):

I don't just want to leave a +1 here, so I explain my use case:
I'm also keeping another system in sync with my bookstack instance. Right now it grabs all the information from all available APIs and calculates the changes.

I would like to reduce the amount of API calls and load on the system by using a centralized log API. First thought was the audit-log in the settings. But an activities API (even filtered by users) would work equally well for my use-case. (I'm more interested in the contents, than the exact values in the database.)

@bennyandresen commented on GitHub (Aug 8, 2023): I don't just want to leave a +1 here, so I explain my use case: I'm also keeping another system in sync with my bookstack instance. Right now it grabs all the information from all available APIs and calculates the changes. I would like to reduce the amount of API calls and load on the system by using a centralized log API. First thought was the audit-log in the settings. But an activities API (even filtered by users) would work equally well for my use-case. (I'm more interested in the contents, than the exact values in the database.)

OVERLORD commented

2026-02-05 07:42:35 +03:00

@ademxoy commented on GitHub (Jan 25, 2024):

@ssddanbrown Hi Dan, any update on this? We had a situation where we lost our database and can't figure out how much data was lost.

@ademxoy commented on GitHub (Jan 25, 2024): @ssddanbrown Hi Dan, any update on this? We had a situation where we lost our database and can't figure out how much data was lost.

OVERLORD commented

2026-02-05 07:42:38 +03:00

@ssddanbrown commented on GitHub (Jan 26, 2024):

@ademxoy No news from me.
Is the a reason this API would help in that scenario?

@ssddanbrown commented on GitHub (Jan 26, 2024): @ademxoy No news from me. Is the a reason this API would help in that scenario?

OVERLORD commented

2026-02-05 07:42:40 +03:00

@ademxoy commented on GitHub (Jan 26, 2024):

Yeah, in this scenario, I would transfer the audit logs to Splunk every X minutes so we could tell what documents were changed by who since the last backup.

@ademxoy commented on GitHub (Jan 26, 2024): Yeah, in this scenario, I would transfer the audit logs to Splunk every X minutes so we could tell what documents were changed by who since the last backup.

OVERLORD commented

2026-02-05 07:42:43 +03:00

@ademstan commented on GitHub (Mar 11, 2024):

+1 This would be really useful for us

@ademstan commented on GitHub (Mar 11, 2024): +1 This would be really useful for us

OVERLORD commented

2026-02-05 07:42:46 +03:00

@ssddanbrown commented on GitHub (May 5, 2024):

#4987 has now been merged to add a simple audit-log list endpoint.
This will therefore be part of the next feature release.
Thanks again @ademxoy for the original request.

@ssddanbrown commented on GitHub (May 5, 2024): #4987 has now been merged to add a simple audit-log list endpoint. This will therefore be part of the next feature release. Thanks again @ademxoy for the original request.

OVERLORD commented

2026-02-05 07:42:48 +03:00

@ademxoy commented on GitHub (May 6, 2024):

Thanks, Dan. We appreciate the work you do!

@ademxoy commented on GitHub (May 6, 2024): Thanks, Dan. We appreciate the work you do!

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#3861