Incorporate Disclosure Policy Templates (#27)

* integrate disclosure policy templates into the guide

* minor clean up

* minor clean up

* mdlint and link fixes

* fix spacing problem

docs/_includes/_quick_start.md

@@ -33,7 +33,7 @@ to achieve.
     as starting points. Additionally, you can use
     [Troubleshooting Coordinated Vulnerability Disclosure](../howto/coordination/cvd_recipes.md)
     as a rubric of scenarios to consider when planning your operational processes.
-    [Disclosure Policy Resources](../reference/disclosure_policy_templates.md)
+    [Disclosure Policy Resources](../reference/policy_templates/index.md)
     contains links to a number of disclosure policy examples and
     templates.
 
@@ -64,7 +64,7 @@ to achieve.
     [Troubleshooting Coordinated Vulnerability Disclosure](../howto/coordination/cvd_recipes.md)
     that are worth considering when you're thinking about writing policy
     that sets out how things are expected to be done.
-    [Disclosure Policy Resources](../reference/disclosure_policy_templates.md)
+    [Disclosure Policy Resources](../reference/policy_templates/index.md)
     contains links to a number of disclosure policy examples and
     templates.
 

docs/howto/preparation/choosing_policy.md

@@ -53,4 +53,4 @@ reporters, vendors, coordinators) can expect in terms of these factors:
 
 !!! info "Disclosure Policy Templates"
 
-    {% include-markdown "../../reference/disclosure_policy_templates.md" heading-offset=1 start="<!--start-->" end="<!--end-->" %}
+    {% include-markdown "../../reference/policy_templates/other.md" heading-offset=1 start="<!--start-->" end="<!--end-->" %}

docs/reference/index.md

@@ -8,7 +8,7 @@ These resources include templates, standards, and other materials that can help
 - :octicons-checklist-16: [CERT/CC Vulnerability Disclosure Policy](./certcc_disclosure_policy.md)
 - :material-form-select: [Basic Vulnerability Reporting Form](./simple_vrf.md)
 - :material-newspaper-variant: [Basic Advisory Format](./simple_advisory.md)
-- :material-clipboard-check-multiple-outline: [Disclosure Policy Resources](./disclosure_policy_templates.md)
+- :material-clipboard-check-multiple-outline: [Disclosure Policy Resources](policy_templates/index.md)
 - :material-bookshelf: [CVD Resources and Standards](./resources.md)
 
 </div>

docs/reference/policy_templates/_consistency_warning.md

@@ -0,0 +1,8 @@
+!!! warning "These examples are not internally consistent"
+
+    Because these policy statements are meant to be remixed and adapted for
+    different organizations and contexts, some of the policy points could
+    conflict with or mutually exclude others.
+    It's up to you to edit them into whatever you want your policy to say.
+    Our hope is that this collection has enough breadth of coverage across issues that the
+    words address most of what you might want a policy to cover.

docs/reference/policy_templates/_policy_tips.md

