Skip to main content

PowerShell Remoting (Beta)

Supported versions

Supported Cortex XSOAR versions: 6.0.0 and later.

beta

This is a beta Integration, which lets you implement and test pre-release software. Since the integration is beta, it might contain bugs. Updates to the integration during the beta phase might include non-backward compatible features. We appreciate your feedback on the quality and usability of the integration to help us identify issues, fix them, and continually improve.

PowerShell Remoting is a comprehensive built-in remoting subsystem that is a part of Microsoft's native Windows management framework (WMF) and Windows remote management (WinRM). This feature allows you to handle most remoting tasks in any configuration you might encounter by creating a remote PowerShell session to Windows hosts and executing commands in the created session. The integration includes out-of-the-box commands which supports agentless forensics for remote hosts.

Configure PowerShell Remoting on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for PowerShell Remoting.

  3. Click Add instance to create and configure a new integration instance.

    ParameterDescriptionRequired
    DomainFully Qualified Domain Name suffix to be added to the hostname.False
    DNSFalse
    UsernameUsername in the target machine.True
    PasswordTrue
    Test HostHostname or IP address to use as a test for the integration connectivity.False
    Authentication MethodTrue
    Trust any certificate (not secure)False
    Use SSL (HTTPS)False
  4. Click Test to validate the URLs, token, and connection.

Commands#

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

ps-remote-command#


Executes remote PowerShell commands on a single host.

Base Command#

ps-remote-command

Input#

Argument NameDescriptionRequired
hostA single hostname or IP address on which to run the command.Required
commandPowerShell commands (can be single or multiple in order of execution) to run on the target machine.Required

Context Output#

PathTypeDescription
PsRemote.HoststringThe host on which the command was invoked.
PsRemote.FQDNstringThe Fully Qualified Domain Name of the host on which the command was invoked.
PsRemote.CommandResultlistThe result of the command run from the target machine.
PsRemote.CommandNamestringThe command sent to the target machine, used as an ID of that query.
PsRemote.UTCTimestringTime the command finished execution in UTC time.

Command Example#

!ps-remote-command host=XSOAR-XSOAR command=whoami

Context Example#

{
"PsRemote": {
"UTCTime": "2021-07-18T15:46:07.2006094+00:00",
"FQDN": "XSOAR-XSOAR.winrm.local",
"Host": "XSOAR-XSOAR",
"CommandName": "whoami",
"CommandResult": [
"winrm\\administrator\n"
]
}
}

Human Readable Output#

Result for PowerShell Remote Command: whoami winrm\administrator

ps-remote-download-file#


Downloads a file from the remote endpoint.

Base Command#

ps-remote-download-file

Input#

Argument NameDescriptionRequired
hostHostname or the IP address on which to run the command.Required
pathThe path of the file to download.Required
zip_fileWhether to compress the file. Possible values: "true" and "false". Default is "false". Possible values are: true, false. Default is false.Optional
check_hashWhether to compare the value of the original file with the downloaded file and return an error if any differences are found. Possible values: "true" and "false". Default is "false". Possible values are: true, false. Default is false.Optional
host_prefixWhether to use the host as a prefix for the name of the downloaded version of the file. Possible values: "true" and "false". Default is "false". Possible values are: true, false. Default is false.Optional

Context Output#

PathTypeDescription
PsRemoteDownloadedFile.HoststringThe host from which the file was downloaded.
PsRemoteDownloadedFile.FQDNstringThe Fully Qualified Domain Name of the host from which the file was downloaded.
PsRemoteDownloadedFile.FileNameStringFile name.
PsRemoteDownloadedFile.FileSizeNumberFile size.
PsRemoteDownloadedFile.FileMD5StringThe MD5 hash of the file.
PsRemoteDownloadedFile.FileSHA1StringThe SHA1 hash of the file.
PsRemoteDownloadedFile.FileSHA256StringThe SHA256 hash of the file.
PsRemoteDownloadedFile.FileExtensionStringThe extension of the file.
File.SizeNumberThe size of the file in bytes.
File.SHA1StringThe SHA1 hash of the file.
File.SHA256StringThe SHA256 hash of the file.
File.SHA512StringThe SHA512 hash of the file.
File.NameStringThe full file name.
File.SSDeepStringThe ssdeep hash of the file.
File.EntryIDStringThe ID for locating the file in the War Room.
File.InfoStringThe file information.
File.TypeStringThe file type.
File.MD5StringThe MD5 hash of the file.
File.ExtensionStringThe file extension, for example: "txt".

Command Example#

!ps-remote-download-file host="XSOAR-XSOAR" path="c:\\XSOAR-XSOAR.etl" zip_file="true" check_hash="true" host_prefix="true"

ps-remote-upload-file#


Uploads a file to the remote endpoint.

Base Command#

ps-remote-upload-file

Input#

