hutschen/mv-tool repository overview

⁠Docker image for MV-Tool

MV-Tool is for tracking measures in information security. If information security is to be implemented according to BSI IT Grundschutz⁠ or another procedure or standard, many information security measures need to be implemented.

MV-Tool supports this process insofar as concrete implementation steps (measures) can be determined for each information security requirement. The implementation of these measures can later be tracked in an issue tracker. Currently, only JIRA by Atlassian⁠ is supported as issue tracker.

⁠Write a configuration file

Before you can run the MV-Tool in a Docker container, you have to configure it. This is done by a configuration file. This is very simple and contains only a few entries:

• The URL to your JIRA instance with which you want to use with the MV-Tool.
• The URL to the database (connect string).
• Optional logging configuration.

jira:
  url: http://localhost:2990/jira
database:
  url: sqlite:///mvtool.db
uvicorn:
  log_level: error
  log_filename: mvtool.log

⁠Connection to JIRA

The connection to JIRA is mandatory for using the MV-Tool. The MV-Tool does not have its own user management, but uses that of the JIRA instance to which it is connected.

To connect to JIRA, simply specify the URL to your JIRA instance in the configuration file. For example, to access a JIRA instance that you have installed locally on your computer, the configuration might look like this:

jira:
  url: http://localhost:2990/jira

⁠Enable JSON API

Users log in to the MV-Tool with their JIRA credentials. The MV-Tool uses these credentials to authenticate with the JSON API of the JIRA instance via HTTP Basic Auth. To make this work, JSON API access must have been enabled in your JIRA instance. The credentials are not stored by the MV-Tool on the server side. The MV-Tool does not manage server-side user sessions. The user session is only managed on the client side.

If you use JIRA as a cloud service, you can only use HTTP Basic Auth in a limited way. Authentication is in this case not possible with your normal JIRA password. Instead of your password you have to use an access token. You need to generate this token in your JIRA user profile.

MV-Tool uses jira-python⁠ to access JIRA. For more information on authentication, see the jira-python documentation⁠.

⁠Database connection

Only SQLite and PostgreSQL are currently supported as databases. You should use PostgreSQL if you want to use MV-Tool in production. MV-Tool is significantly slower with SQLite than with PostgreSQL. SQLite is therefore not suitable in production.

MV-Tool uses SQLAlchemy as the ORM mapper. The database URLs (connect strings) must therefore be specified so that SQLAlchemy understands them:

• For SQLite you can find the information about the structure of the connect string in the SQLAlchemy Dokumentation⁠.
• Connections to PostgreSQL databases are made using the psycopg2⁠ driver. You can also find the information about the connect string in the SQLAlchemy Dokumentation⁠.

A connection to a SQLite database file might look like the following in your configuration file:

database:
  url: sqlite:///mvtool.db

The database file mvtool.db addressed in this example is created automatically if it does not exist. It is stored in the Docker container under /usr/src/api/mvtool.db.

⁠Logging

Logging is important so that bugs can be noticed and fixed in future versions of the MV-Tool. Therefore, you should set up logging and save log files outside the Docker container as well. Regarding logging, there are the following configuration options:

• Log level with the options critical, error, warning, info, debug, trace and the default value error.
• Log Dateiname with the default value mvtool.log.

The logging configuration may look like the following in your configuration file:

uvicorn:
  log_level: error
  log_filename: mvtool.log

The log file is stored in the Docker container at /usr/src/api/mvtool.log. Contents of the log file are not deleted. New log entries are appended to an existing file.

⁠HTTPS / SSL

The use of SSL / HTTPS is higly recommended. A self-signed certificate can be used for testing. For productive use, a certificate signed by a trusted authority, such as Let's Encrypt⁠, is recommended.

A self-signed certificate can be easily generated with the following command on Linux and macOS. A password for the private key (key.pem) must be specified in any case, otherwise the command will fail. -subj '/CN=localhost' has to be adjusted to the hostname you are using if it is not localhost.

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -subj '/CN=localhost'

When certificate (e.g. cert.pem) and key file (e.g. key.pem) are available, these files should be copied / mounted into the Docker container under /usr/src/api/. After that, SSL can be configured as follows:

uvicorn:
  ssl_keyfile: key.pem
  ssl_keyfile_password: password
  ssl_certfile: cert.pem

Important: After restarting the Docker container, the MV tool can no longer be accessed via HTTP. HTTPS must be used instead.

⁠Run the Docker container

Save your configuration in a file (e.g. config.yml) and then execute the following commands to create the container, copy your configuration into the container and finally start the container.

docker container create --name mv-tool -p 4200:8000 hutschen/mv-tool
docker container cp config.yml mv-tool:/usr/src/api/config.yml
docker container start mv-tool