@@ -0,0 +1,64 @@
+!!! tip "Policy statements should be clear and simple"
+
+    Each item in a policy should cover a single expectation.
+    Items should be clear and simple to facilitate interpretation by all participants.
+
+!!! tip "Use RFC 2119-style language"
+
+    Each item SHOULD use "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 
+    "MAY", and "OPTIONAL" consistent with their meaning in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). 
+    RFC-style makes clear the distinction between expectations that are recommendations versus those that are requirements.
+
+!!! tip "Use active voice"
+
+    Write each policy expectation item in the active voice. This means every
+    statement has a clear actor and an expectation on that actor. `ORGANIZATION`
+    SHALL..., Reporter MAY..., etc.) Active voice makes it easy to
+    recognize to whom the expectation applies.
+
+!!! tip "Use imperative expectations of others and declarative expectations of self"
+
+    In general, expectations of others should use "MAY", "SHOULD", "MUST", "MUST
+    NOT", "REQUIRED", or "OPTIONAL". 
+
+    Expectations that the `ORGANIZATION` sets for itself should prefer "SHALL"
+    and "SHALL NOT" in place of "MUST" or "MUST NOT".
+
+    Similarly, it seems unlikely that `ORGANIZATION` would use "SHOULD" to refer to
+    its own behavior, rather preferring to use "SHALL", "SHALL NOT", or "MAY"
+    formulations.
+
+    Rationale: The policy creator is declaring limits and
+    expectations on their own behavior, not recommending to others what they
+    can/should/might do. In other words, use imperatives for others, declaratives
+    for self.
+
+!!! tip "Separate expectations by role"
+
+    To the degree possible, separate expectations by role. For example, as we have
+    done by splitting [reporters](reporters.md)
+    and [receivers](receivers.md) into separate files.
+    In a real policy,
+    these would become different sections of the document.
+
+!!! tip "Keep it simple / limit complexity"
+
+    Limit the logical complexity of individual expectations. A single conditional
+    is fine. Consider splitting statements containing multiple conditionals into
+    separate statements.
+
+!!! tip "Consider symmetry"
+
+    Consider symmetry in policy expectation items. For example, if you expect
+    politeness from Reporters, do you also commit to being polite?
+
+!!! tip "Replace KEYWORDS with specifics"
+
+    In our template statements, we use KEYWORDS to denote specifics that are
+    stakeholder-specific. 
+
+    Replace KEYWORDS with specifics that are relevant to your organization.
+
+    For example, replace `ORGANIZATION` with your organization's name, or
+    `SLC` with "45 days" if that's your organization's
+    standard disclosure timeline.

docs/reference/policy_templates/_terminology.md

@@ -0,0 +1,30 @@
+!!! note "Terminology Notes"
+
+    **Terms from RFC 2119**
+    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+    **Terms from ISO, CERT**
+    The terms *Researcher* or *Reporter* is intended to be consistent with the terms *Finder* and/or *Reporter* as used in ISO/IEC 29147:2014(E) and the [CERT® Guide to Coordinated Vulnerability Disclosure](../../topics/roles/finder.md).
+
+    **Other Terms**
+
+    `ORGANIZATION`
+    : the name of an organization or entity, specifically the one creating this policy.
+
+    `SYSTEM SCOPE`
+    : A defined set of systems covered by this policy. E.g., "`ORGANIZATION`'s information systems", "`ORGANIZATION`'s public web sites", "`PRODUCT` versions X through Y", "Critical infrastructure information systems", or any other similar scope.
+
+    `JURISDICTION`
+    : the territorial, political, or governmental scope of a regulatory authority
+
+    `SLC`
+    : Service Level Commitment, typically expressed in terms of the minimum or maximum time until some event trigger. For example: at least 45 days, not more than 90 days, within 2 business days, etc.
+
+    `PUBLICATION CHANNEL`
+    : A specific medium through which information is conveyed, e.g., a web site, mailing list, Twitter, RSS or Atom Feed, or database.
+
+    `BUG BOUNTY`
+    : A type of Vulnerability Disclosure Program in which the `ORGANIZATION` compensates reporters for reports meeting specific criteria.
+
+    `REPORTING CHANNEL`
+    : A specific medium through which vulnerability reports are communicated from a Reporter to the `ORGANIZATION`. Examples include: an email address, a web form, or a bug tracking platform.

docs/reference/policy_templates/_usage.md

