diff --git a/docs/openhound/collectors/jamf/collect-data.mdx b/docs/openhound/collectors/jamf/collect-data.mdx index cfc33633..bfe1dbc7 100644 --- a/docs/openhound/collectors/jamf/collect-data.mdx +++ b/docs/openhound/collectors/jamf/collect-data.mdx @@ -12,42 +12,103 @@ This page covers configuring the OpenHound Jamf collector for your Jamf Pro tena ## Prerequisites * OpenHound installed with the Jamf collector included. Follow the OpenHound [installation](/openhound/community) instructions to set up OpenHound for BloodHound Community Edition. The Jamf collector is included by default in the OpenHound container image. -* A Jamf Pro account with permissions to access the Jamf Pro API. See the options below for recommended roles and permissions. +* Credentials to authenticate against the Jamf Pro API. See the options below for details on supported authentication methods. -The OpenHound setup instructions for BloodHound Community Edition also apply to BloodHound Enterprise users, for now. + + The OpenHound setup instructions for BloodHound Community Edition also apply to BloodHound Enterprise users. + -### Auditor Account (Recommended) +## Choose an authentication method -Create a [new account](https://docs.jamf.com/10.36.0/jamf-pro/install-guide-linux/Jamf_Pro_User_Accounts_and_Groups.html) directly assigned or part of a group assigned the "Auditor" default Jamf Pro role with "Full Access". +The OpenHound Jamf collector supports two authentication methods. Use the API client method whenever possible. -This account will have restricted read permissions to Jamf Pro objects. +### API client (recommended) -### Administrator Account +Authenticate with a [Jamf Pro API client](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/API_Roles_and_Clients.html) using the OAuth client credentials flow. API clients are not tied to a user account, can be scoped to a specific API role, and can be rotated or revoked independently. -The OpenHound Jamf collector can authenticate using username and password for an account that has the default "Administrator" role with "Full Access" or member of a group with the "Administrator" role and "Full Access". +To prepare OpenHound credentials for this method: -This is the least secure option and does not follow the best practice of least-privilege. + + + In Jamf Pro, create an [API role](https://learn.jamf.com/r/en-US/jamf-pro-documentation-current/Creating_an_API_Role) and grant it the following privileges: + + + - Read User + - Read Accounts + - Read Account Groups + - Read Policies + - Read Scripts + - Read Computer Extension Attributes + - Read Sites + - Read Computers + - Read API Integrations + - Read API Roles + - Read SSO Settings + + + + + In Jamf Pro, create an [API client](https://learn.jamf.com/r/en-US/jamf-pro-documentation-current/Creating_an_API_Client). + + Assign it the API role from the previous step and set the **Access token lifetime** to `7200` seconds (2 hours). + + + + In Jamf Pro, generate a [client secret](https://learn.jamf.com/r/en-US/jamf-pro-documentation-current/Generating_a_Client_Secret) for the API client. + + Copy the **Client ID** and the **Client secret** (you need both to configure the OpenHound `secrets.toml` file). + + + The client secret is only displayed once and cannot be retrieved later. If you lose it, you must generate a new one. + + + + +### Username and password + +Authenticate with a Jamf Pro user account. Create a [new account](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Jamf_Pro_User_Accounts_and_Groups.html), or use an existing one, that is directly assigned or a member of a group assigned to one of the following roles with "Full Access": + +- **Auditor** (recommended) - Provides restricted read permissions to Jamf Pro objects and follows least privilege. +- **Administrator** - Grants full administrative access. Use only when an Auditor account is not available. ## Configure OpenHound -The following OpenHound configuration parameters are required to run the Jamf collector. These can either be set -via the `[sources.source.jamf]` section of the secrets file or via environment variables using the `SOURCES__SOURCE__JAMF` prefix. +Credentials for the Jamf collector are configured under the `[sources.source.jamf.credentials]` section of the secrets file, or via environment variables that use the `SOURCES__SOURCE__JAMF__CREDENTIALS` prefix. + + + The credentials configuration structure changed in a recent release of the OpenHound Jamf collector. If you are upgrading from an earlier version, move existing `username`, `password`, and `host` values from `[sources.source.jamf]` into `[sources.source.jamf.credentials]` and update any matching environment variables to use the new `SOURCES__SOURCE__JAMF__CREDENTIALS` prefix. + -| Parameter Name | Environment Variable | Description | -|----------------|---------------------------------|------------------------------------------------------------------------------------| -| `username` | \{PREFIX\}__USERNAME | The username of the account used to authenticate to the Jamf Pro API. | -| `password` | \{PREFIX\}__PASSWORD | The password of the account used to authenticate to the Jamf Pro API. | -| `host` | \{PREFIX\}__HOST | The full host/url of the Jamf Pro tenant. For example: `https://jamf.example.com`. | +### API client parameters +| Parameter name | Environment variable | Description | +|-----------------|-------------------------------|---------------------------------------------------------------------------------------------------| +| `client_id` | \{PREFIX\}__CLIENT_ID | The client ID of the Jamf Pro API client used to authenticate to the Jamf Pro API. | +| `client_secret` | \{PREFIX\}__CLIENT_SECRET | The client secret of the Jamf Pro API client used to authenticate to the Jamf Pro API. | +| `host` | \{PREFIX\}__HOST | The full host URL of the Jamf Pro tenant. For example: `https://tenant.jamfcloud.com`. | -### Example Configuration ```toml title="secrets.toml" -[sources.source.jamf] -username = "myusername" +[sources.source.jamf.credentials] +client_id = "myclientid" +client_secret = "myclientsecret" host = "https://tenant.jamfcloud.com" +``` + +### Username and password parameters + +| Parameter name | Environment variable | Description | +|----------------|---------------------------|----------------------------------------------------------------------------------------| +| `username` | \{PREFIX\}__USERNAME | The username of the account used to authenticate to the Jamf Pro API. | +| `password` | \{PREFIX\}__PASSWORD | The password of the account used to authenticate to the Jamf Pro API. | +| `host` | \{PREFIX\}__HOST | The full host URL of the Jamf Pro tenant. For example: `https://tenant.jamfcloud.com`. | + +```toml title="secrets.toml" +[sources.source.jamf.credentials] +username = "myusername" password = "mypassword" +host = "https://tenant.jamfcloud.com" ``` -## Running OpenHound and Collecting Data +## Run OpenHound and collect data diff --git a/docs/openhound/collectors/jamf/overview.mdx b/docs/openhound/collectors/jamf/overview.mdx index 034ce8c8..e2019eee 100644 --- a/docs/openhound/collectors/jamf/overview.mdx +++ b/docs/openhound/collectors/jamf/overview.mdx @@ -7,17 +7,19 @@ description: Learn about the SpecterOps-supported OpenHound Jamf collector for B The OpenHound Jamf collector is the SpecterOps-supported tool for retrieving Jamf Pro tenant data for BloodHound. -If you are evaluating collector options for the Jamf extension, this is the recommended path. An alternative collector, [JamfHound](https://github.com/SpecterOps/JamfHound), also exists, but this documentation section focuses specifically on the OpenHound-based collector. + + If you are evaluating collector options for the Jamf extension, this is the recommended path. An alternative collector ([JamfHound](https://github.com/SpecterOps/JamfHound)) also exists, but this documentation focuses specifically on the OpenHound-based collector. + -## Authentication Options +## Authentication options -The OpenHound Jamf collector supports two authentication patterns: +The OpenHound Jamf collector supports two authentication methods against the Jamf API: -- [Auditor account](/openhound/collectors/jamf/collect-data): Recommended for most environments because it follows a read-oriented, lower-privilege collection path. -- [Administrator account](/openhound/collectors/jamf/collect-data): Simpler if you already have an admin account available, but less aligned with least privilege. +- [API client (recommended)](/openhound/collectors/jamf/collect-data#api-client-recommended): Authenticate with a Jamf API client using the OAuth client credentials flow. This approach avoids tying collection to a user account and is the preferred option for production environments. +- [Username and password](/openhound/collectors/jamf/collect-data#username-and-password): Authenticate with a Jamf user account. Pair this method with the Auditor role in Jamf to follow least privilege. -## Next Steps +## Next steps -- Review [Configure the Collector](/openhound/collectors/jamf/collect-data) -- Choose an authentication approach based on your available Jamf Pro roles +- Choose an authentication method and assign an appropriate Jamf role +- Review [Configure the collector](/openhound/collectors/jamf/collect-data) - Import the resulting data with the [Jamf OpenGraph extension](/opengraph/extensions/jamf/getting-started)