Enable a means for changes to devices/fleets/apps to be logged so that it’s then possible to find out when a specific change was made and by whom.
It is also worked here? Implement webhooks/notifications/a means to be alerted of changes · Balena Feature Requests
Chris Crocker-White: this project is more about logging the actions that were taken so there’s a history there that you can look back on to see what actions were taken, whereas the webhooks/notifications is more about informing other services in an automated way.
Is there a plan to implement this into the UI?
Harald (balena): Yes, the plan is to implement this into the balena dashboard. We are going to start with the device audit logs. Right now, we are remodelling the data structure to make it a seamless experience to browse through device audit logs. We’ll update on the progress here, once we have the feature shipped.
The provided example for filtered requests did not work for us in Postman. We used this instead:
https://api.balena-cloud.com/v6/device_history?$select=uuid,tracks__device,is_created_by__actor&$filter=uuid eq ‘ACTUAL_UUID’&$expand=tracks__device,is_created_by__actor($expand=is_of__user)
Also, thanks for the update on audit logging. We are looking forward to it, because of ISO 27001.
Oct 2024
As it’s been a while since we provided an update, we wanted to give you some background on what’s been happening with this work.
As Harald has detailed, we have since implemented device audit logs that can be accessed from the API. However, we recognise that this might not serve the functionality that’s actually being asked for here. From what we assume, this is for users to be able to see the history of the device e.g. who’s interacted with it, when it’s been powered on and off, connectivity history. etc
We’re moving this feature back to ‘open’ so we can go back to the planning stage and deliver functionality that our users need. To do this, we’d like to understand more about everyone’s use cases and what this is needed for. Our assumption is that this would be most valuable for security purposes, but we don’t want to build on assumptions! If you can share your use cases in the comments, we can collect your feedback and discuss the best way to move forward.
Thank you for your help in making balena better for everyone!
Aug 2023
Our current plans are to expose our internal device histories first. This exposed resource will answer questions about ‘What happened to a device and who did it’.
This device history will be visible per device and per fleet through the dashboard. In addition, the information will also be queryable a a regular balenaAPI resource.
Currently we are finalising the exposure of the resource and afterwards start the dashboard integration.
Update:
This week we have released the functionality in our API to request the device history for all accessible devices.
The API provides the device_history
resource which is filterable for example by an device UUID. The interface for the device_history record is:
DeviceHistory {
created_at: DateString;
modified_at: DateString;
id: number;
end_timestamp: DateString | null;
is_created_by__actor: { __id: number } | [Actor?] | null;
is_ended_by__actor: { __id: number } | [Actor?] | null;
tracks__device: { __id: number } | [Device?] | null;
tracks__actor: { __id: number } | [Actor?] | null;
uuid: string | null;
belongs_to__application: { __id: number } | [Application?] | null;
is_active: boolean;
is_running__release: { __id: number } | [Release?] | null;
should_be_running__release: { __id: number } | [Release?] | null;
api_heartbeat_state: 'online' | 'offline' | 'timeout' | 'unknown';
is_connected_to_vpn: boolean;
is_managed_by__service_instance: { __id: number } | [ServiceInstance?] | null;
os_version: string | null;
os_variant: string | null;
supervisor_version: string | null;
is_of__device_type: { __id: number } | [DeviceType?] | null;
cpu_id: string | null;
should_be_managed_by__release: { __id: number } | [Release?] | null;
}
An example query for getting all visible device history records and user who caused the history entry (the user who made the change) is:
https://api.balena-cloud.com/v6/device_history?$select=uuid,tracks__device,is_created_by__actor&$expand=tracks__device,is_created_by__actor($expand=is_of__user)
Filtered by UUID:
https://api.balena-cloud.com/v6/device_history?$select=uuid,tracks__device,is_created_by__actor&$filter=uuid eq '<uuid>'&$expand=tracks__device,is_created_by__actor($expand=is_of__user)
The device history visibility is provided with plan specific look-back timeframes:
- for the Free, Pilot and Prototype plans the history shows all entries from the last 24 hours.
- for the Production plan the history shows all entries from the last 30 days.
- for the Enterprise plan the history shows all entries from the last 90 days
Our next step is the surfacing on the balenaDashboard.
Replying to the update from Laura, we have two uses cases:
- Internal audit. When responding to an incident, we can check if and when something was changed. For example, we store some of the application configuration in the device env variables and it would be convenient to access the device history from the dashboard, rather than executing an API call on demand, or setting up a script that dumps all the device events periodically.
- External audit. Some clients have previously requested logs of the changes done to their devices. We addressed this with the existing API call. However, without involving the tech team, it would be either that we assign an observer user to a fleet and then the client gathers the information they need autonomously, or we should be able to export the logs in csv or comparable format and send to the client on request.