From e5597ac32a67d331aa15f87f8161c85ecb8f6d60 Mon Sep 17 00:00:00 2001 From: splunk-soar-connectors-admin Date: Tue, 1 Aug 2023 12:33:01 -0700 Subject: [PATCH 1/7] 'convert readme.html to manual_readme_content.md' --- manual_readme_content.md | 330 +++++++++++++++++++++++++++++++++++++++ readme.html | 232 --------------------------- 2 files changed, 330 insertions(+), 232 deletions(-) create mode 100644 manual_readme_content.md delete mode 100644 readme.html diff --git a/manual_readme_content.md b/manual_readme_content.md new file mode 100644 index 0000000..25d2686 --- /dev/null +++ b/manual_readme_content.md @@ -0,0 +1,330 @@ +[comment]: # " File: README.md" +[comment]: # " Copyright (c) 2016-2023 Splunk Inc." +[comment]: # " Licensed under the Apache License, Version 2.0 (the 'License');" +[comment]: # " you may not use this file except in compliance with the License." +[comment]: # " You may obtain a copy of the License at" +[comment]: # "" +[comment]: # " http://www.apache.org/licenses/LICENSE-2.0" +[comment]: # " Unless required by applicable law or agreed to in writing, software distributed under" +[comment]: # " the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND," +[comment]: # " either express or implied. See the License for the specific language governing permissions" +[comment]: # " and limitations under the License." +[comment]: # "" +## JIRA + +This app uses the python JIRA module, which is licensed under the BSD License (BSD), Copyright (c) +2001-2022. Python Software Foundation + +## oauthlib + +This app uses the python oauthlib module, which is licensed under the OSI Approved, BSD License +(BSD), Copyright (c) 2001-2022. Python Software Foundation + +## pbr + +This app uses the python pbr module, which is licensed under the Apache Software License, Copyright +(c) 2001-2022. Python Software Foundation + +## PyJWT + +This app uses the python PyJWT module, which is licensed under the MIT License (MIT), Copyright (c) +2001-2022. Python Software Foundation + +## requests-oauthlib + +This app uses the python requests-oauthlib module, which is licensed under the BSD License (ISC), +Copyright (c) 2001-2022. Python Software Foundation + +## requests-toolbelt + +This app uses the python requests-toolbelt module, which is licensed under the Apache Software +License (Apache 2.0), Copyright (c) 2001-2022. Python Software Foundation + +## JIRA + +JIRA is a highly configurable ticketing system, and the actions performed by these API calls are +highly dependent on the process defined in each Jira instance. + +If your action fails, you may need to try an alternate method, or sequence, to perform the actions +desired for Jira to process them properly. One helpful debugging tool: simplify your action, instead +of filling out all the fields, attempt to make only one change at a time. + +Unfortunately, the JIRA API in most cases returns a generic error message with no valuable +information to assist in debugging. + +**Playbook Backward Compatibility** + +- The existing action parameters have been modified in the actions given below. Hence, it is + requested to the end-user to please update their existing playbooks by re-inserting the + corresponding action blocks or by providing appropriate values to these action parameters to + ensure the correct functioning of the playbooks created on the earlier versions of the app. + + + + - Add Watcher - The new \[user_account_id\] parameter has been added for the Jira cloud to add + a watcher into a provided issue. + - Remove Watcher - The new \[user_account_id\] parameter has been added for the Jira cloud to + remove a watcher from a provided issue. + - Create Ticket - The new \[assignee_account_id\] parameter has been added for the Jira cloud + to add the assignee while creating a Jira ticket. + - Lookup Users - Added a new action. This action will get a list of User resources that match + the specified search string. + - Add Comment - The new \[internal\] parameter has been added for comment that whether it + should be internal only or not in Jira Service Desk. This parameter is an optional Boolean + parameter. If the value is not provided for it, then it will be considered as a 'False' + value. + - Get Attachments - Added a new action. The action will store specific attachments from a + given Jira ticket inside the vault. + +**Authentication steps for JIRA Cloud** + +- Create an API token + + + + - Log in to [Click here.](https://id.atlassian.com/manage/api-tokens) + + - Click **Create an API token.** + + - From the dialog that appears, enter a unique and concise **Label** for your token and click + **Create** . + + - Click **Copy to clipboard** , then paste the token to your script, or elsewhere to save. + + + + Notes: + + - For security reasons it isn't possible to view the token after closing the creation dialog; + if necessary, create a new token. + + - You should store the token securely, just as for any password. + + + +- Use an API token + + + + - A primary use case for API tokens is to allow scripts to access REST APIs for Atlassian + Cloud applications using HTTP basic authentication. + - HTTP basic authentication would require a username and API token to access REST APIs for + Atlassian Cloud applications. + + + +**Authentication via Personal Access Token (PAT)** + +- [Click + here](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html#UsingPersonalAccessTokens-CreatingPATsinapplication) + for instructions to create PATs + + + + Personal Access Tokens are a safe alternative to using username and password for authentication + with various services in **Data Center and server editions** of the following applications: + + - Jira Core 8.14 and later + - Jira Software 8.14 and later + - Jira Service Management 4.15 and later + - Confluence 7.9 and later + + + +- Use a PAT + + + + - A primary use case for PATs is to use scripts and integrate external apps with your + Atlassian application by leveraging REST APIs upon Bearer Token Authorization. + - To use Bearer Token Authorization, configure your asset with PAT in the "Password" field and + leave "Username" blank. + +- Note: + + + + - For security reasons it isn't possible to view the token after closing the creation dialog; + if necessary, create a new token. + - For any invalid PAT value, the test_connectivity will pass as per the API behaviour. + + + +**The functioning of On Poll** + +- **NOTE (Consider below points due to a minute's granularity (instead of a second or lesser) for + querying tickets in the JIRA)** + + + + - It is highly recommended for configuring a significantly large value (larger than the number + of existing tickets on the user's instance) in the asset configuration parameter to bring + the ingested tickets in the Splunk SOAR in sync entirely with the JIRA instance in the first + run + - It is highly recommended for configuring a significantly large value (larger than the + possible number of tickets that can be updated in 1 minute or any value larger than the + average number of tickets getting created every unit of time (based on the frequency of + scheduled or interval polling)) in the asset configuration parameter to avoid the duplicate + tickets ingestion + + + +- The On Poll action works in 2 steps. In the first step, all the tickets (issues) in a defined + time duration will be fetched. In the second step, all the components (e.g. fields, comments, + and attachments) of the tickets (retrieved in the first step) will be fetched. A container will + be created for each ticket and for each ticket all the components will be created as the + respective artifacts. + +- The tickets will be fetched in the oldest first order based on the **updated** time in the On + Poll action + +- The updated timestamps of the components have been appended to the end of the artifact name to + maintain the uniqueness of a particular component + +- The timezone parameter in the asset configurations defines the timezone used to query the + tickets from the JIRA instance. If you do not find your exact timezone in the available list in + the dropdown, please select a timezone having the same time offset from the GMT timezone as + yours. Below are the details of setting the timezone parameter for on-prem and cloud JIRA + instances. + + + + 1. On-premise JIRA + - The timezone parameter here is the profile timezone of the JIRA instance + - For checking the profile timezone, navigate to the JIRA instance; navigate to the + profile settings; the value of the **Time Zone** parameter is the timezone that has to + be provided in the app asset configuration + 2. Cloud JIRA + - The timezone parameter here is the system settings timezone of the JIRA instance + - For checking the system settings timezone, navigate to the JIRA instance; navigate to + the option **Jira Settings --> System** in the settings page; the value of the **Default + user time zone** parameter is the timezone that has to be provided in the app asset + configuration + +- Users can provide the JSON formatted list of names of the custom fields (to be considered for + the ingestion) in the asset configuration parameter **custom_fields** e.g. \["Test \\"CF\\" 1", + "test_cf_2"\]. It's a valid JSON formatted list of strings, so the user should use escape + sequences whenever needed. Please find the below points for getting exact names for the custom + fields. + + + + 1. On-premise JIRA + - Navigate to the JIRA instance; navigate to the issues settings; navigate to the **Custom + fields** section under the **Fields** section; in the **Name** column, search for the + custom field that the user wants to be added in the asset configuration parameter + **custom_fields** + 2. Cloud JIRA + - The timezone parameter here is the system settings timezone of the JIRA instance + - For checking the system settings timezone, navigate to the JIRA instance; navigate to + the option **Jira Settings --> System** in the settings page; the value of the **Default + user time zone** parameter is the timezone that has to be provided in the app asset + configuration + +- If there is any error while fetching the custom fields metadata due to project configuration or + lack of permissions, then, the custom fields will be ignored and the ingestion based on the + system fields of the tickets (issues) will be executed successfully + + + + +- Two approaches for fetching tickets + + + + + - Manual polling + + + + - Fetch the tickets + + + + - The tickets will be fetched from the project mentioned in the **Project key to + ingest tickets (issues) from** app configuration parameter + - The tickets will be fetched in the oldest first order based on the **updated** time + and governed by the **container_count** parameter in the On Poll action + + - Fetch the components + + + + - Fetch all created or updated components (e.g. fields, comments, and attachments) for + each ticket (retrieved in the previous step) + + - Create containers for the tickets and artifacts for the fields, comments, and the + attachments + + - It is recommended to provide a sufficiently large value in the **container_count** + parameter for polling because manual polling does not remember the timestamp of last + fetched ticket and it starts polling from the beginning every time. Hence, if the user + runs the manual polling with e.g. 10 as the container count (the tickets are ingested + successfully), then, the user again runs the manual polling with the same value in the + container count; the app will fetch the same 10 tickets from the beginning and it will + display the message as 'duplicate artifacts found' because the same artifacts were + already ingested in the earlier manual polling run. + + + + - Scheduled Polling + + + + - Follows the same steps as manual polling with the below-mentioned points getting + considered + - The application will fetch the number of tickets governed by the **Maximum tickets + (issues) for scheduled polling** parameter (default: 100) in the On Poll action, whose + **updated** time is greater than or equal to one minute less than the time stored in the + **last_time** variable in the state file. The reason for reducing one minute from the + **last_time** is to ensure that no tickets created or updated on the same minute are not + getting skipped due to the granularity of Jira being 1 minute for the time-based + filtering of the tickets. + - If the **last_time** variable is not present in the state file i.e. the On Poll is + executing for the first time, the application will fetch the last **M** tickets ( **M:** + Value provided in the **Maximum tickets (issues) to poll first time** app configuration + parameter (default: 1000)) and then, from the next consecutive runs, it will fetch **N** + tickets ( **N:** Value provided in the **Maximum tickets (issues) for scheduled + polling** app configuration parameter (default: 100)). + - The last_time will be updated by the **updated** time of the last ticket which was + ingested + + + +**Some example caveats** + +- Attempting to set both Status and Resolution fails because the process set by the user doesn't + require a resolution to be set by the user, such as if there is only one resolution for a + particular status. +- Attempting to add a comment while setting Status may return success, however, the comment isn't + posted. In this case, when the status change is made via the Jira UI, no dialogue appears to + offer any additional input, therefore the API expects the same. +- The "simple" format for the update ticket may not work to add a comment, while the "update" + method does. +- Test connectivity may fail due to invalid credentials, such as accidentally using the user's + email address as the authentication login instead of the user's login name. +- While adding an attachment to the Jira ticket using 'Update ticket' action, if the filename + contains Unicode characters, the action is getting failed with the 500 Internal Server Error + because of the Jira SDK issue. Due to this, action behaves differently with the various Splunk + SOAR platforms. As a result, we have deployed the below-mentioned workflow which will ensure a + minimal change in the filename and minimal/no data loss. + 1. For the first time we try to add an attachment to the Jira ticket with the same name as the + filename, if it may get successful, then it will add an attachment with the same name + 2. But if it fails, then, we will check whether there are Unicode characters or not in the + filename, if it has, there are highly possible chances that Jira SDK might get throws an + exception due to these Unicode characters. + 3. And in such a case, we removed those non-ASCII Unicode characters from the filename and add + prefix FILENAME_ASCII to the filename. And, we again try to add an attachment with a newly + created name to the Jira ticket. + 4. If it passes, then it's okay and if it doesn't, then, there might be some other genuine + issue rather than the SDK issue and we fail the action by rethrowing the same error. + +## Port Information + +The app uses HTTP/ HTTPS protocol for communicating with the Jira server. Below are the default +ports used by the Splunk SOAR Connector. + +| SERVICE NAME | TRANSPORT PROTOCOL | PORT | +|--------------|--------------------|------| +| http | tcp | 80 | +| https | tcp | 443 | diff --git a/readme.html b/readme.html deleted file mode 100644 index 569c029..0000000 --- a/readme.html +++ /dev/null @@ -1,232 +0,0 @@ - - -

