Workflow SDK Reference

Reference documentation for custom script steps inside Versus workflows — the versus and integrations objects exposed to script code, the full step catalog available to the visual workflow builder, FQL (Falcon Query Language) syntax for CrowdStrike filtering, and the library of built-in workflows shipped with Versus.

Covers device inventory and direct F5 TMSH/iControl REST access, generic SSH/troubleshooting helpers, ServiceNow and AI shortcuts on versus itself, and integration clients for ServiceNow, AWX/Tower, and CrowdStrike. Zscaler and F5 are not exposed as general-purpose SDK client objects — see the notes below.

📄 Download as PDF: versus-sdk-reference.pdf — the complete method surface for offline reading. The always-current copy is the SDK Reference panel inside any Python step, which autocompletes as you type versus.; the full auto-generated list is also at the bottom of this page.

---

Script step globals

Which globals are injected depends on the step type — the two script-capable steps do not receive the same objects. ctx is an internal object passed to built-in step implementations; it is not exposed to user-written scripts.

• Python Script (core.python_script) — only versus is injected. Reach integrations via versus.integrations.
• HTTP Request (core.http_request) — only http (a get/post/put/patch/delete client) and integrations are injected. versus is not available here.

Never import from apps.* directly inside a script — the sandbox restricts builtins to a safe subset (no file I/O, no __import__, no subprocess, no open()); network and database access happens only through the injected objects.

# Example — core.python_script step (versus injected, integrations reached via versus.integrations)
cs = versus.integrations.crowdstrike()
host = cs.find_host(versus.get_input('target_hostname'))
if host and host['containment_status'] == 'normal':
    cs.contain_hosts([host['aid']])
    versus.log(f"Contained {host['hostname']}")
    versus.set_output('contained_aid', host['aid'])

---

The versus object (VersusSDK)

Injected as versus in Python Script steps. Read access to Versus inventory data, controlled write access to devices (TMSH / iControl REST / SSH), and shortcuts for ServiceNow and the default AI provider.

Logging & variables

Devices & applications

Device dict keys: id, hostname, mgmt_ip, vendor, device_type, status, model, software_version, ha_state

F5 direct access (TMSH / iControl REST)

All three raise RuntimeError if the target device has no credential configured. There is no separate F5 integration client — this direct access is the F5 SDK surface (see F5 BIG-IP below).

Generic device access & troubleshooting

All of these return raw CLI/API output as a string for the script to parse — they do not return structured dicts.

Native vendor troubleshooting (versus.probe)

Beyond the generic helpers above, versus.probe(device_id, kind) runs a read-only probe using the device's own native driver — the same drivers Diagnostics AutoPilot uses — across 23 vendor families (NetScaler, PAN-OS, FortiGate, Check Point incl. SMS Web API, Cisco ACI/ASA/IOS-XE/NX-OS, Arista, AVI, Kemp, Alteon, NSX-T, Infoblox, EfficientIP, BlueCat, Cloudflare, AWS/Azure LB, F5 XC, F5OS (rSeries/VELOS), A10). versus.available_probes(device_id) lists what a device supports; versus.vendor_family(device_id) returns the detected family. See the Complete method reference for every family's probe kinds.

# Check HA state on every ADC in a device group, natively per vendor
for dev in versus.devices(device_type="adc"):
    fam = versus.vendor_family(dev["id"])           # 'netscaler' | 'avi' | 'f5xc' | ...
    if not fam:
        continue                                    # no native driver — use versus.run_ssh() instead
    versus.log(dev["hostname"], fam, versus.probe(dev["id"], "ha"))
    versus.log(versus.probe(dev["id"], "vs_status", vs_name="app1"))   # kinds can take args

versus.probe returns a formatted string, or None when that vendor has no native driver for the requested kind.

Vulnerability tracking

AI

ServiceNow shortcuts

