readme.html

<!-- File: readme.html
  Copyright (c) 2019-2023 Splunk Inc.

  Licensed under Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0.txt)
-->

<h2>Preprocess Script</h2>
<p>
The user can add a script file in the configuration parameter [<b>Script with functions to preprocess containers and artifacts</b>]. The script must contain a function with the name <b>preprocess_container</b> (to pre-process the containers and the artifacts) or else, it will throw an error.
</p>

<h2>App ID</h2>
<ul>
 <li>Optionally, you can specify an <b>App ID</b> to be used with the Crowdstrike OAuth API used in the on poll action. If one isn't set, it will default to the asset ID.</li>
 <li>It is recommended to have a unique <b>App ID</b> for each connection to the Crowdstrike OAuth API. That is to say, if you are planning on having multiple assets using the Crowdstrike OAuth API at once, you should give them unique App IDs.</li>
</ul>

<h2>On Poll</h2>
 <ul>
     <li>Common points for both manual and scheduled interval polling
         <ul>
             <li>
                 Default parameters of the On Poll action are ignored in the app. i.e. start_time, end_time, container_count, artifact_count
             </li>
             <li>
                 The app will fetch all the events based on the value specified in the configuration parameters [Maximum events to get while POLL NOW] (default 2000 if not specified) and [Maximum events to get while scheduled and interval polling] (default 10,000 if not specified). For ingestion, the events are fetched after filtering them based on the event type - <b>DetectionSummaryEvent</b>. The app will exit from the polling cycle in the below-mentioned 2 cases whichever is earlier.
                 <ul>
                     <li>If the total DetectionSummaryEvents fetched equals the value provided in the [Maximum events to get while POLL NOW] (for manual polling) or [Maximum events to get while scheduled and interval polling] (for scheduled | interval polling) parameters</li>
                     <li>If the total number of continuous blank lines encountered while streaming the data equals the value provided in the [Maximum allowed continuous blank lines] (default 50 if not specified) asset configuration parameter</li>
                 </ul>
             </li>
             <li>
                 The default behavior of the app is that each event will be placed in its container.
                 By checking the configuration parameter [Merge containers for Hostname and Eventname] as well as specifying an interval in the configuration parameter [Merge same containers within specified seconds], all events which are of the same type and on the same host will be put into one container, as long as the time between those two events is less than the interval.
             </li>
             <li>
                 The [Maximum allowed continuous blank lines] asset configuration parameter will be used to indicate the allowed number of continuous blank lines while fetching <b>DetectionSummaryEvents</b>. For example, of the entire data of the DetectionSummaryEvents, some of the 'DetectionSummaryEvents' exists after 100 continuous blank lines and if you've set the [Maximum allowed continues blank lines] parameter value to 500, it will keep on ingesting all the 'DetectionSummaryEvents' until the code gets 500 continuous blank lines and hence, it will be able to cover the DetectionSummaryEvents successfully even after the 100 blank lines. If you set it to 50, it will break after the 50th blank line is encountered. Hence, it won't be able to ingest the events which exist after the 100 continuous blank lines because the code considers that after the configured value in the [Maximum allowed continuous blank lines] configuration parameter (here 50), there is no data available for the 'DetectionSummaryEvents'.
             </li>
         </ul>
     </li>

     <li>Manual Polling
         <ul>
             <li>
                 During manual poll now, the app starts from the first event that it can query up to the value configured in the configuration parameter [Maximum events to get while POLL NOW] and creates artifacts for all the fetched DetectionSummaryEvents. The last queried event's offset ID will not be remembered in Manual POLL NOW and it fetches everything every time from the beginning.
             </li>
         </ul>
     </li>

     <li>Scheduled | Interval Polling
         <ul>
             <li>
                 During scheduled | interval polling, the app starts from the first event that it can query up to the value configured in the configuration parameter [Maximum events to get while scheduled and interval polling] and creates artifacts for all the fetched DetectionSummaryEvents. Then, it remembers the last event's offset ID and stores it in the state file against the key [last_offset_id]. In the next scheduled poll run, it will start from the stored offset ID in the state file and will fetch the maximum events as configured in the [Maximum events to get while scheduled and interval polling] parameter.
             </li>
         </ul>
     </li>
 </ul>

<p>The <b>DetectionSummaryEvent</b> is parsed to extract the following values into an Artifact.<br></p>

