HD3Tool - OSADL

HD3Tool - Manual

CI: none

HD3ToolManual

July 14, 2020

Organization: Open Source Automation Development LabDepartment: Safety Critical Linux Working GroupProject: SIL2Author: Markus Kreidl

Release: 1Revision: 1Revision Number: 1.1Date: June 20, 2020Expires: —Ref:Status: reviewed DraftFormat: LATEXQA: reviewTracking: gitLicense: Creative Commons

HD3 Manual

Contents

1 Install 31.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 Create admin user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Back-end 52.1 Admin access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Authentication and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.2.1 Users section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2.2 Create user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2.3 Existing users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.3 HD3CONF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3.1 Analysis types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3.2 HD3 Standard items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.3.3 Analysis Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.3.4 Layer configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.3.5 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.3.6 Guidewords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3.7 Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3.8 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.3.9 Severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3 Front-end 173.1 Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.2 Project view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.2.1 Create session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.3 Current sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4 Example HAZOP project 26

Acronyms 27

1

ChangeLog

Version Author Date Comment

0.1 Markus Kreidl 22, June 2020 initial draft

Reviews:

Version Reviewer Date Comment

Status: Draft, complete unreviewed, released

2

HD3Tool Manual Draft

1 Install

Using Docker is the recommended HD3Tool installation. A native installation is possible, we stronglyrecommend with Debian Buster - no other Linux distribution has been tested. The Dockerfile pointsout which packages have to be installed via apt-get and pip3.

1.1 Requirements

The HD3Tool has the following requirements:

• Linux distribution with docker software installed

• SSH key (*)

• GIToLite server (*)

• https certificate (*)

• IRC Server (1)

The HD3Tool can be installed locally or on a server. Server installation requirements are markedwith (*) For server installation depending on the configuration (e.g. usage behind NGINX reverseproxy) the port 8002 must be exposed or exported in docker-compose.yml.

Note 1: The HD3Tool can record IRC discussions - if there is an configured server in settings.An IRC Server installation is NOT part of this manual.

1.2 Ports

The HD3tool uses the following ports:

• 8002 - HD3Tool

• 8008 - IRC Channel from web tool

• 8003 - Daphne used for channels

• 6667 - Connect to IRC server

Be aware of the ports in your firewall configuration.

1.3 Setup

Execute the following command in a working directory:

$ git clone https://user:[email protected]/git/HD3Tool.git$ cd HD3Tool/src$ docker-compose build$ docker-compose up -d$ docker-compose run hd3_tool python3 manage.py makemigrations$ docker-compose run hd3_tool python3 manage.py migrate

3/27


$ docker-compose run hd3_tool python3 manage.py migrate --run-syncdb$ docker-compose run hd3_tool python3 django-admin sync_roles$ docker-compose run hd3_tool python3 manage.py loaddata HD3tool/fixtures/init_data.json

Note: The last command initializes the sqlite database.

1.4 Create admin user

$ docker exec -it HD3tool /bin/bash

$ python3 manage.py createsuperuser

Depending on the installation type (local/server) the HD3tool is available via:

LOCAL: http://localhost:8001/HD3tool/admin

SERVER: https://server_name/HD3tool/admin

4/27


2 Back-end

HD3Tool configurations and project settings can be modified with the Django back-end. The adminarea has four main sections.

1. Authentication and Authorization

2. HD3 roles

3. HD3App

4. HD3Conf

Sections (1) and (4) are described in this Manual.

2.1 Admin access

Depending on the installation the HD3tool can be accessed:


SERVER: https://my_server_name/HD3tool/admin

2.2 Authentication and Authorization

2.2.1 Users section

Click +Add in authentication and authorization section to add a new user.

Figure 1: Administration of groups/users

5/27


2.2.2 Create user

Set Username and Password and save.

Figure 2: Add user

Add user information in Personal info section and set possible HD3 roles for the user in thepermissions section.

6/27


Figure 3: Details and Permission

2.2.3 Existing users

In the Users section click Users to see added users.

7/27


Figure 4: Created users

8/27


2.3 HD3CONF

All items (except Projects) in this section define HD3Tool behaviour according the HD3 process.

Figure 5: HD3Conf option

2.3.1 Analysis types

Figure 6: Pre configured analysis types

9/27


2.3.2 HD3 Standard items

As mentioned in section Guidewords the HD3Tool can handle different analysis types. Each analysistype has different guide words and depends on different layers. During installation the HD3ToolHAZOP analysis has been pre-configured.

Figure 7: Setup item dialog

This dialog defines the to be used guide words and layers.

10/27


2.3.3 Analysis Layers

In this section HD3 process layers are defined.

Figure 8: A selection of preconfigured layers

The HD3Tool can be also used for security analysis. In this case new layers must be created.(Note: Security analysis have not been tested)

2.3.4 Layer configuration

