| ... | ... | @@ -37,3 +37,281 @@ Attention: You can use a different port than the 8080 on your local machine, as |
|
|
|
|
|
|
|
## Usage of the QSA mechanism
|
|
|
|
|
|
|
|
# Dependability Toolbox - Execution as a Microservice
|
|
|
|
|
|
|
|
In this section, we describe how the QSA mechanism can be used as an individual Microservice. More specifically, we describe how the analysis service can be invoked, whereas intuitive examples are also provided, in an attempt to facilitate understanding.
|
|
|
|
|
|
|
|
## Execution of the Docker Container
|
|
|
|
|
|
|
|
Having the QSA Container already deployed on your local machine (see the [Installation](dependability-toolbox-installation) section for more information), it can be started, paused, and stopped using common Docker commands. For your convenience, some indicative commands are provided in this section. First of all, in order to start the Dependability Toolbox docker container, you need to execute the following commands on your terminal:
|
|
|
|
|
|
|
|
~~~
|
|
|
|
docker start vm4sec-qsa
|
|
|
|
docker exec -it vm4sec-qsa ./catalina.sh run
|
|
|
|
~~~
|
|
|
|
|
|
|
|
The first command starts the docker container of the QSA, whereas the second one starts the Tomcat Server that hosts the three services of the toolbox. If it is not necessary to view the console of the Tomcat Server, in the second command you need to replace the "./catalina.sh run" parameter with "./startup.sh".
|
|
|
|
|
|
|
|
In order to stop the QSA container, you need to execute the following command:
|
|
|
|
|
|
|
|
~~~
|
|
|
|
docker stop vm4sec-qsa
|
|
|
|
~~~
|
|
|
|
|
|
|
|
## Invocation of the individual service (API)
|
|
|
|
|
|
|
|
After starting the Docker Container of the QSA back-end, its web services are up and running. The QSA is accessible through the following end point:
|
|
|
|
|
|
|
|
```
|
|
|
|
<local_IP>:<defined_port>/DependabilityToolbox/SecurityAssessment
|
|
|
|
```
|
|
|
|
|
|
|
|
where the <local_IP> is the IP of the local machine on which the Dependability Toolbox Docker Container has been deployed, whereas the <defined_port> is the port of the Tomcat Server that is defined by the user during the installation (please see the [Installation](dependability-toolbox-installation) section). In the following, a more detailed description of how these services can be used is provided.
|
|
|
|
|
|
|
|
### Quantitative Security Assessment Service
|
|
|
|
|
|
|
|
The *Quantitative Security Assessment (QSA)* web service allows the user to evaluate the internal security level of software applications written in Java, C, and C++ programming languages. This is achieved through a dedicated API exposed by the RESTful web server, which is, in fact, a simple HTTP GET request. Several inputs need to be provided as parameters to this request. These parameters are listed below:
|
|
|
|
|
|
|
|
|
|
|
|
| Parameter | Description | Required | Valid Inputs |
|
|
|
|
|:------------:|:---------------------------------------------------------------:|:--------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
|
|
|
|
| project | The URL of the software project that should be analyzed. | Yes | Any valid URL that points to an existing online Git repository (e.g., GitHub, GitLab, Bitbucket, etc.). |
|
|
|
|
| language | The programming language of the software project that needs to be analyzed. | Yes | One of the following string values: : <br/>·“java” if the selected software project is written in Java programming language. <br/> ·“cpp” if the selected software project is written in C/C++ programming language. <br/> Default value is "java". |
|
|
|
|
| inspection | If the model will return the detailed results of the analysis or not. | No | One of the following string values: [‘yes’, ‘no’].<br>Default value is ‘no'. |
|
|
|
|
|
|
|
|
It should be noted that in case that the selected software project is private (i.e., proprietary), the credentials of the user need to be provided to the submitted request in the form of a Basic Authentication header. In order to ensure confidentiality, HTTPS is used for the cases of the private projects.
|
|
|
|
|
|
|
|
The output of the Quantitative Security Assessment web service is a JSON file containing the security assessment report, which includes the security index, the security scores of the model properties and characteristics, and the detailed static analysis results (provided that the user selected “yes” in the “inspection” parameter). The inspection parameter is very useful as it allows the selection of the level of detail of the produced security assessment report based on the user needs. The produced reports are usually very long especially for very large projects, since they contain the raw results, which are long lists of static analysis alerts. By setting the value of this parameter to ”no”, only the security index and the scores of the properties and the characteristics of the model are presented, leading to the production of much more lightweight security assessment reports.
|
|
|
|
|
|
|
|
For better understanding, an example is presented in the following demonstrating how the Quantitative Security Assessment web service can be invoked through a curl command for assessing the security of a software project. In the given example, a simple [HelloWorldJavaCompiled](https://github.com/siavvasm/HelloWorldJavaCompiled) Java Project that it is available on GitHub is used.
|
|
|
|
|
|
|
|
In brief, we want to analyze the security level of the HelloWorldCompiled project. Hence, in the parameters we set the following:
|
|
|
|
|
|
|
|
- **project:** https://github.com/siavvasm/HelloWorldJavaCompiled (the GitHub URL of the project)
|
|
|
|
- **language:** java (because it is a Java project)
|
|
|
|
- **inspection:** yes (because we want the detailed results to be included in the produced JSON)
|
|
|
|
|
|
|
|
Hence, the following HTTP GET Request needs to be submitted:
|
|
|
|
|
|
|
|
```
|
|
|
|
http://160.40.52.130:8089/DependabilityToolbox/SecurityAssessment?project=https://github.com/siavvasm/HelloWorldJavaCompiled&lang=java&inspection=yes
|
|
|
|
```
|
|
|
|
|
|
|
|
After submitting the request, the Quantitative Security Assessment (QSA) service in invoked and the selected project is analyzed with respect to its Security. In brief, QSA selects the Security Assessment Model for Java, performs static analysis, and aggregates the results according to the model, in order to compute a set of Security Metrics, as well as the overall *Security Index* of the selected project (for more information about the *Security Assessment Model* we refer the reader to the materials that are listed in the References section of the [Dependability Toolbox Description](dependability-toolbox-description) wiki page. After the successful execution of the analysis, a JSON report with the results is produced and sent as a response to the user. The produced JSON for the *HelloWorldCompiled* project is presented below. (It should be noted that for reasons of brevity, although the report provides additional information, this information has been removed from the JSON below, to facilitate its readability)
|
|
|
|
|
|
|
|
```
|
|
|
|
{
|
|
|
|
"name": "HelloWorldJavaCompiled",
|
|
|
|
"path": "",
|
|
|
|
"issues": [
|
|
|
|
{
|
|
|
|
"propertyName": "Misused_Functionality",
|
|
|
|
"issues": []
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"propertyName": "Exception_Handling",
|
|
|
|
"issues": []
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"propertyName": "Logging",
|
|
|
|
"issues": [
|
|
|
|
{
|
|
|
|
"ruleName": "SystemPrintln",
|
|
|
|
"ruleSetName": "Java Logging",
|
|
|
|
"packageName": "miltos.diploma",
|
|
|
|
"description": "\nSystem.out.println is used\n",
|
|
|
|
"externalInfoUrl": "https://pmd.github.io/pmd-5.4.1/pmd-java/rules/java/logging-java.html#SystemPrintln",
|
|
|
|
"priority": 2,
|
|
|
|
"beginLine": 11,
|
|
|
|
"endLine": 11,
|
|
|
|
"beginCol": 9,
|
|
|
|
"endCol": 26,
|
|
|
|
"classPath": "src/main/java/miltos/diploma/App.java"
|
|
|
|
}, ...
|
|
|
|
...
|
|
|
|
]
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"propertyName": "Assignment",
|
|
|
|
"issues": [
|
|
|
|
{
|
|
|
|
"ruleName": "MethodArgumentCouldBeFinal",
|
|
|
|
"ruleSetName": "Optimization",
|
|
|
|
"packageName": "miltos.diploma",
|
|
|
|
"description": "\nParameter 'args' is not assigned and could be declared final\n",
|
|
|
|
"externalInfoUrl": "https://pmd.github.io/pmd-5.4.1/pmd-java/rules/java/optimizations.html#MethodArgumentCouldBeFinal",
|
|
|
|
"priority": 3,
|
|
|
|
"beginLine": 9,
|
|
|
|
"endLine": 9,
|
|
|
|
"beginCol": 30,
|
|
|
|
"endCol": 42,
|
|
|
|
"classPath": "src/main/java/miltos/diploma/App.java"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"propertyName": "Resource_Handling",
|
|
|
|
"issues": [
|
|
|
|
{
|
|
|
|
"ruleName": "MethodArgumentCouldBeFinal",
|
|
|
|
"ruleSetName": "Optimization",
|
|
|
|
"packageName": "miltos.diploma",
|
|
|
|
"description": "\nParameter 'args' is not assigned and could be declared final\n",
|
|
|
|
"externalInfoUrl": "https://pmd.github.io/pmd-5.4.1/pmd-java/rules/java/optimizations.html#MethodArgumentCouldBeFinal",
|
|
|
|
"priority": 3,
|
|
|
|
"beginLine": 9,
|
|
|
|
"endLine": 9,
|
|
|
|
"beginCol": 30,
|
|
|
|
"endCol": 42,
|
|
|
|
"classPath": "src/main/java/miltos/diploma/App.java"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"propertyName": "Null_Pointer",
|
|
|
|
"issues": []
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"propertyName": "Synchronization",
|
|
|
|
"issues": []
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"metrics": {
|
|
|
|
"metricSet": [
|
|
|
|
{
|
|
|
|
"className": "miltos.diploma.App",
|
|
|
|
"wmc": 4,
|
|
|
|
"dit": 1,
|
|
|
|
"noc": 0,
|
|
|
|
"cbo": 0,
|
|
|
|
"rfc": 4,
|
|
|
|
"lcom": 1,
|
|
|
|
"ca": 0,
|
|
|
|
"ce": 0,
|
|
|
|
"npm": 4,
|
|
|
|
"lcom3": 2.0,
|
|
|
|
"loc": 18,
|
|
|
|
"dam": 0.0,
|
|
|
|
"moa": 0,
|
|
|
|
"mfa": 0.0,
|
|
|
|
"cam": 0.5,
|
|
|
|
"ic": 0,
|
|
|
|
"cbm": 0,
|
|
|
|
"amc": 3.5,
|
|
|
|
"methods": [
|
|
|
|
{
|
|
|
|
"methodName": "public static void main(String[] args)",
|
|
|
|
"cyclComplexity": 1,
|
|
|
|
"loc": 0
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"methodName": "public void _init_()",
|
|
|
|
"cyclComplexity": 1,
|
|
|
|
"loc": 0
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
"properties": {
|
|
|
|
"properties": [
|
|
|
|
{
|
|
|
|
"name": "Resource_Handling",
|
|
|
|
"description": "",
|
|
|
|
"thresholds": [
|
|
|
|
0.0024,
|
|
|
|
0.0582,
|
|
|
|
0.102
|
|
|
|
],
|
|
|
|
"eval": 0.5236957387495023,
|
|
|
|
"profile": [
|
|
|
|
0.0,
|
|
|
|
0.0,
|
|
|
|
1.0,
|
|
|
|
0.0,
|
|
|
|
0.0
|
|
|
|
],
|
|
|
|
"positive": false,
|
|
|
|
"measure": {
|
|
|
|
"value": 1.0,
|
|
|
|
"normValue": 0.05555555555555555,
|
|
|
|
"type": 1,
|
|
|
|
"metricName": "",
|
|
|
|
"rulesetPath": "./Rulesets/resourceHandRuleSet.xml",
|
|
|
|
"tool": "PMD",
|
|
|
|
"normalizer": 18
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Assignment",
|
|
|
|
"eval": 0.6227018385291767
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Exception_Handling",
|
|
|
|
"eval": 1.0,
|
|
|
|
{
|
|
|
|
"name": "Misused_Functionality",
|
|
|
|
"eval": 1.0
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Synchronization",
|
|
|
|
"eval": 1.0
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Null_Pointer",
|
|
|
|
"eval": 1.0
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Logging",
|
|
|
|
"eval": 0.0,
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Complexity",
|
|
|
|
"eval": 0.955947912812109,
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Cohesion",
|
|
|
|
"eval": 1.0,
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Coupling",
|
|
|
|
"eval": 1.0,
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Encapsulation",
|
|
|
|
"eval": 1.0,
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
"characteristics": {
|
|
|
|
"characteristics": [
|
|
|
|
{
|
|
|
|
"name": "Confidentiality",
|
|
|
|
"eval": 0.7756464616674826
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Integrity",
|
|
|
|
"eval": 0.837155432254497
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"name": "Availability",
|
|
|
|
"eval": 0.7964089283274383
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
"security_index": {
|
|
|
|
"eval": 0.8029899670557309,
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
As can be seen from the fragment above, the JSON report consists of four main elements which are listed below:
|
|
|
|
|
|
|
|
- **issues:** An array that contains the issues reported by the static code analyzer. These issues are grouped based on the static analysis-based properties (i.e., vulnerability categories) to which they belong.
|
|
|
|
|
|
|
|
- **properties:** An array that contains the results of the properties evaluation. More specifically, it contains the scores (i.e., eval) of the model’s properties.
|
|
|
|
|
|
|
|
- **characteristics:** An array that contains the results of the characteristics evaluation. More specifically, it contains the scores (i.e., eval) of the model’s characteristics.
|
|
|
|
|
|
|
|
- **security_index:** An object that contains the Security Index of the analyzed software.
|
|
|
|
|
