Access logs
This guide covers how to view and manage Zendesk access logs at GitLab. Access logs track read and write events in Zendesk, providing an audit trail of admin and agent actions.
Understanding Access Logs
What are access logs
As per Zendesk:
The access log is a 90-day record of events that captures what an agent or admin has accessed in your account without necessarily updating, creating, or deleting anything. The access log is your record of read and write events for your account.
Understanding Cursors
Access logs use cursor-based pagination. A cursor is a pointer that marks the last-read position in the log stream, allowing the system to fetch only new entries since the last check.
Administrator tasks
Note
- All sections in this section require
Administratorlevel access to Zendesk.
Viewing access logs
To view the access logs:
- Navigate to the admin dashboard for the Zendesk instance
- Go to
Account > Logs > Access log
Automated Log Monitoring
Overview
Technical Details
- Deployment type:
Ad-hoc - Project repo: Zendesk Global
For Zendesk Global (production), we send access log entries for specific endpoints to Devo and Elasticsearch. Other instances (sandbox instances, US Government) do not currently have this automated monitoring.
This is done via the Access logs project.
How it works
Via a scheduled pipeline, the bin/run script runs (currently every 10 minutes) to capture and forward security-relevant access events. This provides near-real-time monitoring of sensitive admin actions.
The bin/run script does the following:
- Reads the monitored endpoint information via the
data/endpoints.yamlfile - Loops over each endpoint to:
- Get all entries since the last checked cursor value
- Logs the new cursor value checked
- Sends the log entries to Devo and Elasticsearch (if any exist)
- Commits any cursor changes to the
data/endpoints.yamlfile
Endpoints monitored
Currently, the endpoints monitored are:
/admin/api/private/accounts/current/remote_authentications/admin/api/private/accounts/current/security_settings/admin/api/private/team_members
Requesting more endpoints as a non-admin
If you wish to request more endpoints are monitored, please file a feature request issue with the Customer Support Operations team.
Adding more endpoints as an admin
To add a new endpoint, you will create a MR on the project modifying the data/endpoints.yaml file. In the file, you need to add the full URI of the new endpoint as well as a starting cursor.
To locate the starting cursor, check the access logs via the API (using this endpoint). Replace YOUR_EMAIL and YOUR_API_TOKEN with your credentials in the example below:
jason@laptop:~$ curl -ss "https://gitlab.zendesk.com/api/v2/access_logs?filter[path]=/api/v2/users/search&page[size]=100" \
--header "Content-Type: application/json" \
-u YOUR_EMAIL/token:YOUR_API_TOKEN | jq '.meta.after_cursor'
"ABCDEF123456"
Using that example, our new entry would be:
- endpoint: "/api/v2/users/search"
cursor: ABCDEF123456
After a peer reviews and approves your MR, merge it. The new endpoint will be monitored starting with the next scheduled run.
Common issues and troubleshooting
As this is a fairly new item we are utilizing, there is nothing here yet. Via iteration, we will populate this as needed.
73d9718f)