Note: create_snow_incident() and create_snow_change() catch integration errors internally, log a warning, and return {} instead of raising — check for an empty dict before using the result. The read-oriented shortcuts (check_snow_approval, get_snow_info, etc.) raise RuntimeError if no ServiceNow instance is configured. These shortcuts use the first configured instance only — for named-instance access or the full method set, use versus.integrations.snow().

Integrations access

---

ServiceNow

Authentication: Basic auth or OAuth2 password grant, plus an optional outbound proxy (proxy_host / proxy_port under System Settings). Configure the instance under Integrations → Service Now.

integrations.snow(name=None) → ServiceNowClient (the first/only configured instance — Versus supports one ServiceNow instance per environment today, so name is rarely needed)

There is no generic .get_record(table, sys_id) or .update_change_request(sys_id, work_notes, state) method — use add_work_notes() to append notes and close_change() to terminate a change. Change/task lookups are by number (e.g. 'CHG0001234'), not sys_id.

# Create a change, wait for approval, then close it on success
snow = versus.integrations.snow()
chg = snow.create_change_request(
    short_description='Deploy new WAF policy to bigip-01',
    description=versus.get_input('change_description', ''),
    risk='3', impact='3',
)
versus.set_output('change_number', chg['number'])

approved, state_label, msg = snow.is_approved(chg['number'])
if not approved:
    raise RuntimeError(f"Change {chg['number']} not approved yet: {msg}")

snow.close_change(chg['number'], close_notes='Deployed successfully via Versus workflow')

---

Rundeck

integrations.rundeck(name=None) → UnifiedRundeckClient

System & projects: .test_connection(), .system_info(), .list_projects(), .get_project(project=None)

Jobs: .list_jobs(project, group_path, job_filter), .get_job(job_id), .find_job(job_name, project, group_path), .export_job_yaml(job_id)

Triggering & tracking: .run_job(job_id, options=None, node_filter=None, as_user=None), .run_job_by_name(job_name, project, options, node_filter, …), .run_and_wait(job_id=None, job_name=None, project=None, options=None, node_filter=None, timeout=300, poll_interval=3), .get_execution(execution_id), .list_executions(job_id, status=None, max_results=20), .list_running_executions(project=None), .abort_execution(execution_id), .wait_for_completion(execution_id, poll_interval=3, timeout=300)

Output & nodes: .get_output(execution_id, offset=0, max_lines=500), .get_full_output(execution_id), .get_output_text(execution_id), .list_nodes(project=None, node_filter=None), .get_node(node_name, project=None)

Also available: .list_keys(path='/'), .get_scm_status(), and .perform_scm_action() for Key Storage and job SCM integration.

For simple "trigger this job and wait" use cases, the visual builder's core.rundeck step (see Step Catalog) wraps run_job + polling without needing a Python Script step at all.

# Run a Rundeck job and check the result
rd = versus.integrations.rundeck()
result = rd.run_and_wait('Deploy ACL', options={'vlan': '100', 'device': 'bigip-01'})
if result['status'] != 'succeeded':
    log = rd.get_output_text(result['id'])
    raise RuntimeError(f"Rundeck job failed: {result['status']}\n{log[:1000]}")

---

AWX / Ansible Tower

Authentication: Bearer token (Personal Access Token from AWX user settings). Configure under Integrations → AWX / Tower.

integrations.awx_list() — Returns all enabled AWX sources: {id, name, url, status}

integrations.awx(name=None) → UnifiedAWXClient

Job Templates: .list_job_templates(name=None), .get_job_template(id), .find_job_template(name) (raises RuntimeError if not found), .launch_job_template(template_id, extra_vars, inventory, limit, credential_ids), .run_and_wait(template_id, extra_vars, inventory, limit, credential_ids, timeout=600, poll_interval=10)

Jobs: .get_job(job_id), .list_jobs(template_id=None, status=None), .get_job_stdout(job_id), .cancel_job(job_id), .wait_for_completion(job_id, timeout=600, poll_interval=10)

Projects & Inventory: .list_inventories(), .list_projects(), .sync_project(project_id)

