Page tree
Skip to end of metadata
Go to start of metadata

1 GUIDE CONTENTS

A description of the PROTECTIVE system for this phase can be found in D6.8 PROTECTIVE System v2 which is available in the Pilot Information pack.

This document is a step-by-step guide to install a PROTECTIVE node. If you follow this guide, complete all the steps you will have:

  • A local Warden Server receiving events via connectors from probes and sensors in your local constituency.
  • A warden_filer_receiver receiving events from your local Warden Server.
  • A Mentat storing the events received from your local Warden Server and from the peers.
  • Warden_filer_receivers for receiveing events from the peer nodes.
  • The connectors are included in the Annex of this document. How to set up connectors for real data mode is documented.
    The connectors are:
      • Real Data: For the live environment during the pilots, steps are provided for connecting the following connectors

        • Kippo

        • Dionaea 

        • LaBrea

        • IntelMQConnector
        • Fortigate
        • Juniper SRX 
        • SIEM Mcafee 
        • Warden Parser

1.1 Support

If you have any problems during installation of after it, please, send and email with your issues to:

2         PREREQUISITES 

2.1        System Requirements

Hardware:

  • Operating System: Ubuntu 16.04 LTS Server
  • HDD: 320 GB
  • RAM: 32 GB

Software:

  • Git, docker (17.12.0-ce+) and docker-compose (1.18.0+) are installed.

System Configuration

  • IPTables allow internal docker network

  • Ports that need to be opened in order to allow the node run and communicate with its components properly:
    • 3001
    • 4200
    • 4201
    • 8080
    • 8089
    • 8888
    • 9080
    • 9280

2.2        Access Requirements

You will need to access to the protective-h2020-eu project in Gitlab - https://gitlab.com/protective-h2020-eu/.This project is Open Source so, you shouldn't find any problem accessing to it. 

If you have any problems accessing, please contact to: pilot@protective-h2020.eu

2.3        Peer Node Certificates

In order to be able to connect with other Peer nodes, certificates are needed for communication between Warden server and each Peer node’s Warden filer receiver. The procedure in order to get the certificates assumes that the system administrator (admin) will get the certificates. Admin will be the person doing the installation of the PROTECTIVE node at each Peer node. To prepare for configuration of event collection from a peer node [warden] server, the process is as follows:

Assuming that the Peer Sender (Peer-S) and Peer Receiver (Peer-R) have agreed to share data, the Peer-R admin provides the following data to the Peer-S admin:

    1. chosen client name
    2. machine DNS name
    3. name and email address of the administrator (where Peer-S admin and automated inspection scripts will be able to reach him)
    4. A  brief description of planned utilisation of the received events
    5. Any additional information or questions

For now, gather this information. 

2.4        Peer Node Admin email

2.4.1 Ensure that you have access to email that is enabled for sending PGP encrpyted email.

2.4.2 You will need to email address of the admin for each peer node that you want to collect events from. If you don't have it, please request it at: pilot@protective-h2020.eu

2.5        Probes and Sensors to be Connected

Information for how to connect each probe/sensor  detection system is included at the end of the installation guide. However, this will be moved out of the installation guide in a later release. It has yet to be decided where to make the connector information available.

3         Installation

3.1        PROTECTIVE Node Event Flow Overview

Figure 1: Event Input and Output

 

Figure 1 shows the Warden and Mentat modules of the PROTECTIVE node, the communication paths for events in a PROTECTIVE node, the interfaces node’s connectors and the interfaces for for communication with a Peer PROTECTIVE node.  Each module is provided as one or more docker images stored in PROTECTIVE’s gitlab registry. These images will be executed as twelve docker containers.

Installation of a PROTECTIVE Node involves the following steps:

  1. Install the node by executing scripts and filling in environment details - ch. 3.2
  2. Register internal warden client receiver - ch 3.3
  3. Connect to peer nodes as a sender by registering the peer nodes as remote clients in the warden server - ch 3.4
  4. Connect to peer nodes as a receiver by configuring your warden filer receivers - ch 3.5
  5. Add connectors to collect data from detections systems within your constituency - ch 3.6 

