Cortex XSOAR and XSIAM

The Stairwell integration for Cortex XSOAR and XSIAM makes Stairwell available inside your playbooks: enrichment, variant discovery, AI triage, detonation, run-to-ground, and file intake, each as a command you can call from an automation.

This is the most complete of Stairwell's integrations. If your team already runs response out of XSOAR, most of what the playbooks on this site describe by hand can be assembled here as automation.

What can it do?

Capability	What you get
File enrichment	Reputation, AV verdicts, YARA matches, and asset sightings for a hash
Variant discovery	Related and similar files, across your environment and the global corpus
AI triage	An automated summary with indicators, threat type, risk assessment, and recommended actions
File intake	Upload a suspicious file, with preflight checks and automatic retry
Object management	Query sightings, detonations, opinions, and run-to-ground results
Sandbox analysis	Trigger a detonation and retrieve behavioral results

One expectation to set on that last row: Stairwell has some detonation and is not a full sandbox. Read behavioral results as an addition to the static evidence rather than a complete profile.

What do I need before I start?

Cortex XSOAR 6.5.0 or higher.
A Stairwell account with API access.
A valid Stairwell API key.

How do I configure it?

First generate the key:

Log in to Stairwell.
Go to API/CLI Tokens.
Generate a new API token.
Copy it. This is the only time you will see it.

Then add the instance in XSOAR:

Go to Settings, then Integrations, then Servers & Services.
Search for Stairwell.
Select Add instance.
Fill in the parameters below.
Select Test to validate the connection.
Select Done.

Parameter	Required	Description
API Key	Yes	Your Stairwell API token
Use system proxy settings	No	Route through the system proxy
Trust any certificate (not secure)	No	Testing with self-signed certificates only. Do not enable in production

Run the Test before saving. It is the only step that confirms the key works, and a bad key produces command failures later that look like playbook bugs.

Commands

File Enrichment

Enrich file hashes with threat intelligence, AV verdicts, YARA matches, and sightings.

Command

stairwell-file-enrichment

Arguments

fileHash (required): MD5, SHA1, or SHA256

Example

!stairwell-file-enrichment fileHash=9fe1ac46f0cdebf03156a6232d771c14559f8daf

Output

File hashes (MD5, SHA256)
Filenames observed
Asset sightings count
Matching YARA rules
AV scanning results (engine name + verdict)

Context Path

Stairwell.File_Details

Variant Discovery

Find file variants using Stairwell similarity analysis.

Command

stairwell-variant-discovery

Arguments

sha256 (required)

Example

!stairwell-variant-discovery sha256=e7762f90024c5366807c7c145d3456f0ac3be086c0ec3557427d3c2c10a2052d

Output

Variant hashes + similarity scores
Variant metadata

Context Path

Stairwell.Variants

AI Triage Summarize

Get an AI-generated summary with IOCs and risk assessment.

Command

stairwell-ai-triage-summarize

Arguments

objectId (required): SHA256 or Stairwell object ID

Example

!stairwell-ai-triage-summarize objectId=357d2eac00ed810e597703ef2a4dfe7c57d528944e337d7f780c2d5d3ddd6283

Output

TL;DR summary
Malicious Likelihood (0-100)
Confidence score
Threat Type classification
Key findings
IOCs (URLs, IPs, paths, registry keys)
Guidance on persistence, obfuscation, exfiltration, etc.

Context Path

Stairwell.AI_Triage

File Intake Upload

Upload a file to Stairwell with validation and retry handling.

Command

stairwell-intake-upload

Arguments

assetId (required)
filePath (required)
sha256 (required)
detonationPlan (optional)
originType (optional: web or blank)
originReferrerUrl (optional)
originHostUrl (optional)
originZoneId (optional)

Example

!stairwell-intake-upload assetId=asset-123 filePath=/path/to/file.exe sha256=e7762f90024c5366807c7c145d3456f0ac3be086c0ec3557427d3c2c10a2052d

Workflow

Preflight check determines if upload is needed
If file exists → returns NO_ACTION_ALREADY_EXISTS
If upload needed → uploads with 3 retries + exponential backoff
Returns upload status and preflight response

