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(Integration only) Retrieves the integration parameters object
Returns:
dict
- Integrations parameters object
#
argsRetrieves a command / script arguments object
Returns:
dict
- Arguments object
#
command(Integration only) Retrieves the integration command that is being run
Returns:
str
- Integrations command name
#
logPrints a message to the current incidents war room log
Arguments:
msg
str - The message to be logged
Returns:
None
- No data returned
#
getExtracts field value from nested object
Arguments:
obj
dict - The object to extract the field fromfield
str - The field to extract from the object, given in dot notation
Returns:
str
- The value of the extracted field
#
getsExtracts field value from nested object
Arguments:
obj
dict - The object to extract the field fromfield
str - The field to extract from the object, given in dot notation
Returns:
str
- The value of the extracted field
#
contextRetrieves the context data object of the current incident
Returns:
dict
- Context data object
#
uniqueFileGenerate a unique file name based upon a random UUID
Returns:
str
- Random UUID
#
getLastRun(Integration only) Retrieves the LastRun object
Returns:
dict
- LastRun object
#
setLastRun(Integration only) Stores given object in the LastRun object
Arguments:
obj
dict - The object to store
Returns:
None
- No data returned
#
infoPrints a message to the server logs in info level
Arguments:
msg
str - The message to be loggedargs
dict - Additional arguments to log
Returns:
None
- No data returned
#
errorPrints a message to the server logs in error level
Arguments:
msg
str - The message to be loggedargs
dict - Additional arguments to log
Returns:
None
- No data returned
#
debugPrints a message to the server logs in debug level
Arguments:
msg
str - The message to be loggedargs
dict - Additional arguments to log
Returns:
None
- No data returned
#
getAllSupportedCommands(Script only) Retrieves all available integration commands and scripts
Returns:
dict
- Object of all available integrations and scripts
#
resultsOutputs 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(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
#
getFilePathRetrieves 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
#
investigationRetrieves the ID of the investigation in which being run in
Returns:
dict
- Object contains the investigation ID
#
executeCommand(Script only) Executes given integration command / script and arguments
Arguments:
command
str - Integration command name or script name to runargs
dict - Integration command / script arguments
Returns:
Union[dict, list]: Command execution response wrapped in Demisto entry object
#
getParam(Integration only) Extracts given parameter from the integration parameters object
Arguments:
param
str - Integration parameter to get value of
Returns:
str
- Integration parameter value
#
getArgExtracts given argument from the arguments object
Arguments:
arg
str - Argument to get value of
Returns:
str
- Argument value
#
setIntegrationContext(Integration only) Stores given object in the IntegrationContext object
Arguments:
context
dict - The object to store
Returns:
None
- No data returned
#
getIntegrationContext(Integration only) Retrieves the IntegrationContext object
Returns:
dict
- IntegrationContext object
#
setIntegrationContextVersioned(Integration only) Stores given object in the IntegrationContext object in given version
Arguments:
context
dict - The object to storeversion
int - The context version to set. If the version is older than the current, an error will be thrown. (Default value = -1) # noqasync
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(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
#
incidentsIn 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
#
incidentRetrieves the current incident
Returns:
dict
- dict representing an incident object
#
setContext(Script only) Sets given value in path in the context data
Arguments:
contextPath
str - The context data path to set the value invalue
str - The value to set in the context data path
Returns:
dict
- Object contains operation result status
#
demistoUrlsRetrieves 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
#
dtExtracts 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(Integration only) Adds an entry to a mirrored investigation war room
Arguments:
id
str - Incident ID to add the entry inentry
str - The text to add in the entryusername
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(Integration only) Marks an investigation as mirrored
Arguments:
id
str - Incident ID to mirrormirrorType
str - Contains mirror type and mirror direction separated by colon, e.g. all:bothautoClose
bool - Whether to close the investigation when the mirrored channel is closed/archived (Default value = False)
Returns:
None
- No data returned
#
updateModuleHealth(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(Integration only) Executes command provided in direct message to messaging bot
Arguments:
message
str - The message sent in personal contextusername
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(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(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(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 inguid
str - The entitlement UUID which identifies the questionemail
str - The email address of the user that respondedcontent
str - The content of the responsetaskID
str - The playbook task ID to mark as complete (Default value = "")
Returns:
None
- No data returned
#
demistoVersionRetrieves server version and build number
Returns:
dict
- Objects contains server version and build number
#
integrationInstance(Integration only) Retrieves the integration instance name in which ran in
Returns:
str
- The integration instance name
#
createIndicators(Integration only) Creates indicators from given indicator objects batch
Arguments:
indicators_batch
list - List of indicators objects to create
Returns:
None
- No data returned
#
searchIndicatorsSearches 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(Integration only) Retrieves the hashed value of the tenant in which ran in
Returns:
str
- Hashed value of tenant name
#
getLicenseIDRetrieves the ID of the license used in the server
Returns:
str
- The license ID
#
mapObjectMapping an object using chosen mapper
Returns:
dict
- the obj after mapping
#
internalHttpRequestRun 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 POSTuri
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"]}
#
parentEntryRetrieves information regarding the war room entry from which the method runs
Returns:
dict
- information regarding the current war room entry