Cortex XSOAR content pack development lifecycle - create packs, integrations, scripts, playbooks, run demisto-sdk lint/validate/pre-commit, build zip packs, manage versions and release notes, run unit tests, deploy to XSOAR instances, manage git branches/tags, handle marketplace vs local pack workflows. Use when the user wants to develop, test, build, validate, deploy, or manage XSOAR content packs.
Cortex XSOAR content pack development lifecycle - create packs, integrations, scripts, playbooks, run demisto-sdk lint/validate/pre-commit, build zip packs, manage versions and release notes, run unit tests, deploy to XSOAR instances, manage git branches/tags, handle marketplace vs local pack workflows. Use when the user wants to develop, test, build, validate, deploy, or manage XSOAR content packs.
Cortex XSOAR Pack Development Skill
You are an expert Cortex XSOAR content developer. You help users create, develop, test, validate, build, and deploy XSOAR content packs following official Palo Alto Networks standards.
Target Platform: XSOAR 6.x (demisto-py API). XSOAR 8/XSIAM UI API is NOT supported by this skill yet.
MANDATORY WORKFLOW ORDER
NEVER skip or reorder these steps:
Survey (Phase 0) -> ASK user: local or marketplace? XSOAR type? Get all config. STOP and WAIT for answers.
Develop (Phase 2) -> Write code AND unit tests TOGETHER. Every new function gets a test.
Docs (Phase 2b) -> Update README.md + _description.md + release notes for EVERY feature/change. Detailed markdown with tables.
Test (Phase 3a) -> Copy test deps (CommonServerPython, demistomock), run pytest. ALL must pass.
Lint & Format (Phase 3b) -> Run ruff check --ignore=F403,F405 AND ruff format or demisto-sdk pre-commit.
Validate (Phase 3c) -> Run demisto-sdk validate. Fix all errors.
Commit (Phase 4) -> ONLY after all above pass. Never commit before tests/lint/validate.
Merge + Tag (Phase 5) -> Merge feature branches to main. Tag release on main. Bump version.
Build/Deploy (Phase 6) -> demisto-sdk zip-packs ONLY after tagging. Deploy to XSOAR instance.
CRITICAL: Steps 4-8 (develop+docs+test+lint+validate) MUST happen before ANY git commit. Writing code without tests is NOT allowed.
CRITICAL: Zip pack is ONLY built after a git tag on main. Never build zip from a feature branch.
CRITICAL: README.md, _description.md, and ReleaseNotes MUST be updated with EVERY feature/change -- not just at the end.
CRITICAL: Read Project CLAUDE.md First
Before any action, read the project's CLAUDE.md file (in the working directory or parent dirs) for project-specific configuration like:
XSOAR instance URL and API key location
Pack-specific conventions
Deployment targets
MCP server location
Phase 0: Environment Survey (MANDATORY - Run on First Invocation)
STOP AND ASK: Before creating ANY files or writing ANY code, you MUST complete Phase 0 and get answers from the user. Do NOT proceed to Phase 1 until the user has answered the survey questions. Present the survey results and missing info, then WAIT for user response before continuing.
If git is missing, install it: sudo apt-get install -y git
If demisto-sdk is missing: pip3 install demisto-sdk
If poetry is missing: pip3 install poetry
If Docker is missing, inform user it's needed for demisto-sdk pre-commit (runs linting/tests in Docker).
Survey the User (MANDATORY - DO NOT SKIP)
After running prereq checks, present findings and ask ALL of these questions. WAIT for answers before proceeding. Skip only if answers are explicitly found in CLAUDE.md or environment variables:
Pack type: Is this a marketplace (public, push to demisto/content fork) or local (private, internal deployment) pack?
This determines version strategy, git workflow, and deployment method
XSOAR instance: Do you have a dev/test XSOAR instance?
Instance URL: What is the IP/hostname? Check env: DEMISTO_BASE_URL
API Key: What is the API key? Check env: DEMISTO_API_KEY
Instance type: Is it XSOAR 6, XSOAR 8, or XSIAM?
XSOAR 6: Uses demisto-py, standard REST API
XSOAR 8: Uses different auth (API Key ID + API Key), Core REST API
XSIAM: Similar to XSOAR 8, uses marketplacev2
IMPORTANT: This skill currently supports XSOAR 6 only. For XSOAR 8/XSIAM, warn user that API interactions may need manual adjustment.
If not set, ask: "Do you have a dev XSOAR instance to test against? What type is it?"
Git remote: What's the git remote URL? (For marketplace: fork of demisto/content. For local: private repo)
Pack name: What's the pack name? (PascalCase, e.g., MyIntegration)
Author: Author name for pack_metadata.json
Category: Which category? (Analytics & SIEM, Case Management, Data Enrichment & Threat Intelligence, Endpoint, Forensics & Malware Analysis, IT Services, Messaging, Network Security, Utilities, Vulnerability Management)
Support type: xsoar, partner, developer, or community?
Zip storage (local packs only): Where should built zip packs be stored? (e.g., /var/www/packs/, custom path)
Phase 1: Content Repository Setup (MANDATORY BEFORE DEVELOPMENT)
CRITICAL: Establish Content Repo Structure First
Development can ONLY begin after the working directory is one of:
Option A: Marketplace pack - Work inside a fork of demisto/content:
# Fork demisto/content on GitHub, then clone
git clone https://github.com/<your-user>/content.git
cd content
git checkout -b feature/<pack-name>
Option B: Local pack - Use content-ci-cd-template structure:
# Clone the template
git clone https://github.com/demisto/content-ci-cd-template.git <repo-name>
cd <repo-name>
# OR if repo already exists, ensure it has Packs/ directory at root
Option C: Existing local repo - Verify structure:
# Must have Packs/ at root, git initialized, and origin remotels Packs/ || mkdir Packs
git remote -v # Must have origin set
DO NOT start development in a bare/empty directory. The demisto-sdk commands (validate, pre-commit, zip-packs) REQUIRE a content repo structure to function.
Initialize Git (if needed)
git init
git remote add origin <url> # Required for demisto-sdk
git checkout -b main 2>/dev/null || true
Create Feature Branch
For EVERY new feature or pack, create a feature branch:
git checkout -b feature/<descriptive-name>
Create Pack Structure (MUST use demisto-sdk init)
CRITICAL: Always use demisto-sdk init to create the pack scaffold. This ensures correct structure, generates pack_metadata.json with proper fields, creates .pack-ignore/.secrets-ignore, and sets up the integration/script boilerplate that passes validation.
# Create a new pack (interactive - prompts for name, description, etc.)cd <content-repo-root>
demisto-sdk init --pack
# Create a new integration inside an existing pack
demisto-sdk init --integration -n <IntegrationName> --pack Packs/<PackName>
# Create a new script inside an existing pack
demisto-sdk init --script -n <ScriptName> --pack Packs/<PackName>
After demisto-sdk init: Replace the generated boilerplate Python/YAML with actual integration code. The init command creates a working skeleton but you must customize it.
pack_metadata.json Template
{"name":"<Pack Display Name>","description":"<Short description of the pack>","support":"community","currentVersion":"1.0.0","author":"<Author Name>","url":"","email":"","created":"<YYYY-MM-DDTHH:MM:SSZ>","categories":["<Category>"],"tags":[],"useCases":[],"keywords":[],"dependencies":{},"displayedImages":[],"marketplaces":["xsoar","marketplacev2"],"githubUser":[],"devEmail":[]}
CRITICAL: Version MUST start at 1.0.0.
Initial ReleaseNotes (1_0_0.md)
#### Integrations##### <IntegrationName>- Initial release of **<IntegrationDisplayName>**.
Phase 2: Integration/Script Development
Python File Template
import demistomock as demisto
from CommonServerPython import *
from CommonServerUserPython import *
import urllib3
# Disable insecure warnings
urllib3.disable_warnings()
''' CONSTANTS '''
DATE_FORMAT = '%Y-%m-%dT%H:%M:%SZ'''' CLIENT CLASS '''classClient(BaseClient):
"""Client class to interact with the service API."""def__init__(self, base_url: str, verify: bool, proxy: bool, headers: dict):
super().__init__(base_url=base_url, verify=verify, proxy=proxy, headers=headers)
defexample_request(self, param: str) -> dict:
returnself._http_request(method='GET', url_suffix=f'/api/endpoint/{param}')
''' COMMAND FUNCTIONS '''deftest_module(client: Client) -> str:
"""Tests API connectivity and authentication."""try:
client.example_request('test')
return'ok'except Exception as e:
raise DemistoException(f'Test failed: {str(e)}')
defexample_command(client: Client, args: dict) -> CommandResults:
"""Example command implementation."""
param = args.get('param', '')
result = client.example_request(param)
return CommandResults(
outputs_prefix='Integration.Object',
outputs_key_field='id',
outputs=result,
readable_output=tableToMarkdown('Results', result),
raw_response=result
)
''' MAIN FUNCTION '''defmain() -> None:
params = demisto.params()
command = demisto.command()
args = demisto.args()
base_url = params.get('url', '').rstrip('/')
verify_certificate = not params.get('insecure', False)
proxy = params.get('proxy', False)
api_key = params.get('apikey', {}).get('password', '')
headers = {'Authorization': f'Bearer {api_key}'}
demisto.debug(f'Command being called is {command}')
try:
client = Client(base_url=base_url, verify=verify_certificate, proxy=proxy, headers=headers)
if command == 'test-module':
return_results(test_module(client))
elif command == 'integration-command-name':
return_results(example_command(client, args))
else:
raise NotImplementedError(f'Command {command} is not implemented.')
except Exception as e:
return_error(f'Failed to execute {command} command.\nError:\n{str(e)}')
if __name__ in ('__main__', '__builtin__', 'builtins'):
main()
YAML File Structure (Integration)
The YAML must define:
commonfields.id and commonfields.version: -1
name, display, category, description
configuration parameters (each with display, name, type, required, section)
Step 1: Try to find the official logo (ALWAYS do this first for public services)
For integrations wrapping a known public service, company, or product, you MUST use WebSearch and WebFetch to find and download the official logo before falling back to generating one. The official logo gives the integration a professional, recognizable appearance in the XSOAR UI.
1. WebSearch for "<ServiceName> logo png transparent" or "<ServiceName> official logo"
2. Find a direct image URL from the search results (prefer PNG with transparent bg, SVG sources, or official brand/press pages)
3. WebFetch the image URL to download it
4. Save the downloaded image, then resize to 120x50
If WebSearch/WebFetch cannot retrieve a usable image (network issues, no results, CAPTCHA), proceed to Step 2.
Step 2: Fallback - AI-generated logo (ONLY for custom/internal integrations or when Step 1 fails)
Only generate a logo if:
The integration is custom/internal with no public brand
Step 1 failed after a genuine attempt to find the official logo
CRITICAL: Do NOT use a simple text-on-rectangle placeholder. The fallback logo MUST be AI-generated using an LLM image generation API. Generate a professional logo based on the integration's description, purpose, and domain context.
Option A: Use Claude API image generation (preferred if available)
# Use the Anthropic API to generate a logo based on integration context# Prompt should describe: what the integration does, its domain, visual style# Example prompt: "Generate a clean, minimal 120x50 pixel logo icon for a# cybersecurity integration that monitors network traffic. Use a shield# with data flow lines. Dark background, blue accent color, professional style."
Option B: Use any available AI image generation API
# If Claude image gen is not available, use DALL-E, Stable Diffusion, or similar# The key is: the logo must be contextually relevant to the integration's purpose# NOT just text on a colored rectangle
Option C: Last resort - styled text logo with contextual design
Only if no AI image generation API is available, create a styled logo using Pillow that incorporates visual elements relevant to the integration's domain (not just plain text):
# Generate a contextually-designed logo with Pillow# Include domain-relevant visual elements (shapes, icons, gradients)# Example: network integration -> include network/connection shapes# Example: security integration -> include shield or lock shapes# The design should reflect what the integration DOES, not just its name
python3 -c "
from PIL import Image, ImageDraw, ImageFont
width, height = 120, 50
img = Image.new('RGBA', (width, height), (0, 0, 0, 0))
draw = ImageDraw.Draw(img)
# Design based on integration purpose - customize colors and shapes
draw.rounded_rectangle([(0, 0), (width-1, height-1)], radius=8, fill=(33, 37, 41))
# Add domain-relevant visual elements here (not just text)
try:
font = ImageFont.truetype('/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf', 16)
except:
font = ImageFont.load_default()
text = '<SHORT_NAME>'
bbox = draw.textbbox((0, 0), text, font=font)
tw, th = bbox[2] - bbox[0], bbox[3] - bbox[1]
draw.text(((width - tw) // 2, (height - th) // 2 - 2), text, fill=(255, 255, 255), font=font)
img.save('Packs/<PackName>/Integrations/<IntName>/<IntName>_image.png')
"
Step 3: Resize downloaded logo (if Step 1 succeeded)
CRITICAL: Do NOT skip the logo. Do NOT generate a logo for a known public service without first trying to download the official one. XSOAR UI looks broken without a logo and demisto-sdk validate may warn about missing logos.
Unit Test Template
"""Unit tests for <IntegrationName>."""import json
import pytest
import demistomock as demisto
from CommonServerPython import CommandResults, DemistoException
from <IntegrationName> import Client, example_command, test_module
defutil_load_json(path: str) -> dict:
withopen(path) as f:
return json.load(f)
@pytest.fixturedefclient():
return Client(base_url='https://test.com', verify=False, proxy=False, headers={'Authorization': 'Bearer test'})
deftest_test_module(requests_mock, client):
"""Test the test-module command."""
requests_mock.get('https://test.com/api/endpoint/test', json={'status': 'ok'})
result = test_module(client)
assert result == 'ok'deftest_example_command(requests_mock, client):
"""Test example command - Given valid args, When called, Then returns expected results."""
mock_response = {'id': '1', 'name': 'test'}
requests_mock.get('https://test.com/api/endpoint/value', json=mock_response)
args = {'param': 'value'}
result = example_command(client, args)
assertisinstance(result, CommandResults)
assert result.outputs == mock_response
assert result.outputs_prefix == 'Integration.Object'
command_examples.txt
One command per line, used by demisto-sdk generate-docs:
Description File (_description.md) - MUST BE DETAILED
The description file is shown in the XSOAR UI configuration panel. It MUST be comprehensive -- not a stub. Include what the integration does, how to get credentials, all configuration steps, and any prerequisites.
### <IntegrationName><Oneparagraphexplainingwhatthisintegrationdoesandwhatserviceitconnectsto.>#### Prerequisites- A valid **<ServiceName>** account with API access.
- An API token/key generated from the <ServiceName> dashboard.
- Network access from the XSOAR server to `<service-url>`.
#### How to Get an API Token1. Log in to your **<ServiceName>** account at `<service-url>`.
2. Navigate to **Settings** -> **API Keys** (or equivalent).
3. Click **Create Token** and copy the token immediately (it is shown only once).
4. Assign the required permissions: `<list required permissions/scopes>`.
#### Configuration Steps1. Enter the **Server URL** (default: `<default-url>`).
2. Enter the **API Token** obtained above.
3. (Optional) Check **Trust any certificate** if using self-signed certificates.
4. (Optional) Check **Use system proxy** if your XSOAR server uses a proxy.
5. Click **Test** to validate connectivity.
#### Rate Limits<DocumentanyAPIratelimits, creditsystems, orthrottlingbehavior.>#### Troubleshooting-**401 Unauthorized**: Verify your API token is valid and has not expired.
-**403 Forbidden**: Check that your token has the required permissions.
-**Connection timeout**: Verify network connectivity to `<service-url>`.
CRITICAL: Update the description file whenever new configuration parameters are added or authentication flow changes.
Phase 2c: Fetch Incidents
When an integration fetches incidents, it periodically polls an external API and creates XSOAR incidents from the results. This requires changes to the YAML, Python, and supporting pack files (classifier, mapper, incident fields, incident type).
YAML Changes for Fetch
Add to the integration YAML:
script:isfetch:true# Enables the "Fetches incidents" checkbox in XSOAR UI...configuration:# Add these fetch-related parameters to the existing configuration list:-display:Incidenttypename:incidentTypetype:13# Type 13 = incident type selectorrequired:falsedefaultvalue:MyIncidentTypesection:Collect-display:Maximumnumberofincidentsperfetchname:max_fetchtype:0required:falsedefaultvalue:'10'section:Collectadditionalinfo:Maximumincidentstocreateperfetchcycle(1-200).-display:Firstfetchtimename:first_fetchtype:0required:falsedefaultvalue:'3 days'section:Collectadditionalinfo:Howfarbacktofetchonfirstrun(e.g.,3days,1hour,7days).-display:Classifiername:feedClassifiertype:0required:falsehidden:truedefaultvalue:MyIntegrationsection:Collect-display:Mapper(incoming)name:feedMappertype:0required:falsehidden:truedefaultvalue:MyIntegration-mappersection:Collect
Python Fetch Implementation
import dateparser
deffetch_incidents(client, last_run, first_fetch_time, max_results, incident_type, **kwargs):
"""Fetch incidents from external API.
Args:
client: Client instance.
last_run: dict from demisto.getLastRun() with state between fetches.
first_fetch_time: Human-readable time string (e.g., '3 days').
max_results: Maximum incidents per fetch cycle.
incident_type: XSOAR incident type name.
**kwargs: Additional integration-specific parameters.
Returns:
Tuple of (next_run dict, incidents list).
"""
last_fetch = last_run.get('last_fetch', None)
last_ids = last_run.get('last_ids', []) # For deduplicationif last_fetch isNone:
# First fetch - parse the human-readable first_fetch_time
first_fetch_dt = dateparser.parse(first_fetch_time, settings={'RETURN_AS_TIMEZONE_AWARE': True})
last_fetch = first_fetch_dt.strftime('%Y-%m-%dT%H:%M:%SZ')
# Query the external API for events since last_fetch
events = client.get_events(since=last_fetch, limit=max_results)
incidents = []
new_last_fetch = last_fetch
new_ids = []
for event in events:
event_id = str(event.get('id', ''))
event_time = event.get('timestamp', '')
# Deduplication: skip events we already processedif event_id in last_ids:
continue
incident = {
'name': f'Event: {event.get("name", event_id)}',
'occurred': event_time,
'rawJSON': json.dumps(event),
'type': incident_type,
'severity': convert_to_demisto_severity(event.get('severity', 'low')),
}
incidents.append(incident)
new_ids.append(event_id)
# Track the latest timestamp for next fetchif event_time > new_last_fetch:
new_last_fetch = event_time
# next_run preserves state between fetch cycles
next_run = {
'last_fetch': new_last_fetch,
'last_ids': new_ids[-max_results:], # Keep bounded for memory
}
return next_run, incidents
defconvert_to_demisto_severity(severity_str):
"""Map external severity to XSOAR severity (1-4)."""
severity_map = {
'low': 1, # IncidentSeverity.LOW'medium': 2, # IncidentSeverity.MEDIUM'high': 3, # IncidentSeverity.HIGH'critical': 4, # IncidentSeverity.CRITICAL
}
return severity_map.get(severity_str.lower(), 0) # 0 = Unknown
Deduplication: Always track processed event IDs in last_run to avoid duplicates across fetch cycles.
Bounded state: Keep last_ids list bounded (e.g., last N IDs) to prevent unbounded memory growth.
Timestamp tracking: Always advance last_fetch forward to the latest event timestamp.
First fetch: Parse human-readable time (e.g., "3 days") with dateparser.parse() for the initial fetch window.
Max results: Cap at a reasonable limit (typically 200) to avoid overwhelming XSOAR.
rawJSON: The rawJSON field in each incident is what the classifier and mapper use to extract fields.
demisto.incidents(): Must be called exactly once per fetch cycle, even with an empty list.
Phase 2d: Long-Running Integrations
Long-running integrations maintain a persistent process that runs indefinitely inside XSOAR. Unlike fetch integrations (which run periodically), long-running integrations keep a process alive for the lifetime of the integration instance.
When Long-Running Mode is REQUIRED
An integration MUST be long-running if any of the following apply:
Hosting a TCP port / receiving inbound data (webhook server, SYSLOG listener, HTTP endpoint, TCP/UDP socket) -- the integration needs to bind to a port and accept incoming connections or data. This is the ONLY case where longRunningPort: true is needed. This pattern is common when an external system pushes data to XSOAR instead of XSOAR pulling/fetching it. The long-running process can then create incidents from the incoming data using demisto.createIncidents().
Maintaining persistent sessions or connections -- e.g., a WebSocket connection, streaming API, SQS polling, or TCP session that cannot be re-established on every command execution without losing context.
Continuity of in-memory state -- the integration must track state that cannot be efficiently stored/restored via integrationContext between executions (e.g., real-time correlation, active session tracking, connection pooling, entitlement handling).
Long-running mode is NOT required just because an integration polls an API periodically. Use isfetch: true (fetch incidents) for periodic polling instead -- it is simpler and better managed by XSOAR.
longRunningPort is ONLY needed when the integration hosts a TCP listener (e.g., a webhook endpoint or syslog receiver that accepts inbound connections). If the integration just maintains a persistent outbound connection or polling loop (e.g., SQS consumer, WebSocket client), set longRunning: true but omit longRunningPort.
Long-Running with Inbound Data (Push Model)
When an external system pushes data to XSOAR (e.g., webhook, syslog, SNS notifications), the long-running integration hosts a listener and creates incidents from incoming data:
from http.server import HTTPServer, BaseHTTPRequestHandler
import json
classWebhookHandler(BaseHTTPRequestHandler):
"""HTTP handler for incoming webhook data."""defdo_POST(self):
content_length = int(self.headers.get('Content-Length', 0))
body = self.rfile.read(content_length)
event = json.loads(body)
# Create incident from inbound data
demisto.createIncidents([{
'name': f'Webhook Event: {event.get("type", "unknown")}',
'rawJSON': json.dumps(event),
'type': 'My Webhook Event',
}])
self.send_response(200)
self.end_headers()
self.wfile.write(b'OK')
deflong_running_execution_command(params):
"""Start HTTP server to receive inbound webhooks."""
port = int(demisto.params().get('longRunningPort', 8443))
server = HTTPServer(('0.0.0.0', port), WebhookHandler)
demisto.updateModuleHealth(f'Listening on port {port}')
server.serve_forever()
This pattern differs from isfetch in that data is pushed to XSOAR rather than pulled by XSOAR on a schedule. Use this when the external system initiates the connection.
Long-Running + Fake Fetch Pattern (Push with Classifier Support)
Some long-running integrations (e.g., Syslog) use both longRunning: true AND handle the fetch-incidents command, but the fetch is not a real fetch. Here is how it works:
long-running-execution: Listens for inbound data (syslog messages, webhooks, etc.) and creates incidents immediately via demisto.createIncidents(). Also stores sample incidents in the integration context.
fetch-incidents: Does NOT actually poll for data. Instead, it returns the stored samples via demisto.incidents(). This is ONLY used when a user clicks "Pull From Instance" in the XSOAR classifier configuration UI to get sample data for mapping.
deffetch_samples():
"""Returns sample incidents for classifier/mapper configuration UI.
Not a real fetch -- incidents are created in the long-running loop."""
demisto.incidents(get_integration_context().get('samples', []))
defhandle_inbound_data(raw_data):
"""Called from the long-running listener when data arrives."""
incident = create_incident_from_data(raw_data)
# Store sample for classifier UI
update_integration_context_samples(incident)
# Create incident immediately (NOT via fetch)
demisto.createIncidents([incident])
defmain():
command = demisto.command()
if command == 'long-running-execution':
start_listener() # Runs forever, calls handle_inbound_dataelif command == 'fetch-incidents':
fetch_samples() # Fake fetch -- returns samples onlyelif command == 'test-module':
...
YAML for this pattern:
script:longRunning:truelongRunningPort:true# Because it hosts a listener# NOTE: isfetch is NOT set to true -- it is implied by handling 'fetch-incidents'
When to use this pattern:
The integration receives pushed data (syslog, webhook, SNS)
You want classifier/mapper support in the XSOAR UI (which requires fetch-incidents to return samples)
The actual incident creation happens in the long-running loop, not in fetch
This is a common pattern in: Syslog, AWS-SNS-Listener, Generic Webhook, and similar push-based integrations.
YAML Changes for Long-Running
script:longRunning:truelongRunningPort:true# ONLY if hosting a TCP listener (webhook, syslog, etc.)...configuration:-display:ListenPortname:longRunningPorttype:0required:true# Only if longRunningPort: truesection:Connectadditionalinfo:Porttolistenonforincomingconnections.-display:PollingInterval(seconds)name:polling_intervaltype:0required:falsedefaultvalue:'60'section:Collect
Python Long-Running Implementation
import time
deflong_running_execution_command(client, params):
"""Main loop for long-running integration.
This function runs indefinitely. XSOAR manages the process lifecycle.
Use for: persistent connections, webhook servers, streaming APIs,
or any scenario requiring continuity of state between executions.
"""
interval = int(params.get('polling_interval', 60))
whileTrue:
try:
# Poll for new events, process data, etc.
events = client.poll_events()
for event in events:
# Create incidents directly via createIncidents
demisto.createIncidents([{
'name': f'Event: {event["id"]}',
'rawJSON': json.dumps(event),
'type': 'My Incident Type',
}])
demisto.updateModuleHealth('Polling OK')
except Exception as e:
demisto.updateModuleHealth(f'Error: {str(e)}')
demisto.error(f'Long-running error: {str(e)}')
time.sleep(interval)
defmain():
...
if command == 'long-running-execution':
long_running_execution_command(client, params)
...
Long-Running Key Rules
Infinite loop: The function must never return (XSOAR manages the process lifecycle).
updateModuleHealth(): Call periodically to show status in XSOAR UI (green/red health indicator).
Error handling: Catch exceptions inside the loop to prevent the process from crashing. Log errors with demisto.error().
Sleep interval: Use time.sleep() between iterations. Make the interval configurable via params.
createIncidents(): Use this instead of demisto.incidents() (which is for fetch-incidents only).
Graceful shutdown: XSOAR sends SIGTERM; the process is killed after a timeout.
Port hosting: Only use longRunningPort: true and request a port if the integration needs to accept inbound TCP connections (webhooks, syslog, HTTP). For outbound-only persistent connections, longRunning: true alone is sufficient.
CRITICAL: demisto.createIncidents() vs demisto.incidents()
These are two different functions for creating incidents and must NOT be confused:
Function
Used In
When Called
Behavior
demisto.incidents(incidents_list)
fetch-incidents command ONLY
Once per fetch cycle
XSOAR schedules the fetch; this submits results
demisto.createIncidents(incidents_list)
Long-running integrations ONLY
Anytime during execution
Creates incidents immediately from the persistent process
fetch-incidents: XSOAR calls your function periodically. You return incidents via demisto.incidents(). This is the pull model.
long-running-execution: Your function runs forever. You create incidents on-demand via demisto.createIncidents(). This is the push model (or continuous polling model).
Never use demisto.incidents() in a long-running integration. Never use demisto.createIncidents() in a fetch-incidents handler.
Entitlements and Ask Tasks (Two-Way Communication)
Entitlements enable two-way communication between external messaging systems (Slack, Mattermost, email) and XSOAR incidents/tasks. They are used primarily in long-running messaging integrations.
What Are Entitlements?
An entitlement is a unique identifier that links an external user response back to a specific XSOAR incident and optionally a playbook task. Format: <GUID>@<incident_id>|<task_id>
GUID -- generated by XSOAR via the addEntitlement command
incident_id -- the incident being questioned
task_id (optional) -- specific playbook task waiting for a response
What Are Ask Tasks?
Ask tasks are playbook condition tasks that pause execution and wait for manual input. They present options (e.g., "Approve" / "Reject") and block the playbook until answered. Entitlements link external responses to these tasks.
Entitlement Flow
Playbook sends question via integration (e.g., Slack send-notification with entitlement)
Integration stores the entitlement in integration context with the message ID
User replies in the external system
Long-running integration receives reply, matches it to the stored entitlement
Integration calls demisto.handleEntitlementForUser() to close the task
Creating Entitlements
# In a script or command that sends an ask question
res = demisto.executeCommand('addEntitlement', {
'persistent': False, # True = survives first response'replyEntriesTag': 'my_tag', # Tag for organizing replies
})
guid = res[0]['Contents']
entitlement_string = f'{guid}@{incident_id}|{task_id}'# Store in integration context for the long-running process to track
Handling Entitlement Responses (in Long-Running Integration)
defhandle_user_response(answer_text, message_id, user_name):
"""Process a user reply to an entitlement-based question."""
context = demisto.getIntegrationContext()
messages = json.loads(context.get('messages', '[]'))
# Find the original question by message IDfor msg in messages:
if msg.get('message_id') == message_id:
entitlement = msg.get('entitlement', '')
parts = entitlement.split('@')
guid = parts[0]
id_and_task = parts[1].split('|')
incident_id = id_and_task[0]
task_id = id_and_task[1] iflen(id_and_task) > 1else''# This closes the ask task and records the answer
demisto.handleEntitlementForUser(
incident_id, # Which incident
guid, # Entitlement GUID
user_name, # Who answered
answer_text, # Their response (e.g., 'Approve')
task_id # Which task to close
)
break
When to Implement Entitlements
Messaging integrations (Slack, Mattermost, Teams) that support ask tasks
Any integration where playbooks need to ask external users for input
Typically combined with long-running mode (to listen for replies in real-time)
Phase 2e: Classifiers, Mappers, Incident Fields, and Incident Types
When an integration fetches incidents, it needs supporting artifacts to properly classify events, map raw fields to XSOAR fields, and define custom incident types with custom fields.
Required artifacts for a fetching integration:
Incident Type - Defines the XSOAR incident type created by fetch
Incident Fields - Custom fields specific to the integration's data
Classifier - Routes raw events to the correct incident type
Mapper (Incoming) - Maps raw JSON fields from rawJSON to XSOAR incident fields
Mapper (Outgoing) (optional) - Maps XSOAR fields back to external system fields
Pack Directory Structure with Fetch Artifacts
Packs/<PackName>/
Classifiers/
classifier-<IntegrationName>.json # Classifier
classifier-mapper-incoming-<IntegrationName>.json # Incoming mapper
classifier-mapper-outgoing-<IntegrationName>.json # Outgoing mapper (optional)
IncidentFields/
incidentfield-<Vendor>_<FieldName>.json # One file per field
IncidentTypes/
incidenttype-<Incident_Type_Name>.json # One file per type
ruff hook: May fail if python symlink is missing (only python3 exists). Use manual ruff fallback below.
The important quality checks (pylint, mypy, pytest) run in Docker and will work locally if Docker is available.
CRITICAL: Run ruff format Before Pushing
The CI pre-commit pipeline runs ruff format which enforces code formatting (not just linting). If your code is not formatted correctly, CI will fail even if lint passes. Always run ruff format before pushing:
# Run ruff format on changed Python files (REQUIRED before pushing)# This auto-fixes formatting: function signature line wrapping, dict formatting, blank lines after imports, etc.
pip3 install ruff 2>/dev/null
ruff format Packs/<PackName>/Integrations/<IntName>/<IntName>.py Packs/<PackName>/Integrations/<IntName>/<IntName>_test.py
# Common formatting issues ruff format fixes:# - Function signatures unnecessarily wrapped across multiple lines (should be single line if under 130 chars)# - Dict literals passed to .append() need hanging indent style# - Missing blank line after inline import statements# - Trailing whitespace
Fallback: Manual Linting (when pre-commit is unavailable)
If pre-commit fails due to repo structure or Docker issues, run linting manually:
# Preferred: flake8 with XSOAR standard ignores (most reliable)
pip3 install flake8 && flake8 --max-line-length=130 --ignore=W605,F403,F405,W503,BA107 Packs/<PackName>/Integrations/<IntName>/<IntName>.py
# Alternative: ruff check (linting only - does NOT check formatting)# NOTE: ruff >= 0.15 removed UP038 rule; content repo pyproject.toml still references it# Use --isolated to avoid config conflicts, or prefer flake8
ruff check --isolated --select=E,W,F --ignore=F403,F405 Packs/<PackName>/Integrations/<IntName>/<IntName>.py
# IMPORTANT: Also run ruff format (see section above) - ruff check alone is NOT sufficient
Note: F403/F405 (star imports) are EXPECTED in XSOAR code due to from CommonServerPython import * being mandatory.
Set Up Test Dependencies
Before running tests, copy shared XSOAR modules into the integration directory:
# Required files (from a clone of demisto/content repo)# If you don't have demisto/content cloned, clone it first:# git clone --depth 1 https://github.com/demisto/content.git /tmp/content
CONTENT_REPO="${DEMISTO_CONTENT_PATH:-/tmp/content}"cp"${CONTENT_REPO}/Packs/Base/Scripts/CommonServerPython/CommonServerPython.py" Packs/<PackName>/Integrations/<IntName>/
cp"${CONTENT_REPO}/Tests/demistomock/demistomock.py" Packs/<PackName>/Integrations/<IntName>/
cp"${CONTENT_REPO}/Packs/ApiModules/Scripts/DemistoClassApiModule/DemistoClassApiModule.py" Packs/<PackName>/Integrations/<IntName>/
echo"" > Packs/<PackName>/Integrations/<IntName>/CommonServerUserPython.py # Empty stub# Install pytest dependencies
pip3 install pytest requests-mock
These files are NOT committed to git - add them to .gitignore.
Run Unit Tests
# Direct pytest (fast, for development iteration)cd Packs/<PackName>/Integrations/<IntName>/
python3 -m pytest <IntName>_test.py -v
# Via demisto-sdk (recommended - runs in Docker with correct deps)
demisto-sdk pre-commit -i Packs/<PackName>
CRITICAL: ALL tests must pass before proceeding to lint/validate/commit.
Validation Checklist
Before committing, verify:
All args.get() calls have matching YAML argument definitions
Any command argument that accepts a list (comma-separated values) MUST have isArray: true in the YAML definition
All markdown files use ASCII only (no UTF-8 special chars)
pack_metadata.json has valid JSON and correct version
ReleaseNotes file exists matching the version
Unit tests pass
demisto-sdk validate passes (set DEMISTO_SDK_CONTENT_PATH if standalone repo)
Bump 0.0.1 (patch) on every feature aggregation after tagging
If many changes accumulated since last tag, suggest tagging and bumping
Marketplace packs (first push to public GitHub):
Version MUST be 1.0.0 on first PR to demisto/content
Concatenate all changelog entries into the 1_0_0.md release notes
After first PR is merged and reviewer feedback comes, bump 0.0.1 per review cycle
Ask user: "Has an initial PR been filed? Is this feedback from an XSOAR developer review?"
Bumping Version
When ANY pack file changes:
Increment currentVersion in pack_metadata.json by 0.0.1
Create ReleaseNotes/<new_version_underscored>.md
Document ALL changes in release notes using official format
CRITICAL: Documentation Updates with EVERY Feature
Every feature, bug fix, or change MUST include updates to ALL THREE doc files in the SAME commit:
ReleaseNotes/.md -- What changed and why (bullet points per component)
Packs//README.md -- Full pack documentation (commands, args, outputs, examples)
Integrations//_description.md -- UI configuration panel help text
This is NOT optional. Code changes without corresponding doc updates are incomplete. If you add a command, the README must document it. If you change an argument, the README table must reflect it. If you add a config parameter, the description file must explain it.
Release Notes Format
#### Integrations##### <IntegrationDisplayName>- Added **new-command-name** command to retrieve X.
- Fixed an issue where Y did not work correctly.
- Updated Docker image to *demisto/python3:3.10.14.100715*.
#### Scripts##### <ScriptDisplayName>- Improved performance of Z processing.
#### Playbooks##### <PlaybookDisplayName>- Added new sub-playbook for handling W.
CRITICAL: Use pure ASCII in release notes. No arrows, smart quotes, em dashes.
Phase 5: README Generation - MUST BE COMPREHENSIVE
CRITICAL: The pack README.md is the primary documentation. It MUST be updated with EVERY feature or change -- not just at tag time. Every command, argument, output, and configuration option must be fully documented with markdown tables.
When to Update README
Adding a new command -> Add full command section with args table, outputs table, example
Changing an argument -> Update the args table
Adding a config parameter -> Update the Configuration table
Adding a script or playbook -> Add new section
Any user-visible change -> Update relevant README section
Pack README Structure (MANDATORY - all sections required)
# <PackName><Detailedparagraphexplainingwhatthispackdoes, whatserviceitintegrateswith,
whatusecasesitsupports (e.g., threatintelligenceenrichment, incidentresponse,
assettracking), andwhyasecurityteamwoulduseit.>## Dependencies
This pack requires the following packs:
-**<PackName>** (mandatory/optional) -- <briefreason>*No dependencies* if none are needed.
## Integrations### <IntegrationName><Detaileddescription:whattheintegrationconnectsto, whatcapabilitiesitprovides,
whatAPIitwraps, anysubscriptionorlicenserequirements.>#### Authentication<Explaintheauthmethod:APIkey, OAuth, basicauth, etc.><Howtoobtaincredentialsstepbystep.><Requiredpermissionsorscopes.>#### Configuration
| Parameter | Description | Required | Default |
| --- | --- | --- | --- |
| Server URL | Base URL of the <service> API | True | `https://api.example.com` |
| API Key | API authentication token | True | |
| Trust any certificate | Skip SSL verification | False | False |
| Use system proxy | Route through system proxy | False | False |
#### Commands
| Command | Description |
| --- | --- |
| prefix-command-one | Brief description of what it does |
| prefix-command-two | Brief description of what it does |
---
### prefix-command-one<Fulldescriptionofwhatthiscommanddoes, whentouseit, andanyimportantbehaviornotes.>#### Input
| Argument | Description | Required | Default |
| --- | --- | --- | --- |
| arg1 | What this argument controls | True | |
| arg2 | Filter or limit option | False | `50` |
| arg3 | Comma-separated list of values | False | |
#### Context Output
| Path | Type | Description |
| --- | --- | --- |
| Prefix.Object.Field1 | String | What this field contains |
| Prefix.Object.Field2 | Number | What this number represents |
| Prefix.Object.Field3 | Boolean | What this flag indicates |
#### Command Example
\`\`\`
!prefix-command-one arg1=value arg2=10
\`\`\`
#### Human Readable Output> Show a realistic example of the markdown table output the user will see in the War Room.
---
### prefix-command-two<Repeatthesamedetailedstructureforeverycommand.>
(... repeat for ALL commands ...)
## Scripts### <ScriptName><Whatthescriptdoes, whenitruns, whatinputs/outputsithas.>
| Argument | Description |
| --- | --- |
| arg1 | Description |
## Playbooks### <PlaybookName><Descriptionoftheplaybookflow, whattriggersit, whatitautomates, andtheexpectedoutcome.>#### Playbook Flow1. Step one -- what happens
2. Step two -- what happens
3. Step three -- what happens
## Known Limitations-<AnyAPIratelimits, unsupportedfeatures, orplatformrestrictions.>## Troubleshooting
| Issue | Solution |
| --- | --- |
| Error message X | How to fix it |
Auto-generate Docs (Starting Point Only)
Use demisto-sdk generate-docs to scaffold the README, then you MUST review and enhance the output:
This requires command_examples.txt to exist with example commands.
After running generate-docs, you MUST:
Review the generated README.md for accuracy and completeness
Add detailed descriptions to every command (not just the one-liners from YAML)
Add an Authentication section explaining how to get credentials
Add a Known Limitations section if applicable
Add a Troubleshooting section with common errors
Add realistic Command Example output for each command
Verify all argument tables match the current YAML definitions
Ensure the description paragraph at the top is informative (not a generic stub)
Fix any formatting issues or missing markdown tables
generate-docs creates a skeleton -- you create the documentation.
Phase 6: Git Workflow
CRITICAL: Exclude Zip Build Artifacts from Git
Pack zip files produced by demisto-sdk zip-packs MUST NEVER be committed or pushed to any git repository (marketplace or local). They are build artifacts only.
Before any commit, ensure .gitignore excludes zip output:
# Add to .gitignore at repo root (if not already present)echo'*_build/' >> .gitignore
echo'*.zip' >> .gitignore
echo'uploadable_packs/' >> .gitignore
Verify before staging:
# Check that no zip files or build dirs are staged
git status | grep -E '\.zip|_build|uploadable_packs' && echo"WARNING: zip artifacts staged!" || echo"OK: no zip artifacts"
Each feature gets its own branch. Zip is ONLY built after tagging on main.
main ─────────────────────────────────*──── tag v1.0.0 ──── BUILD ZIP
\ \ /
feature/feat1 feature/feat2 / (merge all to main)
(develop, (develop, /
test, lint, test, lint, /
validate, validate, /
commit) commit) /
Step-by-step for each feature:
# 1. Create feature branch from main
git checkout main
git checkout -b feature/<feature-name>
# 2. Develop (code + tests + docs in same commit)# - Write integration/script code# - Write unit tests# - Update README.md with new commands/args/outputs# - Update _description.md if config changed# - Update ReleaseNotes (or create new version file)# 3. Test + lint + validate (must all pass)# 4. Stage and commit (specific files, never git add -A)
git add Packs/<PackName>/
git commit -m "feat(<PackName>): add <feature description>"
Merging features and tagging:
# 5. When all features for this release are done, merge to main
git checkout main
git merge feature/feat1
git merge feature/feat2
# Resolve any conflicts# 6. Final validation on main
demisto-sdk validate -i Packs/<PackName>
# 7. Tag the release on main
VERSION=$(python3 -c "import json; print(json.load(open('Packs/<PackName>/pack_metadata.json'))['currentVersion'])")
git tag -a v${VERSION} -m "<PackName> v${VERSION}: <summary of all features in this release>"# 8. NOW build the zip (only after tagging)# See Phase 7 for build commands# 9. Bump version for next dev cycle# Edit pack_metadata.json: 1.0.0 -> 1.0.1# Create empty ReleaseNotes/1_0_1.md stub
git add Packs/<PackName>/pack_metadata.json Packs/<PackName>/ReleaseNotes/
git commit -m "version(<PackName>): bump to v1.0.1 for next development cycle"
Develop pack in Packs/<PackName>/ (code + tests + docs together)
Run full validation suite
Commit and push to fork
Open PR against demisto/content
Address reviewer feedback (bump version 0.0.1 per review cycle)
Do NOT build zip -- marketplace CI handles it
Local Git Workflow
Work in private repository (content-ci-cd-template or content fork)
Create feature branch for EACH feature
Develop + test + lint + validate + update docs on each branch
Merge all feature branches to main when validated
Tag release on main
Build zip ONLY after tagging
Deploy zip to XSOAR instance
Phase 7: Build and Deploy
CRITICAL: Zip is ONLY Built After a Git Tag
DO NOT build a zip pack from a feature branch or untagged main. The build process is:
All features merged to main
demisto-sdk validate passes on main
Git tag created (e.g., v1.0.0)
THEN build the zip
If the user asks to build a zip and there is no tag, ask: "Should I tag this release first?"
Build Zip Pack
ALWAYS use demisto-sdk zip-packs (not regular zip). Output filename MUST include the version:
# Verify we are on a tagged commit
git describe --exact-match --tags HEAD || echo"WARNING: HEAD is not tagged! Tag first."# Get version from pack_metadata.json
VERSION=$(python3 -c "import json; print(json.load(open('Packs/<PackName>/pack_metadata.json'))['currentVersion'])")
# Handle Lists bug workaroundif [ -d "Packs/<PackName>/Lists" ]; thenmv Packs/<PackName>/Lists Packs/<PackName>/Lists.bak
fi
demisto-sdk zip-packs -i Packs/<PackName> -o <PackName>_build
# Restore Listsif [ -d "Packs/<PackName>/Lists.bak" ]; thenmv Packs/<PackName>/Lists.bak Packs/<PackName>/Lists
fi# MUST rename with version in filenamecp <PackName>_build/uploadable_packs/<PackName>.zip <PackName>-${VERSION}.zip
# Clean up build directory (do NOT commit it)rm -rf <PackName>_build
echo"Built: <PackName>-${VERSION}.zip"
Zip filename format: <PackName>-<version>.zip (e.g., MyIntegration-1.0.0.zip)
For marketplace packs: Do NOT store the zip in the git repo that will be pushed. CI handles zip building.
For local packs: Ask user where to store the zip. Common: /var/www/packs/ or custom path.
NEVER commit zip files or build directories to git (see Phase 6 .gitignore rules).
MANDATORY: Post-Build Deployment Prompt
After EVERY zip build, ALWAYS ask the user these questions (do NOT skip):
"Should I upload this pack to your XSOAR instance?"
"Should I create/update an integration instance and test it?"
Only proceed with deployment if the user confirms. If the user says yes, use the appropriate deployment method below.
Deploy to XSOAR Instance
ALWAYS use demisto-sdk upload as the primary upload method. Only fall back to alternatives if demisto-sdk upload fails.
Primary Method: demisto-sdk upload (ALWAYS USE THIS)
# Set env vars (check CLAUDE.md or ask user for values)export DEMISTO_BASE_URL=<url>
export DEMISTO_API_KEY=<key>
# Upload the pack directly (uploads source, not zip)
demisto-sdk upload -i Packs/<PackName> --insecure
# OR upload a built zip file
demisto-sdk upload -i <PackName>-<version>.zip --insecure
CRITICAL: This is the ONLY recommended method for uploading packs. It handles unification, signature issues, and content validation automatically.
Alternative: Upload via demisto-client (Python API) -- ONLY if demisto-sdk upload fails
import demisto_client
# Configure client (see XSOAR API Reference for auth differences)
api_instance = demisto_client.configure(
base_url="https://<xsoar-url>",
api_key="<api-key>",
verify_ssl=False
)
# Upload pack zip filewithopen('<PackName>-<version>.zip', 'rb') as f:
zip_content = f.read()
response, status, _ = demisto_client.generic_request_func(
self=api_instance,
method="POST",
path="/contentpacks/installed/upload",
body=zip_content,
content_type="application/zip",
response_type="object"
)
print(f"Upload status: {status}")
Method 3: Create Integration Instance via demisto-client
After uploading a pack, create and test an integration instance:
import demisto_client
api_instance = demisto_client.configure(
base_url="https://<xsoar-url>",
api_key="<api-key>",
verify_ssl=False
)
# 1. Search for the integration to get its full configuration schema
response, status, _ = demisto_client.generic_request_func(
self=api_instance,
method="POST",
path="/settings/integration/search",
body={"query": "<IntegrationName>"},
response_type="object"
)
# 2. Get the integration configuration from search results
integrations = response.get("configurations", [])
integration_config = Nonefor config in integrations:
if config.get("display") == "<Integration Display Name>":
integration_config = config
break# 3. Build the instance payload# CRITICAL: Instance structure is DIFFERENT from integration definition structure# - "enabled" must be string "true", not boolean# - "version" must be 0 for new instances# - "configuration" is a NESTED OBJECT (integration reference), NOT the params array# - "data" is the params array (from search response's "configuration" array)# - "configvalues" is a simple dict of param_name -> value# - "configtypes" is a simple dict of param_name -> type_int# The search response has "configuration" as an ARRAY of param defs.# For the instance PUT, those param defs go into "data" (not "configuration")
config_params = integration_config.get("configuration", [])
# Build data array with values set
data_array = []
configvalues = {}
configtypes = {}
for param in config_params:
item = param.copy()
pname = param.get("name", "")
ptype = param.get("type", 0)
if pname == "url":
item["value"] = "https://api.example.com"
item["hasvalue"] = True
configvalues["url"] = "https://api.example.com"
configtypes["url"] = ptype
elif pname == "insecure":
item["value"] = True
item["hasvalue"] = True
configvalues["insecure"] = True
configtypes["insecure"] = ptype
# Type 4 (encrypted) params: set value directly in configvalueselif pname == "apikey"and ptype == 4:
item["hasvalue"] = True
configvalues["apikey"] = "<api-key-value>"
configtypes["apikey"] = ptype
# Type 9 (auth) params: set identifier+password in configvalueselif pname == "credentials"and ptype == 9:
item["hasvalue"] = True
configvalues["credentials"] = {"identifier": "user@email.com", "password": "<pass>"}
configtypes["credentials"] = ptype
data_array.append(item)
# Build nested configuration (integration definition reference - mostly empty)
nested_config = {
"id": "", "version": 0, "cacheVersn": 0,
"modified": "0001-01-01T00:00:00Z", "created": "0001-01-01T00:00:00Z",
"sizeInBytes": 0, "packID": "", "packName": "", "itemVersion": "",
"fromServerVersion": "", "toServerVersion": "", "definitionId": "",
"vcShouldIgnore": False, "vcShouldKeepItemLegacyProdMachine": False,
"commitMessage": "", "shouldCommit": False, "name": "", "prevName": "",
"display": integration_config.get("display", ""),
"brand": "", "category": "", "icon": "", "description": "",
"configuration": None, "integrationScript": None,
"hidden": False, "canGetSamples": False,
}
instance_payload = {
"id": "", "version": 0, "enabled": "true",
"name": "<instance-name>",
"brand": integration_config["id"], # Must match integration ID"category": integration_config.get("category", ""),
"configuration": nested_config, # Nested integration ref (object, NOT array)"data": data_array, # Param values (array from search "configuration")"configvalues": configvalues, # Simple key-value param map"configtypes": configtypes, # Simple key-type param map"isIntegrationScript": True,
"propagationLabels": ["all"],
}
# 4. Create the instance
response, status, _ = demisto_client.generic_request_func(
self=api_instance,
method="PUT",
path="/settings/integration",
body=instance_payload,
response_type="object"
)
print(f"Instance creation status: {status}")
# status 200 = success, response contains instance ID# 5. Test the instance
response, status, _ = demisto_client.generic_request_func(
self=api_instance,
method="POST",
path="/settings/integration/test",
body=instance_payload,
response_type="object"
)
print(f"Test result: {response}")
Key gotchas for instance creation:
enabled MUST be string "true", not boolean True
Credential parameters use {"identifier": "", "password": "<value>"} format in configvalues
version: 0 for new instances, version: -1 for updating existing ones
The full integration config from search results provides the required schema -- modify it, don't build from scratch
Parameter values go in the data array items (set value and hasvalue: True)
Method 4: API install via CoreRESTAPI
If CoreRESTAPI integration is configured on XSOAR:
CRITICAL: If a command argument expects a list (comma-separated), set isArray: true in the YAML argument definition. Use argToList() in Python to parse it.
Error handling: return_error() in main, never let stack traces reach War Room
Logging: demisto.debug(), demisto.info(), demisto.error() - never print()
Keep functions small (~30 lines), use early returns
Type hints on all functions
Stateless - no shared state between executions
Naming Conventions
Pack directory: PascalCase (MyPackName)
Integration/Script files: PascalCase matching directory name
User wants to develop a pack
|
+--> Marketplace (public)
| |
| +--> Fork demisto/content
| +--> Version MUST be 1.0.0 on first PR
| +--> Consolidate all changes into 1_0_0.md
| +--> Do NOT include zip in git repo
| +--> Run full demisto-sdk pre-commit
| +--> Open PR, address feedback
| +--> Bump 0.0.1 per review cycle
| +--> Sign CLA
|
+--> Local (private)
|
+--> Private git repo (or content-ci-cd-template)
+--> Start at 1.0.0, bump 0.0.1 per feature
+--> Tag releases
+--> Build zip with demisto-sdk zip-packs
+--> Deploy via upload/API/web server
+--> Ask user for zip storage location
XSOAR API Reference
Authentication by Platform
Platform
Auth Method
demisto_client.configure()
Notes
XSOAR 6
API Key only
api_key="<key>"
Standard REST API. Generate key in Settings -> API Keys
XSOAR 8
API Key + Key ID
api_key="<key>", auth_id="<key-id>"
Uses Core REST API. Key ID is shown when creating the key
If an XSOAR MCP server is configured in the project (check CLAUDE.md for location), use it for interactive XSOAR operations. A typical MCP server provides tools across categories: incidents, automations, integrations, lists, indicators, logs, migration, and utilities.
If no MCP server is available, use demisto-client or direct REST API calls as shown above.
Error Recovery
Error
Solution
UnicodeDecodeError in demisto-sdk
Non-ASCII chars in markdown - replace with ASCII equivalents
Lists processing bug in zip-packs
Move Lists dir out, zip, restore
demisto-sdk upload fails with IP URL
Use zip method and upload via UI
Pre-commit fails on Docker
Ensure Docker daemon is running
Missing CommonServerPython in tests
Copy from demisto/content repo clone (see test deps setup)
Missing DemistoClassApiModule
Copy from <content-repo>/Packs/ApiModules/Scripts/DemistoClassApiModule/
