Metadata-Version: 2.1
Name: intelmq-api
Version: 2.3.0a3
Summary: Intelmq-API is a REST API to manage an intelmq, a solution for IT security teams for collecting and processing security feeds
Home-page: https://github.com/certtools/intelmq-api
License: UNKNOWN
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Requires-Dist: hug (>=2.3.0)
Requires-Dist: intelmq (>=2.3.0)

.. 
   SPDX-FileCopyrightText: 2020 Birger Schacht
   SPDX-License-Identifier: AGPL-3.0-or-later

###########
intelmq-api
###########

|Build Status|

.. |Build Status| image:: https://travis-ci.com/certtools/intelmq-api.svg?branch=develop
   :target: https://travis-ci.com/certtools/intelmq-api

intelmq-api is a `hug <http://hug.rest>`_ based API for the `intelmq <https://github.com/certtools/intelmq/>`_ project.

**********************************
Installing and running intelmq-api
**********************************

``intelmq-api`` requires at least `Python 3.6 <https://www.python.org/downloads/release/python-360/>`_.

Install ``intelmq-api`` using your preferred package installation mechanism (``pip``, ``apt``, ``yum``, ``dnf``...).

* ``pip install intelmq-api``
* ``apt install intelmq-api``
* ``yum install intelmq-api``
* ``zypper install intelmq-api``

Depending on your setup you might have to install ``sudo`` to make it possible for the ``intelmq-api`` to run the ``intelmq`` command as the user-account usually used to run ``intelmq`` (which is also often called ``intelmq``).

You can run ``intelmq-api`` directly using ``hug``:

.. code-block:: bash

   hug -m intelmq_api.serve


Or using uwsgi

.. code-block:: bash

   uwsgi --http 0.0.0.0:8000 -w intelmq_api.serve --callable __hug_wsgi__

Or using gunicorn

.. code-block:: bash

   gunicorn intelmq_api.serve:__hug_wsgi__


The ``intelmq-api`` provides the route ``/api`` for managing the ``intelmq`` installation. If it has access to an installation of the ``intelmq-manager`` files it serves them under the ``/management`` route.

***********************
Configuring intelmq-api
***********************

intelmq-api is configured using a configuration file in ``json`` format. The path to the configuration file is set using
the environment variable ``INTELMQ_MANAGER_CONFIG``. When running the API using ``hug``, you can set the environment
variable like this:

.. code-block:: bash

   INTELMQ_MANAGER_CONFIG=intelmq-api-config.json hug -m intelmq_api.serve


A sample configuration file ``intelmq-api-config.json`` is part of the distribution, it is also listed here fore reference.
In this configuration the setting ``session_store`` is disabled by prepending it with an underscore:

.. code-block:: json

   {
           "intelmq_ctl_cmd": ["intelmqctl"],
           "allowed_path": "/opt/intelmq/var/lib/bots/",
           "_session_store": "/tmp/intelmq-session.sqlite",
           "session_duration": 86400,
           "allow_origins": ["*"],
           "html_dir": "/usr/share/intelmq-manager/html/"
   }

The following configuration options are available:

* ``intelmq_ctl_cmd``: Your ``intelmqctl`` command. If this is not set in a configuration file the default is used, which is ``["sudo", "-u", "intelmq", "/usr/local/bin/intelmqctl"]``
   The option `"intelmq_ctl_cmd"` is a list of strings so that we can avoid shell-injection vulnerabilities because no shell is involved when running the command.
   This means that if the command you want to use needs parameters, they have to be separate strings.

* ``allowed_path``: intelmq-api can grant **read-only** access to specific files- this setting defines the path those files can reside in
* ``session_store``: this is an optional path to a sqlite database, which is used for sesssion storage and authentication. If it is not set (which is the default), no authentication is used!
* ``session_duration``: the maximal duration of a session, its 86400 seconds by default
* ``allow_origins``: a list of origins the responses of the API can be shared with. Allows every origin by default.
* ``html_dir``: the path to the html files of the ``intelmq-manager``. If this path exists it is served under the path ``/management``

*************
Adding a user
*************

If you set theh ``session_store`` configuration setting you have to create a user to be able to access the API functionality. You can do this also using hug:

.. code-block:: bash

   hug -m intelmq_api.serve -c add_user <username>

**************
Usual problems
**************

If the command is not configured correctly, you'll see exceptions on startup like this:

.. code-block:: bash

   intelmq_manager.runctl.IntelMQCtlError: <ERROR_MESSAGE>

This means the intelmqctl command could not be executed as a subprocess.
The ``<ERROR_MESSAGE>`` should indicate why.

To save the positions of the bots in the configuration map, you need
an existing writable ``manager/positions.conf`` file. If it's missing,
just create an empty one.

*************
Type checking
*************

Except for the parts that directly deal with ``hug``, the code can be
typechecked with ``mypy``. To run the type checker, start with the module
``serve``:

.. code-block:: bash

   mypy intelmq_manager/serve.py