@@ -0,0 +1,37 @@
+!!! tip "How To Use These Templates"
+
+    Organizations will likely find that some expectations do not apply to their
+    situation based on the kind of stakeholder they are. In particular we anticipate
+    that 
+    [product vendors](../../topics/roles/vendor.md),
+    [service providers](../../topics/roles/deployer.md),
+    and 
+    [coordinators](../../topics/roles/coordinator.md) will have related but
+    distinct needs. Inclusion or exclusion of items from these templates into your
+    organization's policy should be based on which combination of stakeholder roles
+    you expect to play.
+
+    Here's a checklist of tasks you should complete in order to make use of these
+    templates.
+
+    - [x] Review the content of the [Disclosure Policy Style Guide](./style_guide.md).
+    - [x] Review the content of the [Reporters](./reporters.md) and [Receivers](./receivers.md) files.
+    - [x] Select the policy expectation items you want to use.
+    - [x] Adjust the recommendation strength (e.g., change some of the SHOULDs to MUSTs or MAYs to SHOULD NOTs etc.).
+    - [x] Adjust the wording of the items to fit your organization's style or needs.
+    - [x] Replace any KEYWORDS with an appropriate substitution (e.g., "45 days"
+          instead of `SLC`").
+    - [x] Construct a single policy document from the collected items.
+    - [x] Add any needed introduction, boilerplate, or legal info to the document.
+    - [x] Review the entire document for internal consistency and fix any
+          contradictions.
+    - [x] Review the document for external consistency with other organization policies,
+          applicable laws, regulations, etc.
+    - [x] Get approval for the policy and to publish the document from necessary decision makers
+    - [x] Establish sufficient operational capability in order to provide the service(s) the policy commits you to offer.
+    - [x] Publish the policy
+
+    !!! note "Disclaimer"
+        
+        We are not lawyers, and this is not legal advice.
+        You are encouraged to consult your own legal counsel in the process of creating your disclosure policy.

docs/reference/policy_templates/index.md

@@ -0,0 +1,41 @@
+# Vulnerability Disclosure Policy Templates
+
+In recent years the CERT/CC has advised a number of organizations on their
+vulnerability disclosure policies.
+This section contains a collection of resources intended for use in
+constructing a vulnerability disclosure policy.
+Here we are attempting to capture common
+verbiage in order to help others develop or improve their own policies. We've
+taken these items from a variety of vulnerability disclosure policies including
+[our own](../certcc_disclosure_policy.md), generalized them, organized them by topic, and assembled them into this
+collection.
+
+This collection is a general set of templates from which you can derive and
+spawn a disclosure policy for an organization.
+
+<div class="grid cards" markdown>
+
+!!! tip "How to Use This Collection"
+
+    This collection of example policy statements is meant to be remixed and adapted for different
+    organizations and contexts. It is unlikely that any single organization would
+    choose to adopt all of these items wholesale without some modification.
+
+- :material-feather: [Style Guide](./style_guide.md)
+
+    ---
+    {%include-markdown "./style_guide.md" start="<!--start-->" end="<!--end-->" %}
+
+- :material-set-left-center: [Setting Expectations for Reporters](./reporters.md)
+
+    ---
+    {%include-markdown "./reporters.md" start="<!--start-->" end="<!--end-->" %}  
+
+- :material-set-center-right: [Setting Expectations for Receivers](./receivers.md)
+
+    ---
+    {%include-markdown "./receivers.md" start="<!--start-->" end="<!--end-->" %}
+
+</div>
+
+{% include-markdown "./_usage.md" %}

docs/reference/disclosure_policy_templates.md → docs/reference/policy_templates/other.md

@@ -2,7 +2,9 @@
 
 <!--start-->
 
-Following are some resources that can help you create a disclosure policy:
+In addition to the [Disclosure Policy Templates](./index.md) we provide as part of this guide,
+there are many other resources available to help you create a vulnerability disclosure policy.
+Here are a few examples:
 
 - CISA provides a [Vulnerability Disclosure Policy Template](https://www.cisa.gov/vulnerability-disclosure-policy-template){:target="_blank"}
   for U.S. Federal Agencies. This template is also useful as a starting point for other organizations
@@ -13,9 +15,6 @@ Following are some resources that can help you create a disclosure policy:
 
 - The [disclose.io](https://disclose.io/){:target="_blank"} [Policymaker](https://policymaker.disclose.io/policymaker/introduction){:target="_blank"} tool can help you create a policy that fits your organization's needs.
 
-- CERT/CC has a set of [Disclosure Policy Templates](https://github.com/CERTCC/vulnerability_disclosure_policy_templates){:target="_blank"}
-  derived from multiple sources. Our templates are a collection of statements that can be used to create a policy that fits your organization's needs.
-
 - [IETF RFC 2350](https://datatracker.ietf.org/doc/html/rfc2350){:target="_blank"} provides recommendations on how to publish information about your CSIRT and disclosure policy and procedures.
 
 - [ISO/IEC 29147:2018 *Information technology -- Security techniques -- Vulnerability disclosure*](https://www.iso.org/standard/72311.html){:target="_blank"} provides guidelines for vulnerability disclosure, including a section on required, recommended, and optional policy elements.