-

JIRA

- This app uses the python JIRA module, which is licensed under the BSD License (BSD), Copyright (c) 2001-2022. Python Software Foundation -

-

-

oauthlib

- This app uses the python oauthlib module, which is licensed under the OSI Approved, BSD License (BSD), Copyright (c) 2001-2022. Python Software Foundation -

-

-

pbr

- This app uses the python pbr module, which is licensed under the Apache Software License, Copyright (c) 2001-2022. Python Software Foundation -

-

-

PyJWT

- This app uses the python PyJWT module, which is licensed under the MIT License (MIT), Copyright (c) 2001-2022. Python Software Foundation -

-

-

requests-oauthlib

- This app uses the python requests-oauthlib module, which is licensed under the BSD License (ISC), Copyright (c) 2001-2022. Python Software Foundation -

-

-

requests-toolbelt

- This app uses the python requests-toolbelt module, which is licensed under the Apache Software License (Apache 2.0), Copyright (c) 2001-2022. Python Software Foundation -

- -

JIRA

- -

JIRA is a highly configurable ticketing system, and the actions performed by these API calls are highly dependent on the process defined in each Jira instance.

- -

If your action fails, you may need to try an alternate method, or sequence, to perform the actions desired for Jira to process them properly. -One helpful debugging tool: simplify your action, instead of filling out all the fields, attempt to make only one change at a time.

