Add your endpoints to your SIEM (Cisco AMP4EP APIs)

Originally published on LinkedIn on the 6th of May 2018

There is a lot of data going into a SIEM and we will try today to add to it some more of that. Our IT tools continuously produce large amount of logs and information. Whilst is easy to look into each of our servers and search for logs, having a 360 degrees view of what is going on is a different story. Our SIEM is a good place for correlating data coming from multiple sources and investigating incidents. Are your endpoints part of the equation and to which extend? AMP for Endpoints offers the opportunity of integrating with just about any SIEM and/or any other piece of software you might need to integrate to

Before we start

This article is in no way sponsored, endorsed or administered by, or associated with my employer. The opinions expressed are my own views and not those employer

The activities shown in this article are not generally speaking dangerous but, you know, there is always a risk that something could go wrong. In particular there are some aspects about security that are not taken into account (peer hostname verification and others). Please seek for professional services support if you do not feel confident in any of the steps here described. I wrote this article as a weekend project and is offered “as is”, without any support or responsibility in case of data loss, security breaches, and/or other calamities

What is AMP for Endpoint?

If you are reading this article you probably already know. For completeness, “Cisco AMP for Endpoints” (AMP4EP) is a next-generation endpoint security solution that prevents, detects, and responds to advanced threats”. An additional advantage of the solution is the possibility of collecting a considerable amount of security information regarding the endpoint themselves and the relations they have or might have had with other devices, servers and endpoints in terms of files, network connections and others. We want to concentrate on all of those relations. This is all information we might want to share with our SIEM

How do I do it?

There are different ways, some out of the box, some others via AMP4EP APIs. We will look today at how to use the latter option. The first step is to visit the APIs documentation page and click on the version that belongs to the area where your cloud instance is located (US, APJC or EU). On the next page we want to select the “v1” version of the APIs. The majority of the resources in there will need to be called on demand by our script, software or whatever we are using or building. An exception to that are the Event Streams. These are resources that will continuously expose streams of data from AMP4EP to our client(s). This is much more convenient as we will not need to write a scheduled procedure to look for new data. In other words we will initiate a connection to a stream of data and will keep on listening for new messages coming in

Activating the APIs

In order to use the APIs first we need to create an username and password that give us access to the exposed resources. These are different from the ones normally used to log in into the AMP4EP web portal. Log into your AMP4EP console by using your usual credentials and follow the instructions from the documentation (Under “Accounts” –> “API Credentials”) to create a read&write username and password for your APIs. Tick the “Enable Command Line” option as well if you want to. You might need to activate Two-Steps verification if not done yet

I almost forgot to mention: in this tutorial I will be using Microsoft Windows to quickly try out the Event Stream API and the following steps will assume you are using it too. Linux and other alternatives are largely described in the documentation, support portals and other online resources. The good news is that the way all this works on other operative systems and environments is not so dramatically different from what we are doing here after all

Creating the AMQP messaging resource

AMQP is the standard that the Event Streamer implements. In this step we basically create the resource that will enable us to receive our data streams from AMP4EP. This process is described in the documentation. Remember that you should always point to the documentation that belongs to the area where your instance is (US, APJC, EU). I am currently pointing to the US documentation. Let’s now download and install Postman or have handy your favorite tool to work with APIs. Postman is an API Development Environment that comes with a free version and is available for multiple operative systems. You might or not create an account (just click on “Take me straight to the app” at the bottom of the application window if you don’t want to). Close all the floating windows to get to the main application window. Unfortunately we cannot use the Event Streamer API quite yet. First we need to figure out what types of events we want to capture

Finding out Events IDs

There is a specific API to retrieve the list of Events IDs. Examples of events are: Threat Quarantined, Threat Detected, Cloud Recall Restore from Quarantine, and many others. In other words we need to select the IDs of the events we want to stream (and receive). We can pick one or many. I suggest to test with Threat Quarantined and Threat Detected. In order to do that we need to find out what the corresponding IDs are. Within the documentation, under the “Response” paragraph, there is an example of the “GET /v1/event_types” API response. This contains many events names, descriptions and IDs. Let’s do the same with our environment