Argument NameDescriptionRequired
hostA single hostname or IP address on which to run the command.Required
pathThe path of the file to upload.Required
entry_idThe file entry ID to upload.Required
zip_fileWhether to compress the file before upload. Possible values: "true" and "false". Default is "false". Possible values are: true, false. Default is false.Optional
check_hashWhether to compare the values of the original file and uploaded file and return an error if any differences are found. Possible values: "true" and "false". Default is "false". Possible values are: true, false. Default is false.Optional

Context Output#

PathTypeDescription
PsRemoteUploadedFile.FileNameStringFile name.
PsRemoteUploadedFile.FilePathStringFile path in the remote server.
PsRemoteUploadedFile.FileSizeNumberFile size.
PsRemoteUploadedFile.FileMD5StringThe MD5 hash of the file.
PsRemoteUploadedFile.FileSHA1StringThe SHA1 hash of the file.
PsRemoteUploadedFile.FileSHA256StringThe SHA256 hash of the file.
PsRemoteUploadedFile.FileExtensionStringThe extension of the file.
PsRemoteUploadedFile.HoststringThe host to which the file was uploaded.
PsRemote.FQDNstringThe Fully Qualified Domain Name of the host the file was uploaded to.

Command Example#

!ps-remote-upload-file entry_id=105@1d0796aa-dde9-4f18-8f04-bbe92434ba81 host="XSOAR-XSOAR" path="c:\\tmpetl.etl"

Human Readable Output#

File 1d0796aa-dde9-4f18-8f04-bbe92434ba81_105@1d0796aa-dde9-4f18-8f04-bbe92434ba81 was uploaded successfully as: c:\tmpetl.etl

ps-remote-etl-create-start#


This command starts the recording of an ETL file on a Windows endpoint. An ETL file is just like a PCAP file which is created by the Windows Netsh command.

Base Command#

ps-remote-etl-create-start

Input#

Argument NameDescriptionRequired
hostA single hostname or IP address on which to run the command.Required
etl_pathThe path on the hostname on which to create the ETL file. For example c:\temp\myhost.etl. Default is "C:\Users\<username>\AppData\Local\Temp\NetTraces\NetTrace.etl".Required
etl_filterThe filter to apply when creating the ETL file. For example IPv4.Address=1.1.1.1 to capture traffic just from the 1.1.1.1 IP address. If no filter is specified all traffic will be recorded. For more examples, see: https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-r2-and-2012/jj129382(v=ws.11)#using-filters-to-limit-etl-trace-file-details.Optional
etl_max_sizeThe maximum file size for the ETL. Once the file has reached this size, the capture will stop. For example 10MB. The default size is 10MB. Default is 10.Optional
overwriteWhether to overwrite the file in the path. Possible values: "yes" and "no". Default is "no". Possible values are: yes, no. Default is no.Optional

Context Output#

PathTypeDescription
PsRemote.CommandResultstringThe start ETL command results.
PsRemote.EtlFileNamestringThe name of the ETL file.
PsRemote.EtlFilePathunknownThe path and name of the ETL file.
PsRemote.CommandNamestringThe name of the command that ran on the host.
PsRemote.FQDNstringThe Full Qualified Domain Name of the host.
PsRemote.HoststringThe name of the host.

Command Example#

!ps-remote-etl-create-stop host="XSOAR-XSOAR"

Human Readable Output#

Trace configuration: ------------------------------------------------------------------- Status: Running Trace File: C:\XSOAR-XSOAR__a.etl Append: Off Circular: On Max Size: 10 MB Report: Off

Context Example#

{
"PsRemote": {
"CommandResult": [
"Trace configuration:\n",
"-------------------------------------------------------------------\n",
"Status: Running\n",
"Trace File: C:\\XSOAR-XSOAR__a.etl\n",
"Append: Off\n",
"Circular: On\n",
"Max Size: 10 MB\n",
"Report: Off\n"
],
"FQDN": "XSOAR-XSOAR.winrm.local",
"EtlFilePath": "c:\\XSOAR-XSOAR__a.etl",
"UTCTime": "2021-07-18T15:58:08.2528721+00:00",
"Host": "XSOAR-XSOAR",
"CommandName": "netsh trace start capture=yes traceFile=c:\\XSOAR-XSOAR__a.etl maxsize=10 overwrite=no ",
"EtlFileName": "XSOAR-XSOAR__a.etl"
}
}

ps-remote-etl-create-stop#


Ends the recording of an ETL file on a Windows endpoint.

Base Command#

ps-remote-etl-create-stop

Input#

Argument NameDescriptionRequired
hostA single Hostname or IP address on which to run the command.Required

Context Output#

PathTypeDescription
PsRemote.CommandResultstringThe stop ETL command results.
PsRemote.CommandNamestringThe name of the command that ran on the host.
PsRemote.EtlFileNamestringThe name of the ETL file.
PsRemote.EtlFilePathunknownThe path and name of the ETL file.
PsRemote.HoststringThe host the command was invoked on.
PsRemote.FQDNstringThe Fully Qualified Domain Name of the host on which the command was invoked.

