Keen documentation
Open Keen ↗

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

  1. 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.
  2. 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.
  3. Set these in Keen's .env and 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 actionEvent action
User Loginadmin.user_login
Create API Integrationadmin.create_api_integration
Renew API Integration Access Tokenadmin.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_date and event.ip
  • event.details, an object whose fields depend on the action, such as event.details.E-mail for a sign-in or event.details.Profile Name for 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.