Steps 2 - 4 are independent of each other in your PROTECTIVE node.

 

 

3.2 Installation

IMPORTANT NOTE: If you have the PROTECTIVE Node from Pilot 1 Phase 1 already installed, follow the instructions on: https://gitlab.com/protective-h2020-eu/protective-node/tree/master#upgrade-protective-node-from-pilot1-phase1-to-pilot1-phase2 to upgrade the node to phase 2 in an easy way. With this way, you won't need to reconfigure anything.

 

If you are installing the node from scratch, you will need the DNS names for each of the two peer nodes your node will connect to - see ch. 2.4 

Follow the instructions in the README.md on https://gitlab.com/protective-h2020-eu/protective-node to install the node.

The PROTECTIVE node should now be started and accessible on port 4200 of your machine. The first time we install, and run it it takes a few minutes to start, since it has to download all the dependencies for prot-dash.

3.3 Register Internal Warden Filer Receiver

The first thing we should do is to configure our internal warden filer receiver in order to get local Warden Server events (ingested by the connectors) into Mentat.

3.3.1 Check internal client is registered

Ensure that in Warden Server the internal client is registered:

3.3.2 Registering in Warden RA

Next step is to register in warden_ra to get the certs:

3.3.3 Applying for the certificate

Now we must run warden_apply.sh (located  at the root folder of protective-node) and copy the certificates to the appropiate folder:

3.3.4 Copy keys

Step 3.3.3 should generate a set of certificates cert.pem and key.pem that you have to copy in keys folder of the internal receiver:

3.3.5 Restart the internal Warden Filer Receiver

Finally we only have to restart the internal receiver for the changes to take effect:

The next step is to set up the certificates for the Peer nodes.

An example of a working node can be found at our test bed http://protective_dev.gmv.com. This node is based in GMV and is collecting data from Cesnet and Roedunet.

3.4 Configuration to send events to Peers

In order to send data to peer nodes, the peer node warden filer receivers must be registered in the warden server of the PROTECTIVE node by the Peer-S admin.

3.4.1 Receive email from Peer-R at each peer node

As Peer-S admin, you will have received a PGP encrpyted email from an Peer-R requesting a token [and server.crt] with the following information:

    1. chosen client name
    2. machine DNS name
    3. name and email address of the administrator (where Peer-S admin and automated inspection scripts will be able to reach him)
    4. A  brief description of planned utilisation of the received events
    5. Any additional information or questions

3.4.2 Registering in Warden Server

First step is to register the new client into Warden Server. If you have already done, you can jump to next step

From your PROTECTIVE Node machine, enter warden_server docker by default protective_warden_1 and a register the new client as follows:

 

# List the clients
docker exec -it protective_warden_1 python warden_server.py list
# If the client if not listed
    docker exec -it protective_warden_1 python warden_server.py register --name warden.registered.client --secret clientSecret --hostname X.X.X.X --requestor client@mail.com --read --write --notest
  
## If the client is listed, modify an existing client:
    docker exec -it protective_warden_1 python warden_server.py modify [--help] -i ID [-n NAME] [-h HOSTNAME]
                        [-r REQUESTOR] [-s SECRET] [--note NOTE]
                        [--valid | --novalid] [--read | --noread]
                        [--nowrite | --write] [--nodebug | --debug]
                        [--test | --notest]

 

3.4.3 Registering in Warden_ra

Using, the information received in the 2.2.2, register this new client into Warden_ra. 

Enter warden_ra container by default protective_wardenra_1 and run the command to add the new client to it.

 

docker exec -it protective_warden_ra_1 python warden_ra.py register --name warden.registered.client --admins client@mail.com
 
# Output should be:
 
Client:   warden.registered.client
Admins:   client@mail.com
Status:   New

 

3.4.4 Generating token for client in Warden_ra

Enter warden_ra container and run the command to generate the token for the client. Note the token is returned as "Application password". 

 