<table style="width:100%">
 <tr>
     <td><b>Artifact Field</b></td>
     <td><b>Event Field</b></td>
 </tr>
 <tr>
     <td>cef.sourceUserName</td>
     <td>UserName</td>
 </tr>
 <tr>
     <td>cef.fileName</td>
     <td>FileName</td>
 </tr>
 <tr>
     <td>cef.filePath</td>
     <td>FilePath</td>
 </tr>
 <tr>
     <td>cef.sourceHostName</td>
     <td>ComputerName</td>
 </tr>
 <tr>
     <td>cef.sourceNtDomain</td>
     <td>MachineDomain</td>
 </tr>
 <tr>
     <td>cef.hash</td>
     <td>MD5String</td>
 </tr>
 <tr>
     <td>cef.hash</td>
     <td>SHA1String</td>
 </tr>
 <tr>
     <td>cef.hash</td>
     <td>SHA256STring</td>
 </tr>
 <tr>
     <td>cef.cs1</td>
     <td>cmdLine</td>
 </tr>
</table>

<p>The app also parses the following <b>sub-events</b> into their own artifacts.<br></p>
 <ul>
     <li>Documents Accessed</li>
     <li>Executables Written</li>
     <li>Network Access</li>
     <li>Scan Result</li>
     <li>Quarantine Files</li>
     <li>DNS Requests</li>
 </ul>

<p>Each of the sub-events has a CEF key called <b>parentSdi</b> which stands for Parent Source Data Identifier. This is the value of the SDI of the main event that the sub-events were generated from.</p>


<h2>Falcon X Sandbox Actions</h2>
<b>This is different from Falcon Sandbox.</b>
  <li><b>Action -</b> File Reputation, Url reputation</li>
      <ul>
        <li>
          Report of the resource will be fetched if it has been detonated previously on the CrowdStrike Server otherwise no data found message will be displayed to the user.
        </li>
      </ul>

      <li><b>Action -</b> Download Report </li>
      <ul>
        <li>
          This action will download the resource report based on the provided artifact ID. Currently, we support the following Strict IOC CSV, Strict IOC JSON, Strict IOC STIX2.1, Strict IOC MAEC5.0, Broad IOC CSV, Broad IOC JSON, Broad IOC STIX2.1, Broad IOC MAEC5.0, Memory Strings, Icon, Screenshot artifact IDs.
        </li>
      </ul>

      <li><b>Action -</b> Detonate File </li>
      <ul>
        <li>
          This action will upload the given file to the CrowdStrike sandbox and will submit it for analysis with the entered environment details. If the report of the given file is already present with the same environment, it will fetch the result and the file won't be submitted again.
        </li>
        <li>
          If the analysis is in progress and reaches the time entered in the detonate_timeout parameter, then this action will return the resource_id of the submitted file using which the submission status can be checked.
        </li>
        <li>
          If the submitted file will be analyzed within the entered time in the detonate_timeout parameter, its report will be fetched. Currently, these file types are supported .exe, .scr, .pif, .dll, .com, .cpl, etc., .doc, .docx, .ppt, .pps, .pptx, .ppsx, .xls, .xlsx, .rtf, .pub, .pdf, Executable JAR, .sct, .lnk, .chm, .hta, .wsf, .js, .vbs, .vbe, .swf, pl, .ps1, .psd1, .psm1, .svg, .py, Linux ELF executables, .eml, .msg.
        </li>
      </ul>

      <li><b>Action -</b> Detonate Url </li>
      <ul>
        <li>
          This action will submit the given URL for analysis with the entered environment details. If the report of the given URL is already present with the same environment, it will fetch the result and the url won't be submitted again.
        </li>
        <li>
          If the analysis is in progress and it reaches the time entered in the detonate_timeout parameter, then this action will return the resource_id of the submitted URL using which the status of the submission can be checked. If the analysis status is running then do not re-run the detonate URL action, otherwise, the URL will be again submitted for the analysis.
        </li>
        <li>
          If the submitted URL will be analyzed within the entered time in the detonate_timeout parameter, its report will be fetched. Currently, 3 domains of URL are supported http, https, and ftp.
        </li>
      </ul>
      <li><b>Action -</b> Check Status </li>
      <ul>
        <li>
          This action will return the status of the given resource_id in case of timeout in detonate file and detonate URL actions.
        </li>
      </ul>

