diff --git a/content-repo/extra-docs/articles/microsoft-auth-guide.md b/content-repo/extra-docs/articles/microsoft-auth-guide.md index 49007a117..955d8f013 100644 --- a/content-repo/extra-docs/articles/microsoft-auth-guide.md +++ b/content-repo/extra-docs/articles/microsoft-auth-guide.md @@ -76,13 +76,14 @@ Alternatively, instead of providing the *Client Secret*, you can authenticate us * Private Key - The private key of the registered certificate -### Authorize on Behalf of a User +### Authorization Code flow Some Cortex XSOAR-Microsoft integrations (e.g., Microsoft Graph Mail Single User) require authorization on behalf of a user (not admin consent). For more information about this authorization flow, refer to the [authorization code flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow). To configure a Microsoft integration that uses this authorization flow with a self-deployed Azure application: 1. Make sure the needed permissions are granted for the app registration, e.g., for Microsoft Graph User: API/Permission name `Directory.AccessAsUser.All` of type `Delegated`. -2. The Redirect URI can direct any web application that you wish to receive responses from Azure AD. If you are not sure what to set, you can use `https://localhost`. +2. In your app. click **Authentication** > **Platform configurations** > **Add a platform.** Choose **Web** and add [Redirect URI](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-a-redirect-uri). +The Redirect URI can direct any web application that you wish to receive responses from Azure AD. If you are not sure what to set, you can use `https://localhost`. 3. Enter your client ID in the *ID* parameter field. 4. Enter your client secret in the *Key* parameter field. 5. Enter your tenant ID in the *Token* parameter field. @@ -149,7 +150,7 @@ After you a redirected to the next page, in the **Overview** tab you will find y ![Overview](../../../docs/doc_imgs/tutorials/tut-microsoft-auth-guide/subscription_id_resourse_group.png) -## Self Deployed Application - Example +## Self Deployed Application - Example for [Microsoft Graph User integration](https://xsoar.pan.dev/docs/reference/integrations/microsoft-graph-user) 1. In Microsoft Azure portal, create a new app registration. 1. Select Azure Active Directory> App registrations> New registration. @@ -268,3 +269,5 @@ For example, when using the "self-deployed Azure app" for Microsoft Graph Mail S 2. Validate that all the credentials you entered are correct (Client ID, Client Secret, Tenant ID, Application redirect URI). 3. Run !msgraph-mail-generate-login-url to generate a new *Authorization code*. 4. Run !msgraph-mail-test to test the connectivity of the email. + +**Note**: If encountering an "Insufficient privileges to complete the operation" error, ensure the necessary permissions were added, according to the integration documentation. Subsequently, reset the authentication and initiate the authentication process again. \ No newline at end of file diff --git a/content-repo/extra-docs/articles/splunk-add-on.md b/content-repo/extra-docs/articles/splunk-add-on.md index 807acff59..5c2882e81 100644 --- a/content-repo/extra-docs/articles/splunk-add-on.md +++ b/content-repo/extra-docs/articles/splunk-add-on.md @@ -46,7 +46,7 @@ In order to use the add-on and create incidents in XSOAR, you must complete the * Additional Settings (optional): * If you have an SSL certificate, provide its full path under the **"Location to Certificate"** field. By default, **"Validate SSL"** is enabled. - * If you would like to extend the incident creatiin request timeout, provide the desired timeout under the "Timeout Value" field. + * If you would like to extend the incident creation request timeout, provide the desired timeout under the "Timeout Value" field. By default, timeout value is 10 seconds. ![splunk-add-on-config.png](../../../docs/doc_imgs/reference/splunk-add-on-config.png) diff --git a/content-repo/extra-docs/articles/troubleshooting.md b/content-repo/extra-docs/articles/troubleshooting.md index 04ef8d142..81b8ccb4c 100644 --- a/content-repo/extra-docs/articles/troubleshooting.md +++ b/content-repo/extra-docs/articles/troubleshooting.md @@ -231,6 +231,14 @@ For example for an integration instance name of: `Cortex_XDR_instance_1` run the !Cortex_XDR_instance_1-test-module debug-mode=true ``` +**Note:** +- If the instance name contains spaces, replace the space with an underscore (`_`). +- The "Do not use by default" checkbox should be unchecked on the integration instance you are testing. + +Screenshot of running a `test-module` command with `debug-mode=true` and the resulting log file (`test-module.log`): + +![test-module-debug](../../../docs/doc_imgs/reference/test-module-debug.png) + ### Fetch Incidents in `debug-mode` Starting with Cortex XSOAR 6.0 it is possible to run the fetch incidents command from the Cortex XSOAR CLI with `debug-mode=true`. This is done by issuing a command of the form: @@ -250,13 +258,6 @@ For example for an integration instance name of: `Cortex_XDR_instance_1` run the Screenshot of running a `fetch` command with `debug-mode=true` and the resulting log file (`fetch-incidents.log`): ![fetch-incidents-debug](../../../docs/doc_imgs/reference/fetch-incidents-debug.png) -**Note:** -- If the instance name contains spaces, replace the space with an underscore (`_`). -- The "Do not use by default" checkbox should be unchecked on the integration instance you are testing. - -Screenshot of running a `test-module` command with `debug-mode=true` and the resulting log file (`test-module.log`): - -![test-module-debug](../../../docs/doc_imgs/reference/test-module-debug.png) ## Integration Debug Logs :::caution Important Note diff --git a/content-repo/extra-docs/packs/content-management.md b/content-repo/extra-docs/packs/content-management.md index 644d3d921..c96bb9d3d 100644 --- a/content-repo/extra-docs/packs/content-management.md +++ b/content-repo/extra-docs/packs/content-management.md @@ -84,7 +84,7 @@ For general information about the CI/CD process, see [CI/CD FAQs](#cicd-faqs). | `config.yml` | The CI/CD configuration file (in the `.github\workflows` folder), which validates the content pack, creates an ID set, runs tests, etc. When you want to deploy your content, you need to update the file with your repository and whether you want to use an artifact server. For more information, see Configure the config.yml file in [Deployment](#deployment). | | `pre-commit` | Within the `.hooks` folder, the pre-commit file uses the Git rebase interactive tool for manual control of your history revision process. | | `.vscode` | Used when using VSC as your IDE. | - | `build_related_scripts` | Contains the CI/CD scripts. The `build_related_scripts/bucket_upload.py` script enables you to upload to Google Cloud Storage (artifact server). Before deploying your content, you need to update the name of the bucket list when uploading the Google Cloud Storage. For more information, see Configure the the bucket_upload.py file in [Deployment](#deployment).
**NOTE**: If using another storage application such AWS, you need to replace Google Cloud Storage. Contact Customer Support to assist with this.
The `get_modified_packs.py` script enables you to get the latest version of the content pack before merging. | + | `build_related_scripts` | Contains the CI/CD scripts. The `build_related_scripts/bucket_upload.py` script enables you to upload to Google Cloud Storage (artifact server) and the `build_related_scripts/bucket_upload_aws.py` script enables you to upload to AWS s3. Before deploying your content, you need to update the name of the bucket list when uploading the Google Cloud Storage. For more information, see Configure the the bucket_upload.py file in [Deployment](#deployment).
The `get_modified_packs.py` script enables you to get the latest version of the content pack before merging. | | `dev_envs/pytest`| A folder that contains the `conftest.py`, which validates python files. | | `.demisto-sdk-conf`| The custom configuration file for the `demisto-sdk` commands. For more information, see [Setting a preset custom command configuration](https://xsoar.pan.dev/docs/concepts/demisto-sdk#setting-a-preset-custom-command-configuration). | | `.gitignore` | Specifies intentionally untracked files that Git should ignore. | diff --git a/content-repo/extra-docs/packs/palo-alto-networks-cortex-xdr---investigation-and-response.md b/content-repo/extra-docs/packs/palo-alto-networks-cortex-xdr---investigation-and-response.md index d48ad905a..5ab286918 100644 --- a/content-repo/extra-docs/packs/palo-alto-networks-cortex-xdr---investigation-and-response.md +++ b/content-repo/extra-docs/packs/palo-alto-networks-cortex-xdr---investigation-and-response.md @@ -19,14 +19,32 @@ The playbooks included in this pack help you save time and keep your incidents i - Remediates the incident by blocking malicious indicators and isolating infected endpoints. The Palo Alto Networks Cortex XDR - Investigation and Response pack enables the following flows: +- [Lite Incident Handling](#lite-incident-handling) - A lite playbook for handling Palo Alto Networks Cortex XDR incidents, which encompasses incident enrichment, investigation, and response for each incident. - [Device Control Violations](#device-control-violations) - Fetch device control violations from XDR and communicate with the user to determine the reason the device was connected. - [XDR Incident Handling](#xdr-incident-handling) - Compare incidents in Palo Alto Networks Cortex XDR and Cortex XSOAR, and update the incidents appropriately. -- [AWS IAM User Access Investigation](#aws-iam-user-access-investigation) - Investigates and responds to Cortex XDR Cloud alerts where an AWS IAM user's access key is used suspiciously to access the cloud environment. +- [Cloud IAM User Access Investigation](#cloud-iam-user-access-investigation) - Investigates and responds to Cortex XDR Cloud alerts where an Cloud IAM user's access key is used suspiciously to access the cloud environment. - [Cortex XDR - Cloud Cryptomining](#Cortex_XDR_-_Cloud_Cryptomining) - Investigates and responds to Cortex XDR XCloud Cryptomining alerts. The playbook Supports AWS, Azure and GCP. +## Lite Incident Handling +This playbook is a lite default playbook to handle XDR incidents, and it doesn't require additional integrations to run. +The [Palo Alto Networks Cortex XDR - Investigation and Response](#palo-alto-networks-cortex-XDR---investigation-and-response) integration fetches Cortex XDR incidents and runs the [Cortex XDR Lite - Incident Handling](#cortex-xdr-lite---incident-handling) playbook. - +First, the playbook runs the ***xdr-get-incident-extra-data*** command to retrieve data fields of the specific incident including a list of alerts with multiple events, alerts, and key artifacts. + +Then, the playbook uses the [Entity Enrichment Generic v3](https://xsoar.pan.dev/docs/reference/playbooks/entity-enrichment---generic-v3) sub-playbook which takes all the entities in the incidents and enriches them with the available products in the environment. + +In the investigation phase, the playbook uses the [Command-Line Analysis](https://xsoar.pan.dev/docs/reference/playbooks/command-line-analysis) sub-playbook to analyze the command line if it exists to determine whether the command line usage was malicious or suspicious. + +The playbook also uses the [Cortex XDR - Get entity alerts by MITRE tactics](https://xsoar.pan.dev/docs/reference/playbooks/get-entity-alerts-by-mitre-tactics) sub-playbook to search for alerts related to the endpoint and to the username from Cortex XDR, on a given timeframe, based on MITRE tactics. + +Based on the enrichment and the investigation results, the playbook sets the verdict of the incident. Whether the incident verdict is not malicious, the analyst decides whether the incident verdict is malicious or benign. + +Whether the verdict is set to malicious by the playbook or by the analyst's decision the playbook will perform remediation actions by isolating the endpoint and blocking all the indicators that were extracted from the incident either manually or automatically using the [Block Indicators - Generic v3](https://xsoar.pan.dev/docs/reference/playbooks/block-indicators---generic-v3) sub-playbook. After the remediation stage, the playbook will close the incident. + +If the verdict is set to benign, the playbook will close the incident. + +As part of this playbook, you'll receive a comprehensive layout that presents incident details, analysis, investigation findings, and the final verdict. Additionally, the layout offers convenient remediation buttons for quicker manual actions. ## Device Control Violations If a user connects an unauthorized device to the corporate network, such as a USB dongle or a portable hard disk drive, the connection creates an event in Cortex XDR. @@ -44,7 +62,9 @@ All collected data is displayed in the XDR device control incident layout. ### XDR Incident Handling -The [Palo Alto Networks Cortex XDR - Investigation and Response](#palo-alto-networks-cortex-XDR---investigation-and-response) integration fetches Cortex XDR incidents and runs the [Cortex XDR incident handling v3](#cortex-xdr-incident-handling-v3) playbook. The playbook runs the ***xdr-get-incident-extra-data*** command to retrieve data fields of the specific incident including a list of alerts with multiple events, alerts, and key artifacts. +The [Palo Alto Networks Cortex XDR - Investigation and Response](#palo-alto-networks-cortex-XDR---investigation-and-response) integration fetches Cortex XDR incidents and runs the [Cortex XDR incident handling v3](#cortex-xdr-incident-handling-v3) playbook. This playbook will be triggered by fetching a Palo Alto Networks Cortex XDR incident, but only if the classifier is set to 'Cortex XDR - Classifier' and the incident type is left empty during the integration configuration. + +The playbook runs the ***xdr-get-incident-extra-data*** command to retrieve data fields of the specific incident including a list of alerts with multiple events, alerts, and key artifacts. The playbook then searches for similar incidents in Cortex XSOAR to link to the current incident. If a similar incident is found, the analyst will be asked whether to close the current incident as a duplicate since there is an older incident already being handled. The analyst will review the linked incident and decide if the incident should be resolved and closed as a duplicate incident. @@ -69,36 +89,28 @@ After the remediation, if there are no new alerts, the playbook stops the alert ### Syn Indicators between Cortex XSOAR and Cortex XDR The [Cortex XDR - IOCs](https://xsoar.pan.dev/docs/reference/integrations/cortex-xdr---ioc) feed integration syncs indicators between Cortex XSOAR and Cortex XDR. The integration syncs indicators according to the defined fetch interval. At each interval, the integration pushes new and modified indicators defined in the Sync Query from Cortex XSOAR to Cortex XDR. Additionally, the integration checks if there are manual modifications of indicators on Cortex XDR and syncs back to Cortex XSOAR. Once per day, the integration performs a complete sync which also removes indicators that have been deleted or expired in Cortex XSOAR, from Cortex XDR. -## AWS IAM User Access Investigation -The [AWS IAM user access investigation](https://xsoar.pan.dev/docs/reference/playbooks/cortex-xdr---aws-iam-user-access-investigation) playbook investigates and responds to Cortex XDR Cloud alerts where an AWS IAM user's access key is used suspiciously to access the cloud environment. +## Cloud IAM User Access Investigation +The [Cloud IAM user access investigation](https://xsoar.pan.dev/docs/reference/playbooks/cortex-xdr---cloud-iam-user-access-investigation) playbook investigates and responds to Cortex XDR Cloud alerts where an Cloud IAM user's access key is used suspiciously to access the cloud environment. The playbook fetches data from the incident and then retrieves additional cloud alert data that was not available in the incident. It then checks if the alerts are one of the following XCLOUD supported alerts: - Penetration testing tool attempt - Penetration testing tool activity -- Suspicious API call from a Tor exit node. +- Suspicious API call from a Tor exit node If the alert is not one of the supported alerts, the playbook ends. Otherwise, the incident type is set to XCLOUD and the playbook starts to collect additional information pertaining to the alert. First the source IP addresses are enriched. These are the IP addresses that are used to connect to the environment. -Then the playbook enriches information about the user who connected to the environment through the AWS IAM integration using the [AWS IAM - User enrichment](https://xsoar.pan.dev/docs/reference/playbooks/aws-iam---user-enrichment) sub-playbook. The sub-playbook lists the user access keys and retrieves information about the IAM user, including the user's creation date, path, unique ID, and ARN. From this, it can be seen if these user keys are active and the analyst can block these keys later in the investigation if they are causing malicious activities. - +Then the playbook enriches information about the user who connected to the environment through the relevant IAM integration using the [Cloud IAM Enrichment - Generic](https://xsoar.pan.dev/docs/reference/playbooks/cloud-iam-enrichment---generic) sub-playbook. The sub-playbook lists the user access keys and retrieves information about the IAM user, including the user's creation date, path, unique ID, and ARN. From this, it can be seen if these user keys are active and the analyst can block these keys later in the investigation if they are causing malicious activities. -Then the playbook validates that the access key type is AKIA (which marks this as a user key). If the access key is AKIA, queries are run to retrieve the last 100 API calls made with the access key and retrieve actions performed by the user in the last 7 days. This information shows who made the call, and provides information about the IP address and data about which user was used in the request, what operation was performed, the status of the operation and on what resource it was executed. - -Now the investigation starts. -First the playbook checks if there were new IP addresses that were found on the XQL queries that did not appear in the original alert and enriches them. -Then the analyst manually reviews the results of the XQL queries from the previous steps to determine if this is a true positive event. The analyst investigates the operations performed by the access key and the user. The analyst examines the executed operations, by who it was executed, on which resource, and the operation status. +Based on the enrichment and the analysis results, the playbooks sets the verdict of the incident. If malicious indicators are found, the playbook takes action using [Cloud Response - Generic](https://xsoar.pan.dev/docs/reference/playbooks/cloud-response---generic) sub-playbook. +If the verdict not determined, it lets the analyst decide whether to continue to the remediation stage or close the investigation. The analyst looks at any persistence, for example, a new user or key creation or for any lateral movement operations. For example, an operation can be = AsumeRole. As an extra validation step, it is recommended to query the user and/or the user’s manager regarding the investigated suspicious activity. Based on this investigation, the analyst manually decides if the alert is a false or true positive. If false, the playbook ends. -Otherwise the remediation steps begin -The IP address is checked to see if it is a Tor IP. If it is not a Tor IP, the IP is blocked (either manually or automatically) and the analyst can tag the indicator for EDL. -The compromised IAM access keys are deactivated. -The analyst manually checks if the user has an AWS login profile and deletes it. ## Cortex XDR - Cloud Cryptomining @@ -394,6 +406,14 @@ The collected data generates a CSV report, including a detailed list of the disc The report will be sent to email addresses provided in the playbook input. The playbook includes an incident type with a dedicated layout to visualize the collected data. +#### [Cortex XDR Lite - Incident Handling](https://xsoar.pan.dev/docs/reference/playbooks/cortex-xdr-lite---incident-handling) +This playbook is a lite default playbook to handle XDR incidents, and it doesn't require additional integrations to run. +The playbook is triggered by fetching a Palo Alto Networks Cortex XDR incident. +First, The playbook performs enrichment on the incident’s indicators. +Then, the playbook performs investigation and analysis on the command line and search for related Cortex XDR alerts by Mitre tactics to identify malicious activity performed on the endpoint and by the user. +Based on the enrichment and the investigation results, the playbooks sets the verdict of the incident. If malicious indicators are found, the playbook takes action to block these indicators and isolate the affected endpoint to prevent further damage or the spread of threats. +If the verdict not determined, it lets the analyst decide whether to continue to the remediation stage or close the investigation as benign. +As part of this playbook, you'll receive a comprehensive layout that presents incident details, analysis, investigation findings, and the final verdict. Additionally, the layout offers convenient remediation buttons for quicker manual actions. #### [Cortex XDR Incident Handling](https://xsoar.pan.dev/docs/reference/playbooks/cortex-xdr-incident-handling) This playbook is triggered by fetching a Palo Alto Networks Cortex XDR incident. @@ -409,7 +429,7 @@ Based on the severity, it lets the analyst decide whether to continue to the rem After the remediation, if there are no new alerts, the playbook stops the alert sync and closes the XDR incident and investigation. #### [Cortex XDR incident handling v3](https://xsoar.pan.dev/docs/reference/playbooks/cortex-xdr-incident-handling-v3) -This playbook is triggered by fetching a Palo Alto Networks Cortex XDR incident. +This playbook is triggered by fetching a Palo Alto Networks Cortex XDR incident, but only if the classifier is set to 'Cortex XDR - Classifier' and the incident type is left empty during the integration configuration. The playbook syncs and updates new XDR alerts that construct the incident and triggers a sub-playbook to handle each alert by type. Then, the playbook performs enrichment on the incident’s indicators and hunts for related IOCs. Based on the severity, it lets the analyst decide whether to continue to the remediation stage or close the investigation as a false positive. @@ -442,11 +462,10 @@ Executes specified shell commands. Kills the specified process. +#### [Cortex XDR - Cloud IAM user access investigation](https://xsoar.pan.dev/docs/reference/playbooks/cloud-iam-user-access-investigation) +Investigates and responds to Cortex XDR Cloud alerts where an Cloud IAM user`s access key is used suspiciously to access the cloud environment. -#### [Cortex XDR - AWS IAM user access investigation](https://xsoar.pan.dev/docs/reference/playbooks/cortex-xdr---aws-iam-user-access-investigation) -Investigates and responds to Cortex XDR Cloud alerts where an AWS IAM user`s access key is used suspiciously to access the cloud environment. - -The following alerts are supported for AWS environments: +The following alerts are supported for all cloud environments: - Penetration testing tool attempt - Penetration testing tool activity - Suspicious API call from a Tor exit node diff --git a/content-repo/extra-docs/releases/22.2.0.md b/content-repo/extra-docs/releases/22.2.0.md index d4a9f0690..bd31208b8 100644 --- a/content-repo/extra-docs/releases/22.2.0.md +++ b/content-repo/extra-docs/releases/22.2.0.md @@ -160,7 +160,6 @@ Maps incoming Trend Micro Vision One alerts. Trend Micro Vision One is a threat defense platform that provides added value and new benefits beyond XDR solutions, allowing you to see more and respond faster. It provides deep and broad extended detection and response (XDR) capabilities that collect and automatically correlate data across multiple security layers—email, endpoints, servers, cloud workloads, and networks. Trend Micro Vision One prevents the majority of attacks with automated protection. #### Layouts **Trend Micro Vision One XDR Incident** -(Available from Cortex XSOAR 6.2.0) --- diff --git a/docs/doc_imgs/integrations/Screenshot-long-encrypted.png b/docs/doc_imgs/integrations/Screenshot-long-encrypted.png new file mode 100644 index 000000000..9cfabb8b1 Binary files /dev/null and b/docs/doc_imgs/integrations/Screenshot-long-encrypted.png differ diff --git a/docs/doc_imgs/integrations/fetch-incidents.png b/docs/doc_imgs/integrations/fetch-incidents.png new file mode 100644 index 000000000..78ab95d23 Binary files /dev/null and b/docs/doc_imgs/integrations/fetch-incidents.png differ diff --git a/docs/documentation/images_in_documentation_files.md b/docs/documentation/images_in_documentation_files.md new file mode 100644 index 000000000..cf4798cd9 --- /dev/null +++ b/docs/documentation/images_in_documentation_files.md @@ -0,0 +1,88 @@ +--- +id: images_in_documentation_files +title: Images in Documentation Files +--- + + + +Images in documentation markdown files are divided into 2 different types: +- Images that appear in integration/script/playbook readmes. These images only appear in https://xsoar.pan.dev/. They do not appear in the Cortex XSOAR/XSIAM product UI. +- Images that appear in pack readmes and integration description files. These images appear in both https://xsoar.pan.dev/ and in the Cortex XSOAR/XSIAM product UI. + +## Integration/Script/Playbook Readme Images + +When creating markdown `README` documents for playbooks, integrations, or scripts that appear in https://xsoar.pan.dev/ only, you can use a relative or absolute URL. + +### Relative Image URLs for Integration/Script/Playbook Readmes +You can use relative URLs to documentation images stored in the `doc_files` or `doc_imgs` directories. To use relative URLs simply link the image using a relative path such as: +``` +![Setup Account](./../../doc_files/create-account.png) +``` + +Make sure to view the `README.md` file in GitHub's web interface and validate that the images display properly. + +**Documentation with Relative URL examples:** +* Google Calendar: https://github.com/demisto/content/blob/master/Packs/GoogleCalendar/Integrations/GoogleCalendar/README.md +* G Suite Admin: https://github.com/demisto/content/blob/master/Packs/GSuiteAdmin/Integrations/GSuiteAdmin/README.md + +### Absolute Image URLs for Integration/Script/Playbook Readmes + +To obtain an absolute URL to an image from GitHub: + +* Commit the image and push to GitHub. +* View the file in the GitHub web interface. +* Copy the URL from the `Download` button. +* Make sure the URL you are copying is not referring to a branch which will be deleted after the PR is merged. The URL should refer to a commit hash or the `master` branch. +* Note: if you click the `Download` button, GitHub will perform a redirect and the url in the browser will point to the domain: `raw.githubusercontent.com`. You may also use this URL as the absolute URL. + + +Embed the image in the README.md using a Markdown Image Link, such as: +``` +![Playbook Image](https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png) +``` +If you want more control on the image (for example setting width dimension) you can use the HTML `` tag, such as: + +``` + +``` +**Screenshot of `Download` button:** +![Github Download](/doc_imgs/integrations/github-download-button.png) + +**Absolute Image URL Examples:** +* URL to commit hash: https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png +* URL to `master` branch: https://github.com/demisto/content/raw/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png +* URL after redirection (also valid): https://raw.githubusercontent.com/demisto/content/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png + +:::note +To keep our main Content repo small we limit images to 2MB. For larger images, follow the instructions for [Videos](#videos) on how to store large media files in our [content-assets](https://github.com/demisto/content-assets) repository. +::: + +## Pack Readmes and Integration Description Files Images + +When creating a markdown pack `README` or an integration description file for XSOAR/XSIAM entities you must use an absolute URL. + +To obtain an absolute URL to an image from GitHub: + +* Commit the image and push to GitHub. +* View the file in the GitHub web interface. +* Copy the URL from the `Download` button. +* Make sure the URL you are copying is not referring to a branch which will be deleted after the PR is merged. The URL should refer to a commit hash or the `master` branch. +* Note: if you click the `Download` button, GitHub will perform a redirect and the url in the browser will point to the domain: `raw.githubusercontent.com`. You may also use this URL as the absolute URL. + + +Embed the image in the README.md using a Markdown Image Link, such as: +``` +![Playbook Image](https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png) +``` + +**Screenshot of `Download` button:** +![Github Download](/doc_imgs/integrations/github-download-button.png) + +**Absolute Image URL Examples:** +* URL to commit hash: https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png +* URL to `master` branch: https://github.com/demisto/content/raw/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png +* URL after redirection (also valid): https://raw.githubusercontent.com/demisto/content/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png + +:::note +To keep our main Content repo small we limit images to 2MB. For larger images, follow the instructions for [Videos](#videos) on how to store large media files in our [content-assets](https://github.com/demisto/content-assets) repository. +::: \ No newline at end of file diff --git a/docs/documentation/integration-description.md b/docs/documentation/integration-description.md index 044dc3fd7..af27454d5 100644 --- a/docs/documentation/integration-description.md +++ b/docs/documentation/integration-description.md @@ -34,6 +34,10 @@ The file's content can include troubleshooting tips and advanced details for dif This should not be confused with the integration README file, documented [here](../documentation/readme_file). ::: +## Images +Images can be added to your documentation files. For information, see [Images in Documentation Files](https://xsoar.pan.dev/docs/documentation/images_in_documentation_files). + + ## Example This is the contents of the `HelloWorld_description.md` file: ``` @@ -56,3 +60,14 @@ The content of the description file will be displayed: Starting from version 6.1, the content of the description file is shown on the side of the configuration data: ![](/doc_imgs/integrations/integration-config-panel-61.png) + +### Support Level Header YML metadata key +The `supportlevelheader` key can be set to one of the following values to set the `support level header` in the content description. +* `xsoar` - The description would specify that PANW supports this integration. +* `partner` - The description would specify that this integration is partner supported and list the partner's contact information. +* `community` - The description would specify that this integration is community supported or list the pack's author. + +#### How To Set the Support Level Header YML metadata key +Open the yml of the integration in the same folder where the description file is located and add the `supportlevelheader` key with one of the `xsoar/partner/community` values. + +If this key is not set in the integration's yml, the support level header is set to the `support` key in the `pack_metadata.json`. \ No newline at end of file diff --git a/docs/documentation/readme_file.md b/docs/documentation/readme_file.md index c38acdc26..a9200d6e9 100644 --- a/docs/documentation/readme_file.md +++ b/docs/documentation/readme_file.md @@ -60,59 +60,14 @@ demisto-sdk generate-docs -i Packs/Nmap/Integrations/NmapV2/NmapV2.yml --old-ver Though not advised, if you do not wish to create the version differences section in the documentation you can run the command with the `--skip-breaking-changes` flag. ## Images -Images in the documentation should be added to the relevant pack under a `doc_files` or `doc_imgs` directory. Images may be included with **absolute** or **relative** URLs. - -### Relative Image URLs -When creating Markdown `README` documents for XSOAR entities (Playbooks, Integrations, Scripts, etc.), you may use relative URLs to documentation images stored in the `doc_files` or `doc_imgs` directories. To use relative URLs simply link the image using a relative path such as: -``` -![Setup Account](./../../doc_files/create-account.png) -``` - -Make sure to view the `README.md` file in GitHub's web interface and validate that the images display properly. - -**Note**: Relative image URLs are not supported for [Pack `README`s](https://xsoar.pan.dev/docs/documentation/pack-docs). - -**Documentation with Relative URL examples:** -* Google Calendar: https://github.com/demisto/content/blob/master/Packs/GoogleCalendar/Integrations/GoogleCalendar/README.md -* G Suite Admin: https://github.com/demisto/content/blob/master/Packs/GSuiteAdmin/Integrations/GSuiteAdmin/README.md - -### Absolute Image URLs -To obtain an absolute URL to an image from GitHub: - -* Commit the image and push to GitHub. -* View the file in the GitHub web interface. -* Copy the URL from the `Download` button. -* Make sure the URL you are copying is not referring to a branch which will be deleted after the PR is merged. The URL should refer to a commit hash or the `master` branch. -* Note: if you click the `Download` button, GitHub will perform a redirect and the url in the browser will point to the domain: `raw.githubusercontent.com`. You may also use this URL as the absolute URL. - - -Embed the image in the README.md using a Markdown Image Link, such as: -``` -![Playbook Image](https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png) -``` -Or if you want more control on the image (for example setting width dimension) you can use the HTML `` tag, such as: - -``` - -``` -**Screenshot of `Download` button:** -![Github Download](/doc_imgs/integrations/github-download-button.png) - -**Absolute Image URL Examples:** -* URL to commit hash: https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png -* URL to `master` branch: https://github.com/demisto/content/raw/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png -* URL after redirection (also valid): https://raw.githubusercontent.com/demisto/content/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png - -:::note -To keep our main Content repo small we limit images to 2MB. For larger images, follow the instructions for [Videos](#videos) on how to store large media files in our [content-assets](https://github.com/demisto/content-assets) repository. -::: +Images can be added to your documentation files. For information, see [Images in Documentation Files](https://xsoar.pan.dev/docs/documentation/images_in_documentation_files). ## Videos A video can provide a great addition to the documentation either as a demo video or tutorial. The preferred video format is `mp4`. ### Videos Stored in GitHub -Because of their size and in order to keep our main Content repo small, we store large media files in a separate repository: [content-assets](https://github.com/demisto/content-assets). +Because of their size and in order to keep our main Content repo small, we store large media files in a separate repository: "documentation/images_in_documentation_files". To add the video file, open a pull request with the video file at [content-assets](https://github.com/demisto/content-assets/pulls) repository. The file should be placed in the directory: `Assets//`. diff --git a/docs/integrations/code-conventions.md b/docs/integrations/code-conventions.md index 62207fb61..a16ae70ad 100644 --- a/docs/integrations/code-conventions.md +++ b/docs/integrations/code-conventions.md @@ -1029,7 +1029,7 @@ demisto.results( { 'Type': EntryType.NOTE, 'ContentsFormat': EntryFormat.TEXT, - 'Content': res, + 'Contents': res, 'HumanReadable': 'Submitted file is being analyzed.', 'ReadableContentsFormat': EntryFormat.MARKDOWN, 'EntryContext': entry_context, diff --git a/docs/integrations/collectors.md b/docs/integrations/collectors.md index 867f0109e..488af356d 100644 --- a/docs/integrations/collectors.md +++ b/docs/integrations/collectors.md @@ -30,7 +30,7 @@ marketplaces: ## Commands Every Collection integration will at minimum support these three commands: - `test-module` - this is the command that is run when the `Test` button in the configuration panel of an integration is clicked. -- `-get-events` - where `` is replaced by the name of the Product or Vendor source providing the events. So for example, if you were developing a Collection integration for Microsoft Intune, this command might be called `msintune-get-indicators`. This command should fetch a limited number of events from the external source and display them in the war room. +- `-get-events` - where `` is replaced by the name of the Product or Vendor source providing the events. So for example, if you were developing a Collection integration for Microsoft Intune, this command might be called `msintune-get-events`. This command should fetch a limited number of events from the external source and display them in the war room. - `fetch-events` - this command will initiate a request to the external product chosen endpoint(s) using the relevant chosen params, and send the fetched events to the XSIAM database. If the integration instance is configured to `Fetch evnts`, then this is the command that will be executed at the specified `Events Fetch Interval`. ## API Command: send_events_to_xsiam() @@ -67,6 +67,7 @@ def main(): Notice: - You should always path the `events` to the `send_events_to_xsiam()` function, also in cases when no events were fetched. This is important as the `send_events_to_xsiam()` function also updates the UI for the number of events fetched which could also be 0. Don't be troubled, in such cases the empty data will not be sent forward to the DataBase. - In the given example we assume the events are **not** in a `cef` or `leef` formats and therefore the `data_format` argument is not used. +- `send_events_to_xsiam()` function will work only if the integration is a system integration. The function will fail if it will be called from a custom integration. Fore more info on the `send_events_to_xsiam()` function visit the [API reference](https://xsoar.pan.dev/docs/reference/api/common-server-python#send_events_to_xsiam). diff --git a/docs/integrations/fetching-incidents.md b/docs/integrations/fetching-incidents.md index de89ec7c6..62e2d2582 100644 --- a/docs/integrations/fetching-incidents.md +++ b/docs/integrations/fetching-incidents.md @@ -12,9 +12,11 @@ This topic provides: - Troubleshooting tips ## fetch-incidents Command -The ***fetch-incidents*** command is the function that Cortex XSOAR calls every minute to import new incidents. It is triggered by the *Fetches incidents* parameter in the integration configuration. It is not necessary to configure the ***fetch-incidents*** command in the integration settings. +The ***fetch-incidents*** command is the function that Cortex XSOAR calls to import new incidents. It is triggered by the *Fetches incidents* parameter in the integration configuration. It is not necessary to configure the ***fetch-incidents*** command in the integration settings. -![screen shot 2019-01-07 at 15 35 01](/doc_imgs/integrations/50771147-6aedb800-1292-11e9-833f-b5dd13e3507b.png) +When you select the *Fetch incidents* parameter in the integration configuration, you should also configure the *incidentFetchInterval* parameter (displayed as *Incidents Fetch Interval* in the integration configuration window). This controls how often the integration will perform a ***fetch_incidents*** command. The default is 1 minute. + +![screen shot 2023-09-20](/doc_imgs/integrations/fetch-incidents.png) Open the ***fetch-incidents*** command. Make sure the command is also referenced in the execution block. @@ -28,6 +30,9 @@ if demisto.command() == 'fetch-incidents': ``` + + + ## Last Run The *demisto.getLastRun()* function retrieves the last previous run time. This helps avoid duplicate incidents by fetching only events that occurred since the last time the function was run. diff --git a/docs/integrations/parameter-types.md b/docs/integrations/parameter-types.md index 88df48802..f71f97beb 100644 --- a/docs/integrations/parameter-types.md +++ b/docs/integrations/parameter-types.md @@ -12,7 +12,7 @@ See [here](https://xsoar.pan.dev/docs/integrations/yaml-file#configuration) for This type of parameter creates a checkbox in the integration configuration. When the checkbox is ticked, the value in the integration code is `True`, and `False` otherwise. -The type number is: 0. +The type number is: 8. ![image](/doc_imgs/integrations/54881985-48654700-4e5e-11e9-8e1c-7a95d1b84328.png) @@ -24,7 +24,7 @@ Access: `demisto.params().get('proxy')` This type of parameter is used for short input parameters, such as server URLs, ports or queries. It creates a small sized text box in the integration configuration. -The type number is: 8. +The type number is: 0. ![image](/doc_imgs/integrations/54881995-616df800-4e5e-11e9-8f15-475422b97066.png) @@ -44,7 +44,7 @@ The type number is: 12. Access: `demisto.params().get('cert')` -## Encrypted +## Short Encrypted This type of parameter is used for encrypted inputs, such as API tokens. This should not be used for username-password credentials however. It creates a small sized text box with an encrypted text, which would also be stored encrypted in @@ -57,6 +57,17 @@ The type number is: 4. Access: `demisto.params().get('token')` +## Long Encrypted + +This type of parameter is used for long encrypted inputs, such as certificates. +It creates a text-area with encrypted text. The text would also be stored encrypted in +the database. +The type number is: 14. + +![image](/doc_imgs/integrations/Screenshot-long-encrypted.png) + +Access: `demisto.params().get('cert')` + ## Authentication This type of parameter is used for username-password credentials - username as plain text and an encrypted password. diff --git a/docs/integrations/scheduled-commands.md b/docs/integrations/scheduled-commands.md index 4624244e9..d821f7803 100644 --- a/docs/integrations/scheduled-commands.md +++ b/docs/integrations/scheduled-commands.md @@ -3,8 +3,6 @@ id: scheduled-commands title: Scheduled Commands --- -### Available from Cortex XSOAR version 6.2.0 and later. - A command can schedule the future execution of another command. diff --git a/docs/playbooks/generic-polling.md b/docs/playbooks/generic-polling.md index a0a4ef13f..42be36a23 100644 --- a/docs/playbooks/generic-polling.md +++ b/docs/playbooks/generic-polling.md @@ -7,7 +7,7 @@ In some cases, when working with 3rd party software (detonation, scan, search, e Due to hardware limitations, you can not achieve this via integrations or automations. The `GenericPolling` playbook, however, enables you to pause a playbook and resume execution after a remote host finishes a process. -* Starting in Cortex XSOAR version 6.2.0, you can implement polling in integrations and automations via [Scheduled Commands](./../integrations/scheduled-commands). +* You can implement polling in integrations and automations via [Scheduled Commands](./../integrations/scheduled-commands). ## What it does The playbook periodically polls the status of a process being executed on a remote host. When the host returns that the process execution is done, the playbook finishes execution. diff --git a/docs/playbooks/playbook-conventions.md b/docs/playbooks/playbook-conventions.md index 72931c5fe..4391edf7c 100644 --- a/docs/playbooks/playbook-conventions.md +++ b/docs/playbooks/playbook-conventions.md @@ -8,6 +8,11 @@ To keep playbook consistency, usability and readability, we've created some conv ## Wording ### Playbooks - Names are **T**itle **C**ase. + - The playbook name cannot contain the following special characters: + + Punctuation marks: ! " # $ % & ' ( ) * + , . / : ; < = > ? @ [ \ ] ^ ` { | } ~ + Symbols: © ® ™ ° µ ± ß + Formatting characters: ¶ § - Before specifying whether the playbook is generic or of a certain integration, add a dash (-). - Before adding "Test", add a (dash), but add it only at the very end of the name diff --git a/sidebars.js b/sidebars.js index 19863b302..aa8c8a6b1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -60,7 +60,8 @@ const sidebars = { "contributing/docs-contrib", "contributing/marketplace", "contributing/demo-prep", - "contributing/sla" + "contributing/sla", + "contributing/sdk" ] }, { @@ -224,8 +225,9 @@ const sidebars = { "documentation/pack-docs", "documentation/release-notes", "documentation/readme_file", - "documentation/integration-description" - ] + "documentation/integration-description", + "documentation/images_in_documentation_files" + ] }, { type: "category",