Command Example#

!ps-remote-etl-create-stop host="XSOAR-XSOAR"

Human Readable Output#

Correlating traces … done Merging traces … done Generating data collection … done The trace file and additional troubleshooting information have been compiled as "c:\XSOAR-XSOARa.cab". File location = c:\XSOAR-XSOARa.etl Tracing session was successfully stopped.

Context Example#

{
"PsRemote": {
"CommandResult": "Correlating traces ... done Merging traces ... done Generating data collection ... done The trace file and additional troubleshooting information have been compiled as \"c:\\XSOAR-XSOAR__a.cab\". File location = c:\\XSOAR-XSOAR__a.etl Tracing session was successfully stopped. ",
"FQDN": "XSOAR-XSOAR.winrm.local",
"EtlFilePath": "c:\\XSOAR-XSOAR__a.etl",
"Host": "XSOAR-XSOAR",
"CommandName": "netsh trace stop",
"EtlFileName": "XSOAR-XSOAR__a.etl"
}
}

ps-remote-export-registry#


Exports the specified registry of hive to a file.

Base Command#

ps-remote-export-registry

Input#

Argument NameDescriptionRequired
hostA single hostname or IP address on which to run the command.Required
reg_key_hiveThe registry key or hive to export. For example, reg_key_hive=HKEY_LOCAL_MACHINE. If the user specifies "all", the entire registry will be exported. Default is "all". Default is all.Optional
file_pathThe path and name on the Windows host where the registry file will be created. For example, file_path=c:\hklm.reg.Required

Context Output#

PathTypeDescription
PsRemote.CommandResultstringThe command results in the remote host - regedit for all or reg export.
PsRemote.RegistryFilePathstringThe path and name of the registry file.
PsRemote.RegistryFileNamestringThe name of the registry file.
PsRemote.Command.NamestringThe name of the command that ran on the host.
PsRemote.FqdnstringThe Full Qualified Domain Name of the host.
PsRemote.HoststringThe host on which the command was invoked.
PsRemote.FQDNstringThe Fully Qualified Domain Name of the host on which the command was invoked.

Command Example#

!ps-remote-export-registry host="XSOAR-XSOAR" file_path="c:\\XSOAR-XSOAR__a.reg"

Human Readable Output#

Ran Export Registry. Registry file expected path: c:\XSOAR-XSOAR__a.reg

Context Example#

{
"PsRemote": {
"RegistryFileName": "XSOAR-XSOAR__a.reg",
"RegistryFilePath": "c:\\XSOAR-XSOAR__a.reg",
"FQDN": "XSOAR-XSOAR.winrm.local",
"CommandName": "regedit /e c:\\XSOAR-XSOAR__a.reg",
"Host": "XSOAR-XSOAR",
"CommandResult": null
}
}

ps-remote-export-mft#


Extracts the master file table from the volume.

Base Command#

ps-remote-export-mft

Input#

Argument NameDescriptionRequired
hostA single hostname or IP address on which to run the command.Required
volumeThe volume from which to retrieve its master file table.Optional
output_pathThe path in which the MFT file is to be created.Optional

Context Output#

PathTypeDescription
PsRemote.ExportMFTunknownThe extract master file table command result.
PsRemote.HoststringThe host on which the command was invoked.
PsRemote.FQDNstringThe Fully Qualified Domain Name of the host on which the command was invoked.

Command Example#

!ps-remote-export-mft host="XSOAR-XSOAR" volume=C

Human Readable Output#

MFT Export results:#

ComputerNameMFT FileMFT SizeMFT VolumeNetworkPathPSComputerNamePSShowComputerNameRunspaceId
XSOAR-XSOARC:\Users\ADMINI~1\AppData\Local\Temp\zzthh5sh.hl2222 MBC\\XSOAR-XSOAR\C$\Users\ADMINI~1\AppData\Local\Temp\zzthh5sh.hl2XSOAR-XSOAR.winrm.localtrue{"value":"58aa1f39-f86d-4f18-978a-c9257295df49","Guid":"58aa1f39-f86d-4f18-978a-c9257295df49"}

Context Example#

{
"PsRemote": {
"ExportMFT": {
"ComputerName": "XSOAR-XSOAR",
"MFT File": "C:\\Users\\ADMINI~1\\AppData\\Local\\Temp\\zzthh5sh.hl2",
"MFT Size": "222 MB",
"PSComputerName": "XSOAR-XSOAR.winrm.local",
"NetworkPath": "\\\\XSOAR-XSOAR\\C$\\Users\\ADMINI~1\\AppData\\Local\\Temp\\zzthh5sh.hl2",
"MFT Volume": "C",
"RunspaceId": "58aa1f39-f86d-4f18-978a-c9257295df49",
"PSShowComputerName": true
},
"Host": "XSOAR-XSOAR",
"FQDN": "XSOAR-XSOAR.winrm.local"
}
}