<h2>Notes</h2>
  <li><b>Action -</b> List Groups</li>
    <ul>
      <li>
        The filter parameter values follow the <a href="https://falcon.crowdstrike.com/support/documentation/45/falcon-query-language-fql-reference" target="_blank">FQL Syntax</a>.
      </li>
      <li>
        The sort parameter value has to be provided in the format property_name.asc for ascending and property_name.desc for descending order.
      </li>
    </ul>
  <br>
  <li><b>Action -</b> Query Device</li>
    <ul>
      <li>
        Both the filter and sort parameters follow the same concepts as mentioned above for the list groups action.
      </li>
    </ul>
  <br>
  <li><b>Action -</b> Assign Hosts, Remove Hosts, Quarantine Device, and Unquarantine Device</li>
      <ul>
        <li>
          The devices will be fetched based on the values provided in both the device_id and hostname parameters.
        </li>
        <li>
          If an incorrect value is provided in both the device_id and hostname parameters each, then, the action will fail with an appropriate error message.
        </li>
      </ul>
  <li><b>Action -</b> List Session Files, Get Session File</li>
      <ul>
        <li>
          To add [session id] to the action parameters of these actions, a session with the Create Session action needs to be created. Also, the user can delete the session using the Delete Session action.
        </li>
      </ul>
      <br>
  <li><b>Action -</b> Run Command</li>
      <ul>
        <li>
          This action can run the below-mentioned RTR commands on the host:
          <ul>
            <li>cat</li>
            <li>cd</li>
            <li>env</li>
            <li>eventlog</li>
            <li>filehash</li>
            <li>getsid</li>
            <li>ipconfig</li>
            <li>ls</li>
            <li>mount</li>
            <li>netstat</li>
            <li>ps</li>
            <li>reg query</li>
          </ul>
        </li>
        <li>
          To add [session id] to the action parameters of these actions, a session with the Create Session action needs to be created. Also, the user can delete the session using the Delete Session action.
        </li>
        <li>
          Example action run: If "cd C:\some_directory" command needs to be run using this action, valid [device_id] and [session_id] parameters should be provided by the user. The user should select "cd" from the [command] dropdown parameter and provide "C:\some_directory" input in the [data] parameter.
        </li>
      </ul>
  <li><b>Action -</b> Run Admin Command</li>
      <ul>
        <li>
          This action can run the below-mentioned RTR administrator commands on the host:
          <ul>
            <li>cat</li>
            <li>cd</li>
            <li>cp</li>
            <li>encrypt</li>
            <li>env</li>
            <li>eventlog</li>
            <li>filehash</li>
            <li>get</li>
            <li>getsid</li>
            <li>ipconfig</li>
            <li>kill</li>
            <li>ls</li>
            <li>map</li>
            <li>memdump</li>
            <li>mkdir</li>
            <li>mount</li>
            <li>mv</li>
            <li>netstat</li>
            <li>ps</li>
            <li>put</li>
            <li>reg query</li>
            <li>reg set</li>
            <li>reg delete</li>
            <li>reg load</li>
            <li>reg unload</li>
            <li>restart</li>
            <li>rm</li>
            <li>run</li>
            <li>runscript</li>
            <li>shutdown</li>
            <li>unmap</li>
            <li>xmemdump</li>
            <li>zip</li>
          </ul>
        </li>
        <li>
          To add [session id] to the action parameters of these actions, a session with the Create Session action needs to be created. Also, the user can delete the session using the Delete Session action.
        </li>
        <li>
          Example action run: If "cd C:\some_directory" command needs to be run using this action, valid [device_id] and [session_id] parameters should be provided by the user. The user should select "cd" from the [command] dropdown parameter and provide "C:\some_directory" input in the [data] parameter.
        </li>
      </ul>
<h2>Port Information</h2>
  <p>
    The app uses HTTP/HTTPS protocol for communicating with the Crowdstrike Server. Below are the default ports used by Splunk SOAR.
    <table>
      <tr class=plain>
        <th>Service Name</th>
        <th>Transport Protocol</th>
        <th>Port</th>
      </tr>
      <tr>
        <td>http</td>
        <td>tcp</td>
        <td>80</td>
      </tr>
      <tr>
        <td>https</td>
        <td>tcp</td>
        <td>443</td>
      </tr>
    </table>
  </p>
<h2>Playbook Backward Compatibility</h2>
	<p>
		<ul>
			<li>The output data-paths have been updated in the below-existing action. Hence, it is requested to update existing playbooks created in the earlier versions of the app by re-inserting | modifying | deleting the corresponding action blocks.</li>
			<ul>
				<li>list users - Below output data-paths have been updated.</li>
				<ul>
					<li>Updated name from 'customer' to 'cid'</li>
          <li>Updated name from 'firstName' to 'first_name'</li>
          <li>Updated name from 'lastName' to 'last_name'</li>
				</ul>
			</ul>
		</ul>
	</p>