Demisto Class

'All Python integrations and scripts have available as part of the runtime the demisto class object. The object exposes a series of API methods which are used to retrieve and send data to the Cortex XSOAR Server.

note

The demisto class is a low level API. For many operations we provide a simpler and more robust API as part of the Common Server Functions.

params

demisto.params()

(Integration only) Retrieves the integration parameters object

Returns:

  • dict - Integrations parameters object

args

demisto.args()

Retrieves a command / script arguments object

Returns:

  • dict - Arguments object

command

demisto.command()

(Integration only) Retrieves the integration command that is being run

Returns:

  • str - Integrations command name

log

demisto.log(msg)

Prints a message to the current incidents war room log

Arguments:

  • msg str - The message to be logged

Returns:

  • None - No data returned

get

demisto.get(obj, field)

Extracts field value from nested object

Arguments:

  • obj dict - The object to extract the field from
  • field str - The field to extract from the object, given in dot notation

Returns:

  • str - The value of the extracted field

gets

demisto.gets(obj, field)

Extracts field value from nested object

Arguments:

  • obj dict - The object to extract the field from
  • field str - The field to extract from the object, given in dot notation

Returns:

  • str - The value of the extracted field

context

demisto.context()

Retrieves the context data object of the current incident

Returns:

  • dict - Context data object

uniqueFile

demisto.uniqueFile()

Generate a unique file name based upon a random UUID

Returns:

  • str - Random UUID

getLastRun

demisto.getLastRun()

(Integration only) Retrieves the LastRun object

Returns:

  • dict - LastRun object

setLastRun

demisto.setLastRun(obj)

(Integration only) Stores given object in the LastRun object

Arguments:

  • obj dict - The object to store

Returns:

  • None - No data returned

info

demisto.info(msg, *args)

Prints a message to the server logs in info level

Arguments:

  • msg str - The message to be logged
  • args dict - Additional arguments to log

Returns:

  • None - No data returned

error

demisto.error(msg, *args)

Prints a message to the server logs in error level

Arguments:

  • msg str - The message to be logged
  • args dict - Additional arguments to log

Returns:

  • None - No data returned

debug

demisto.debug(msg, *args)

Prints a message to the server logs in debug level

Arguments:

  • msg str - The message to be logged
  • args dict - Additional arguments to log

Returns:

  • None - No data returned

getAllSupportedCommands

demisto.getAllSupportedCommands()

(Script only) Retrieves all available integration commands and scripts

Returns:

  • dict - Object of all available integrations and scripts

results

demisto.results(results)

Outputs entries to the war-room

Arguments:

  • results Union[list, dict] - The entry object or array of entry objects to output

Returns:

  • None - No data returned

credentials

demisto.credentials(credentials)

(Integration only) For integrations that support fetching credentials. Send the fetched credentials to the server.

Arguments:

  • credentials list - List of credential objects

Returns:

  • None - No data returned

getFilePath

demisto.getFilePath(id)

Retrieves file path and name, given file entry ID

Arguments:

  • id str - File entry ID to get details of

Returns:

  • dict - Object contains file ID, path and name

investigation

demisto.investigation()

Retrieves the ID of the investigation in which being run in

Returns:

  • dict - Object contains the investigation ID

executeCommand

demisto.executeCommand(command, args)

(Script only) Executes given integration command / script and arguments

Arguments:

  • command str - Integration command name or script name to run
  • args dict - Integration command / script arguments

Returns:

Union[dict, list]: Command execution response wrapped in Demisto entry object

getParam

demisto.getParam(param)

(Integration only) Extracts given parameter from the integration parameters object

Arguments:

  • param str - Integration parameter to get value of

Returns:

  • str - Integration parameter value

getArg

demisto.getArg(arg)

Extracts given argument from the arguments object

Arguments:

  • arg str - Argument to get value of

Returns:

  • str - Argument value

setIntegrationContext

demisto.setIntegrationContext(context)

(Integration only) Stores given object in the IntegrationContext object

Arguments:

  • context dict - The object to store

Returns:

  • None - No data returned

getIntegrationContext

demisto.getIntegrationContext()

(Integration only) Retrieves the IntegrationContext object

Returns:

  • dict - IntegrationContext object

setIntegrationContextVersioned

demisto.setIntegrationContextVersioned(context, version=-1, sync=False)

(Integration only) Stores given object in the IntegrationContext object in given version

Arguments:

  • context dict - The object to store
  • version int - The context version to set. If the version is older than the current, an error will be thrown. (Default value = -1) # noqa
  • sync bool - Whether to save the context to the DB right away. If false, the context will be saved at the end of the command. (Default value = False)

Returns:

  • None - No data returned

getIntegrationContextVersioned

demisto.getIntegrationContextVersioned(refresh=False)

(Integration only) Retrieves the versioned IntegrationContext object

Arguments:

  • refresh bool - Whether to get the integration context straight from the DB and not from the instance memory. (Default value = False) # noqa

Returns:

  • dict - IntegrationContext versioned object

incidents

demisto.incidents(incidents=None)

In script, retrieves the Incidents list from the context In integration, used to return incidents to the server

Arguments:

  • incidents list - In integration only, list of incident objects (Default value = None)

Returns:

  • list - List of incident objects

incident

demisto.incident()

Retrieves the current incident

Returns:

  • dict - dict representing an incident object

setContext

