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:

class iscore.base.models.Service(id, parent, name, event_time, expire_time, max_score, score_released, subtype_ptr, url, port, protocol, external, tsi, tsi_pool, in_progress, public_visibility, blue_visibility, green_visibility, red_visibility, service_data, order)

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 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.

iscore.base.actions.insert_service_score_in_progress(service)

Mark a service check as being in progress. This will display a spinner next to the check in the service scanner displays.

Parameters:service (iscore.servicecheck.registry.ServiceHolder) – The service to be marked

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 insert_service_score()

iscore.base.actions.insert_service_score(service, result, status, error_msg, tsi=None)

Add the score for the specific service into the database.

Parameters:
  • service (iscore.servicecheck.registry.ServiceHolder) – The service details
  • result (int) – The score the team received for that check
  • status (str) – The status of the service check
  • error_msg (string) – The error message for the scan if any, None otherwise
  • tsi (iscore.base.models.TeamSpecificInfoCategory) – The TSI used by the check
Returns:

The saved Score object

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

iscore.base.actions.insert_service_score_done(service)

Mark a service check as being done. This should be called after insert_service_score_in_progress(). It will remove the spinner from the UI.

Parameters:service (iscore.servicecheck.ServiceHolder) – The ID of the service that has completed

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

iscore.base.actions.report_service_error(score, e)

Records the error for a service after a service scan.

Parameters:
  • score – The score object for the check
  • e – The error that was returned from the check

Note

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.