diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..a5fc0ea --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,24 @@ +name: docs + +on: + push: + branches: + - update-docs + paths: + - docs/** + - mkdocs.yml + - .github/workflows/docs.yml + +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: write + pages: write + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: 3.12 + - run: pip install mkdocs==1.6.0 mkdocs-material==9.5.32 mkdocs-print-site-plugin==2.6.0 + - run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/README.md b/README.md index 946f9c9..2f56c4a 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ [![Latest release (latest by date)](https://img.shields.io/github/v/release/splunk/ta_cisco_webex_add_on_for_splunk?label=Latest%20Release)](https://github.com/splunk/genesys_cloud_ta/releases) [![License](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0) +Find more details in our [Github Page](https://splunk.github.io/ta_cisco_webex_add_on_for_splunk/) and [README](https://github.com/splunk/ta_cisco_webex_add_on_for_splunk/blob/main/package/README.md#here-are-the-endpoints-their-corresponding-source-types-and-the-required-scopes) > **Cisco Webex Add-on for Splunk** is an Add-on to pull in data from _[Webex REST API](https://developer.webex.com/docs/basics)_ to Splunk. Here are the endpoints and their mapping soucetypes. @@ -20,7 +21,7 @@ Here are the endpoints and their mapping soucetypes. ## Versions Supported - - Tested for installation and basic ingestion on Splunk 9.X and 8.2 for **CentOS** system. + - Tested for installation and basic ingestion on Splunk 10.x, 9.X and 8.2. > Built by Splunk's FDSE Team (#team-fdse). @@ -32,4 +33,4 @@ Here are the endpoints and their mapping soucetypes. * Isaac Fonseca Monge * Marie Duran * Ashley Hoang -* Isaac Fonseca \ No newline at end of file +* Erica Pescio \ No newline at end of file diff --git a/docs/Configuration/index.md b/docs/Configuration/index.md deleted file mode 100644 index 7d544d9..0000000 --- a/docs/Configuration/index.md +++ /dev/null @@ -1,197 +0,0 @@ -# Create a Webex Integration - -The Cisco Webex Add-on for Splunk supports OAuth2 Authentication, which allows third-party integrations to get a temporary access token for authenticating API calls. Therefore, creating an **Admin-level Webex integration** is required to work along with this Add-on. -Please follow the following steps to create a dedicated Webex integration for this Add-on. Further documentation can be found [here](https://developer.webex.com/docs/integrations). - -1. **Registering your Integration**: - - Visit the [Webex for Developers](https://developer.webex.com/) and then log in using your **Webex Admin Account** - - Select `My Webex Apps` from the menu under your avatar at the top of this page - - Click `Create a New App` then `Create an Integration` to start the wizard -2. **Provide app related information**: - - **Integration name**: Enter a name for yor integration. `e.g. Webex Integration for Splunk` - - **Icon**: Upload your own or select from the defaults - - **Description**: Provide some details about your integration - - **Redirect URI(s)**: Follow the following steps to retrieve your Redirect URI: - - Open **Cisco Webex Add-on for Splunk** in Splunk. Go to `Configuration > Account > Add`. The Redirect URI will show up in the `Redirect url` field. Please copy and paste it to the `Redirect URI(s)` field in the Webex Integration. - - **For Splunk Heavy Forwarders (or IDM)**: please replace the `{domain}` with the domain of your Splunk Heavy Forwarder (or IDM). For example, if the domain of your HF or IDM is `example.splunk.link`, then the Redirect URI you have to enter is: `https://example.splunk.link/en-US/app/ta_cisco_webex_add_on_for_splunk/ta_cisco_webex_add_on_for_splunk_redirect`. Ensure not to submit the form yet. - - - **Scopes**: Please select the following scopes: - **Note**: No matter whether you will use Webex Meetings Input or not, you **MUST** select all the following scopes. - - `audit:events_read` - - `analytics:read_all` - - `spark-admin:calling_cdr_read` - - `spark-admin:people_read` - - `meeting:admin_participants_read` - - `meeting:admin_schedule_read` - - `meeting:admin_config_read` - - `spark:organizations_read` - -3. Click **Add Integration** on the bottom of the page, your `Client ID` and `Client Secret` are ready to use. - -# Configure Cisco Webex Add-on for Splunk - -Open the Web UI for the Heavy Forwarder (or IDM). Access the Add-on from the list of applications. Please follow the following steps in order: - - -#### 1. Create Account -- Click on the `Configuration` button on the top left corner. -- Click on the `Account` button. -- Click on the `Add` button on the top right to create a new account. -- Enter the following details in the pop-up box: - - **Account name**: Enter a unique name for this account. - - **Webex API Base Endpoint**: Enter your Webex API Base Endpoint. The default one is `webexapis.com`. - - **Client ID**: Enter the `Client ID` that you obtained above here. - - **Client Secret**: Enter the `Client Secret` that you obtained above here. - - **Redirect URI**: The Redirect URI will auto show up. - - Click on the `Add` button. - - -#### 2. Create Input - -**Webex Scheduled Meetings Input** - -The **Webex Scheduled Meetings** input is used to fetch the active scheduled meetings from [Meetings](https://developer.webex.com/docs/api/v1/meetings/list-meetings) endpoint. It allows users to retrieve account-wide scheduled meetings of all users in your organization. - -Query parameters used for this input: -- `meetingType: scheduledMeeting` -- `hostEmail: `, where all HOST_EMAILs are getting from [List People](https://developer.webex.com/docs/api/v1/people/list-people) endpoint - -**Note: In order to avoid ingesting duplicate meetings, each scheduled meeting will be only ingested when it reaches its start time. It doesn’t pull in the future scheduled meetings whose start time is in the future.** - -The `Interval` is required. It's used to specify how often it hits the Webex Meetings endpoint to pull the scheduled meetings in. The ingestion time increase as the number of users increases. If you have more than 100 users in your organization, it's recommended to set the interval to be at least 300 (5 mins). - -The `Start Time` is required. Set the starting date and time to fetch the scheduled meetings. The Start time is inclusive and should be in the format YYYY-MM-DDTHH:MM:SSZ (example:2023-01-01T00:00:00Z). This input aims to get active scheduled meetings, it's recommended to set Start Time to the current time. For example, the current time is `2023-08-01T10:05:28Z`, you can set it as `2023-08-01T00:00:00Z`. If you'd like to get all historical meetings, please use the **Webex Meetings Summary Report Input**. - -The `End Time` is optional. If you set it to be a specific date, only the scheduled meetings within the time range from Start Date to End Date will be ingested. The format should be YYYY-MM-DDTHH:MM:SSZ (example:2023-02-01T00:00:00Z). - -The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the end time of the last round as the checkpoint, and will be used as the `Start Time` (advancing by one second) for the next run. - -- Click on the `Inputs` button on the top left corner. -- Click on `Create New Input` button on the top right corner. -- Enter the following details in the pop-up box: - - **Name** (_required_): Unique name for the data input. - - **Interval** (_required_): Time interval of input in seconds. - - **Index** (_required_): Index for storing data. - - **Global Account** (_required_): Select the account created during Configuration. - - **Start Time** (_required_): Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ. It's recommended to set Start Time to the current time. For example, the current time is `2023-08-01T10:05:28Z`, you can set it as `2023-08-01T00:00:00Z`. - - **End Time** (_optional_): End date and time in the format YYYY-Mon-DDTHH:MM:SSZ.(Optional), `example:2023-02-01T00:00:00Z`. End Time must be after the Start Time. -- Click on the `Add` green button on the bottom right of the pop-up box. - -**Webex Meetings Summary Report Input** - -The **Webex Meetings Summary Report** input is used to fetch the data from both [Meeting Usage Reports](https://developer.webex.com/docs/api/v1/meetings-summary-report/list-meeting-usage-reports) endpoint and [Meeting Attendee Reports](https://developer.webex.com/docs/api/v1/meetings-summary-report/list-meeting-attendee-reports) endpoint. It allows users to retrieve account-wide reports on past meetings and their correlated meeting attendees. - -**Please Note**: The input only returns the **historical** meeting reports and attendee reports, since these two endpoints only contain historical data. The input will have a few hours delay due to the API behavior. Typically, meeting data is not showing up in the API until 2 to 3 hours after the meetings end. Therefore, the meetings data is only ingested 2 to 3 hours after the meetings end. - -The `Start Time` is required. Set the starting date and time to fetch meetings & attendees. The Start Time is inclusive and should be in the format YYYY-MM-DDTHH:MM:SSZ (example:2023-01-01T00:00:00Z). The interval between Start Time and End Time cannot exceed 30 days and Start Time cannot be earlier than 90 days ago. - -The `End Time` is optional. If you set it to be a specific date, only reports within the time range from Start Time to End Time will be ingested. The format should be YYYY-MM-DDTHH:MM:SSZ (example:2023-02-01T00:00:00Z). The interval between Start Time and End Time cannot exceed 30 days. Leave it blank if an ongoing ingestion mode is needed. - -The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest meeting start time as the checkpoint, and will be used as the `Start Time` (advancing by one second) for the next run. - -- Click on the `Inputs` button on the top left corner. -- Click on `Create New Input` button on the top right corner. -- Enter the following details in the pop-up box: - - **Name** (_required_): Unique name for the data input. - - **Interval** (_required_): Time interval of input in seconds. - - **Index** (_required_): Index for storing data. - - **Global Account** (_required_): Select the account created during Configuration. - - **Site Name** (_required_): Site Name of the Webex Meeting account. `example: example.webex.com` - - **Start Time** (_required_): Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-01-01T00:00:00Z`. The interval between Start Time and End Time cannot exceed 30 days and Start Time cannot be earlier than 90 days ago. - - **End Time** (_optional_): End date and time in the format YYYY-Mon-DDTHH:MM:SSZ.(Optional), `example:2023-02-01T00:00:00Z`. Leave it blank if an ongoing ingestion mode is needed. The interval between Start Time and End Time cannot exceed 30 days. -- Click on the `Add` green button on the bottom right of the pop-up box. - -**Webex Admin Audit Events Input** - -The **Webex Admin Audit Events** input is used to fetch the data from [Admin Audit Events](https://developer.webex.com/docs/api/v1/admin-audit-events) endpoint. It allows users to retrieve organization-wide audit logs all over the account. - -The `Start Time` is required. Set the starting date and time to fetch admin audit events. The Start time is inclusive and should be in the format YYYY-MM-DDTHH:MM:SS.SSSZ (example:2023-01-01T00:00:00.000Z). If you leave the `End Time` blank, Start Time **MUST** be within one year from the current time. - -The `End Time` is optional. If you set it to be a specific date, only logs within the time range from Start Date to End Date will be ingested. The format should be YYYY-MM-DDTHH:MM:SS.SSSZ (example:2023-02-01T00:00:00.000Z). - -**Please Note**: Due to the API behavior, the selected time range cannot be more than a year. Therefore, If you want to obtain the audit logs that happened more than one year ago, you **MUST** fill in both `Start Time` and `End Time`, and ensure that the range does not exceed one year. - -The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest audit event created time as the checkpoint, and will be used as the `Start Time` (advancing by one millisecond) for the next run. - -- Click on the `Inputs` button on the top left corner. -- Click on `Create New Input` button on the top right corner. -- Enter the following details in the pop-up box: - - **Name** (_required_): Unique name for the data input. - - **Interval** (_required_): Time interval of input in seconds. - - **Index** (_required_): Index for storing data. - - **Global Account** (_required_): Select the account created during Configuration. - - **Start Time** (_required_): Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SS.SSSZ, `example:2023-01-01T00:00:00.000Z`. If you leave the `End Time` blank, Start Time **MUST** be within one year from the current time. - - **End Time** (_optional_): End date and time in the format YYYY-MM-DDTHH:MM:SS.SSSZ.(Optional), `example:2023-02-01T00:00:00.000Z`. End Time must be after the Start Time. -- Click on the `Add` green button on the bottom right of the pop-up box. - -**Webex Meeting Qualities** - -The **Webex Meeting Qualities** input is used to fetch the data from [Webex Meeting Qualities](https://developer.webex.com/docs/api/v1/meeting-qualities/get-meeting-qualities) endpoint. It allows users to retrieve quality data for meetings. Only organization administrators can retrieve meeting quality data. - -The `Start Time` is required. Set the starting date and time to fetch meeting quality data. The Start time is inclusive and should be in the format YYYY-MM-DDTHH:MM:SSZ (example:2023-01-01T00:00:00Z). Due to the Webex API limitation, Quality information may be retrieved for up to 7 days. The Start Time **MUST** be within 7 days from the current time. - -The `End Time` is optional. If you set it to be a specific date, only data within the time range from Start time to End time will be ingested. The format should be YYYY-MM-DDTHH:MM:SSZ (example:2023-02-01T00:00:00Z). Leave it blank if an ongoing ingestion mode is needed. - -The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest meeting start time as the checkpoint, and will be used as the `Start Time` (advancing by one millisecond) for the next run. - -- Click on the `Inputs` button on the top left corner. -- Click on `Create New Input` button on the top right corner. -- Enter the following details in the pop-up box: - - **Name** (_required_): Unique name for the data input. - - **Interval** (_required_): Time interval of input in seconds. - - **Index** (_required_): Index for storing data. - - **Global Account** (_required_): Select the account created during Configuration. - - **Start Time** (_required_): Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-01-01T00:00:00Z`. The Start Time **MUST** be within 7 days from the current time. - - **End Time** (_optional_): End date and time in the format YYYY-MM-DDTHH:MM:SSZ.(Optional), `example:2023-02-01T00:00:00Z`. Leave it blank if an ongoing ingestion mode is needed. -- Click on the `Add` green button on the bottom right of the pop-up box. - - -**Webex Detailed Call History** - -The **Webex Detailed Call History** input is used to fetch the data from [Webex Detailed Call History](https://developer.webex.com/docs/api/v1/reports-detailed-call-history/get-detailed-call-history) endpoint. It allows users to retrieve detailed data from calls. Only organization administrators can retrieve the data and it requires the administrator role "Webex Calling Detailed Call History API access" to be enabled. - -The `Start Time` is required. Set the starting date and time to fetch the calls data. The Start time is inclusive and should be in the format YYYY-MM-DDTHH:MM:SSZ (example:2023-01-01T00:00:00Z). The Start Time **MUST** must be between 5 minutes ago and 48 hours ago, more than that is not possible. - -The `End Time` is optional. If you set it to be a specific date, only data within the time range from Start time to End time will be ingested. The format should be YYYY-MM-DDTHH:MM:SSZ (example:2023-02-01T00:00:00Z). Leave it blank if an ongoing ingestion mode is needed. The End Time **MUST** be later than the Start Time but no later than 48 hours. - -The `Locations` field is also optional. You can include up to 10 comma-separed locations, and each location name should the same as shown in the Control Hub. - -The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest call start time as the checkpoint, and will be used as the `Start Time` (advancing by one millisecond) for the next run. - -- Click on the `Inputs` button on the top left corner. -- Click on `Create New Input` button on the top right corner. -- Enter the following details in the pop-up box: - - **Name** (_required_): Unique name for the data input. - - **Interval** (_required_): Time interval of input in seconds. - - **Index** (_required_): Index for storing data. - - **Global Account** (_required_): Select the account created during Configuration. - - **Start Time** (_required_): Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-01-01T00:00:00Z`. The Start Time **MUST** must be between 5 minutes ago and 48 hours ago. - - **End Time** (_optional_): End date and time in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-02-01T00:00:00Z`. Leave it blank if an ongoing ingestion mode is needed. The End Time **MUST** be later than the Start Time but no later than 48 hours. - - **Locations** (_optional_): Enter up to 10 locations separated by a comma. -- Click on the `Add` green button on the bottom right of the pop-up box. - - -**Webex Security Audit Events Input** - -The **Webex Security Audit Events** input is used to fetch the data from [Security Audit Events](https://developer.webex.com/admin/docs/api/v1/security-audit-events/list-security-audit-events) endpoint. It allows users to retrieve user sign-in and sign-out data. - -**Prerequisites**: This input is only available to customers with **Pro Pack** for Control Hub. To use this input, you must make sure you have **Pro Pack** for Webex Contol Hub, and then follow these two steps to enable this feature. -1. Sign in to Control Hub, then under **Management** > **Organization Settings**. -2. In the **User authentication data** section, toggle **Allow user authentication data** on. - -The `Start Time` is required. Set the starting date and time to fetch admin audit events. The Start time is inclusive and should be in the format YYYY-MM-DDTHH:MM:SS.SSSZ (example:2023-01-01T00:00:00.000Z). If you leave the `End Time` blank, Start Time **MUST** be within one year from the current time. - -The `End Time` is optional. If you set it to be a specific date, only logs within the time range from Start Date to End Date will be ingested. The format should be YYYY-MM-DDTHH:MM:SS.SSSZ (example:2023-02-01T00:00:00.000Z). - -The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest audit event created time as the checkpoint, and will be used as the `Start Time` (advancing by one millisecond) for the next run. - -- Click on the `Inputs` button on the top left corner. -- Click on `Create New Input` button on the top right corner. -- Enter the following details in the pop-up box: - - **Name** (_required_): Unique name for the data input. - - **Interval** (_required_): Time interval of input in seconds. - - **Index** (_required_): Index for storing data. - - **Global Account** (_required_): Select the account created during Configuration. - - **Start Time** (_required_): Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SS.SSSZ, `example:2023-01-01T00:00:00.000Z`. If you leave the `End Time` blank, Start Time **MUST** be within one year from the current time. - - **End Time** (_optional_): End date and time in the format YYYY-MM-DDTHH:MM:SS.SSSZ.(Optional), `example:2023-02-01T00:00:00.000Z`. End Time must be after the Start Time. -- Click on the `Add` green button on the bottom right of the pop-up box. \ No newline at end of file diff --git a/docs/ConfigureAccount/index.md b/docs/ConfigureAccount/index.md new file mode 100644 index 0000000..62dee8f --- /dev/null +++ b/docs/ConfigureAccount/index.md @@ -0,0 +1,35 @@ +# Prerequisites + + +#### Create the Webex OAuth Integration in Webex + +The Cisco Webex Add-on for Splunk supports OAuth2 Authentication, which allows third-party integrations to get a temporary access token for authenticating API calls. Therefore, creating an **Admin-level Webex integration** is required to work along with this Add-on. +Please follow the following steps to create a dedicated Webex integration for this Add-on. Further documentation can be found [here](https://developer.webex.com/docs/integrations). + +1. **Registering your Integration**: + - Visit the [Webex for Developers](https://developer.webex.com/) and then log in using your **Webex Admin Account** + - Select `My Webex Apps` from the menu under your avatar at the top of this page + - Click `Create a New App` then `Create an Integration` to start the wizard +2. **Provide app related information**: + - **Integration name**: Enter a name for yor integration. `e.g. Webex Integration for Splunk` + - **Icon**: Upload your own or select from the defaults + - **Description**: Provide some details about your integration + - **Redirect URI(s)**: Follow the following steps to retrieve your Redirect URI: + - Open **Cisco Webex Add-on for Splunk** in Splunk. Go to `Configuration > Account > Add`. The Redirect URI will show up in the `Redirect url` field. Please copy and paste it to the `Redirect URI(s)` field in the Webex Integration. + - **For Splunk Heavy Forwarders (or IDM)**: please replace the `{domain}` with the domain of your Splunk Heavy Forwarder (or IDM). For example, if the domain of your HF or IDM is `example.splunk.link`, then the Redirect URI you have to enter is: `https://example.splunk.link/en-US/app/ta_cisco_webex_add_on_for_splunk/ta_cisco_webex_add_on_for_splunk_redirect`. Ensure not to submit the form yet. + + - **Scopes**: Please select only the scopes you need referring to the table below + + #### Here are the endpoints, their corresponding source types, and the required scopes. +| Splunk Input | Webex Endpoint | Splunk Sourcetype | Required Scopes | +|--------------------|-----------------------|---------------------------------|---------------------------------| +| Webex Scheduled Meetings | [Meetings](https://developer.webex.com/docs/api/v1/meetings/list-meetings) | cisco:webex:meetings | meeting:admin_schedule_read spark-admin:people_read | +| Webex Meetings Summary Report | [Meeting Usage Reports](https://developer.webex.com/docs/api/v1/meetings-summary-report/list-meeting-usage-reports) | cisco:webex:meeting:usage:reports | meeting:admin_schedule_read meeting:admin_participants_read meeting:admin_config_read | +| Webex Meetings Summary Report | [Meeting Attendee Reports](https://developer.webex.com/docs/api/v1/meetings-summary-report/list-meeting-attendee-reports) | cisco:webex:meeting:attendee:reports | meeting:admin_schedule_read meeting:admin_participants_read meeting:admin_config_read | +| Webex Admin Audit Events | [Admin Audit Events](https://developer.webex.com/docs/api/v1/admin-audit-events) | cisco:webex:admin:audit:events | audit:events_read spark:organizations_read | +| Webex Meeting Qualities | [Meeting Qualities](https://developer.webex.com/docs/api/v1/meeting-qualities/get-meeting-qualities) | cisco:webex:meeting:qualities | analytics:read_all | +| Webex Detailed Call History | [Detailed Call History](https://developer.webex.com/docs/api/v1/reports-detailed-call-history/get-detailed-call-history) | cisco:webex:call:detailed_history | spark-admin:calling_cdr_read | +| Webex Security Audit Events | [Security Audit Events](https://developer.webex.com/admin/docs/api/v1/security-audit-events/list-security-audit-events) | cisco:webex:security:audit:events | audit:events_read spark:organizations_read | + +3. Click **Add Integration** on the bottom of the page, your `Client ID` and `Client Secret` are ready to use. + diff --git a/docs/ConfigureAdminAuditEventInput/index.md b/docs/ConfigureAdminAuditEventInput/index.md new file mode 100644 index 0000000..924a405 --- /dev/null +++ b/docs/ConfigureAdminAuditEventInput/index.md @@ -0,0 +1,27 @@ +# Webex Admin Audit Events Input + +The **Webex Admin Audit Events** input is used to fetch the data from [Admin Audit Events](https://developer.webex.com/docs/api/v1/admin-audit-events) endpoint. It allows users to retrieve organization-wide audit logs all over the account. + +**Please Note**: Due to the API behavior, the selected time range cannot be more than a year. Therefore, If you want to obtain the audit logs that happened more than one year ago, you **MUST** fill in both `Start Time` and `End Time`, and ensure that the range does not exceed one year. + +The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest audit event created time as the checkpoint, and will be used as the `Start Time` (advancing by one millisecond) for the next run. + + +## Configure Webex Admin Audit Events input through Splunk Web + +1. In the **Inputs** tab select **Create New Input**. +2. Choose **Webex Admin Audit Events**. +3. Enter the information in the related fields using the following input parameters table. + +## Input Parameters + +Each attribute in the following table corresponds to a field in Splunk Web. + +|Input name |Corresponding field in Splunk Web | Description| +|-------------------------|----------------------------------|------------| +|`name` |Name |A unique name for your input.| +|`interval` |Interval |Time interval of input in seconds.| +|`index` |Index |The index in which the data should be stored. The default is default.| +|`account` |Global Account |The Webex account created in the Configuration tab.| +|`start_time` |Start Time |Required, Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-01-01T00:00:00Z`. If you leave the `End Time` blank, Start Time **MUST** be within one year from the current time.| +|`end_time` |End Time |Optional, End date and time in the format YYYY-Mon-DDTHH:MM:SSZ.(Optional), `example:2023-02-01T00:00:00Z`. End Time must be after the Start Time.| \ No newline at end of file diff --git a/docs/ConfigureDetailedCallHistoryInput/index.md b/docs/ConfigureDetailedCallHistoryInput/index.md new file mode 100644 index 0000000..429f51a --- /dev/null +++ b/docs/ConfigureDetailedCallHistoryInput/index.md @@ -0,0 +1,25 @@ +# Webex Detailed Call History + +The **Webex Detailed Call History** input is used to fetch the data from [Webex Detailed Call History](https://developer.webex.com/docs/api/v1/reports-detailed-call-history/get-detailed-call-history) endpoint. It allows users to retrieve detailed data from calls. Only organization administrators can retrieve the data and it requires the administrator role "Webex Calling Detailed Call History API access" to be enabled. + +The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest call start time as the checkpoint, and will be used as the `Start Time` (advancing by one millisecond) for the next run. + +## Configure Webex Detailed Call History input through Splunk Web + +1. In the **Inputs** tab select **Create New Input**. +2. Choose **Webex Detailed Call History**. +3. Enter the information in the related fields using the following input parameters table. + +## Input Parameters + +Each attribute in the following table corresponds to a field in Splunk Web. + +|Input name |Corresponding field in Splunk Web | Description| +|-------------------------|----------------------------------|------------| +|`name` |Name |A unique name for your input.| +|`interval` |Interval |Time interval of input in seconds.| +|`index` |Index |The index in which the data should be stored. The default is default.| +|`account` |Global Account |The Webex account created in the Configuration tab.| +|`start_time` |Start Time |Required, Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-01-01T00:00:00Z`. The Start Time **MUST** must be between 5 minutes ago and 48 hours ago.| +|`end_time` |End Time |Optional, End date and time in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-02-01T00:00:00Z`. Leave it blank if an ongoing ingestion mode is needed. The End Time **MUST** be later than the Start Time but no later than 48 hours.| +|`location` |Locations. |Optional, Enter up to 10 comma-separed locations. Each location name should the same as shown in the Control Hub.| \ No newline at end of file diff --git a/docs/ConfigureGenericInput/index.md b/docs/ConfigureGenericInput/index.md new file mode 100644 index 0000000..84f02fc --- /dev/null +++ b/docs/ConfigureGenericInput/index.md @@ -0,0 +1,32 @@ +# Webex Generic Endpoint + +The **Webex Generic Endpoint** provides the flexibility to create a custom input using the Webex API endpoint of your choice. If you encounter scenarios where the predefined input options do not meet your requirements, you can use this option to enable data ingestion from a different source. + + +Keep in mind that the endpoint you want to use may require special permissions, roles, and/or scopes. Please refer to the API documentation to see the requirements needed to enable data ingestion for the endpoint. + +Enter a `Start Time` whenever it is supported by the endpoint to help avoid duplicates. If an `End Time` is specified, data will be fetched up to that time; otherwise, data will be fetched up to the current time. If a `Start` or `Created` time is present in the response, it will be saved as a checkpoint and used as the `Start Time` for the next run. + +Some endpoints require specific query parameters to function correctly. Users can add these parameters using the `Query Params` field. The input also supports path parameters in the URL, which should be included in the `API Endpoint` field. + +## Configure Webex Generic Endpoint input through Splunk Web + +1. In the **Inputs** tab select **Create New Input**. +2. Choose **Webex Generic Endpoint**. +3. Enter the information in the related fields using the following input parameters table. + +## Input Parameters + +Each attribute in the following table corresponds to a field in Splunk Web. + +|Input name |Corresponding field in Splunk Web | Description| +|-------------------------|----------------------------------|------------| +|`name` |Name |A unique name for your input.| +|`interval` |Interval |Time interval of input in seconds.| +|`index` |Index |The index in which the data should be stored. The default is default.| +|`account` |Global Account |The Webex account created in the Configuration tab.| +|`webex_endpoint` |API Endpoint |The Webex API endpoint. It is not necessary to include a leading slash as for example: `device`, or `devices/12345678`.| +|`webex_base_url` |Webex Base API URL |Enter the base URL for the endpoint. Most Webex APIs use `webexapis.com`, but some may require a different base URL. For example, endpoints that require the `analytics:read_all` scope often use `analytics.webexapis.com`. Always refer to the endpoint documentation to confirm the correct base URL.| +|`start_time` |Start Time |Required, Inclusive start date and time in the format `YYYY-MM-DDTHH:MM:SSZ`, e.g. `2023-01-01T00:00:00Z`. Be aware of the endpoint limitations and valid ranges.| +|`end_time` |End Time |Optional, End date and time in the format `YYYY-Mon-DDTHH:MM:SSZ`, e.g. `2023-02-01T00:00:00Z`. Leave blank if an ongoing ingestion mode is needed. Be aware of the endpoint limitations and valid ranges.| +|`query_params. ` |Query Params |Include any query parameters for the endpoint. For multiple parameters, enter them as comma-separated values (e.g. `locationId=0000000, messageId=0000000, teamId=0000000`).| \ No newline at end of file diff --git a/docs/ConfigureMeetingQualitiesInput/index.md b/docs/ConfigureMeetingQualitiesInput/index.md new file mode 100644 index 0000000..34ba8ff --- /dev/null +++ b/docs/ConfigureMeetingQualitiesInput/index.md @@ -0,0 +1,24 @@ +# Webex Meeting Qualities + +The **Webex Meeting Qualities** input is used to fetch the data from [Webex Meeting Qualities](https://developer.webex.com/docs/api/v1/meeting-qualities/get-meeting-qualities) endpoint. It allows users to retrieve quality data for meetings. Only organization administrators can retrieve meeting quality data. + +The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest meeting start time as the checkpoint, and will be used as the `Start Time` (advancing by one millisecond) for the next run. + +## Configure Webex Meeting Qualities input through Splunk Web + +1. In the **Inputs** tab select **Create New Input**. +2. Choose **Webex Meeting Qualities**. +3. Enter the information in the related fields using the following input parameters table. + +## Input Parameters + +Each attribute in the following table corresponds to a field in Splunk Web. + +|Input name |Corresponding field in Splunk Web | Description| +|-------------------------|----------------------------------|------------| +|`name` |Name |A unique name for your input.| +|`interval` |Interval |Time interval of input in seconds.| +|`index` |Index |The index in which the data should be stored. The default is default.| +|`account` |Global Account |The Webex account created in the Configuration tab.| +|`start_time` |Start Time |Required, Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-01-01T00:00:00Z`. The Start Time **MUST** be within 7 days from the current time.| +|`end_time` |End Time |Optional, End date and time in the format YYYY-Mon-DDTHH:MM:SSZ. `example:2023-02-01T00:00:00Z`. Leave it blank if an ongoing ingestion mode is needed.| \ No newline at end of file diff --git a/docs/ConfigureMeetingSummaryReportInput/index.md b/docs/ConfigureMeetingSummaryReportInput/index.md new file mode 100644 index 0000000..8e5de38 --- /dev/null +++ b/docs/ConfigureMeetingSummaryReportInput/index.md @@ -0,0 +1,27 @@ +# Webex Meetings Summary Report Input + +The **Webex Meetings Summary Report** input is used to fetch the data from both [Meeting Usage Reports](https://developer.webex.com/docs/api/v1/meetings-summary-report/list-meeting-usage-reports) endpoint and [Meeting Attendee Reports](https://developer.webex.com/docs/api/v1/meetings-summary-report/list-meeting-attendee-reports) endpoint. It allows users to retrieve account-wide reports on past meetings and their correlated meeting attendees. + +**Please Note**: The input only returns the **historical** meeting reports and attendee reports, since these two endpoints only contain historical data. The input includes a 24‑hour delay due to the behavior of the API. According to the Webex documentation, “The report data for a meeting should be available within 24 hours after the meeting ends.” To ensure the data is complete and to avoid data gaps, the input ingests meeting data only after a full 24 hours have passed since the meeting ended. + +The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest meeting start time as the checkpoint, and will be used as the `Start Time` (advancing by one second) for the next run. + +## Configure Webex Meeting Summary input through Splunk Web + +1. In the **Inputs** tab select **Create New Input**. +2. Choose **Webex Meetings Summary Report**. +3. Enter the information in the related fields using the following input parameters table. + +## Input Parameters + +Each attribute in the following table corresponds to a field in Splunk Web. + +|Input name |Corresponding field in Splunk Web | Description| +|-------------------------|----------------------------------|------------| +|`name` |Name |A unique name for your input.| +|`interval` |Interval |Time interval of input in seconds.| +|`index` |Index |The index in which the data should be stored. The default is default.| +|`account` |Global Account |The Webex account created in the Configuration tab.| +|`site_url` |Site Name |Site Name of the Webex Meeting account. `example: example.webex.com`| +|`start_time` |Start Time |Required, Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ, `example:2023-01-01T00:00:00Z`. The start time must be set to 24 hours prior to the current UTC time. The interval between Start Time and End Time cannot exceed 30 days and Start Time cannot be earlier than 90 days ago.| +|`end_time` |End Time |Optional, End date and time in the format YYYY-Mon-DDTHH:MM:SSZ.(Optional), `example:2023-02-01T00:00:00Z`. Leave it blank if an ongoing ingestion mode is needed. The interval between Start Time and End Time cannot exceed 30 days.| \ No newline at end of file diff --git a/docs/ConfigureScheduledMeetingsInput/index.md b/docs/ConfigureScheduledMeetingsInput/index.md new file mode 100644 index 0000000..8370a2d --- /dev/null +++ b/docs/ConfigureScheduledMeetingsInput/index.md @@ -0,0 +1,29 @@ +# Webex Scheduled Meetings Input + +The **Webex Scheduled Meetings** input is used to fetch the active scheduled meetings from [Meetings](https://developer.webex.com/docs/api/v1/meetings/list-meetings) endpoint. It allows users to retrieve account-wide scheduled meetings of all users in your organization. + +Query parameters used for this input: +- `meetingType: scheduledMeeting` +- `hostEmail: `, where all HOST_EMAILs are getting from [List People](https://developer.webex.com/docs/api/v1/people/list-people) endpoint + +**Note: In order to avoid ingesting duplicate meetings, each scheduled meeting will be only ingested when it reaches its start time. It doesn’t pull in the future scheduled meetings whose start time is in the future.** + +## Configure Webex Scheduled Meetings input through Splunk Web + +1. In the **Inputs** tab select **Create New Input**. +2. Choose **Webex Scheduled Meetings**. +3. Enter the information in the related fields using the following input parameters table. + + +## Input Parameters + +Each attribute in the following table corresponds to a field in Splunk Web. + +|Input name |Corresponding field in Splunk Web | Description| +|-------------------------|----------------------------------|------------| +|`name` |Name |A unique name for your input.| +|`interval` |Interval |Interval is used to specify how often it hits the Webex Meetings endpoint to pull the scheduled meetings in. The ingestion time increase as the number of users increases. If you have more than 100 users in your organization, it's recommended to set the interval to be at least 300 (5 mins).| +|`index` |Index |The index in which the data should be stored. The default is default.| +|`account` |Global Account |The Webex account created in the Configuration tab.| +|`start_time` |Start Time |Required, Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SSZ. It's recommended to set Start Time to the current time. For example, the current time is `2023-08-01T10:05:28Z`, you can set it as `2023-08-01T00:00:00Z`.| +|`end_time` |End Time |Optional, if you set it to be a specific date, only the scheduled meetings within the time range from Start Date to End Date will be ingested. The format should be YYYY-MM-DDTHH:MM:SSZ (example:2023-02-01T00:00:00Z).| \ No newline at end of file diff --git a/docs/ConfigureSecurityAuditEventInput/index.md b/docs/ConfigureSecurityAuditEventInput/index.md new file mode 100644 index 0000000..f59f5c1 --- /dev/null +++ b/docs/ConfigureSecurityAuditEventInput/index.md @@ -0,0 +1,28 @@ +# Webex Security Audit Events Input + +The **Webex Security Audit Events** input is used to fetch the data from [Security Audit Events](https://developer.webex.com/admin/docs/api/v1/security-audit-events/list-security-audit-events) endpoint. It allows users to retrieve user sign-in and sign-out data. + +**Prerequisites**: This input is only available to customers with **Pro Pack** for Control Hub. To use this input, you must make sure you have **Pro Pack** for Webex Contol Hub, and then follow these two steps to enable this feature. +1. Sign in to Control Hub, then under **Management** > **Organization Settings**. +2. In the **User authentication data** section, toggle **Allow user authentication data** on. + +The input uses checkpointing to avoid ingesting duplicate data. After the initial run, the script will save the latest audit event created time as the checkpoint, and will be used as the `Start Time` (advancing by one millisecond) for the next run. + +## Configure Webex Security Audit Events input through Splunk Web + +1. In the **Inputs** tab select **Create New Input**. +2. Choose **Webex Security Audit Events**. +3. Enter the information in the related fields using the following input parameters table. + +## Input Parameters + +Each attribute in the following table corresponds to a field in Splunk Web. + +|Input name |Corresponding field in Splunk Web | Description| +|-------------------------|----------------------------------|------------| +|`name` |Name |A unique name for your input.| +|`interval` |Interval |Time interval of input in seconds.| +|`index` |Index |The index in which the data should be stored. The default is default.| +|`account` |Global Account |The Webex account created in the Configuration tab.| +|`start_time` |Start Time |Required, Start date and time (inclusive) in the format YYYY-MM-DDTHH:MM:SS.SSSZ, `example:2023-01-01T00:00:00.000Z`. If you leave the `End Time` blank, Start Time **MUST** be within one year from the current time.| +|`end_time` |End Time |Optional, End date and time in the format YYYY-Mon-DDTHH:MM:SSZ. `example:2023-02-01T00:00:00Z`. End Time must be after the Start Time.| \ No newline at end of file diff --git a/docs/ConfigureWebexAccount/index.md b/docs/ConfigureWebexAccount/index.md new file mode 100644 index 0000000..65e2a45 --- /dev/null +++ b/docs/ConfigureWebexAccount/index.md @@ -0,0 +1,17 @@ +# Set up your Webex Account in Splunk + + + +1. Open the Web UI for the Heavy Forwarder (or IDM). Access the Add-on from the list of applications. +2. Click on the `Configuration` tab on the top left corner. +3. Click on the `Account` button. +4. Click on the `Add` button on the top right to create a new account. +5. Enter the following details in the pop-up box: + - **Account name**: Enter a unique name for this account. + - **Webex API Base Endpoint**: Enter your Webex API Base Endpoint. The default one is `webexapis.com`. + - **Client ID**: Enter the `Client ID` that you obtained above here. + - **Client Secret**: Enter the `Client Secret` that you obtained above here. + - **Redirect URI**: The Redirect URI will auto show up. + - **Scopes**: Select the authorization scopes. Please ensure that the scopes entered here match those selected in your Webex Integration. + - **Gov Account**: Please check this box if you are using a Webex Gov Account. +6. Click on the `Add` button. \ No newline at end of file diff --git a/docs/Installation/index.md b/docs/Installation/index.md index 832f4a0..d0bcbc1 100644 --- a/docs/Installation/index.md +++ b/docs/Installation/index.md @@ -6,4 +6,12 @@ - Please follow the steps [here](https://docs.splunk.com/Documentation/AddOns/released/Overview/Distributedinstall) to install the Add-on in a distributed Splunk Enterprise deployment. #### Installation Steps for `Splunk Cloud` -Please follow the steps [here](https://docs.splunk.com/Documentation/AddOns/released/Overview/SplunkCloudinstall) to install the Add-on in Splunk Cloud. \ No newline at end of file +Please follow the steps [here](https://docs.splunk.com/Documentation/AddOns/released/Overview/SplunkCloudinstall) to install the Add-on in Splunk Cloud. + +#### Install the Cisco Webex Add-on for Splunk +You can install the Cisco Webex Add-on for Splunk with Splunk Web or from the command line. + +1. Download the [Cisco Webex Add-on for Splunk](https://github.com/splunk/ta_cisco_webex_add_on_for_splunk/releases) from GitHub. +2. Determine where and how to install this add-on in your deployment. +3. Perform any prerequisite steps before installing. +4. Complete your installation. \ No newline at end of file diff --git a/docs/Sourcetypes/index.md b/docs/Sourcetypes/index.md new file mode 100644 index 0000000..91996c4 --- /dev/null +++ b/docs/Sourcetypes/index.md @@ -0,0 +1,12 @@ +> **Cisco Webex Add-on for Splunk** is an Add-on to pull in data from _[Webex REST API](https://developer.webex.com/docs/basics)_ to Splunk. + + +| Splunk Input | Webex Endpoint | Splunk Sourcetype | Required Scopes | +|--------------------|-----------------------|---------------------------------|---------------------------------| +| Webex Scheduled Meetings | [Meetings](https://developer.webex.com/docs/api/v1/meetings/list-meetings) | cisco:webex:meetings | meeting:admin_schedule_read spark-admin:people_read | +| Webex Meetings Summary Report | [Meeting Usage Reports](https://developer.webex.com/docs/api/v1/meetings-summary-report/list-meeting-usage-reports) | cisco:webex:meeting:usage:reports | meeting:admin_schedule_read meeting:admin_participants_read meeting:admin_config_read | +| Webex Meetings Summary Report | [Meeting Attendee Reports](https://developer.webex.com/docs/api/v1/meetings-summary-report/list-meeting-attendee-reports) | cisco:webex:meeting:attendee:reports | meeting:admin_schedule_read meeting:admin_participants_read meeting:admin_config_read | +| Webex Admin Audit Events | [Admin Audit Events](https://developer.webex.com/docs/api/v1/admin-audit-events) | cisco:webex:admin:audit:events | audit:events_read spark:organizations_read | +| Webex Meeting Qualities | [Meeting Qualities](https://developer.webex.com/docs/api/v1/meeting-qualities/get-meeting-qualities) | cisco:webex:meeting:qualities | analytics:read_all | +| Webex Detailed Call History | [Detailed Call History](https://developer.webex.com/docs/api/v1/reports-detailed-call-history/get-detailed-call-history) | cisco:webex:call:detailed_history | spark-admin:calling_cdr_read | +| Webex Security Audit Events | [Security Audit Events](https://developer.webex.com/admin/docs/api/v1/security-audit-events/list-security-audit-events) | cisco:webex:security:audit:events | audit:events_read spark:organizations_read | \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..9b24b2a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +# Cisco Webex Add-on for Splunk + +| | | +|--------------------------|----------------------| +| Version | 1.3.0 | +| Vendor Products | Cisco Webex. | +| Splunk platform versions | 9.3.x, 9.4.x, 10.0.x | +| Platforms | Platform independent | \ No newline at end of file diff --git a/docs/static/splunk-logo-corporate.png b/docs/static/splunk-logo-corporate.png new file mode 100644 index 0000000..bae7246 Binary files /dev/null and b/docs/static/splunk-logo-corporate.png differ diff --git a/docs/static/splunk.png b/docs/static/splunk.png new file mode 100644 index 0000000..f63b827 Binary files /dev/null and b/docs/static/splunk.png differ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..51b0a66 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,62 @@ +site_name: Cisco Webex Add-on for Splunk +site_author: Splunk Community +remote_branch: gh-pages + +repo_name: Cisco Webex Add-on for Splunk +repo_url: "https://github.com/splunk/ta_cisco_webex_add_on_for_splunk" + +markdown_extensions: + - toc: + permalink: True + - smarty + - fenced_code + - sane_lists + - codehilite + - admonition + - pymdownx.details + - pymdownx.superfences + - attr_list + - md_in_html + +theme: + name: material + logo: "static/splunk-logo-corporate.png" + favicon: "static/splunk.png" + palette: + primary: "black" + accent: "orange" + +extra_css: + - stylesheets/styles.css + +validation: + omitted_files: warn + absolute_links: warn + unrecognized_links: warn +strict: true + +plugins: + - search + - print-site + +# copyright: 'Splunk Documentation covered by: Legal | Terms | Privacy
© Copyright 2024 Splunk Inc. All rights reserved.
Webpages built on GitHub Pages | GitHub Terms | GitHub Privacy' +copyright: 'This Add-On is developed and maintained by the Splunk Community.
Webpages built on GitHub Pages | GitHub Terms | GitHub Privacy' + +nav: + - Overview: + - Introduction: 'index.md' + - Sourcetypes: 'Sourcetypes/index.md' + - Installation: + - Install: 'Installation/index.md' + - Configuration: + - Configure Accounts: + - Prerequisites: 'ConfigureAccount/index.md' + - Configure Webex Account: 'ConfigureWebexAccount/index.md' + - Configure Inputs: + - Webex Generic Input : 'ConfigureGenericInput/index.md' + - Webex Scheduled Meetings Input : 'ConfigureScheduledMeetingsInput/index.md' + - Webex Meeting Summary Report Input : 'ConfigureMeetingSummaryReportInput/index.md' + - Webex Admin Audit Events Input : 'ConfigureAdminAuditEventInput/index.md' + - Webex Meeting Qualities Input : 'ConfigureMeetingQualitiesInput/index.md' + - Webex Detailed Call History Input : 'ConfigureDetailedCallHistoryInput/index.md' + - Webex Security Audit Event Input : 'ConfigureSecurityAuditEventInput/index.md' \ No newline at end of file diff --git a/package/README.md b/package/README.md index 75d791d..17d7a0b 100644 --- a/package/README.md +++ b/package/README.md @@ -220,7 +220,7 @@ The input uses checkpointing to avoid ingesting duplicate data. After the initia ## Versions Supported - - Tested for installation and basic ingestion on Splunk 9.X and 8.2 for **CentOS** system. + - Tested for installation and basic ingestion on Splunk 9.X and 8.2. > Built by Splunk's FDSE Team (#team-fdse).