Mohsin,
I haven't watched this one, but I'm thinking
this video will probably explain everything I'm about to talk about a bit more clearly.
Maybe
this guide will help too, it is a little outdated, but it's what I used when I was first starting to use the product and it helped me understand the process. Any mention of any
resilient-circuits
commands other then
resilient-circuits run
have been replaced by
resilient-sdk
. The commands should be nearly identical other than that.
A function (really a package, there can be many functions in a single package) is a separate process from the IBM SOAR console process(es) that registers with IBM SOAR and enables IBM SOAR to send that package messages when it encounters a function within a workflow. So you define the inputs to a function within a workflow, IBM SOAR then sends those inputs to the code you create, your code executes and returns data back to IBM SOAR and then the post-process script in the workflow can operate on the results of that function.
This can get a little confusing at first, but once you've made a couple of functions you'll get the hang of it pretty quick.
The first think you will need to create is a message destination and then a function that uses that message destination within the GUI. Once you do that you will then start writing python code.
resilient-sdk is a pypi library that provides some functionality useful for developers, you would need to pip install it into whatever environment you plan on doing your development in (I highly recommend using a python virtual environment for each package you create). When creating a function you can use the
resilient-sdk codegen
command to generate a boilerplate package (there can be multiple functions per a package - generally I make a package for a single security tool and include many functions within it). When you use the command you need to pass in the function / message destination that you have created within the IBM SOAR GUI. Within the files of the boilerplate project, the code that runs when the function gets called is under the
package_name/package_name/components
directory, where
package_name
is the name you specify when using the resilient-sdk codegen command. These are the files you would want to edit with whatever business logic / processes you need your function to do.
Now that you have the files for a function you need a way to connect the function to Resilient and run it. While you are still developing the function(s) I would use an Integration Server (
see this guide for more information). This is essentially a computer that has the pypi library
resilient-circuits installed and a process created from using the
resilient-circuits run
command. Here's a diagram that may illustrate it better than my words:
So you will need to create an integration server to actually run your function. I generally only use integration servers while I'm developing a function. Once I feel the function is complete I then move it to our
apphost, but that's another topic. I do all of my development on my computer, so I turn my computer into an integration server by running the command
resilient-circuits run
and while the process that command creates is running my computer is registered to IBM SOAR and can listen for messages from it. Another note is that you will need to install the package (the python files you have been working on) before running
resilient-circuits run
in order to tell IBM SOAR that those functions are available on your computer.
I would focus on first creating a connection to IBM SOAR with an integration server. Once you are able to connect successfully I would then start working on creating functions.
Let us know if you have any questions
------------------------------
Liam Mahoney
------------------------------
Original Message:
Sent: Mon September 06, 2021 06:18 PM
From: Mohsin Ali
Subject: Send Artifacts via Outbound Email
Hello Liam,
I have exactly the same problem and same confusion, what does creating a function mean in IBM SOAR? Does it mean we have to install resilient-sdk on our environment through pip install resilient-sdk and write an extension/function?
OR
Creating a function means creating a function from soar web UI
Customize>function> and create a function
I have gone through App Developer's Guide documentation multiple times, there is no guide/example to create custom function. I don't know where to write the function and where to place the .py file on my soar system.
------------------------------
Mohsin Ali
Original Message:
Sent: Mon September 06, 2021 12:03 PM
From: Liam Mahoney
Subject: Send Artifacts via Outbound Email
Asad,
I think the App Developer's Guide documentation will explain it better than I can. If you have any questions I'd be happy to try and answer them.
Once you start developing the function I'd take a look at the way this function uses self.rest_client
to make requests to the IBM SOAR API. There is a helper object provided with the output of the codegen that makes interacting with the IBM SOAR API very easy from within a function.
Let us know if you run into any problems
------------------------------
Liam Mahoney
Original Message:
Sent: Mon September 06, 2021 11:53 AM
From: Asad Aftab
Subject: Send Artifacts via Outbound Email
hello liam,
hope you are doing fine. Kindly tell me about how to creating a function to get all of the artifacts on an incident. like you said that use restAPI so kindly can you tell us a little more description and where to add that function in Resilient.
Regards
Asad Aftab
------------------------------
Asad Aftab
Original Message:
Sent: Fri September 03, 2021 05:19 PM
From: Liam Mahoney
Subject: Send Artifacts via Outbound Email
Asad,
I would recommend creating a function to get all of the artifacts on an incident. This function would use the Resilient API, specifically the GET /orgs/{org_id}/incidents/{inc_id}/artifacts
endpoint (it's possible this function already exists on the community, I'm not sure).
This endpoint will return a list of dictionaries where each dictionary is an artifact on the incident. Within each artifact's dictionary will be a hits
key. Here's an example with most of the other artifact data removed:
{..."hits": [ { "value": "https://exmaple.com", "threat_source_id": 122, "artifact_type_id": 3, "properties": { "Analysis Start Time": "2021-09-03T19:53:45+00:00", "Full Report": "https://sandbox-analysis.com/urls/573e2bc054fd1dea202989be35b18abc5e64ef38d18a3dca13e71c2f57882d93", "Threat Score": "72", "Verdict": "malicious" }, "active": true } ],...}
If you pass in the query parameter handle_format=objects
with your API request, you'll get the CTS name along with the ID. This would also be helpful for the key type
, which will contain the ID of the artifact type and the name of the artifact type (URL, DNS Name, etc.).
Once this function is created I would call it in the workflow before you call the outbound email function. Within the pre-process script of the outbound email function you could iterate over the results of the first function, look for any applicable artifact types, and then look for the scan data you want included in the email (threat score, etc.). You could then use that data as the input to the outbound email function.
Best of luck!
------------------------------
Liam Mahoney
Original Message:
Sent: Fri September 03, 2021 08:16 AM
From: Asad Aftab
Subject: Send Artifacts via Outbound Email
Hi Team,
We are trying to send artifacts scan data(threat score etc ) via fn_email_outbound. We need to fetch Source and destination IP and their reputation from artifacts and send as Outbound email text to networking team. we are using the following extension IBM Security App Exchange - Outbound Email for SOARIbmcloud | remove preview |
| IBM Security App Exchange - Outbound Email for SOAR | IBM X-Force Exchange is a threat intelligence sharing platform enabling research on security threats, aggregation of intelligence, and collaboration with peers | View this on Ibmcloud > |
|
|
The current flow is based on Incident and we cannot directly call the artifact.
If you have any idea that how can we send the artifacts scan result(X-force) to the respective team via outbound email text. do let us know.
Regards,
Asad Aftab
------------------------------
Asad Aftab
------------------------------