Workflow Templates: .list_workflow_templates(), .launch_workflow_template(template_id, extra_vars, inventory)

# Run an AWX job template and surface output on failure
awx = versus.integrations.awx()
job = awx.run_and_wait(
    template_id=42,
    extra_vars={'target': versus.get_input('hostname')},
    limit=versus.get_input('hostname'),
    timeout=3600,
)
if job['status'] != 'successful':
    versus.log(awx.get_job_stdout(job['id']))
    raise RuntimeError(f"Job {job['id']} failed: {job['status']}")

---

CrowdStrike Falcon

Authentication: OAuth2 client-credentials. Token auto-refreshes every 30 min (60 s buffer). Configure Client ID and Secret under Integrations → CrowdStrike. Base URL defaults to https://api.crowdstrike.com — change to US-2, EU-1, or US-GOV-1 as needed.

integrations.crowdstrike_list() — Returns enabled sources: {id, name, base_url, status}

integrations.crowdstrike(name=None) → UnifiedCrowdStrikeClient

Hosts: .find_host(hostname) → dict|None, .list_hosts(filter_fql, limit=100) → list[dict], .get_host_details(aids) → list[dict], .search_hosts(filter_fql, limit=100) → list[str]

Host dict keys: aid, hostname, platform, os_version, agent_version, status, containment_status, external_ip, local_ip, mac_address, first_seen, last_seen, groups, tags

Containment: .contain_hosts(aids), .lift_containment(aids)

Detections: .search_detections(filter_fql, limit=50) → list[str], .list_detections(filter_fql, limit=50) → list[dict], .get_detection_details(detection_ids), .update_detection(detection_id, status, assigned_to_uuid, comment)

Status values: new · in_progress · true_positive · false_positive · ignored · closed · reopened

Alerts & Incidents: .search_alerts(filter_fql, limit=50), .list_alerts(filter_fql, limit=50), .update_alerts(alert_ids, action_params), .search_incidents(filter_fql, limit=50), .list_incidents(filter_fql, limit=50)

Spotlight (Vulnerabilities): .get_host_vulnerabilities(aid, limit=100), .search_vulnerabilities(filter_fql, limit=100), .get_vulnerability_details(vuln_ids)

Vuln dict keys: id, aid, hostname, cve_id, severity, severity_name, description, status, remediation, created, updated

Real Time Response (RTR): .run_rtr_script(aid, script, timeout=120), .init_rtr_session(aid), .run_rtr_command(session_id, command, base_command='runscript', timeout=120), .get_rtr_result(cloud_request_id, sequence_id=0), .delete_rtr_session(session_id)

Policies & Groups: .list_prevention_policies(), .list_host_groups(), .get_host_group_members(group_id)

FQL (Falcon Query Language) examples

"hostname:'BIGIP-01'"
"platform_name:'Windows'"
"status:'contained'"
"tags:'CriticalInfra'"
"status:'new'+max_severity_displayname:'Critical'"
"aid:'abc123'+status:'open'"

# Contain a host and log open CVEs
cs = versus.integrations.crowdstrike()
host = cs.find_host(versus.get_input('target_hostname'))
if not host:
    raise RuntimeError('Host not found in Falcon')

cs.contain_hosts([host['aid']])
versus.log(f"Contained {host['hostname']} (AID {host['aid']})")

vulns = cs.get_host_vulnerabilities(host['aid'])
critical = [v for v in vulns if v['severity_name'] == 'CRITICAL']
versus.log(f"{len(critical)} critical CVEs on {host['hostname']}")
versus.set_output('contained_aid', host['aid'])
versus.set_output('critical_vuln_count', len(critical))

---

Zscaler

Unlike ServiceNow, AWX, and CrowdStrike, Zscaler has no integrations.zscaler() SDK client — there is no UnifiedZscalerClient and no general-purpose firewall-rule API reachable from a custom script. Zscaler ZIA/ZPA access is a fixed set of workflow steps (zscaler.zia_* / zscaler.zpa_*) built for the Zscaler upgrade-orchestration workflow — see the Zscaler group in the Step Catalog below for the full list.

