Enter The Matrix (ETM) allows operators to collaboratively edit Threat Scenarios and Events to be exported as threat matrices for entire assessments, or Directed Threat Graphs for individual Scenarios. Threat Matrices are based on the NIST 800-30r1 guidelines, and also include some minor changes that incorporate, among other things, the MITRE ATT&CK framework.
- Deploying ETM
- ETM Usage
This guide is for installing ETM on a fresh install of Ubuntu 18.04.
ETM is written with .NET Core, so it is compatible with Linux systems. ETM also is designed to work within Docker containers.
sudo apt updatesudo apt upgrade
sudo apt install vim
sudo apt install git
sudo apt install dos2unix
sudo apt updatesudo apt install apt-transport-https ca-certificates curl gnupg-agent software-properties-commoncurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"sudo apt updatesudo apt install docker-ce docker-ce-cli containerd.io docker-compose
sudo mkdir /var/matrixsudo mkdir /var/matrix/appsudo mkdir /var/matrix/mongosudo mkdir /var/matrix/mongo/dbsudo mkdir /var/matrix/mongo/configdb
sudo cd /var/matrix/appsudo git clone https://github.com/blacklanternsecurity/enter_the_matrix.git
git config --global http.sslverify false
cd /var/matrix/app/enter_the_matrixsudo vim docker-compose.yaml- Change the following line to a unique password (alphanumeric)
- MONGO_INITDB_ROOT_PASSWORD=CHANGEMESUCKAH
sudo cd /var/matrix/app/enter_the_matrixsudo vim appsettings.json- Alter the ConnectionString to use your password from the previous step for the MongoDB container
- Replace the "Ldap" fields with your LDAP configuration
- Replace the "LocalAuthSettings" with your desired administrative account credentials
- Place your SSL certificate at
/var/matrix/app/enter_the_matrix/matrix.cer - Place your SSL key at
/var/matrix/app/enter_the_matrix/matrix.key - To create your own self-signed certificate and key:
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout matrix.key -out matrix.cer
For whatever reason the nginx configuration does not play nicely coming from a Windows development environment even when specifically telling GIT to convert to LF end-of-line format. So, do the following:
sudo dos2unix /var/matrix/app/enter_the_matrix/enter_the_matrix.conf
wget https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.debsudo dpkg -i packages-microsoft-prod.debsudo apt-get install -y apt-transport-httpssudo apt-get updatesudo apt-get install -y dotnet-sdk-5.0
sudo cd /var/matrix/app/enter_the_matrixsudo dotnet publish --configuration Release
sudo cd /var/matrix/app/enter_the_matrixsudo docker-compose up -d
- Navigate to https://localhost or http://localhost to test everything is working as it should be.
Access to all parts of the application requires authentication first.
If you do not have LDAP authentication in place already, an administrative user can create user accounts within the application. From the login screen, select the "ADMIN" authentication option and sign in with the credentials set in the appsettings.json file during deployment.
Once you are authenticated as an administrator, you will be brought to the User Management page. Selecting "CREATE" will prompt you to input a new Username, Display Name, Given Name and Password.
Display Names are used in the application as part of the CSS styling. Given Names are used when creating Assessments/Scenarios/Events to tag activities to users.
You can also get to this page by clicking the "Admin" link at the top of every page after a person is authenticated. If the user is not in the "Admin" role, then they will be loggeed out and brought to the login screen again in order to authenticate as an "Admin" user.
Selecting the "Edit" link next to each user will bring up a prompt to edit the Display Name, Given Name and Password for a user. The Username is not able to be changed.
Selecting the "Delete" link next to each user will bring up a confirmation prompt before proceeding to remove the user from the database.
Once you are logged in properly, navigate to "Assessments" and then click the "CREATE ASSESSMENT" button. Supply a title for the assessment you are creating and click "CREATE".
After creating an assessment you will be brought to the Scenario page. You can also get to the Scenario page later by selecting the appropriate Assessment.
To create a new Scenario, click "CREATE SCENARIO" and provide a title for the new Scenario.
From the Scenario page, you are also able to edit the title of the Assessment by clicking "EDIT ASSESSMENT" or delete the Assessment by clicking "DELETE ASSESSMENT".
Scenarios are able to be re-ordered by clicking and dragging the Scenario element and releasing somewhere else in the list of Scenarios. This will determine the order that the Scenarios will be exported in the Threat Matrix Spreadsheet. Once the order is how you want it, click "SAVE CHANGES" to commit the ordering.
To create an Event, select the Assessment and then Scenario you want to add the Event to. Once on the Events page, clicking "CREATE EVENT" will present you the option of either importing an Event from one of the Steplates already created, or create a new event.
Events on this page can be re-ordered if needed by clicking and dragging an Event item in the list and dropping it where you want it. This will determine the ordering of the Events in that particular Scenario in the exported Threat Matrix Spreadsheet. Once you are happy with the order they are in, click "SAVE CHANGES" to commit your ordering changes.
From this page you may also edit the Scenario title by clicking "EDIT SCENARIO", delete the current Scenario by clicking "DELETE SCENARIO" or return to the Scenarios page by clicking "SCENARIOS".
While filling in the individual factors for the event you are editing, you can take advantage of the helper info buttons on most of the factors. Clicking on these will display a modal overlay that contains the NIST descriptions for each severity level.
You are able to select an appropriate MITRE ATT&CK ID by selecting the category which expands displaying the various MITRE ATT&CK Tactics for that category. Selecting one of the tactics then displays the various Techniques under that Tactic.
Each Technique has a helper icon you can click on that will take you to that Technique's detailed information page on the MITRE website in a new tab.
These Techniques will be present in the exported Threat Matrix as IDs hyperlinked to the MITRE ATT&CK website for your clients to use in their remediation efforts.
The threat sources presented in the list box are pulled from NIST guildlines on conducting a Risk Assessment.
Each Event should have some relevance to technical findings during your assessment.
Based on your entries into this page, two factors are automatically calculated (Overall Likelihood and Risk) for you to avoid biasing outcomes.
NIST provides the information needed to properly calculate Risk. Three factors directly contribute to the final Risk value. These include Likelihood of Attack Initiation, Likelihood of Adverse Impact, and Level of Impact. The Likelihood factors are combined to form the Overall Likelihood value. Risk is then calculated based on combining the Overall Likelihood value and the Level of Impact value.
Finding Reference/Vulnerability Severity and Predisposing Condition/Pervasiveness of Predisposing Condition
NIST provides guidance on quantifying a Serverity and Pervasiveness factor for a particular event. To make this more obvious and understandable, these have been broken out into separate fields. If a Finding Reference is not supplied, then the Vulnerability Severity slider will not be activated. Similarly, if a Predisposing Condition is not provided then the matching Pervasiveness of Predisposing Condition slider will be deactivated.
If only one of these are filled in, then the overall Severity and Pervasiveness factor in the exported Threat Matrix will be taken from the one enabled. If both are provided, then an average is taken of the two and floored.
To create a graph export of your Scenarios, you will need to provide information for each event.
Which Entity you choose here will determine the graph node image displayed in the exported graph.
The Description you provide will become the label underneath the graph image in the exported graph.
This list contains each event already present in the current Scenario. If there are no events that precede this one, or you want this particular event to be tied directly to the root node (The attacker node) then you can select None (Root Node). Otherwise, selecting on of the other events in the list will make that event the parent to the one you are editing currently.
To create a Steplate, navigate to the Steplates page. Once there, you can click "CREATE STEPLATE". This will create a new blank Steplate and bring you to the Steplate editing page.
Editing a Steplate is an identical process to editing an Event, however certain considerations should likely be made to make these as reusable as possible. This should allow you to maintain more consistency in quantifying event factors.
To export a threat graph for a specific Scenario, select the Assessment that the Scenario belongs to. From the Scenarios page, select the Scenario you want to export as a graph. From the Events page, click the "EXPORT GRAPH" button. This generates a graph using GraphViz in the background, and displays the resulting graph in the browser. The graph will have a transparent background once saved so it may be used in other reporting materials as supportive information.
To return to the application just use your browser's back button.
To export your Assessment to a Threat Matrix Spreadsheet, select the Assessment you want to export. Then, from the Scenarios page, click "EXPORT XLSX". The default title for the exported spreadsheet will be AssessmentTitle_ThreatMatrix_YYYY_MM_DD. Once you're happy with the filename, click "EXPORT".