Unfetter Analytic

Measure the effectiveness of your analytics.


Unfetter Analytic is a reference implementation, inspired by The MITRE Corporation CAR and ATT&CK™ framework, and supported by The MITRE Corporation and the National Security Agency (NSA). Unfetter Analytic is a prototype that allows developers to gain familiarity with the ATT&CK™ framework to measure the effectiveness of their analytics. Write analytics and map them to the MITRE ATT&CK™ techniques you want to detect. When the analytic event is created, the Kibana display shows the context around the event.

ATT&CK™ stands for Adversarial Tactics, Techniques and Common Knowledge. It is a model and framework that describes the actions an adversary may take while attacking an enterprise network. ATT&CK™ specifically focuses on post-exploitation of Windows host systems. Think of it as a roadmap that lays out what an attacker COULD be doing on your network.

MITRE's Cyber Analytic Repository, or CAR, is an effort to document and share analytic ideas and lessons learned. Each CAR analytic is framed by the ATT&CK™ behavior(s) it is trying to identify.

Unfetter Analytic, a reference implementation that provides a framework for collecting events from a client machine (Windows 7), supports building and testing analytics in the CAR model, and displays the alerts as they reference the ATT&CK™ framework. Unfetter Analytic is not designed to be a production intrusion detection system, but it is an educational capability for analytic developers to try, explore, and learn the concepts discussed at http://mitre.github.io/unfetter.


This reference implementation provides a framework for collecting events from a client machine (Windows 7), and performing Cyber Analytics Repository (CAR) analytics to detect potential adversary activity.

On the left-hand side of the diagram, you see the Windows System, or the "victim machine." NXLog ships standard Windows events to the Unfetter Analytic system. The Windows system, once built, runs Microsoft Sysmon.

On the right, the Unfetter Analytic server is running an Elasticsearch, Logstash, Kibana software stack and Apache Spark as the main analytic system. Event logs from the victim system and generated alerts are stored in Elasticsearch and are viewable through Kibana.

Designed For Experimentation

This is not designed for production use. Architectural decisions were made to make it easier to collect and analyze data, as opposed to the more robust requirements needed in a production system. The system was designed to make personalized data source additions easier for experimentation purposes. Take it, use it, learn, and let us know what you think through our GitHub Issues Tracker.


Setup PageThe Unfetter Analytic server side system is built using Docker to easily spin up containers for running each of the desired applications.

These instructions show how to setup the Windows Victim system with Vagrant. Services will be configured and started, Windows event logs and Sysmon data will be forwarded and ingested, and Kibana dashboards will be running, analytics will run and alerts will be pushed to Unfetter-Discover.

The Unfetter Analytic system was tested on Windows 7 Professional and Windows 10 Home host operating systems (OSes) using VirtualBox. However, any OS that supports Vagrant should work, since both systems run in virtual machines (VMs).

If using Windows as your host OS we recommend you run a Bash client to interact with Vagrant, but it is not strictly necessary.

Under the main directory, there are two sub-directories: unfetter-analytic and unfetter-windows. The unfetter-analytic system contains a docker-compose.yml file for using docker-compose to create the system. The unfetter-windows directory contains a Vagrantfile and all the scripts necessary to provision each system.

When first starting each VM with vagrant up, Vagrant provisioning will go out and install all the software needed for each VM. No software, other than source code, is provided in the GitHub project.

