Documentation Best Practices

This article describes the desired documentation standards in XSOAR content entities, and contains examples that can be very useful when writing documentation.

Entities Description Field#

For playbook and scripts, use the following guideline:#

  • Should start with the verb that describes what the entity does.
  • There's a limited space for descriptions, so we don't want to waste space (and time) with words that don't matter.

Bad example: The XYZ playbook is a playbook that...
We should shorten the description to what matters most.
Good example: Executes as a sub-playbook and enriches indicators from the list.

Additional good examples:

  • Investigates an access incident by gathering user and IP information, and handling the incident based on the stages in "Handling an incident - Computer Security Incident Handling Guide" by NIST.
  • Blocks domains using Palo Alto Networks Panorama or Firewall External Dynamic Lists.
  • Enables you to get all of the corresponding file hashes for a file even if there is only one hash type available.
  • Uses generic polling to get saved question results.

For integrations:#

The description should summarize all of the currently supported endpoints into a sentence that users can digest.

For example:

  • Use the IronDefense integration to rate alerts, update alert statuses, add comments to alerts, and to report observed bad activity.
  • Use the Gmail integration to send/receive emails, manage user accounts, and listen to specified mailboxes and folders.

Fetch Incidents/Indicators section#

Common parameters for this section are:

Parameter nameDisplay name
First fetchFirst fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days, 3 months, 1 year)
Fetch sizeThe maximum number of results to return per fetch. The default is 50.
  • Any other important information for fetching incidents from the service should be added as a parameter.

It’s important to add documentation about the fetch function (especially the first fetch) that is not obvious from looking at the integration. This could be done in the README file or the integration detailed description file.
For example: By default, the integration will import PagerDuty incidents data as Demisto incidents. All incidents created in the minute prior to the configuration of Fetch Incidents and up to the current time will be imported.

Common Integration Parameters#

The most commonly used integration parameters:

Parameter nameDisplay nameNotes
API token/keyAPI Token/ API Key/ API Secret.Provided by the third party integration.
URLServer URL
insecureTrust any certificate (not secure)When ‘trust any certificate’ is selected, the integration ignores TLS/SSL certificate validation errors. Used to test connection issues or connect to a server without a valid certificate.
proxyUse system proxy settingsRuns the integration instance using the proxy server (HTTP or HTTPS) that you defined in the server configuration.
ThresholdThe minimum number/severity/score ...
LimitThe maximum number of...

Parameters found in all integrations:#

ParameterNotes
Run on Single engine / Run on Load Balancing GroupCommunications between the XSOAR server and the 3rd party service are executed through the selected engine or load balancing group, not directly.
Do not use by defaultUse to avoid exceeding API quotas
  • When enabled, commands from this integration will not be available through the CLI, when you run a generic command that uses all available integration commands.
  • To use a command at the CLI from an instance with ‘do not use by default’ enabled, you need to specify the instance with the ‘using’ argument.
  • Commands from this integration will still run in Playbooks, unless you have also added the ignore.default.in.playbooks server configuration, set to true.
  • If you have multiple instances of this integration, and the ‘do not use by default’ option is selected in one or more of the instances, the setting will apply for all instances of the integration.

Common Command Arguments#

Argument typeDescription TemplateExample
BooleanIf “true”... If “false”... Default is “true”.If “true”, will return full results. If “false”, will return partial results. Default is “true”.
StringThe...The User name of the user whose endpoint is being blocked.
Integer- The number of...\n - The total number of…\n - The maximum number\n- The number of times the script attempted to run. - The total number of matches. - The maximum number of results to return.
ArrayA comma-separated list ofA comma-separated list of IP addresses...
List of predetermined optionsThe…. Can be “optionA”, “optionB”, or “optionC”.The severity oh the incident to fetch. Can be "Low", "High" or "Critical"

Outputs#

Try to be as specific as possible regarding what the output really does.
For example, if the context path is: Tripwire.Version.exists
A bad description will be: Exists of element versions.
A good description will be: True if the version of the element exists.

Argument typeDescription TemplateExample
BooleanIf “true”... If “false”... Default is “true”.If “true”, will return full results. If “false”, will return partial results. Default is “true”.
StringThe...The User name of the user whose endpoint is being blocked.
Integer- The number of...\n - The total number of…\n - The maximum number\n- The number of times the script attempted to run. - The total number of matches. - The maximum number of results to return.
ArrayA comma-separated list ofA comma-separated list of IP addresses...
List of predetermined optionsThe…. Can be “optionA”, “optionB”, or “optionC”.The severity oh the incident to fetch. Can be "Low", "High" or "Critical"
Unknown- An array of...\n - A list of…\n -A dictionary of...A list of indicators associated to..
Date- The date and time that...\n - The date and time when...The date and time when the indicator was last updated. The date format is: YYYYMMDDThhmmss, where "T" denotes the start of the value for time, in UTC time.
Last updated on