---

F5 BIG-IP

F5 also has no integrations.f5() client / UnifiedF5Client. F5 BIG-IP is a first-class device type, so access from a custom script goes through versus directly: run_tmsh(), http_get(), and http_patch() (documented under "F5 direct access" above), plus the vendor-aware helpers (get_vs_status, get_pool_status, check_ha_status, etc.) that work across F5 and other ADC vendors. Software upgrades, decommissioning, and pool/WideIP maintenance are handled by a large dedicated f5.* step family used by the built-in F5 workflows — see the F5 BIG-IP group in the Step Catalog below.

# Pull VS status and pool health directly from an F5 via TMSH
device = versus.devices(vendor='f5_bigip', hostname='bigip-01')[0]
vs_status = versus.get_vs_status(device['id'], vs_name='vs_https_443')
versus.log(vs_status)

pool_health = versus.http_get(device['id'], '/mgmt/tm/ltm/pool/~Common~pool_web/members')
down = [m for m in pool_health.get('items', []) if m.get('state') != 'up']
if down:
    versus.set_output('pool_members_down', [m['name'] for m in down])

---

Step Catalog

Steps are the building blocks of visual workflows. Each step has a key (e.g. crowdstrike.contain_host), a display label, and a config schema. Steps store outputs as context variables accessible by downstream steps.

There is no dedicated "ServiceNow" step category in the palette. ServiceNow actions are performed from a Python Script step using the versus.create_snow_* shortcuts or versus.integrations.snow(). A handful of narrowly-scoped ServiceNow steps do exist (snow.create_cr, snow.check_change, snow.close_change, checkpoint.snow_create_cr, and siblings) but they're wired into the internals of specific built-in upgrade workflows rather than general-purpose palette items.

Core

AWX / Ansible Tower

CrowdStrike Falcon

Zscaler

F5 BIG-IP

Partial list — F5 has the largest step catalog in Versus (~20 more covering config-load verification, NTP/license checks, HA member snapshots, auto-sync toggling, decommissioning, and WideIP decommissioning). Browse the full set from the step palette under the F5 category.

---

Built-in Workflows

Built-in workflows are pre-built, version-controlled templates seeded into every Versus instance. Use them as-is or clone and customise. Find them under Workflows → All Workflows → Built-in. The table below covers the workflows built directly on the integrations documented on this page (ServiceNow, AWX, CrowdStrike) — Versus also ships a much larger library of vendor upgrade/decommission workflows (F5, NetScaler, Palo Alto, Cisco IOS, Check Point, Zscaler, Alteon, vSphere) that isn't reproduced here.

Built-in workflows are seeded by migrations and updated with each Versus release. Cloning a built-in workflow lets you customise it without losing the ability to compare against the original.

---

Complete method reference

Everything below is generated by introspecting the live SDK, so it matches the current platform exactly. The always-current copy is the SDK Reference panel in any Python step (it autocompletes as you type versus.); this page and the downloadable PDF are a point-in-time snapshot for reading offline.

At a glance: 41 core methods, 34 integration methods across the providers below, and native troubleshooting across 23 vendor families.

Core — versus.* (41)

Integrations — versus.integrations.* (34)

Each provider exposes a <name>_list() (list configured instances) and a <name>(name=None) accessor that returns a client with its own methods. Those per-client methods are documented inline in the in-app panel and the PDF.

Native vendor troubleshooting — versus.probe(...)

versus.probe(device_id, kind, **args) runs one read-only probe using the device's own native driver (the same drivers Diagnostics AutoPilot uses), returning a formatted string — or None when that vendor has no native driver for the probe (fall back to versus.run_ssh(...)). versus.available_probes(device_id) lists what a device supports and versus.vendor_family(device_id) returns its detected family.

Probe kinds: health, ha, stats, vs_status, pool_status, interfaces, routes, arp, objects, certs, events, sessions, cpu, bgp, vs_stats, capture.