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

internalHttpRequest

demisto.internalHttpRequest(method, uri, body=None)

Run an internal HTTP request to the XSOAR server. The request runs with the permissions of the executing user, when a command is being executed manually (such as via the War Room or when browsing a widget). When run via a playbook, will run with a readonly user with limited permissions isolated to the current incident only. Available for both Integrations and Scripts starting from Server version 6.1.

Arguments:

• method str - HTTP method such as: GET or POST
• uri str - Server uri to request. For example: "/contentpacks/marketplace/HelloWorld". body Optional[str]: Optional body for a POST request. Defaults to None.

Returns:

• dict - dict cotainnig the following fields:
  • statusCode (int): HTTP status code such as 200
  • status (str): HTTP status line such as: "200 OK"
  • body (str): response body
  • headers (dict): dict of headers. Each key is a header name with an array of values. For example: "headers": {"Content-Type": ["text/plain; charset=utf-8"]}

parentEntry

demisto.parentEntry()

Retrieves information regarding the war room entry from which the method runs

Returns:

• dict - information regarding the current war room entry