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.
- Install the VirusTotal App (v1.0.6) and pairing to an AppHost.
- 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]
- Config VirusTotal Function Inputs to recognize artifact types added in Step2.
- 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)
- if the detection ratio >= 60%, post info in Artifact description or/and Summary and publish Hit.
- 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