.. _external-service-checks:

=======================
External Service Checks
=======================

IScorE supports "external" service checks, which means that IScorE itself will not run the
check as part of the regular checks. An example of an external check can be found in
`cimorescan.py` and the script that runs it, `run_cimorescan.bash`. Service checks that are
marked as external are responsible for updating the service check object themselves. An example
use case for service checks is for a service that returns the results for all teams at once.
The service check object contains the following information:

.. autoclass:: base.models.Service

When defining the service check in the admin section, the URL and port are available to the
script running the check. If they are not relevant for the particular check, as is the case
in the cimore example, they can be set to anything you want to be displayed to the teams.

-------------------------------
Writing your own external check
-------------------------------

When starting a check, call the :py:func:`~base.actions.insert_service_score_in_progress` method
to display an indicator next to the check on the `Service Status` page. The documentation for
this function can be found below.

.. autofunction:: base.actions.insert_service_score_in_progress

After marking the scan as in progress, you can perform whatever actions are necessary for
the scan. Calculate a score for the check in a way that makes sense for the service in
question. Once you have a score for the check insert it into the database using
:py:func:`~base.actions.insert_service_score`

.. autofunction:: base.actions.insert_service_score

When the check has completed you can mark it as completed which will remove the indicator
from the service status pages.

.. autofunction:: base.actions.insert_service_score_done

If a there was an error with the check (timeout, failed content check, invalid credentials, etc.), then the error should
be recorded with :py:func:`~base.actions.report_service_error` using the :py:class:`~base.models.Score` object returned
by :py:func:`~base.actions.insert_service_score` and the error. These errors are saved as
:py:class:`~base.models.ServiceError` objects.

.. autofunction:: base.actions.report_service_error

.. note::

    :py:class:`~base.models.ServiceError` objects are currently only viewable through the django admin console. There
    are plans to create an interface for admins/white team to use them to investigate service scanner errors/failures.