demisto.setContext(contextPath, value)

(Script only) Sets given value in path in the context data

Arguments:

  • contextPath str - The context data path to set the value in
  • value str - The value to set in the context data path

Returns:

  • dict - Object contains operation result status

demistoUrls

demisto.demistoUrls()

Retrieves the following URLs related to the incident.

  • evidenceBoard
  • investigation
  • relatedIncidents
  • server
  • warRoom
  • workPlan You can use these URLs when you send notifications outside the system over email or slack and would like to include a link to the incident.

Returns:

  • dict - Object contains server URLs with page as key and URL as value

dt

demisto.dt(obj=None, trnsfrm=None)

Extracts field from object using DT language syntax

Arguments:

  • obj dict - The object to look in for the requested field (Default value = None)
  • trnsfrm str - The field to get value of (Default value = None)

Returns:

  • str - The field value in the object

addEntry

demisto.addEntry(id, entry, username=None, email=None, footer=None)

(Integration only) Adds an entry to a mirrored investigation war room

Arguments:

  • id str - Incident ID to add the entry in
  • entry str - The text to add in the entry
  • username str - The username of the user to be the entry creator (Default value = None)
  • email str - The email address of the user to be the entry creator (Default value = None)
  • footer str - The email address of the user to be the entry creator (Default value = None)

Returns:

  • None - No data returned

mirrorInvestigation

demisto.mirrorInvestigation(id, mirrorType, autoClose=False)

(Integration only) Marks an investigation as mirrored

Arguments:

  • id str - Incident ID to mirror
  • mirrorType str - Contains mirror type and mirror direction separated by colon, e.g. all:both
  • autoClose bool - Whether to close the investigation when the mirrored channel is closed/archived (Default value = False)

Returns:

  • None - No data returned

updateModuleHealth

demisto.updateModuleHealth(error)

(Integration only) Updated integration module health with given error message

Arguments:

  • error str - The error message to display in the integration module health

Returns:

  • None - No data returned

directMessage

demisto.directMessage(message, username=None, email=None, anyoneCanOpenIncidents=None)

(Integration only) Executes command provided in direct message to messaging bot

Arguments:

  • message str - The message sent in personal context
  • username str - The username of the user that sent the direct message (Default value = None)
  • email str - The email address of the user that sent the direct message (Default value = None)
  • anyoneCanOpenIncidents bool - Whether external users can create incidents or not (Default value = None)

Returns:

  • str - Server response to command executed in the direct message

createIncidents

demisto.createIncidents(incidents, lastRun=None, userID=None)

(Integration only) Creates incident in long running execution

Arguments:

  • incidents list - List of incident objects to create, with the following optional keys:
    • name (str)
    • type (str) - If not provided, an Unclassified incident will be created
    • labels (list) - List of {"type": , "value": } objects
    • rawJSON (str) - Will be omitted after the classification & mapping step
    • occurred (str)
    • details (str)
    • severity (int)
  • lastRun dict - the LastRun object to set (Default value = None)
  • userID str - The user associated with the request (Default value = None)

Returns:

Union[list, dict]: Created incident object

findUser

demisto.findUser(username=None, email=None)

(Integration only) Looks up for a user in the system

Arguments:

  • username str - The username of the user to search for (Default value = None)
  • email str - The email address of the user to search for (Default value = None)

Returns:

  • dict - Object representing the user found

handleEntitlementForUser

demisto.handleEntitlementForUser(incidentID, guid, email, content, taskID="")

(Integration only) Sends request to server to process entitlement response given from messaging client

Arguments:

  • incidentID str - The incident ID in which the question was sent in
  • guid str - The entitlement UUID which identifies the question
  • email str - The email address of the user that responded
  • content str - The content of the response
  • taskID str - The playbook task ID to mark as complete (Default value = "")

Returns:

  • None - No data returned

demistoVersion

demisto.demistoVersion()

Retrieves server version and build number

Returns:

  • dict - Objects contains server version and build number

integrationInstance

demisto.integrationInstance()

(Integration only) Retrieves the integration instance name in which ran in

Returns:

  • str - The integration instance name

createIndicators

demisto.createIndicators(indicators_batch)

(Integration only) Creates indicators from given indicator objects batch

Arguments:

  • indicators_batch list - List of indicators objects to create

Returns:

  • None - No data returned

searchIndicators

demisto.searchIndicators(fromDate='', query='', size=100, page=0, toDate='', value='', searchAfter=None)

Searches for indicators according to given query

Arguments:

  • fromdate str - The start date to search from (Default value = '')
  • query str - Indicator search query (Default value = '')
  • size int - Limit the number of returned results (Default value = 100)
  • page int - Response paging (Default value = 0)
  • todate str - The end date to search until to (Default value = '')
  • value str - The indicator value to search (Default value = '')
  • searchAfter str - Use the last searchIndicators() outputs for search batch (Default value = None)

Returns:

  • dict - Object contains the search results

getIndexHash

demisto.getIndexHash()

(Integration only) Retrieves the hashed value of the tenant in which ran in

Returns:

  • str - Hashed value of tenant name

getLicenseID

demisto.getLicenseID()

Retrieves the ID of the license used in the server

Returns:

  • str - The license ID

mapObject

demisto.mapObject(obj, mapper, mapper_type)

Mapping an object using chosen mapper

Returns:

  • dict - the obj after mapping