To install the prerequisites

  • Install Docker
  • Install Vagrant
  • Install Oracle's VirtualBox
  • Install a git client and run clone github.com/unfetter-analytic/unfetter.git
  • Starting The Server

    The Unfetter Analytic Linux VM contains the ELK stack, Apache Spark, and the Python (PySpark) files that run the analytics.

    The Windows VM is a Windows 7 32-bit with Microsoft Sysmon and Nxlog installed. Nxlog is already configured to send logs to Unfetter Analytic.

    There are a number of GitHub projects needed to run the Unfetter Analytic system. They are all found under www.github.com/unfetter-analytic

    You can easily clone all those projects in a couple of easy steps:

    mkdir unfetter-analytic;cd unfetter-analytic
    git clone https://github.com/unfetter-analytic/unfetter.git
    cd ./unfetter
    docker-compose up

    In analytic-system directory, there is a file called run.sh. Docker will run this file as the main workhorse for the analytic system. It is looping through all the analytics and running them, pushing any results to Elasticsearch AND the locally created Unfetter-Discover. Change run.sh to perform whatever analytics you want.

    Wait until Docker has started. There won't be any data until the Windows system begins running and forwards events.

    The running docker container "analytic-system" has the analytics. If you want to run analytics individually, attach to this container to run them.

    Starting Windows

    Setting up the Windows system the first time has a few more steps than setting up the analytic server. You will need a version of Windows 7 that can be created as a box file. There are a few ways to do this, but these instructions will show you how to use modern.ie to download an evaluation copy of Windows 7 from Microsoft.

  • Go to the modern.ie site and download an IE11 on Win7 Virtual Machine for the Vagrant platform.
  • Unzip IE11.Win7.Vagrant.zip and load the box file (IE11 - Win7.box) to your host computer. The box file is a VM packaged with metadata that Vagrant uses as a starting point for your VM.
  • Go to the directory where you unzipped the .box file and run the command: vagrant box add win7 'IE11 - Win7.box'
  • Your Vagrant system should now have a base Windows 7 image called Win7
  • Go to the "unfetter-windows" directory and run: vagrant up
  • Vagrant won't be able to complete the provisioning on its own. Manual configuration of Vagrant is necessary so that Vagrant can communicate with the guest Windows OS. When the Windows GUI starts, do the following on the VirtualBox window

    Set the network location to Home or Work. Go to Control panel -> Network and Sharing Center and click on "Public network" under "View Your Active Networks" in order to change the type. Run the following script as administrator:

    @echo off
    set WINRM_EXEC=call %SYSTEMROOT%\System32\winrm %WINRM_EXEC% 
    quickconfig -q
    %WINRM_EXEC% set
    winrm/config/winrs @{MaxMemoryPerShellMB="300"} 
    %WINRM_EXEC% set winrm/config @{MaxTimeoutms="1800000"}
    set winrm/config/client/auth @{Basic="true"}
    %WINRM_EXEC% set winrm/config/service @{AllowUnencrypted="true"}
    %WINRM_EXEC% set winrm/config/service/auth @{Basic="true"}

    This script is located in unfetter-windows/resources/winrm.cmd on the host OS. After you change the network type in the guest OS the script will be accessible under \\VBOXSVR\vagrant\resources. Either execute it from that location or copy it and paste it into a new .cmd file on the guest OS using Notepad.

    Navigate back to the window where "vagrant up" was executed. Provisioning should continue now that Vagrant can communicate with the guest OS. Vagrant will install and configure Sysmon and Nxlog. When it is all done, check the following log file for errors to make sure the Windows machine can see the analytic server: c:\Program Files\nxlog\data\nxlog.log

    The VM can be accessed through the GUI. If you used Modern.ie, then the credentials are "IEUser/Passw0rd!"

    It is HIGHLY recommended that if you work with Microsoft Windows, you purchase a licensed copy and build your own Vagrant box file. If you want to make your own base Windows box, this webpage has an example.

    Web Interfaces

    Unfetter Analytic provides three interfaces to see your collected data. Kibana provides a full-featured interface to perform complex searches. You can access it at: https://localhost

    The Elasticsearch head plugin provides a simple interface that allows you to browse through the collected data. It is accessible at: https://localhost/elasticsearch/_plugin/head

    The Unfetter-Discover system is avilable at https://localhost/unfetter-discover Next, learn to Generate Events


    Unfetter Analytic uses a Windows VM to generate interesting events such as process creation, user logins, and network connections.The events are shipped to the Unfetter Analytic server, Logstash is used to ingest them into Elasticsearch, and then Apache Spark is used to run an analytic that generates new events (generally either alerts or items for situational awareness).

    Below is an example process to generate an event that will trigger an alert in the Windows VM.

    Interact with the Windows VM Graphical User Interface (GUI) and start Powershell as administrator. Run the Powershell command to clear the security event logs: PS C:\Windows\System32> Clear-EventLog -Logname Security

    To see the events in Elasticsearch you can use either Kibana or the lighter weight Elasticsearch-head plugin. From the browser in your host OS, go to Kibana: https://localhost Another option is to use the Elasticsearch-head plugin. Click on the "Browser" tab on the following page:

    The results of the analytics are also visible in Unfetter-Discover at https://localhost/cti-stix-ui/sightings. https://localhost/elasticsearch/_plugin/head Events from the Windows Event Log, as well as Sysmon events, should begin to populate Elasticsearch and be viewable via Kibana or Elasticsearch-head.

    Running the Analytics

    Create new analytics by putting them in the unfetter-analytic/unfetter-analytic/analytic-system/src directory. A quick ls shows a number of Python files with names similar to CAR_2016_04_002.py. Each of these files is a separate analytic that you can read about in CAR. You can also look at the file itself using a text editor like emacs, vim, or nano. Create a new analytic. Then, edit the run.sh file to run the new analytic in the loop. Stop the docker containers, and rerun them docker-compose up.

    Restarting the containers will pull the new run.sh file and start running them.

    The es_helper.py helps set up and interact with Elasticsearch.

    The main program is run_unfetter_analytic.py. This Python program will call the CAR analytic Python code you specify. Hereis a simple example: spark-submit run_unfetter_analytic.py -c CAR_2016_04_002.py -d day 1 -p

    This command will use spark-submit to run the "run_unfetter_analytic.py" program, which will load and execute CAR analytic CAR_2016_04_002 and will look through the last 24 hours of events. It will push any alerts to Elasticsearch and also Unfetter-Discover.

    After printing the Unfetter banner, run_unfetter_analytic will display the CAR name, number, and description. This will generate a number of alerts once it completes.

    The alert should now appear in Kibana. Adjusting the time interval in the upper right-hand corner may be necessary.

    Getting Involved

    Are you interested in getting involved? We welcome any and all comments, suggestions, or bug reports through our GitHub Issue tracker. Checkout our GitHub Page for installations.

    We can't wait to hear what you do with Unfetter Analytic