Administering Keen
Mosyle administrator action logs
Chapter 36 of 40
Mosyle
Mosyle is a built-in, read-only ingester for Mosyle Business. It collects administrator action logs from the Mosyle API: an audit trail of who signed in to Mosyle and who changed what in the device fleet.
Enable the API and configure Keen
- In Mosyle, open Organization → API Integration, enable the profile and copy its access token. Mosyle signs API users in with a JSON Web Token; a profile that still uses Basic Authentication needs a new API token.
- Choose the Mosyle administrator Keen signs in as. The API asks for an administrator's email address and password as well as the access token, so create an administrator for Keen alone, give it the least access Mosyle allows for reading logs, and give it a long password used nowhere else.
- Set these in Keen's
.envand recreate the API, worker and beat containers:KEEN_MOSYLE_ENABLED=true KEEN_MOSYLE_ACCESS_TOKEN=YOUR_API_ACCESS_TOKEN KEEN_MOSYLE_EMAIL=keen@example.org KEEN_MOSYLE_PASSWORD=YOUR_ADMINISTRATOR_PASSWORD KEEN_MOSYLE_CONFIG_PATH=/app/config/mosyle.yml KEEN_MOSYLE_POLL_SECONDS=7200
Mosyle collection is off until KEEN_MOSYLE_ENABLED is true. Create a named Mosyle source for each Mosyle organisation; the Environment default connection uses the deployment settings.
Going deeper: transport security
Keen sends requests to Mosyle's own server alone, https://businessapi.mosyle.com/v1; no setting or connection field names another server. Each run signs in. The password is sent to the sign-in alone, in the body of the request, and the bearer token that returns is sent with the access token to that server alone. The bearer token lasts a day at Mosyle and Keen keeps it only for the run; when Mosyle stops accepting it during a run, Keen signs in once more, so a run sends the password at most twice. Each sign-in appears in the log as a User Login by the administrator Keen uses.
HTTPS and certificate verification are mandatory, redirects are refused, cookies Mosyle sets are discarded, each request ends within two minutes and responses are limited to 8 MiB. No credential appears in a URL. A saved password and a saved access token are write-only.
Select the stream in Keen
Define a Mosyle source with the access token and the administrator's email address and password, then select Add input on that source in Sources & evidence mapping and enter the stream adminlogs, the one stream Mosyle offers here. An optional label becomes the event's system; otherwise it is Mosyle. The shipped stream list is empty, so enabling the adapter alone collects nothing; add the stream, then use Ingest runners → Run Mosyle or wait for the scheduled run.
Going deeper: the YAML file and its settings
Administrators can also manage config/mosyle.yml; saved web-UI configuration overrides it.
ui_name: Mosyle
badge_color: '#00A1DE'
streams:
- stream: adminlogs
# label: Device fleet
initial_lookback_days: 30
window_hours: 24
overlap_minutes: 60
max_pages: 100
initial_lookback_days is how far back the first run reads (0 to 367). window_hours is the span of the log read at a time (1 to 168), overlap_minutes how far each window reaches back for logs Mosyle lists late (0 to 1,440) and max_pages the pages one run reads (1 to 1,000).
Going deeper: windows, pages and limits
Keen reads the log in windows of time, oldest first, from its cursor to the present. Each page of a window is stored and committed before the next is requested, and the cursor moves to a window's end only when every page of it is stored, so a failure never skips logs. A run that reaches max_pages inside a window keeps its page and the next run continues that window.
Mosyle states a page size and a count of logs with each page. A page shorter than the page size, whose count reaches no further page, ends its window; after a full page Keen asks for the next, and a page without logs ends the window. A window of more than 1,000 pages is refused with an error that asks for a lower window_hours.
Mosyle gives a log no identifier, so Keen recognises one it has already stored by its content, and a log read twice is stored once. Two logs alike in every field, including the time to the second, are therefore stored as one.
Mosyle writes a log's date and time without a time zone; Keen reads it as UTC. A log without a readable time is dated when it was collected. An entry that is not a log object is left out and counted as invalid_records in the run's result. An answer in a shape Keen cannot read is reported as an error and keeps the cursor, as do HTTP 429 and transient failures, which the next scheduled run retries.
Map Mosyle evidence
Choose Create mapping, source mosyle. Keen names each event's action admin. followed by Mosyle's own name for the action, in lower case with underscores, and its actor is the administrator's name.
| Mosyle action | Event action |
|---|---|
| User Login | admin.user_login |
| Create API Integration | admin.create_api_integration |
| Renew API Integration Access Token | admin.renew_api_integration_access_token |
Every event has outcome info and severity 3. An action without plain words becomes admin.unknown.
Example: source mosyle, action admin.user_login, mapped to your privileged-access control. A second mapping on action admin.create_api_integration records new API integrations.
Going deeper: useful JSON paths
event.action,event.username,event.action_dateandevent.ipevent.details, an object whose fields depend on the action, such asevent.details.E-mailfor a sign-in orevent.details.Profile Namefor an API integration
The whole log Mosyle returned is kept under event in the payload and in the artifact, through the standard Keen redaction, artifact storage, SHA-256 and framework-rule pipeline.
Scope
This adapter reads administrator action logs. It does not read devices, users or groups, it does not read the Mosyle Logs Stream, and it changes nothing in Mosyle. Start collection soon after enabling it: the first run reads back only as far as initial_lookback_days and as far as Mosyle still holds logs. The source is unavailable in demo environments.