comply or explain docs + admin tweaks

parent d97cd939
# Comply or explain
Comply or explain allows owners of services to publicly explain why a certain rating should be different / ignored or invalidated.
This allows them to handle edge cases which impede them from ever becoming compliant to common basic security practices.
An explanation can be given for each scan that is done on an organization. Each explanation allows to enter some reasoning and
has an expiration date. An explanation will thus expire after some time and should be set to a reasonable amount of time.
(typically a year).
All explanations are published on the website and can also be downloaded for (later) import in other systems.
Some common reasons why an explanation is used:
- A scanner gave a wrong rating, or the rating can be explained without compromising security.
- A scanner could not connect to the scanned service because of incorrect implementation in failmap.
- A scanner was not behaving according to modern security practices or RFC's.
- The result contains a glitch, for example: two conflicting results are shown instead of one.
## Explanation and abuse
Comply or explain can be extremely powerful. With this power also comes responsibility. There are several tools that prevent
abuse. Some of them are:
### Transparency
An explanation can applied to any issue, even high risk issues. Explaining something does not make the finding go away. Instead
the finding is shown accompanied by the explanation. This is done because a third-party scan will still see your service
as insecure: the third party can now correlate their can result with your explanation.
Here is an example of a high-risk issue that has been explained. Note that the high-risk has a strike through but is still present.
![Example explanation by Groningen](comply_or_explain/example_explain_groningen.png)
### Known common incorrect explanations
Not everyone is a tech or security wizard. This leads to some explanations being given that do not make sense from a security and
usually the operational perspective. The following are two examples of explanations which will be ignored:
Invalid explanation 1: This is a public service, thus the data does not need to be encrypted.
This is invalid because the organization should not determine the privacy of the client. The client will determine if
they want to shield their data-transfer from third parties or not. Additionally encryption also results in data integrity
which is also important when serving public information.
Invalid explanation 2: We don't offer this kind of security as a matter of policy.
Not implementing the most basic security norms because of a differing policy is possible. But the policy has to be explained publicly.
Usually a vague explanation like this will be met with scrutiny: why is your policy more important than the universally advised
security practices? What makes you decide security in this case is not as relevant?
### Explanation agreement and public accountability
Every volunteer handling explanations agrees to the guidelines outlined in the explanation code of conduct. This helps
define expected behaviour of our volunteers such as being professional and security oriented.
## Example Explanation: SIP Telephone services
Below screenshot shows a municipality explaining a high risk: their domain runs SIP (phone services) on ports 80 and 443.
The vendor of these services has explained they will only use these ports for voice traffic between clients using their
own (public and trusted) certificate.
The certificate used by the third party is technically correct, but does not use the name of the municipality. Therefore
there is no explicit trust. The clients however do check the certificate and there is no website configured at this address.
Usually ports 80 and 443 are used for the HTTP protocol: websites and webservices. In this case these ports are used
because they are easier to configure on the firewall.
Our scanner sees that the incorrectly named certificate is used on a standard website port. Therefore it marks the website
as not trusted. Yet because the url is only used by phones, and there is no website configured, the finding has been
![Example explanation by Groningen](comply_or_explain/example_explain_groningen.png)
If you do not agree with the explanation or the type of explanation, it's possible to open an issue at our gitlab page.
This page is located at:
## Becoming an comply or explain volunteer
It's possible to participate in the "comply or explain" program as a volunteer. You will be granted access to the
private issue feed where you can view explain-requests. You'll also be able to manipulate explain information for scans.
This gives a unique position to help your and other organizations to handle edge cases.
As a volunteer you will be given:
- Access to the issue list, with confidential issues:
- Access to the admin interface using a personal client-certificate.
- Access to the scans in failmap, with the possibility to alter explanations.
- Access to the chat group:
## Explanation code of conduct
When handling explain-requests, or any issue in failmap, you're working with partially confidential information. For example:
who is doing the explanation is secret because of privacy reasons (but not the organization explaining it).
When handling explain request we expect a professional attitude which is politically neutral and technically oriented. For example:
your preference of organization should not alter your judgement.
## How to explain a scan
### Find the scan
### Alter comply or explain information
### Optional: rebuild reports
Reports are usually built every night.
If you want to make changes visible earlier it's possible to rebuild the report using the shiny and glittery "rebuild ratings" button.
Note that it can still take an hour to process that request: rebuilding reports take time, as well as the amount of work
currently done by the system may delay your request. Additionally caching on the server will prevent you seeing the new report.
The report first shows on the admin website, as that doesn't use caching.
## Frequently asked questions
### Why is my explanation gone?
Explanations will be tied to a specific scan. When the scan result changes, you need to explain again. So if the result
changes, better make sure that no explanation is needed anymore. We usually see this happen with TLS scans, as the
security of TLS slowly degrades over time.
This diff is collapsed.
......@@ -239,7 +239,7 @@ class ExplainMixin(models.Model):
comply_or_explain_explanation = models.TextField(
help_text="Text that helps explain why this result is not counted in the report. For example: "
"a broken scanner or another edge-case that is mainly on the side of the scanning party. Having "
"requested the supplier for a fix, or promising a fix should be stored as a promise, not as an "
......@@ -251,7 +251,7 @@ class ExplainMixin(models.Model):
comply_or_explain_explained_by = models.CharField(
help_text="Please also refer to a thread, discussion or another fact that can be verified.",
verbose_name="explained by",
......@@ -267,7 +267,7 @@ class ExplainMixin(models.Model):
comply_or_explain_case_handled_by = models.CharField(
help_text="Who entered the comply-or-explain information, so it's easy to find the right person to talk to in "
"case of follow-ups.",
verbose_name="case handled by",
......@@ -277,7 +277,7 @@ class ExplainMixin(models.Model):
comply_or_explain_case_additional_notes = models.TextField(
help_text="Notes about the scenario for follow up. Things such as phone numbers, mail addresses, contact info."
"Will not be exported, but are not secret.",
verbose_name="additional case notes",
......@@ -320,6 +320,7 @@ class TlsQualysScan(ExplainMixin):
class Meta:
managed = True
db_table = 'scanner_tls_qualys'
ordering = ['-rating_determined_on', ]
def __str__(self):
return "%s - %s" % (self.scan_date, self.qualys_rating)
......@@ -366,6 +367,7 @@ class TlsScan(ExplainMixin):
class Meta:
verbose_name = _('tlsscan')
verbose_name_plural = _('tlsscan')
ordering = ['-rating_determined_on', ]
......@@ -422,6 +424,7 @@ class GenericScanMixin(ExplainMixin):
another abstract base class. You just need to remember to explicitly set abstract=True each time.
abstract = True
ordering = ['-rating_determined_on', ]
class EndpointGenericScan(GenericScanMixin):
......@@ -196,7 +196,10 @@ def qualys_scan_thread(url):
"Slow down. ""%s" % data['errors'][0]['message'])
if waiting_time < max_waiting_time:
waiting_time += 30
if data['errors'][0]['message'] == "Too many new assessments too fast. Please slow down.":
if data['errors'][0]['message'].startswith("Too many concurrent assessments"):
if waiting_time < max_waiting_time:
waiting_time += 30
if data['errors'][0]['message'].startswith("Concurrent assessment limit reached"):
if waiting_time < max_waiting_time:
waiting_time += 30
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment