IBM Security QRadar SOAR

 View Only

Decorate Artifacts using SOAR Functions in v43

By Sam Wang posted Tue December 07, 2021 04:34 AM

  

Hi all, 

This post aims to share the new feature we made in the v43 version of SOAR to allow Functions to be able to publish updates to the Artifacts listed in the Incident. It provides the capability to extract a table from the built-in or custom Threat Source, publish the data as fit, and only requires the installation of the Integration. 

The advantage you can take from this new feature:

  • A way to publish a Hit to an Artifact via API or in-product Python3 script, allows the method to set the name of the Threat Source as well as all of the content in the hit body.
  • Artifact's attributes (e.g., tags, summary, related incident count, scan option, etc.) can be read/set via in-product script, which extends the orchestration and automation capability
The above methods are available in
  • Scripts (Python 3 only)
  • Workflows: Function Post-Process Script
  • Playbook local/global scripts
  • Playbook condition point script

In the following, I will show a playbook example to leverage this feature and SOAR function to have granular control (e.g., define detection ratio as hit criteria in the script) to meet a specific need and publish a hit.

  1. Install the VirusTotal App (v1.0.6) and pairing to an AppHost.


  2. Create an artifact playbook for VT function threat lookup, considering playbook Activation setting:
    auto-activation, condition: Artifact Type = built-in artifact type [Malware MD5 hash] or custom artifact type [VirusTotal MD5 Hash Scan] 

  3. Config VirusTotal Function Inputs to recognize artifact types added in Step2.


  4. Make Hit publishing criteria via python3 in-product script composed of VT’s detection rate (external TI) and artifact properties (local historical reference).

    - Obtain the Detection Ratio from enrichment result of VT function, set HIT_THRESHOLD (positives/total) = 0.6 (60%), check specific tag was attached via artifact.containsTag().

    ## Convert VirusTotal function scan result into messagescan
    if playbook.functions.results.report.scan.get('positives') is not None:
      ## Define hit threshold and Calculate detection rate 
      HIT_THRESHOLD = 0.6
      detection_rate = float(playbook.functions.results.report.scan.get('positives'))/float(playbook.functions.results.report.scan.get('total'))
      
      msg = msg + u"<p>Positives: <span style='color:red'>{}</span> out of {} (detection rate is {:.2f}) </p> <p>{}</p>".format(playbook.functions.results.report.scan.get('positives'), playbook.functions.results.report.scan.get('total'), detection_rate, mk_report(playbook.functions.results.report.scan.get('permalink')))
    
      ## if detection rate >= 60%:
      if detection_rate >= HIT_THRESHOLD:
        add_hit_card()
        if artifact.containsTag("mitigated"):
          incident.severity_code = "High"​

    - Set the name of the Threat Source to "VT Function hits added" as well as all of the content in the hit properties. Here must provide a name, value, and type for each property. The type must be a string, number, uri, ip, or lat_lng. Publish a hit via artifact.addHit().

    ## Construct artifact hit card from VirusTotal scan result
    # You must provide a name, value, and type for each property.
    # The type must be a string, number, uri, ip, or lat_lng. 
    # This operation does not support the Observed Data artifact type, and is available in Python 3 only.
    def add_hit_card():
      hit = [
                {
                    "name": "Positives",
                    "type": "string",
                    "value": "{} out of {}".format(playbook.functions.results.report.scan.get('positives'), playbook.functions.results.report.scan.get('total'))
                },
                {
                    "name": "Scan Date",
                    "type": "string",
                    "value": "{}".format(playbook.functions.results.report.scan.get('scan_date'))
                },
                {
                    "name": "Scan Report",
                    "type": "uri",
                    "value": "{}".format(playbook.functions.results.report.scan.get('permalink'))
                }
            ]
      artifact.addHit("VT Function hits added", hit)

  5. if the detection ratio >= 60%, post info in Artifact description or/and Summary and publish Hit.


  6. if the detection ratio >= 60% and contains the specific tag "mitigated", post info in Artifact description or/and Summary, publish Hit and escalate the incident severity to High.


We hope this helps to provide a better artifact enrichment experience, extend the orchestration and automation capability from this new feature.
It's just a start, we look forward to seeing more creative usage of these newly added artifact methods and fields in the latest version. Have fun!

For more information see artifact operations on IBM Docs
https://www.ibm.com/docs/en/rsoa-and-rp/43?topic=scripts-artifact-operations

For artifact script samples see here
https://github.com/ibmresilient/resilient-scripts/tree/master/python3/artifact

-----------------------------------
Sam Wang, IBM Security SOAR

2 comments
85 views

Permalink

Comments

Fri January 07, 2022 03:17 AM

Hi Liam, 

thanks for sharing your thought and use case.

Artifact hit is a label directly related to if hit card exists. For additional and informational labeling, artifact tags could be a useful tool. 

Thu January 06, 2022 10:35 AM

I think unifying functions and artifact enrichment will be a great improvement for the developer / admin experience.

One thing I would love to see is the ability to define whether a hit is malicious or not. In your example, if `HIT_THREASHOLD` > 0.6, then mark the hit as malicious, if `HIT_THREASHOLD` < 0.6 mark as informational (non-malicious). An informational hit would not cause the artifact to be highlighted in red (and possibly would have a separate section in the artifact view).

An issue we continue to run into is that our analysts don't trust that an artifact was looked up if there are no hits in the artifact. This leads to our threat sources looking up the artifact value(s), and our analysts manually submitting them again once they start working the incident. If we were able to display a non-malicious hit, then our analysts would know the value was looked up in that given tool.

Another benefit would be doing informational lookups for artifact values. For example, looking up a computer name in our AD to get information about it. This information would never be malicious, but I think it would be convenient to have it stored in the artifact. Right now we have to store this data in a data table. So we have a data table with the computer name and the AD information as well as an artifact with the computer name. I think it'd be great if we could start to eliminate some of our data tables that contain information about the artifacts we have identified in an incident.