API - Audit Logs

[ademxoy]

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).

[ssddanbrown]

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.

[ademxoy]

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!

[ssddanbrown]

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.

[bennyandresen]

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.)

[ademxoy]

@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.

[ssddanbrown]

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

[ademxoy]

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.

[ademstan]

+1 This would be really useful for us

[ssddanbrown]

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.

[ademxoy]

Thanks, Dan. We appreciate the work you do!