- -

Unfortunately, the JIRA API in most cases returns a generic error message with no valuable information to assist in debugging.

- -

Playbook Backward Compatibility -

-

- -

- Authentication steps for JIRA Cloud -

-

- -

- Authentication via Personal Access Token (PAT) -

-

- -

- The functioning of On Poll -

- -

- -

Some example caveats

- - -

Port Information

-

- The app uses HTTP/ HTTPS protocol for communicating with the Jira server. Below are the default ports used by the Splunk SOAR Connector. - - - - - - - - - - - - - - - - -
SERVICE NAMETRANSPORT PROTOCOLPORT
httptcp80
httpstcp443
-

From 411b3b4e483448016b24c22ff5034a0d588cdee5 Mon Sep 17 00:00:00 2001 From: splunk-jessica Date: Tue, 28 Nov 2023 13:44:44 -0800 Subject: [PATCH 2/7] PAPP-32450 Vault path bug fix --- jira_connector.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/jira_connector.py b/jira_connector.py index a16156c..2799100 100644 --- a/jira_connector.py +++ b/jira_connector.py @@ -31,6 +31,7 @@ from bs4 import BeautifulSoup, UnicodeDammit from dateutil.parser import parse from phantom.vault import Vault +from phantom_common import paths from jira.client import JIRA # THIS Connector imports @@ -1679,7 +1680,8 @@ def _handle_attachment(self, attachment, container_id, artifact_list, action_res if hasattr(Vault, 'get_vault_tmp_dir'): tmp = tempfile.NamedTemporaryFile(dir=Vault.get_vault_tmp_dir(), delete=False) else: - tmp = tempfile.NamedTemporaryFile(dir='/opt/phantom/vault/tmp/', delete=False) + local_dir = os.path.join(paths.PHANTOM_VAULT, "tmp") + tmp = tempfile.NamedTemporaryFile(dir=local_dir, delete=False) ret_val = self._download_file(attachment.content, tmp.name) From 74936bc6c09882247167c125687635cd220ff2cf Mon Sep 17 00:00:00 2001 From: root Date: Wed, 29 Nov 2023 12:44:02 -0800 Subject: [PATCH 3/7] Bumped up the version of jira from 3.6.0 to 3.6.1 --- jira.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jira.json b/jira.json index 2c24ecb..735420a 100644 --- a/jira.json +++ b/jira.json @@ -10,8 +10,8 @@ ], "type": "ticketing", "main_module": "jira_connector.py", - "app_version": "3.6.0", - "utctime_updated": "2022-02-04T03:00:20.000000Z", + "app_version": "3.6.1", + "utctime_updated": "2023-11-29T20:43:56.000000Z", "package_name": "phantom_jira", "product_vendor": "Atlassian", "product_name": "Jira", @@ -10747,4 +10747,4 @@ } ] } -} +} \ No newline at end of file From 2f247c5e8f0cbb26e3b9011ae8d621592054967f Mon Sep 17 00:00:00 2001 From: root Date: Wed, 29 Nov 2023 12:45:05 -0800 Subject: [PATCH 4/7] Release notes for version 3.6.1 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b94efd0..dcbc4a1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Jira Publisher: Splunk -Connector Version: 3.6.0 +Connector Version: 3.6.1 Product Vendor: Atlassian Product Name: Jira Product Version Supported (regex): ".\*" From 359d34f4fc256af71d9dab06a574727db6955b4f Mon Sep 17 00:00:00 2001 From: root Date: Wed, 29 Nov 2023 12:45:22 -0800 Subject: [PATCH 5/7] Release notes for version 3.6.1 From 1811122f1dd1cf226be513519b8399eba7142d8b Mon Sep 17 00:00:00 2001 From: splunk-jessica Date: Wed, 29 Nov 2023 13:18:28 -0800 Subject: [PATCH 6/7] add release notes --- release_notes/unreleased.md | 1 + 1 file changed, 1 insertion(+) diff --git a/release_notes/unreleased.md b/release_notes/unreleased.md index fbcb2fd..6d9b8b6 100644 --- a/release_notes/unreleased.md +++ b/release_notes/unreleased.md @@ -1 +1,2 @@ **Unreleased** +* Bug fix for accessing vault temp directory path [PAPP-32450] \ No newline at end of file From 9ba324ab05d25d9c3f93d52fa3f4ceb68fed69ab Mon Sep 17 00:00:00 2001 From: root Date: Wed, 29 Nov 2023 16:17:17 -0800 Subject: [PATCH 7/7] Release notes for version 3.6.1 --- release_notes/3.6.1.md | 1 + release_notes/unreleased.md | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 release_notes/3.6.1.md diff --git a/release_notes/3.6.1.md b/release_notes/3.6.1.md new file mode 100644 index 0000000..e91ab4f --- /dev/null +++ b/release_notes/3.6.1.md @@ -0,0 +1 @@ +* Bug fix for accessing vault temp directory path [PAPP-32450] \ No newline at end of file diff --git a/release_notes/unreleased.md b/release_notes/unreleased.md index 6d9b8b6..fbcb2fd 100644 --- a/release_notes/unreleased.md +++ b/release_notes/unreleased.md @@ -1,2 +1 @@ **Unreleased** -* Bug fix for accessing vault temp directory path [PAPP-32450] \ No newline at end of file