Layers can be configured in a very flexible way. Attributes can be created and added. An examplelayer configuration for the High Level layer in the HD3 process.

11/27


Figure 9: HL (High Level) Layer Configuration

Each layers attributes are managed in the Attrs section. The order can be manipulated with theup/down arrow. Every Layer in the HD3 process has a SAC layer and needs to be assigned. Tocontrol the layer order also an Up layer needs to be assigned. In this case HL is the top level layer.

2.3.5 Attributes

The attribute section is needed to define the behaviour of certain attributes depending on the mode.Four different modes (view, edit, print and add) are defined. E.g. the attribute origin is mostlyhandled like label GUI element for the modes (print, view) but when an element is added or editedthe origin has to be hidden.

12/27


2.3.6 Guidewords

Depending on the HAZOP type different guide words are used. Guide words can be added dependingon the analysis type (e.g security).

2.3.7 Projects

Shows information about existing projects. Via ADD PROJECT a new project can be created.Project name, analysis type and user to be added must be defined.

Figure 10: Project example configuration

Important: The settings tab has per default two settings are preconfigured. Silbox and local.

13/27


After the project has been created the needed repositories must be initialized.

Figure 11: Project repositoyr init

2.3.8 Settings

This settings file describes a HD3Tool hosted on an server behind a NGINX reverse proxy. Importantto let tool know the full URL. If data should be pushed to a git server the fields Git server, Gituser, Git port and Git key must be set.

The git ssh key location:

/home/user/.ssh/hd3tool

The HD3tool works exclusively with Gitolite (https://gitolite.com) because of the wild repo feature.

14/27


Figure 12: Server installation Figure 13: Local installation

This local settings file only contains the server and name information. In both cases no IRC serverhas been defined.

2.3.9 Severity

The HD3 process defined severities are defined in this section

15/27


Figure 14: Pre defined severities

16/27


3 Front-end

Enter the address

LOCAL: http://localhost:8001/HD3tool/HD3app

SERVER: https://sil2.osadl.org/HD3tool/HD3app

to get to the initial HD3app page.

Figure 15: HD3tool start page after login

3.1 Projects

Figure 16: HD3tool existing projects

17/27


3.2 Project view

Figure 17: Project page view

Figure 18: Create HD3 item

Figure 19: Create PDF

Figure 20: Show Item graph

Figure 21: Logout current user

18/27


3.2.1 Create session

Create new session by clicking (3) the create session symbol.

Figure 22: Setup item dialog

Define an item name and the corresponding layer.

Figure 23: Select item origin

Each item has an origin. High level items at the moment refer to Top Level.

19/27


Figure 24: Recorder view

The Recorder has the following controls:

• Activate ... Activate attribute. The current attribute header changes its color to red

• Propose ... Used signal, that the user wants to propose a text

• Send ... User sends proposed text to other users

• Confirm ... The user can press confirm if he/she agrees with the proposed text.

• User info ... Below the Activate button a list of joined user is diplayed. When a user confirmsa proposed text a ”confirmed” is displayed next to the user name.

• +Todo ... Add a todo which occured because of the current item/attribute

• +SAC ... Add a new SACs. The SAC origin will be set automatically.

• +Selection Criteria ... Add a selection criteria

20/27


Figure 25: Add Todo view Figure 26: Add SAC view

21/27


Figure 27: Review room view

The review view is similar to the recorder view just without two differences

• Only the recorder can activate a new attribute

• The recorder commits (Figure 28) the item which have to be signed (Figure 29) first by theothers

22/27


Figure 28: Recorder room commit

Figure 29: Review room sign

23/27


Figure 30: Using reference shortcut ”:r”

By pressing :r an catalogue opens with already created elements. By selecting the desired itemand pressing enter the corresponding reference will be inserted. The same can be done to insertseverity tags. Press :S a catalogue opens with available severities.

3.3 Current sessions

Figure 31: Overview of created sessions

24/27


The current user (admin) can join the last session as recorder. Users roles are defined in the back-end.

25/27


4 Example HAZOP project

In this section we create an example project and start a session und the premise that the settingshave ben adapted to the existing enviornment.

1. Access back end:


SERVER: https://sil2.osadl.org/HD3tool/admin

2. Section HDconf - Projects click +ADD (see Figure 5)

3. Add information (see Figure 10, adapt name, created by, users and settings) and save

4. Click check box next to created project and set Action to Init project git repos and clickGo

5. Access front end

LOCAL: http://localhost:8001/HD3tool/HD3app

SERVER: https://sil2.osadl.org/HD3tool/HD3app

6. Click on the created project (see Figure 16)

7. Click on the Create HD3 item link (see Figure 18)

8. Define item name (see Figure 18)

9. Set current layer (HL)

10. set origin and press Start

11. Start session

26/27


27/27

Documents

HD3Tool - OSADL