demisto / content-docs Goto Github PK

Describe the problem

• Page: AutoFocus Feed
• Source: https://github.com/demisto/content/blob/master//Packs/FeedAutofocus/Integrations/FeedAutofocus/README.md

The explanation in the video about the Autofocus "Samples Search" is not accurate. It instructs the users to click on:

_ API

However, the correct/easiest way to grab the JSON query is to click on the "Export Search" button.

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

It would be nice if you could edit the video and at least modify the voice over to provide the right instructions

Describe the problem

The various pages show inconsistent size limits for the integration logo (4KB vs 10KB).

Pages affected:

• https://xsoar.pan.dev/docs/integrations/integration-logo (4KB + 10KB)
• https://xsoar.pan.dev/docs/concepts/design-best-practices (10KB)
  https://xsoar.pan.dev/docs/tutorials/tut-integration-ui#integration-settings (4KB)

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Settle on a single size limit.

Describe the problem

There are typos in https://xsoar.pan.dev/docs/integrations/code-conventions#commandresults.

results = CommandResults(
    outputs='VirusTotal.IP',
    outputs_key_field='Address',
    outputs={
        'Address': '8.8.8.8',
        'ASN': 12345
    }
)
return_results(results)

It is not possible to set the same keyword argument(outputs).
Apparently, the first outputs is a typo of outputs_prefix.

Screenshots

Environment

• OS: macOS
• Browser: Chrome
• Browser Version: Version 83.0.4103.116 (Official Build) (64-bit)

Suggested fix

Replace outputs with outputs_prefix.

Describe the problem

• Page: CrowdStrike Falcon
• Source: https://github.com/demisto/content/blob/master//Packs/CrowdStrikeFalcon/Integrations/CrowdStrikeFalcon/README.md

Screenshots

Suggested fix

Need new lines in the section that is in the image above
also it is not clear what this section is trying to say

Describe the problem

• Page: AssignAnalystToIncident
• Source: https://github.com/demisto/content/blob/master//Packs/CommonScripts/Scripts/script-AssignAnalystToIncident_README.md

Documentation is not complete : the onCall parameter is not explained

Screenshots

Environment

• OS: any
• Browser: any
• Browser Version: any

Suggested fix

Write the documentation :)

On the deployment of #22 @mchasepan sees this on his system:

It should show "Automate the future"
"with Demisto". Also the links on top should not return carriage.

@sserrata @csestito could you please have a look?

Thanks!

Describe the problem

• Page: SetMultipleValues
• Source: https://github.com/demisto/content/blob/master//Packs/CommonScripts/Scripts/script-SetMultipleValues_README.md

Customer mentioned they would like a simple example of this script and the purpose of it.

Suggested fix

Here's what I provided them:

!SetMultipleValues parent=test_parent keys=key1,key2,key3 values=val1,valu2,val3

Describe the problem

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Describe the problem

• Page: Microsoft Graph Security
• Source: https://github.com/demisto/content/blob/master//Packs/MicrosoftGraphSecurity/Integrations/MicrosoftGraphSecurity/README.md

Directory.ReadWrite.All application permission for Microsoft Graph basically grants the application "God Mode" privileges on Azure AD and this certainly should not be needed, or if it is needed there should be really good justification as to why it is needed and other lesser privileged permissions can't be utilized instead to follow a least privileged model.

User.ReadWrite.All is also problematic here, unless there is a good reason for it.

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Update the docs to illustrate why these permissions are needed, or implement a new set of permissions to better follow a least privilege model.

Describe the problem

Link to partner-owned integration is wrong in https://xsoar.pan.dev/docs/partners/development-partners#how-it-works #5 -

Suggested fix

It should be: https://xsoar.pan.dev/docs/partners/partner-owned-integration

Describe the problem

• Page: Create a Conditional Task
• Source: https://github.com/demisto/content-docs/tree/master/docs/playbooks/playbooks-create-conditional-task.md

Typo in the very last link on the page: "Playboook"

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Describe the problem

Video is not starting

