2. CyberCAPTOR-Server - User and Programmer Guide

This project is a part of FIWARE. For more information, please consult [FIWARE website] (http://www.fiware.org/).

CyberCAPTOR is an implementation of the Cyber Security Generic Enabler, the future developments of the [Security Monitoring GE] (http://catalogue.fiware.org/enablers/security-monitoring).

The high-level README file of CyberCAPTOR-Server can be found here.

2.2. Introduction

This is the User and Programmer Guide of CyberCAPTOR-Server.

2.3. User Guide

This guide describe how to use CyberCAPTOR-Server.

2.3.1. CyberCAPTOR-Server API

CyberCAPTOR-Server only contains the REST API Server of CyberCAPTOR. Thus, it can be used only via its REST API. If you want a GUI for CyberCAPTOR-Server, you can use CyberCAPTOR-Client which is described in [https://github.com/fiware-cybercaptor/cybercaptor-client].

2.3.1.1. API usage

2.3.1.1.1. Version API calls

To use the CyberCAPTOR server API, the first call to test that the server is available is

curl http://localhost:8080/cybercaptor-server/rest/version/detailed

which should returns something like

{"version":"4.4"}
2.3.1.1.2. Initialization calls

Before using the API to manipulate the attack graph, the attack paths, and the remediations, the first call that needs to be done is

curl -c /tmp/curl.cookie http://localhost:8080/cybercaptor-server/rest/json/initialize

which loads the topology, generates the attack graph with MulVAL and computes the attack paths.

Note the -c /tmp/curl.cookie option of curl, allowing to keep the session cookie, necessary to chain calls and keep the attack graph and attack paths in session.

It is also possible to load the topology from an XML file, or a XML string containing the XML network topology, using the POST method of the /rest/json/initialize call :

Using a XML String:

curl -c /tmp/curl.cookie -H "Content-Type: application/xml" -X POST -d '<topology><machine><name>linux-user-1</name><security_requirement>7</security_requirement><interfaces><interface><name>eth0</name><ipaddress>192.168.1.111</ipaddress><vlan><name>user-lan</name><label>user-lan</label></vlan></interface></interfaces><routes><route><destination>0.0.0.0</destination><mask>0.0.0.0</mask><gateway>192.168.1.111</gateway><interface>eth0</interface></route></routes></machine><machine><name>linux-user-2</name><security_requirement>30</security_requirement><interfaces><interface><name>eth0</name><ipaddress>192.168.1.112</ipaddress><vlan><name>user-lan</name><label>user-lan</label></vlan></interface></interfaces><services><service><name>mdns</name><ipaddress>192.168.1.112</ipaddress><protocol>udp</protocol><port>5353</port><vulnerabilities><vulnerability><type>remoteExploit</type><cve>CVE-2007-2446</cve><goal>privEscalation</goal><cvss>10.0</cvss></vulnerability></vulnerabilities></service></services><routes><route><destination>0.0.0.0</destination><mask>0.0.0.0</mask><gateway>192.168.1.111</gateway><interface>eth0</interface></route></routes></machine></topology>' http://localhost:8080/cybercaptor-server/rest/json/initialize

Using a XML file:

curl -c /tmp/curl.cookie -X POST  -H "Content-Type: multipart/form-data"  -F "file=@./topology.xml" http://localhost:8080/cybercaptor-server/rest/json/initialize

The exhaustive description of this file is XML topological file is provided in https://github.com/fiware-cybercaptor/cybercaptor-data-extraction/blob/master/doc/topology-file-specifications.md. This file can be generated automatically using CyberCAPTOR-Data-Extraction.

2.3.1.1.3. Attack graph, attack paths and remediation calls

Then, the calls to get the attack paths, attack graph or remediations can be used:

Get the number of attack paths:

curl -b /tmp/curl.cookie http://localhost:8080/cybercaptor-server/rest/json/attack_path/number

Note the -b /tmp/curl.cookie option of curl, to load the previously saved session cookie.

Get the attack path 0:

curl -b /tmp/curl.cookie http://localhost:8080/cybercaptor-server/rest/json/attack_path/0

Get the attack graph

curl -b /tmp/curl.cookie http://localhost:8080/cybercaptor-server/rest/json/attack_graph

Get the remediations for attack path 0:

curl -b /tmp/curl.cookie http://localhost:8080/cybercaptor-server/rest/json/attack_path/0/remediations

Get the XML network topology (useful for backups):

curl -b /tmp/curl.cookie http://localhost:8080/cybercaptor-server/rest/json/topology

The full list of API calls and specifications is stored in apiary.apib and can be visualized on Apiary.io using the Apiary Blueprint format.

2.4. Programmer Guide

This guide describe how to develop within CyberCAPTOR-Server.

2.4.1. Javadoc

The Javadoc of CyberCAPTOR-Server as well as many interesting information for developers can be found on github pages: Developer pages - Javadoc.

Javadoc can be updated directly with Maven using

mvn site-deploy

Don’t forget to configure GitHub OAuth token in ~/.m2/settings.xml. Tokens can be generated on https://github.com/settings/tokens, with repo and user:email authorized scopes.

<settings>
      <servers>
          <server>
                <id>github</id>
                <password>OAuth token</password>
          </server>
      </servers>
</settings>

2.4.1.1. API verification

The API specified using Blueprint can be checked with the dredd tool. In order to do that, first install bredd with NPM (you should have Node.js installed).

sudo npm install -g dredd

Go in the folder in which is the dredd configuration file tools/api/dredd.yml:

cd tools/api

Execute dredd

dredd

In addition to the console reports provided by dredd, a detailed report file can be found in tools/api/report.html.