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:
Service(id, team, subtype, url, port, external, username, password, credential_pool, team_specific_info, protocol, http_string, last_scan, last_scan_time, last_scan_error, team_specific, in_progress, public_visibility, blue_visibility, green_visibility, red_visibility, administratively_down, down_reason, score_cap)¶
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
to display an indicator next to the check on the Service Status page. The documentation for
this function can be found below.
Mark a service check as being in progress. This will display a spinner next to the check in the service scanner displays.
Parameters: service_id – The ID of the service that is 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
insert_service_score(service_id, result, error_msg)¶
Add the score for the specific service into the database.
When the check has completed you can mark it as completed which will remove the indicator from the service status pages.
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_id – 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
insert_service_score() and the error. These errors are saved as
Records the error for a service after a service scan.
- score – The score object for the check
- e – The error that was returned from the check
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.