The automation functionality is part of the Enterprise version of securiCAD.
Running simulations automatically from a script or other application is essentially the process of uploading a model file, triggering a simulation and fetching the results from securiCAD Enterprise.
This process is handled by the automation.py script that we will discuss on this page. It will require login credentials to an installation of securiCAD Enterprise as well as a client certificate to access it.
Also, the automation script will use a “project” in securiCAD Enterprise to upload and simulate models. We suggest you create a new, empty one for that purpose.
This guide will focus on the json formatted output it will provide. That output is intended to be input to your applications.
Creating the APIsimulation project
When running simulations using the automation.py script, it will use a project in securiCAD Enterprise. Therefore, start by logging in to securiCAD Enterprise and create that project.
Running the script
The automation.py will authenticate to securiCAD Enterprise, upload a model file you specify on the command line, check that the model file is syntactically complete, trigger a simulation, wait for the simulation to complete and then fetch the simulation results.
To run the script, you will need a model file you wish to simulate. In our example, we have the example.sCAD file in the same directory as the automation.py file itself.
Go to the securiCADautomation/simulation directory and then run the script like shown below.
PS C:\tmp2\securiCADautomation\simulation> python .\automation.py -m .\example.sCAD training.enterprise.securicad.com Logging in Uploading model and validating it Starting scenario, wait for result ………. Adding attack path for 94.Write Adding attack path for 60.Compromise Result summary ============== Risk 8.554 Confidentiality 66 Integrity 66 Availability 66 Scenario data saved to C:\tmp2\securiCADautomation\simulation\scenarioData.json Simulation results saved to C:\tmp2\securiCADautomation\simulation\simulationData.json Attackpaths saved to C:\tmp2\securiCADautomation\simulation\attackpaths.json PS C:\tmp2\securiCADautomation\simulation>
The automation.py script will give us a small summary of the risk level as well as the C/I/A values for the example.sCAD model. It will also store simulation results in three different json files.
Simulation results in securiCAD Enterprise
After the simulation is done, we can log in to securiCAD Enterprise to take a look at the results. It is found under the “APIsimulations” project where we can check the results, the model, the risk levels, the attack paths and so on.
This step is not necessary for the automation, but only for follow up purposes.
Simulation results in json format
The results of the simulation will be stored in json format. The automation.py script will create the scenarioData.json, the simulationData.json and the attackpaths.json files.
These contain lots of tags and information but we will only look at a few examples of it in this guide.
The scenarioData.json file contains information on risk level of the model as well as more “summary” style information.
Risk and C/I/A
are related to the following fields in the securiCAD Enterprise interface
The field /simulationIdNumber/results/risks contains two chunks of information in our example; one for each of our selected high value assets; “Customer records” and “Stage srv 2”.
Here we find information on the TTC levels for these two objects, as well as the sample values for each “day” sample in the TTC plot. This means that this data can be used to create your own TTC plot or to select a certain risk level to see how many days are expected to be needed for the attacker to reach that risk level.
The simulationData.json file contains more detailed information that we will find in the securiCAD Enterprise report. It also contains information related to the model itself.
Suggested mitigations are found in the fields under /suggestions/configs/defense/ and the object securiCAD is suggesting to apply a certain mitigation to. For instance, we know that in the example model we were using, a suggested mitigation is to patch the RDP service with id number 111. In the json file, we see it as;
Missing objects are a similar type of mitigations but with the difference that securiCAD suggests adding a security related asset or object rather than improving the propertied of the existing ones. In our example, we see that the “Stage srv 2”, “Prod srv 2”, “Prod srv 1” and the “Prod srv 3” hosts would benefit from having a HIDS finctionality added to them. In the json data that information is found under /missing/objects and looks like the following;
Chokepoints are, as a reminder, assets in the model that are expected to be more frequently used by the attacker. In the securiCAD Enterprise report for the example model, we see that the object at the top of the chokepoints diagram is the “RDP Service” object.
In the json data, we find it in the /chokepoints/ list of items where we also see that it is showing up with a feequency of 76 and that it is related to the attack step “94.Write”, which is the same as “Writing to the Customer Data datastore”.
The attackpaths.json contains information on the “nodes”, the “links” and the “target” forming the attack path(s) from the attacker’s entry point to the selected high value asset.
The /data/target data contains information on the high value asset with the name, the id-number and what attack step has been selected as the final goal of the attack.
The nodes field of the attackpath json data contains a list of the different attack steps involved in the attack path from the attacker’s entry point to the “Customer Records.Write” attack step as shown above.
In the attack path of the example model, we have a set of early attack steps leading up to the “RDP Service.RootShellLogin”. That attack step is represented as a node like the following;
In the above set of data, we see a tag/list called “groups”. This information is telling us which attack paths this attack step is involved in. When first showing the attack path in the securiCAD interface/report, you will see the most likely attack path. This is however not the only attack path, since there are additional/alternative attack paths that the attacker could also choose to use. This the list called “groups”. In this case, it says that this particular attack step is part of the main group (number 0) as well as 1-8. This is not surprising, since the model is small and this is part of the main entrance for the attacker in the architecture.
We also see that there is no information on which other attack steps lead to this one or vice versa. This is information that is found in the “links” tag of the json data.
Looking back at the “node” information above, we see a field like “index”: 107. This is the “id number” of the RootShellLogin attack step of the RDP service. When we then search for the string “target”: 107 in our json data, we find the following information in the “links” section of the data.
The above relations are also seen in the attack step map shown in the securiCAD Enterprise interface.
By combining the “target” information with information on the “nodes” (which attack steps that are part of which attack path) and the “links” information telling which attack steps lead to which other attack steps, it is possible to build the attack step graph/map in your own application as well.
The simulation API of securiCAD Enterprise that we have now been using, gives several more options for automation. Some of them are related to altering the model, adding mitigations and similar operations that might be interesting from an automation persoective, depending on the use case. If you need to add such extensions to the automation.py, we would be happy to discuss that with you.
Book a Demo
Please don’t hesitate to request a personal demo if you have questions around this process, the scripts or how to use it.