Context Path

Stairwell.Intake

Object Sightings

List sightings of a file across your organization's assets.

Command

stairwell-object-sightings

Arguments

objectId (required)

Example

!stairwell-object-sightings objectId=357d2eac00ed810e597703ef2a4dfe7c57d528944e337d7f780c2d5d3ddd6283

Output

Sightings per asset with timestamps
Note: does not include virtual sightings from unpacked objects

Context Path

Stairwell.Sightings

Object Detonation - Trigger

Trigger a sandbox detonation.

Command

stairwell-object-detonation-trigger

Arguments

objectId (required)

Example

!stairwell-object-detonation-trigger objectId=357d2eac00ed810e597703ef2a4dfe7c57d528944e337d7f780c2d5d3ddd6283

Output

Trigger confirmation
Detonation metadata

Context Path

Stairwell.Detonation.Trigger

Object Detonation - Get

Retrieve detonation results.

Command

stairwell-object-detonation-get

Arguments

objectId (required)

Example

!stairwell-object-detonation-get objectId=357d2eac00ed810e597703ef2a4dfe7c57d528944e337d7f780c2d5d3ddd6283

Output

Detonation status + behavioral results
Execution details

Context Path

Stairwell.Detonation

Object Opinions

Retrieve Stairwell opinions/assessments for a file.

Command

stairwell-object-opinions

Arguments

objectId (required)

Example

!stairwell-object-opinions objectId=357d2eac00ed810e597703ef2a4dfe7c57d528944e337d7f780c2d5d3ddd6283

Output

List of opinions/assessments
Threat context

Context Path

Stairwell.Opinions

Run-To-Ground Generate

Trace files across your environment and map relationships.

Command

stairwell-run-to-ground-generate

Arguments

objectIds (required): comma-separated list of object IDs or hashes

Example

!stairwell-run-to-ground-generate objectIds=357d2eac00ed810e597703ef2a4dfe7c57d528944e337d7f780c2d5d3ddd6283,e7762f90024c5366807c7c145d3456f0ac3be086c0ec3557427d3c2c10a2052d

Output

RTG analysis results
File relationships and propagation links

Context Path

Stairwell.RunToGround

Use Cases

1. Automated Threat Enrichment

Enrich alerts with Stairwell intelligence and AI triage.

- name: Enrich Suspicious File
  steps:
    - name: Get File Hash
      # Extract hash from alert / incident context

    - name: Enrich with Stairwell
      command: !stairwell-file-enrichment
      args:
        fileHash: ${hash}

    - name: Get AI Analysis
      command: !stairwell-ai-triage-summarize
      args:
        objectId: ${hash}

    - name: Check Sightings
      command: !stairwell-object-sightings
      args:
        objectId: ${hash}

2. Variant Hunting

Discover and enrich similar malware variants.

- name: Hunt for Variants
  steps:
    - name: Discover Variants
      command: !stairwell-variant-discovery
      args:
        sha256: ${known_malware_hash}

    - name: Enrich Each Variant
      loop:
        for: ${Stairwell.Variants.variants}
      command: !stairwell-file-enrichment
      args:
        fileHash: ${item.hash}

3. File Upload and Analysis

Upload a file, detonate it, and retrieve results.

- name: Upload and Analyze File
  steps:
    - name: Upload File
      command: !stairwell-intake-upload
      args:
        assetId: ${asset.id}
        filePath: ${file.path}
        sha256: ${file.sha256}

    - name: Trigger Detonation
      command: !stairwell-object-detonation-trigger
      args:
        objectId: ${file.sha256}

    - name: Get Detonation Results
      # Detonations take time; add a delay/poll
      command: !stairwell-object-detonation-get
      args:
        objectId: ${file.sha256}

    - name: Get AI Summary
      command: !stairwell-ai-triage-summarize
      args:
        objectId: ${file.sha256}

4. Incident Response Investigation

End-to-end file investigation workflow.