Buttons (i.e. Sign Up Now and Download the partnership agreement) are not displayed in the rendered file. They are displayed in the v1 website (https://demisto.developers.paloaltonetworks.com/docs/en/get-started)

Describe the problem

• Page: PhishingDemo-Onboarding
• Source: https://github.com/demisto/content/blob/master//Packs/OnboardingIntegration/Playbooks/playbook-PhishingDemo-Onboarding_README.md

The description paragraph is saying "For more information, refer to the on-boarding walkthroughs in the help section."
however, there is no help section with walkthrough available.

Screenshots

Suggested fix

Either delete this line or link for the help section (it's not on the product as well)

Thank you for taking the time to help us improve our documentation! Please describe the problem and a suggested fix below and we'll get back to you as soon as we can. --DevRel

Describe the problem

The "Architecture Basics" links are broken.

Suggested fix

Current URL: https://demisto-content-docs.netlify.com/docs/en/dev-architecture
Suggested URL: https://demisto-content-docs.netlify.com/docs/dev-architecture

Describe the problem

Did a quick web crawl to get all the links in https://demisto.pan.dev/docs/welcome, and checked them to see if any were broken, will try to update this output to find the pages these links are located at:

• https://demisto.pan.dev/docs/partners/why-demisto 404
• https://demisto.pan.dev/Tests/scripts/hook_validations/integration.py 404
• https://github.com/demisto/demisto-sdk/blob/master/demisto_sdk/commands/init/init_command.md 404
• https://demisto.pan.dev/Integrations/Kafka_V2/Kafka_V2.yml 404
• https://xsoar.pan.dev/docs/reference 404
• https://demisto.pan.dev/docs/howtos/integrations/packs-format 404
• https://demisto.pan.dev/docs/howtos/integrations/testing 404
• https://github.com/demisto/demisto-sdk/blob/master/docs/validate_command.md 404
• https://github.com/demisto/demisto-sdk/blob/master/docs/lint_command.md 404
• https://demisto.pan.dev/docs/.hooks/bootstrap 404
• https://demisto.pan.dev/docs/dev-requirements-py2.txt 404
• https://demisto.pan.dev/docs/dev-requirements-py3.txt 404
• https://demisto.pan.dev/docs/Tests/scripts/hook_validations/integration.py 404
• https://github.com/demisto/content/blob/master/Integrations/Slack/README.md 404

Screenshots

Suggested fix

Update or remove links

Describe the problem

• Page: Azure Sentinel (Beta)
• Source: https://github.com/demisto/content/blob/master//Packs/AzureSentinel/Integrations/AzureSentinel/README.md

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Describe the problem

OTRS needs to be configured correctly for pyOTRS (and our integration) to work.

Suggested fix

We should link to/or mirror the advice under the prerequisites section at https://pypi.org/project/PyOTRS/

In particular - ensuring that the following is provided:

This YAML configuration template includes the Route: /TicketList endpoint that is required for PyOTRS but which is not included in the default OTRS webservice setup.

The manage credentials link at the top of the doc points to the old docs. We need to point here:
https://xsoar.pan.dev/docs/reference/articles/managing-credentials

Describe the problem

• Page: HashiCorp Vault
• Source: https://github.com/demisto/content/blob/master//Packs/HashiCorp-Vault/Integrations/integration-HashiCorp-Vault_README.md

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Describe the problem

• Page: VirusTotal - Private API
• Source: https://github.com/demisto/content/blob/master//Packs/VirusTotal-Private_API/Integrations/VirusTotal-Private_API/README.md

The parameter " Do not use by default " is not documented.

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Please explain the purpose of this setting and its effect(s).

Unformatted table in xdr-get-incidents section of the doc page.

• Page: Palo Alto Networks Cortex XDR - Investigation and Response
• Source: https://github.com/demisto/content/blob/master//Packs/CortexXDR/Integrations/PaloAltoNetworks_XDR/README.md

Screenshots

Environment

• OS: Mac
• Browser: Chrome

Suggested fix

Describe the problem

Links lead nowhere, due to use of quotations.

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Remove quotations from the URLs

Describe the problem

Typo on Cortex - spelled "Coretx" in multiple locations on the page.

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Describe the problem

There are some missing conventions in the code conventions page (https://xsoar.pan.dev/docs/integrations/code-conventions):

1. python code should include type hints (reference to https://xsoar.pan.dev/docs/integrations/linting#mypy)
2. docstring format should be google format. In Pycharm:
   

Describe the problem

The current Create an Integration tutorial uses a code conventions different from those described in Code Conventions.

Screenshots

Tutorial page:

import requests
import json
import collections
# disable insecure warnings
requests.packages.urllib3.disable_warnings()
PROXY = demisto.params().get('proxy')
INSECURE = demisto.params().get('insecure')
BASE_URL = demisto.params().get('url')
API_KEY = demisto.params().get('apikey')
URL_SUFFIX = 'yoda'
if not demisto.params().get('proxy', False):
    del os.environ['HTTP_PROXY']
    del os.environ['HTTPS_PROXY']
    del os.environ['http_proxy']
    del os.environ['https_proxy']
'''HELPER FUNCTIONS'''
def http_request(method, URL_SUFFIX, json=None):
    if method is 'GET':
        headers = {}
    elif method is 'POST':
        if not API_KEY:
            headers = {
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            }
        else:
            headers = {
                'Content-Type': 'application/json',
                'Accept': 'application/json',
                'X-FunTranslations-Api-Secret': API_KEY
            }
    r = requests.request(
        method,
        BASE_URL + URL_SUFFIX,
        data=json,
        headers=headers,
        verify=INSECURE
    )
    if r.status_code is not 200:
        return_error('Error in API call [%d] - %s' % (r.status_code, r.reason))
    return r.json()
# Allows nested keys to be accesible
def makehash():
    return collections.defaultdict(makehash)
'''MAIN FUNCTIONS'''
def translate(text):
    query = { 'text': text }
    search = json.dumps(query)
    r = http_request('POST', URL_SUFFIX, search)
    return r
def translate_command():
    text = demisto.args().get('text')
    contxt = makehash()
    human_readable = makehash()
    res = translate(text)
    contents = res['contents']
    if 'translated' in contents:
        human_readable['Original'] = text
        human_readable['Translation'] = contents['translated']
        contxt['Original'] = text
        contxt['Translation'] = contents['translated']
    ec = {'YodaSpeak.TheForce(val.Original && val.Original == obj.Original)': contxt}
    demisto.results({
        'Type': entryTypes['note'],
        'ContentsFormat': formats['markdown'],
        'Contents': res,
        'HumanReadable': tableToMarkdown('Yoda Says...', human_readable),
        'EntryContext': ec
    })
''' EXECUTION '''
LOG('command is %s' % (demisto.command(), ))
try:
    if demisto.command() == 'yoda-speak-translate':
        translate_command()
    elif demisto.command() == 'test-module':
        text = 'I have the high ground!'
        translate(text)
        demisto.results('ok')
except Exception, e:
    demisto.debug('The Senate? I am the Senate!')
    LOG(e.message)
    LOG.print_log()
    return_error(e.message)

Code convention page:

def main():
    """
        PARSE AND VALIDATE INTEGRATION PARAMS
    """
    username = demisto.params().get('credentials').get('identifier')
    password = demisto.params().get('credentials').get('password')
    # Remove trailing slash to prevent wrong URL path to service
    base_url = urljoin(demisto.params()['url'], '/api/v1/suffix')
    verify_certificate = not demisto.params().get('insecure', False)
    # How many time before the first fetch to retrieve incidents
    first_fetch_time = demisto.params().get('fetch_time', '3 days').strip()
    proxy = demisto.params().get('proxy', False)
    LOG(f'Command being called is {demisto.command()}')
    try:
        client = Client(
            base_url=base_url,
            verify=verify_certificate,
            auth=(username, password),
            proxy=proxy)
        if demisto.command() == 'test-module':
            # This is the call made when pressing the integration Test button.
            result = test_module(client)
            demisto.results(result)
        elif demisto.command() == 'fetch-incidents':
            # Set and define the fetch incidents command to run after activated via integration settings.
            next_run, incidents = fetch_incidents(
                client=client,
                last_run=demisto.getLastRun(),
                first_fetch_time=first_fetch_time)
            demisto.setLastRun(next_run)
            demisto.incidents(incidents)
        elif demisto.command() == 'helloworld-say-hello':
            return_outputs(*say_hello_command(client, demisto.args()))
    # Log exceptions
    except Exception as e:
        return_error(f'Failed to execute {demisto.command()} command. Error: {str(e)}')
if __name__ in ('__main__', '__builtin__', 'builtins'):
    main()

Environment

• OS: MacOS
• Browser: Chrome
• Browser Version: -

Suggested fix

Update the tutorial content or add clarifying statement regarding coding style.

Describe the problem

• Page: SplunkPy
• Source: https://github.com/demisto/content/blob/master//Packs/SplunkPy/Integrations/SplunkPy/README.md

Several commands are not documented at all, including all the commands starting with splunk-kv-store

Screenshots

Environment

• OS: any
• Browser: any
• Browser Version: any

Suggested fix

Write the documentation

Describe the problem

Images were published to the base directory

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Add to static/img or remove.

When running npm run build locally, the build function does:

"build": "copyfiles -E -V -f docs/doc_imgs/* static/doc_imgs/. && replace 'doc_imgs' '/doc_imgs' docs/* --include='*.md*' && docusaurus build",

This has two issues:

1. Replacing the relative links from 'doc_imgs' to '/doc_imgs' in the md files locally changes all the files, so git detects all of them as changed.
2. static/doc_imgs/* gets added to the repo, which are detected as new files by git. This can probably be fixed easily by adding static/doc_imgs to .gitignore.

With this issues, if you test the build locally then you need to revert before adding files to staging and committing.

tried your tutorial step by step integrate demisto to PyCharm and everything is fine event when i set the apikey it returns seuccessfull when i verify it but when i try to run it like what you said on the video it returns result below.

Please contact me @ [email protected]
We are trying to integrate our mailing phishing using demisto and I believe i am missing something here

DBot
June 8, 2020 4:52 PM
Scripts returned an error
Command:

!Hi5DevTeam dev="Shachar"
Hide reason
Reason
Error from Scripts is : Script failed to run: Runner request timeout reached (script timeout) for script [Hi5DevTeam]. timeout: [5m0s] (2618) (2603)

Describe the problem

In the Incidents section, there is a word, "incdients". It should probably be 'incidents'

• Page: Welcome
• Source: https://github.com/demisto/content-docs/tree/master/docs/welcome.md

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Describe the problem

Link to go to Proofpoint TAP v2 example leads to a 404 page.
https://demisto.developers.paloaltonetworks.com/docs/integrations/code-conventions

Incorrect link : https://github.com/demisto/content/tree/master/Integrations/ProofpointTAP_v2

Screenshots

Environment

• Browser: Chrome

Suggested fix

Add the correct link.

The optional field "from" on the search event integration don't work on MISP 2.4.119

Describe the problem

Broken link to demisto-sdk readme's and a couple of typos

Screenshots

Fix

Typos: pre-commit hook to check that possible
Fix link to point to correct location: https://github.com/demisto/demisto-sdk/tree/master/demisto_sdk/commands/secrets

npm install complains about a security issue documented here: https://www.npmjs.com/advisories/1014

Describe the problem

Under Commands-external commands, there is a word, "repuration". I think you mean reputation

• Page: Cortex XSOAR Concepts
• Source: https://github.com/demisto/content-docs/tree/master/docs/concepts/concepts.md

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Describe the problem

The first paragraph has a trailing slash.

The link to HelloWorld is a 404.

Screenshots

Not needed

Environment

• OS: Windows 10
• Browser: Edge Chromium
• Browser Version: Latest

Suggested fix

Fix the link and remove the slash.

Describe the problem

In Authentication section, the link is wrong: https://xsoar.pan.dev/docs/reference/integrations/microsoft-management-activity-api-(O365/Azure-Events)

Suggested fix

Not sure where the link shall point.

Describe the problem

• Page: Set
• Source: https://github.com/demisto/content/blob/master//Packs/CommonScripts/Scripts/script-Set_README.md

The documentation mentions "The value to set to the key. Can be an array. Usually, a DQ expression.", but what is a DQ expression?

Describe the problem

Yoda Speak integration code written with Python 2.x and produce errors when running within the newer Python 3.x oriented versions of Cortex XSOAR 5.5+

Suggest either at least mention that code have to be run under Python 2.x
Or as a best solution to provide the code for Python 3.x versions as well by substituting (is -> ==) and (is not -> !=)

Suggested fix

I could provide PR by adding separate sections for Python 2 and 3 code correspondingly.

Describe the problem

Required URLs to open in Proxies are not listed in the integration doc.

Environment

• Last CDL integration version
• XSOAR 5.5

Suggested fix

Add a section with requirements including below URLs:

oproxy.demisto.ninja (license validation)
api.us.cdl.paloaltonetworks.com (mandatory)
api.nl.cdl.paloaltonetworks.com (optional, if CDL is in Europe)

Thank you for taking the time to help us improve our documentation! Please describe the problem and a suggested fix below and we'll get back to you as soon as we can. --DevRel

Describe the problem

Table of contents menu is appearing in the wrong place on the doc page.

Suggested fix

Identify the code block that is causing the issue. As with similar issues in the past, it's likely due to a code block not wrapping properly which extends the width, resulting in the overflow.

Describe the problem

Due to new docs structure, some links seem to be broken, I found one as example

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Fix all links, verify they lead somewhere

Hi, everyone.

I am reading documentation at this link. There is one step, where I should run

demisto-sdk lint

command on the folder Packs/HelloWorld/Integrations/HelloWorld using -d option.

Command:

demisto-sdk lint -d /path/to/demisto/content/Packs/HelloWorld/Integrations/HelloWorld/

Command result:

Usage: demisto-sdk lint [OPTIONS]

Error: no such option: -d

But, when I run command with -i argument, everything works fine.

demisto-sdk lint -i /path/to/demisto/content/Packs/HelloWorld/Integrations/HelloWorld/

Maybe something changes, and requires documentation update ?

I am using python 3.8.3 and demisto_sdk 1.1.2.

Thanks.

Describe the problem

• Page: HashiCorp Vault
• Source: https://github.com/demisto/content/blob/master//Packs/HashiCorp-Vault/Integrations/integration-HashiCorp-Vault_README.md

The link at the first paragraph points to ZD artical

Suggested fix

should point to Palo Alto Networks tech docs here https://xsoar.pan.dev/docs/reference/articles/managing-credentials

Describe the problem

Missing additionalinfo in the integration parameters description for tooltip

See: https://github.com/demisto/content/blob/9b211dafa82a99ff4e68b9ec25f4e0257b64df20/Packs/EDL/Integrations/EDL/EDL.yml#L20

Suggested fix

Add the additionalinfo to the documentation

Describe the problem

• Page: Python Code Conventions
• Source: https://github.com/demisto/content-docs/tree/master/docs/integrations/code-conventions.md

Stale / incorrect information

Under the documentation for the CommandResults section, the parameter for the human readable content is incorrect

Screenshots

Environment

• OS: Windows
• Browser: Chrome

Suggested fix

Change from human_readable to readable_output

Describe the problem

No grid examples pictures

Screenshots

Environment

• OS: MAC
• Browser: Chrome
• Browser Version: Version 83.0.4103.97 (Official Build) (64-bit)

Suggested fix

Missing image in: /docs/integration-docs

There is a link to: /doc_imgs/65404184-313ced00-dde0-11e9-9257-e61e2943fd75.gif that is missing in the doc_imgs directory.

I've tried to find the original image in the content repo but couldn't find it.

Describe the problem

Backticks in example command syntax for !cdl-query-logs get rendered as markdown styling elements when viewed in the browser and do not come through when copying/pasting text to another window. This causes the requirement of backticks in the query to be unclear in the documentation.

Screenshots

Environment

• OS: [e.g. Windows]
• Browser: [e.g. chrome, safari, firefox..]
• Browser Version:

Suggested fix

Escape the backticks in the example SQL syntax for the cdl-query-logs command so they are visible in the browser.

Describe the problem

In Dark Mode the search box text is almost non-visible.

Screenshots

In the screenshot I typed test in the search box:

Environment

• OS: [e.g. Windows]
• Browser: chrome
• Browser Version:

Suggested fix

Change css so text in search bar with dark mode is visable