-
Notifications
You must be signed in to change notification settings - Fork 423
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[jamf_pro] Various minor improvements and fixes (#11065)
Mostly tidying of the README and pipelines, but also some small fixes.
- Loading branch information
1 parent
8c67d4c
commit 2eea5ec
Showing
26 changed files
with
579 additions
and
267 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,99 +1,119 @@ | ||
| # Jamf Pro integration | ||
|
|
||
| Jamf Pro is a comprehensive management solution designed to help organizations deploy, configure, secure, and manage Apple devices. This integration enables organizations to seamlessly monitor and protect their Mac fleet through Elastic, providing a unified view of security events across all endpoints and facilitating a more effective response to threats. This integration encompasses both event and inventory data ingestion from Jamf Pro. | ||
|
|
||
|
|
||
| ## Data streams | ||
|
|
||
| * __inventory__ provides Inventory data for computers. Includes: hardware, OS, etc. Saves each device as a separate log record. | ||
| This data stream utilizes `/v1/computers-inventory` endpoint from Jamf Pro API. | ||
| - **`inventory`** Provides Inventory data for computers. Includes: hardware, OS, etc. Saves each device as a separate log record. | ||
| This data stream utilizes the Jamf Pro API's `/v1/computers-inventory` endpoint. | ||
|
|
||
| * __events__ catches events, generated by [Jamf Pro Webhooks](https://developer.jamf.com/developer-guide/docs/webhooks) This datastream requires opening a port on kibana system | ||
| - **`events`** Receives events sent by [Jamf Pro Webhooks](https://developer.jamf.com/developer-guide/docs/webhooks). | ||
| This data stream requires opening a port on the Elastic Agent host. | ||
|
|
||
|
|
||
| ## Requirements | ||
|
|
||
| ### Inventory | ||
| #### Inventory | ||
|
|
||
| * __Jamf Pro Active License and OAuth2 Credentials:__ | ||
| This connector utilizes Jamf Pro API, therefore active license- Jamf __Business__ or __Enterprise__ is a requirement(Jamf __Now__ doesn't have access to API) | ||
| - **Jamf Pro Active License and OAuth2 Credentials** | ||
| This connector utilizes Jamf Pro API, therefore an active license - either Jamf **Business** or **Enterprise** - is required (Jamf _**Now**_ does not have access to the API) | ||
|
|
||
| ### Events | ||
| #### Events | ||
|
|
||
| - **HTTP(S) port open for incoming connections** | ||
| A port for incoming connections (`9202` by default) will be set during policy configuration. This port on host must be accessible from the Jamf server. | ||
|
|
||
| * __HTTP(S) Port opened for connection:__ On setting up the data_stream a port should be defined (9202 by default). To run the listener this port on host must be available from Jamf server. | ||
| - **Jamf Pro webhooks** | ||
| Please refer to the Jamf Pro documentation about [Setting up webhooks](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Webhooks.html). | ||
| **NOTE**: For HTTPS usage, a valid, trusted certificate is essential; Jamf Pro webhooks cannot accept a self-signed certificate. If necessary, the HTTP protocol may serve as a fallback option. Although Jamf Pro webhooks do not require HTTPS, its use is strongly recommended for security reasons. | ||
|
|
||
| * __Jamf Pro webhooks__ | ||
| [Setting up webhooks ](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Webhooks.html) in Jamf Pro Dashboard. | ||
| __NOTE__: For HTTPS usage, a valid verified certificate is essential; Jamf Pro webhooks cannot accept a self-signed certificate. If necessary, the HTTP protocol may serve as a fallback option. Although Jamf Pro webhooks do not require HTTPS, its use is strongly recommended for security reasons. | ||
|
|
||
| ## Setup | ||
|
|
||
| ### Step 1: Create an Application in Jamf Pro: | ||
|
|
||
| To create a connection to Jamf Pro, an [application must be created](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/API_Roles_and_Clients.html) first. | ||
| Credentials generated during this process are required for the subsequent steps. | ||
| To create a connection to Jamf Pro, an [application must be created](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/API_Roles_and_Clients.html) first. Credentials generated during this process are required for the subsequent steps. | ||
|
|
||
| __Permission required for Jamf Pro application__ | ||
| - _Read Computer Inventory Collection_: Access to read inventory data from the computer collection. | ||
| - _Read Computers_: Allows the application to access and read data from computers. | ||
| __Jamf Pro API Credentials__ | ||
| **client_id** is an app specific ID, it is generated on createin step and available from app settings | ||
| **client_secret** generated after app is created, it is available only after creation. Can be regenerated if lost. | ||
| **Permissions required by the Jamf Pro application**: | ||
| - **Read Computer Inventory Collection**: Access to read inventory data from the computer collection. | ||
| - **Read Computers**: Allows the application to access and read data from computers. | ||
|
|
||
| **Jamf Pro API Credentials** | ||
| - **`client_id`** is an app specific ID generated during app creation, and is available in the app settings. | ||
| - **`client_secret`** is only available once after app creation. Can be regenerated if lost. | ||
|
|
||
| Permissions can be set up on app creation or can be updated for existing app | ||
|
|
||
| ### Step 2: Integration Setup: | ||
| To set up the *Inventory* data stream these three fields are required: | ||
| - jamf_pro host | ||
| - cliet_id | ||
| - client_secret | ||
| *Events* data_stream is a passive listener, it should be created before webhook will be created at Jamf Pro Dashboard. | ||
| Network settings should be defined by IT or Security person: | ||
| **Listen Address** | ||
| **Listen Port** | ||
| **URL** | ||
| Auth settings will be required on Jamf Pro Webhook settings: | ||
| **Secret Header** | ||
| **Secret Value** | ||
|
|
||
| ### Step 3: Create a Webhook in Jamf Pro: | ||
| Following [official documentation](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Webhooks.html): | ||
| Settings: | ||
| * _Webhook URL_ must be in form `https://your-elastic-agent:9202/jamf-pro-events` Note note: `9202` is a port and `/jamf-pro-events` are default values and can be changed this connector's setup. | ||
| * _Authentication type_: `None` and `Header Authentication` are supported. | ||
| `None` will expect _Webhook URL_ is available with no authorization required, no `secret header` and `secret value` were set on integration setup. | ||
| `Header Authentication` will require Auth token name and value set on integration setup | ||
|
|
||
| | Jamf Pro Setting | Corresponding Connector Setting | Value example | | ||
| |-------------------------|---------------------------------|---------------------------------------------------| | ||
| | _Webhook URL_ | Port + URL | `https://your-elastic-agent:${PORT}${URL}` | | ||
| | _Authentication type_ | | Header Authentication | | ||
| | _Header Authentication_ | Secret Header + Secret Value | {"Authorization":"${Header}", "Token":"${Value}"} | | ||
|
|
||
| * _Content Type_: `JSON` | ||
| * _Webhook Event_: Event to be selected. In case set of events is required, 1:1 webhooks should be created. | ||
| Connector provides UI to display `ComputerAdded` and `ComputerCheckIn` events. | ||
|
|
||
| To set up the inventory data stream these three fields are required: | ||
| - `api_host` (the Jamf Pro host) | ||
| - `client_id` | ||
| - `client_secret` | ||
|
|
||
| The events data stream is a passive listener, it should be set up before webhooks are created in the Jamf Pro Dashboard. | ||
| The following network settings should be confirmed by an IT or security person: | ||
| - Listen Address | ||
| - Listen Port | ||
| - URL | ||
|
|
||
| Auth settings will be required for the Jamf Pro Webhook settings: | ||
| - Secret Header | ||
| - Secret Value | ||
|
|
||
| ### Step 3: Create Webhooks in Jamf Pro: | ||
|
|
||
| Please follow the Jamf Pro [Webhooks documentation](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Webhooks.html). | ||
|
|
||
| You will require the following settings: | ||
| - **Webhook URL**: must be in form `https://your-elastic-agent:9202/jamf-pro-events` | ||
| Note: `9202` is a port and `/jamf-pro-events` are default values and can be changed this connector's setup. | ||
|
|
||
| - **Authentication type**: "None" and "Header Authentication" are supported. | ||
| "None" means the (target) Webhook URL is available without authentication, so no secret header or secret value were set during integration policy configuration. | ||
| "Header Authentication" will require an auth token name and value, set during integration policy configuration. | ||
|
|
||
| | Jamf Pro setting | Corresponding integration setting | Example value | | ||
| |-------------------------|-----------------------------------|-----------------------------------------------------| | ||
| | _Webhook URL_ | Port + URL | `https://your-elastic-agent:${PORT}${URL}` | | ||
| | _Authentication type_ | | Header Authentication | | ||
| | _Header Authentication_ | Secret Header + Secret Value | `{"Authorization":"${Header}", "Token":"${Value}"}` | | ||
|
|
||
| - **Content Type**: `JSON` | ||
|
|
||
| - **Webhook Event**: Event to be selected. In case set of events is required, 1:1 webhooks should be created. | ||
|
|
||
|
|
||
| ## Logs | ||
|
|
||
| ### Inventory | ||
| Documents from inventory are saved under `logs-*` and can be found on discover page with filtering by `event.dataset :"jamf_pro.inventory"` | ||
|
|
||
| By default these sections are included into Jamf API query: | ||
| - _GENERAL_ | ||
| - _HARDWARE_ | ||
| - _OPERATING_SYSTEM_ | ||
| All the sections can be enabled or disabled on connector's settings page | ||
| Inventory documents can be found in `logs-*` by setting the filter `event.dataset :"jamf_pro.inventory"`. | ||
|
|
||
| By default these sections are included inventory documents: | ||
| - `GENERAL` | ||
| - `HARDWARE` | ||
| - `OPERATING_SYSTEM` | ||
|
|
||
| All the sections can be enabled or disabled on the integration policy settings page. | ||
|
|
||
| Here is an example inventory document: | ||
|
|
||
| {{event "inventory"}} | ||
|
|
||
| The following non-ECS fields are used in inventory documents: | ||
|
|
||
| {{fields "inventory"}} | ||
|
|
||
| ### Events | ||
|
|
||
| Documents from events data_stream are saved under `logs-*` and can be found on discover page with filtering by `event.dataset :"jamf_pro.events"` | ||
|
|
||
| Here is an example real-time event document: | ||
|
|
||
| {{event "events"}} | ||
|
|
||
| {{fields "events"}} | ||
| The following non-ECS fields are used in real-time event documents: | ||
|
|
||
| {{fields "events"}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -63,8 +63,15 @@ | |
| "os": { | ||
| "version": "92.5786" | ||
| }, | ||
| "related": { | ||
| "user": [ | ||
| "John Doe", | ||
| "[email protected]" | ||
| ] | ||
| }, | ||
| "user": { | ||
| "email": "[email protected]" | ||
| "email": "[email protected]", | ||
| "name": "John Doe" | ||
| } | ||
| } | ||
| ] | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -66,6 +66,16 @@ | |
| }, | ||
| "os": { | ||
| "version": "87.2388" | ||
| }, | ||
| "related": { | ||
| "user": [ | ||
| "John Doe", | ||
| "[email protected]" | ||
| ] | ||
| }, | ||
| "user": { | ||
| "email": "[email protected]", | ||
| "name": "John Doe" | ||
| } | ||
| } | ||
| ] | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -63,8 +63,15 @@ | |
| "os": { | ||
| "version": "57.4997" | ||
| }, | ||
| "related": { | ||
| "user": [ | ||
| "John Doe", | ||
| "[email protected]" | ||
| ] | ||
| }, | ||
| "user": { | ||
| "email": "[email protected]" | ||
| "email": "[email protected]", | ||
| "name": "John Doe" | ||
| } | ||
| } | ||
| ] | ||
|
|
||
Oops, something went wrong.