- name: Investigate File
  steps:
    - name: Enrich File
      command: !stairwell-file-enrichment
      args:
        fileHash: ${incident.file_hash}

    - name: Get AI Analysis
      command: !stairwell-ai-triage-summarize
      args:
        objectId: ${incident.file_hash}

    - name: Find Variants
      command: !stairwell-variant-discovery
      args:
        sha256: ${incident.file_hash}

    - name: Check Sightings
      command: !stairwell-object-sightings
      args:
        objectId: ${incident.file_hash}

    - name: Generate Run-To-Ground
      command: !stairwell-run-to-ground-generate
      args:
        objectIds: ${incident.file_hash},${Stairwell.Variants.variants.hash}

API Endpoints Used

The integration calls the following Stairwell APIs:

File Reputation API
https://reputation.app.stairwell.com/api/v3/files/
Variants API
https://app.stairwell.com/v202112/variants/
Intake API
https://http.intake.app.stairwell.com/v2021.05/upload
V1 Objects API
https://app.stairwell.com/v1/objects/
V1 Base API
https://app.stairwell.com/v1/

Error Handling

404 Not Found → "File not found"
400 Bad Request → "Invalid request" with details
500 Server Errors → graceful failure messaging
Retry Logic → uploads retry 3x with exponential backoff
Timeouts
- Standard calls: 120s
- File uploads: 600s

Context Data Structures

`Stairwell.File_Details`

{
  "summary": {
    "md5": "string",
    "sha256": "string",
    "filenames": ["string"],
    "seen_assets_count": 0
  },
  "raw": {}
}

`Stairwell.Variants`

{
  "variants": [
    {
      "hash": "string",
      "similarity": 0.0
    }
  ]
}

`Stairwell.AI_Triage`

{
  "hash": "string",
  "malicious_likelihood": 95,
  "confidence": 90,
  "threat_type": "string",
  "tldr": "string",
  "raw": {}
}

`Stairwell.Intake`

{
  "preflight": {},
  "result": "already_exists | upload_completed",
  "upload_status": 200
}

`Stairwell.Sightings`

{
  "sightings": [
    {
      "asset": {},
      "timestamp": "string"
    }
  ]
}

`Stairwell.Detonation`

{
  "status": "string",
  "results": {}
}

`Stairwell.Opinions`

{
  "opinions": [
    {}
  ]
}

`Stairwell.RunToGround`

{
  "analysis": {},
  "relationships": []
}

Best Practices

API Key Security
- Store keys in XSOAR credentials
- Rotate regularly
- Use least-privilege tokens
Performance Optimization
- Use AI triage for fast assessment
- Use enrichment for deeper detail
- Batch variants for large hunts
Playbook Design
- Add wait/poll between detonation trigger and get
- Branch on AI malicious likelihood
- Combine enrichment + sightings for full context
Resilient Error Handling

- name: Safe File Enrichment
  steps:
    - name: Enrich File
      command: !stairwell-file-enrichment
      args:
        fileHash: ${hash}
      on_error:
        - name: Log Error
          # Handle enrichment failure gracefully

Data Retention
- Results stored in XSOAR incident context
- Consider retention limits for large scale cases
- Use RTG for relationship-heavy investigations

Troubleshooting

Authorization Error

Confirm API key is correct and active
Re-generate token in Stairwell dashboard if needed

File Not Found (404)

Verify hash format
Upload file first using stairwell-intake-upload

Upload Timeout

Large files may exceed 600s
Verify connectivity and file path access

Detonation Not Ready

Wait 5-10 minutes after triggering
Use polling in playbooks

Rate Limits and Quotas

Standard calls follow your Stairwell plan limits
Upload retries handle temporary throttling
Detonation: one active detonation per object at a time
AI triage quotas depend on subscription tier

For exact limits, contact Stairwell Support.

Support and Resources

Stairwell Docs: https://docs.stairwell.com
API Reference: https://docs.stairwell.com/reference
Support: [email protected]
Website: https://www.stairwell.com

Version Information

Current Integration Version: 1.0.5
Minimum XSOAR Version: 6.5.0
Python Version: 3.10.10
Docker Image: demisto/python3:3.10.10.48392

Changelog

1.0.5

Added AI Triage Summarize command
Added sightings, detonation trigger/get, opinions, RTG, intake upload
Rebranded from "Inception" to Stairwell
Enhanced parsing + retry robustness