Let’s go back to Postman and make sure the request type is set to GET, the URL Request is the one corresponding to your instance (US, APJC or EU) and pointing to the right API (in my case “https://api.amp.cisco.com/v1/event_types”), the authentication type is set to “Basic Auth” and that Username and Password are there. These are the API credentials you previously created by following the instructions in the documentation

Eventually when you hit “Send” the JSON response will be available in the text area at the bottom of the application window. In my environment the IDs for Threat Quarantined is 553648143 and for Threat Detected is 1090519054. What are yours? (They might be the same). You can find all the critical areas to look at highlighted in red in the picture here below

Creating an AMQP resource

Next we need to create the queue, that is the streaming resource. The process is described in the documentation. At the end of this step we will have an additional set of username and password, used to connect to the AMQP resource. Let’s use Postman once more

Everything is pretty much as in the previous step. The only difference would be clicking on the “Params” button to add the parameters to the query. You might skip this step by adding directly a complete URL. Please note how the action now is a “POST” one (we are creating the queue here. This is done once, and afterwards we will call it as many times as we need to). Please note I named the queue “DQrbpudi2”. You may name it as you prefer. For your convenience the complete URL for the request I used is the following: https://api.amp.cisco.com/v1/event_streams?event_type[]=553648143&event_type[]=1090519054&name=DQrbpudi2

Under the “Body” section we can see the JSON response. In there we can find the name of the queue, username, password, host, port and protocol. It is now time to retrieve events from our recently created queue. One could implement a software that captures the events sent from the queue and redirect them to a SIEM, store them into a database, save them in a text file and many thousands of possible different uses more. The libraries to integrate the process into your middleware and favorite programming language could be from different vendors and providers. As an example, RabbitMQ is one of the possible message broker alternatives you might look into. However, for the moment we will limit the activity to just displaying the incoming messages in a command line console

Installing Ruby

The example from the documentation uses Ruby to capture the incoming messages from the queue. We will do the same. I downloaded from https://rubyinstaller.org/downloads/ the “Ruby+Devkit 2.5.1-1 (x64)” installer. You might pick a more recent (or older) version, if available, and the right flavor for your operative system (x86 or x64). I installed it using all the defaults. The only things that I unchecked/changed were the “MSYS2 development toolchain” and the “ridk install”. There is no need to have those installed for the moment

Running the Ruby client

Let’s now follow the instructions from the following page: https://github.com/ruby-amqp/bunny. What we need to do next is to prepare the text file with our program (Ruby script). Change the snippet here below with your information (“connection_url”, username, password, and “event_stream_name”) and save it to “C:\Ruby25-x64” or the path you chose when you installed Ruby. I saved it with filename “test.rb”

require 'bunny'

connection_url = "amqps://531-c3f9f207XXXXXXXXXXXX:7522e7c03f4217155dXXXXXXXXXXXXXXXXXXXXXX@export-streaming.amp.cisco.com:443"

conn = Bunny.new(connection_url)
conn.start

ch = conn.create_channel

q  = ch.queue('event_stream_531', :passive => true, :durable => true)

x  = ch.default_exchange

q.subscribe(:block => true) do |delivery_info, metadata, payload|

  puts "Received #{payload}"

end

Please note that in the line connection_url = “amqps://531-c3f9f207XXXXXXXXXXXX:7522e7c03f4217155dXXXXXXXXXXXXXXXXXXXXXX@export-streaming.amp.cisco.com:443”, “531-c3f9f207XXXXXXXXXXXX” represents your queue username and “7522e7c03f4217155dXXXXXXXXXXXXXXXXXXXXXX” your queue password. Open a command shell, go to “C:\Ruby25-x64” or the path you choose when you installed Ruby and run “gem install bunny”

In the same command shell we can now run the Ruby script “ruby test.rb”

The client is now listening to AMP4EP events. Move to the next section if you do not believe it 🙂

Testing the queue

I don’t know how much data you already have in your AMP4EP instance. I am using a demo environment so there is not much data available in there. I will do two things: firstly I will refresh the demo data in the console (log into https://console.amp.cisco.com/ and go to “Accounts” –> “Demo Data” –> “Refresh Demo Data”). Secondly I am downloading a “fake” virus (EICAR) that will trigger an event in AMP4EP. The best download is the one highlighted here below

If the file wasn’t already picked by AMP4EP or you local antivirus, run the scan as shown here below. I am using Windows File Explorer

The file is recognized as a virus and removed

Go back to your AMP4EP console and see if the EICAR event is there. Here below you can see what I have in my environment

Well, let’s see now how our ruby script is doing. I expect to see the same event from the AMP4EP web console in the command line as well…

… and there it is! As the file was removed and not quarantined we only have the Threat Detected event

Conclusions

I hope you enjoyed this example. Remember that going forward, to make it better you should build something more robust and complete than the example that has been presented here. The idea is that you take all of those received messages and send them to your SIEM or do something meaningful with them. I previously mentioned RabbitMQ. These libraries can be used with your preferred programming language to properly process the messages and do something purposeful with them. This example is the starting point of your AMP4EP APIs journey. Best wishes for a productive, happy, and fun journey!

Additional resources

Event Streams Python examples are available on both walbit and QuiLoxx repositories

APIs Tutorial: Overview of the Cisco AMP for Endpoints API

APIs Documentation: Cisco AMP for Endpoints API

Header picture attribution: https://pixabay.com/en/code-code-editor-coding-computer-1839406/