docker exec -it protective_warden_ra_1 python warden_ra.py applicant --name warden.registered.client
  
Output should be:
  
Client:   warden.registered.client
Admins:   client@mail.com
Status:   Issuable
 
Application password is: DhegTGnM7hQvgvHk

 

Note: The token generated is a one-shot password, so only can be use one time. If the client need to generate the certificates again you have to provide a new token.

3.4.5 Email (using php) registered client details to the admin in the peer node

Once you have the token, the token and the server.crt located in protective-node/node_name/data/keys/warden_server, next step is to send an email to the Peer-R admin by secure mail. The email should include the token, the server.crt and the url of the warden server. Also, if in step 3.4.2 when registering the client you generated a secret for it, you should include this secret in the email.

3.5 Configuration To Receive events from Peers

To receive event from a peer node, the warden filer receiver must be configured in the PROTECTIVE node by the admin acting as the Peer-R admin. The Peer-R admin will be doing the reverse of the steps outlined in chapter 3.3.

3.5.1 Send email to Peer-S admin

For each peer node you would like to receive events from, send an email to the peer node admin requesting registration in and connection to the peer node warden server.

As Peer-R admin, you will send a PGP encrpyted email to an Peer-S requesting a token, a server.crt and the url for the warden server. You will provide the following information:

    1. chosen client name
    2. machine DNS name
    3. name and email address of the administrator (where Peer-S admin and automated inspection scripts will be able to reach him)
    4. A  brief description of planned utilisation of the received events
    5. Any additional information or questions

3.5.2 Receive email from each Peer-S admin in the peer nodes

You will receive an email with a token, server.crt  and warden server url by secure mail from each peer node. 

3.5.3 Applying for the certificates

The token, server.crt and url received in step 3.5.2 is now used to apply for certificates to the peer node. This step must be done for each peer node.

In the client machine, use the token, the server.crt and the script to apply for the certificates: warden_apply.sh. Located in the root folder of https://gitlab.com/protective-h2020-eu/protective-node/

Then:

 

# The command is:
./warden_apply.sh --cacert server.crt https://WARDEN_RA_IP:WARDEN_RA_PORT/warden_ra/ client_name token
 
For example:
./warden_apply.sh --cacert server.crt https://10.255.0.8:9280/warden_ra/ warden.registered.client DhegTGnM7hQvgvHk

 

If everything goes correctly, the files key.pem and cert.pem will appear in the current directory (along with csr.pem, which is not necessary anymore, but you can save it for potential debugging)

Now copy the generated certificates key.pem, cert.pem and server.crt in protective-node/node_name/data/keys/receiver_name

And finally to apply this configuration, you only need to restart the receiver as:



4. Connector Registration

For each connector configuration, you will need the URL of the Warden server and the server.crt used in chapter 3.

You will need to do the steps outlined in this chapter to get the client certificate and corresponding private key (cert.pem and key.pem) used in the warden_client.cfg file for each connector.

4.1 Get a token

Choose a client name for the connector. To get a token, the client needs to be registered in the warden server and warden ra. Do the steps outlined in chapter 3.4.23.4.3 and 3.4.4.

4.2 Get the cert and key

To get the cert.pem and key.pem files, using the token received in chapter 4.1, the url of the warden server and the server.crt, follow the steps in chapter 3.4.4.

4.3 Configure connection between connector and Warden Server

Once you have the certificates, you need to follow the specific instructions of each connector to configure the sending of events to Warden Server. Normally, it should be just setting up a warden_filer_sender.

 

5. Maintenance

In this chapter, we will include all the know issues and recommendations of the protective node installation.

5.1. Reinstallation of PROTECTIVE Node

In order to reinstall PROTECTIVE Node correctly do the following:

After that, to ensure all the docker containers are stopped and removed run:

5.2. Error of internal receiver on Linux

We have detected that on some Linux systems after configuring the internal receiver and restart it, it always throws an error:

In consequence the internal receiver is not working. To correct it you must allow internal docker network in IPTables as follows:

 

 

  • No labels