Add design documentation (#1)

* mkdocs new . * add requirements.txt * add initial content * move user stories into place * add user stories table * add report management page converted from latex using pandoc still needs cleanup * add embargo management page converted from latex using pandoc still needs cleanup * add case state page converted from latex using pandoc still needs cleanup * add section index page * continued cleanup of latex conversion * update nav * update nav features * replace math with italics * add diagram to index.md * add index to nav * add transition names to arrows * add embargo management state machine * fix link * add copyright and footer * add some diagrams * use stateDiagrams instead of flowcharts in mermaid * add more files from pandoc .tex -> .md * add todo * rename file * split worked example from formal protocol * cleanup file * add todo * add pages * add more formatting features * improved formatting * setup for icon usage * keep on formatting... * rearrange some files * update todo * update nav * add features * add glossary page * basic home page * update todo * split file * move diagram into separate file * fix links, add empty iso page * generic todo file * remove double highlight * highlight refs * simplify diagram * refactor content * link to empty ssvc crosswalk * fix nav * redo headers in lower section * put info in a box * fix ssvc links * move em to folder * refactor dm definition to separate file * add regex to todo * replace acronyms and start editing * refactor diagram into separate file * lots of text cleanup, insets, and diagrams * add new files for refactor * refactor docs * refactor negotiating embargoes into separate file * keep revising content * add gh workflow (not working yet) * add site deploy workflow * add gh workflow (not working yet) * add mkdocs build line * install python dependencies * fix setup python * installing dependencies * installing dependencies * Update deploy_site.yml * break out user story table * move case state to dir * keep slogging * add some diagram titles * refactor big diagram into separate file * update todo * fixup acronyms * link RM and EM * refactor pxa diagram into separate file * fix links, add formatting and diagrams * more diagrams * header fix * revise diagrams * move model interactions to dir * refactor doc * refactor doc * restructure site according to diataxis framework * pull out goal into highlight box * clean up * add excerpts * refactor diagram into separate file * clarify expectations * remove todo * mention parallelism * update diagram headers * extract table for inclusion * reduce LaTeX * remove todo and extend example diagram * nav fixup * title fixup * reorganize files to diataxis directories * initial commit of introduction * chunking up the intro * formatting background * de-LaTeX * table and link cleanup * refactor interoperability.md into its own doc * refactor overview.md to separate doc * iso links * cleanup * cleanup * break up file * acronyms * highlight refs * draw cvd_bt and vuldisco_bt diagrams * draw rm_bt diagram * horiz bt * add diagrams and clean up text * add diagrams and clean up text * deployment behavior * break out sections * add diagram * add diagrams and clean up * fix xref * refactor note * add diagram * add diagram & cleanup * add links * add diagram and clean up * refactor RM behaviors * refactor EM behaviors * fix links * add diagram, links * add diagram, links * add links * add diagram, split content * add diagram, split content * add diagram, clean up * add diagrams, clean up * add diagrams, clean up * fix error in diagram node types * s/global/participant-agnostic/ bring terms in line with SSVC * s/global/participant-agnostic/ update chart * s/global/participant-agnostic/ add diagrams * s/global/participant-agnostic/ s/global/participant-agnostic/ * add diagram, cleanup * cleaning up equations * set up for doc refactor * refactor states.md * refactor messages.md * refactor transitions.md * cleanup * move footnotes * add todo * clean up messages.md * clean up transitions.md * add message table * add rm transition tables * add rm transition tables * complete transition tables * add game board diagrams and refactor summary * clean up worked_example * minor tweak * highlight todos * break out case object into a page * fix bad latex * fix diagrams * split off process implementation * split off general implementation notes * clean up section * add skeleton iso crosswalk docs * add links * add table * clean up * initial pandoc conversion * first pass edit * add diagrams * clean up * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * fix links * add pr template * fixing links * fixing links * first shot at em_icalendar (table missing) * add table * minor fix ups * refactor future work into sections * more cleanup * add state meanings * typo fix * cross-refs and format fixups * add github header and return to top nav * updating external refs * update home page * indicate normative/not normative * reference fixes * link and reference fixes * MPCVD protocol -> Vultron protocol * capitalize Vultron Protocol add warning for folks who land on the formal protocol definition page first add links to blog and sei podcast to tutorials page * make legend a table * link fixes * format fixes * top-bottom walkthrough edits * top-bottom walkthrough edits * top-bottom walkthrough edits * add version blurb * link fix * link fix * link fix * add doc conventions * fix minor bugs
CERTCC · Sep 8, 2023 · ab89a88 · ab89a88
1 parent f7ed7c4
commit ab89a88
Show file tree

Hide file tree

Showing 219 changed files with 11,974 additions and 164 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
@@ -0,0 +1 @@
+Please note: Pull request submissions are subject to our [Contribution Instructions](https://github.com/CERTCC/Vultron/blob/main/ContributionInstructions.md).
diff --git a/.github/workflows/deploy_site.yml b/.github/workflows/deploy_site.yml
@@ -0,0 +1,60 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: [main, feature/*]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Build Site
+        run: |
+          mkdocs build --verbose --clean --config-file mkdocs.yml       
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          # Upload entire repository
+          path: 'site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
diff --git a/.gitignore b/.gitignore
@@ -128,3 +128,4 @@ dmypy.json
 # Pyre type checker
 .pyre/
 /tmp/
+/TODO.md
diff --git a/Acknowledgements.md b/Acknowledgements.md
@@ -11,28 +11,28 @@ Department of Defense.
 ### The CERT Guide to Coordinated Vulnerability Disclosure
 
 - Allen D. Householder, Garret Wassermann, Art Manion, Christopher King
-- Original 2017 publication: https://doi.org/10.1184/R1/12367340.v1
-- 2019 Update: https://vuls.cert.org/confluence/display/CVD
+- Original 2017 publication: <https://doi.org/10.1184/R1/12367340.v1>
+- 2019 Update: <https://vuls.cert.org/confluence/display/CVD>
 
 ### A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure (MPCVD)
 
 - Allen D. Householder and Jonathan Spring
-- https://doi.org/10.1184/R1/16416771
+- <https://doi.org/10.1184/R1/16416771>
 
 ### Are We Skillful or Just Lucky? Interpreting the Possible Histories of Vulnerability Disclosures
 
 - Allen D. Householder and Jonathan Spring
-- https://doi.org/10.1145/3477431
+- <https://doi.org/10.1145/3477431>
 
 ### Designing Vultron: A Protocol for Multi-Party Coordinated Vulnerability Disclosure (MPCVD)
 
 - Allen D. Householder
-- https://doi.org/10.1184/R1/19852798
+- <https://doi.org/10.1184/R1/19852798>
 
 ### Coordinated Vulnerability Disclosure User Stories
 
 - Brad Runyon, Eric Hatleback, Allen D. Householder, Art Manion, Vijay S. Sarvepalli, Timur D. Snoke, Jonathan Spring,
   Laurie Tyzenhaus, Charles G. Yarbrough
-- https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=886543
+- <https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=886543>
 
 DM23-0698
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,7 +2,8 @@
 
 Thank you for your interest in contributing to Vultron!
 
-Please review [ContributionInstructions.md](ContributionInstructions.md) before submitting any Pull Requests.
+Please review our [Contribution Instructions](https://github.com/CERTCC/Vultron/blob/main/ContributionInstructions.md)
+before submitting any Pull Requests.
 
 <!--
 ## Code of Conduct
@@ -16,7 +17,7 @@ There are a number of ways you can contribute to the development of Vultron.
 
 ### Participate in Discussions
 
-- Participate in an existing [Discussions](https://github.com/CERTCC/Vultron/discussions) or start a new one.
+- Participate in an existing [Discussion](https://github.com/CERTCC/Vultron/discussions) or start a new one.
 
 ### Report Bugs
 

diff --git a/ContributionInstructions.md b/ContributionInstructions.md
@@ -39,7 +39,7 @@ provided that this license is conditioned upon compliance with Section 2.2.
 
 ### 2.2 Outbound License
 
-Based on the grant of rights in [Sections 2.1](#2.1-copyright-license), if We include Your Contribution in a Material, 
+Based on the grant of rights in Section 2.1, if We include Your Contribution in a Material, 
 We may license the Contribution under any license, including copyleft, permissive, commercial, or proprietary licenses.
 As a condition on the exercise of this right, We agree to also license the Contribution under the terms of the license 
 or licenses which We are using for the Material on the Submission Date.

diff --git a/VERSION b/VERSION
@@ -0,0 +1 @@
+0.5.0
diff --git a/doc/README.md b/doc/README.md
@@ -1,6 +1,6 @@
 # Vultron Docs
 
 What's here:
-- [User Stories](/doc/user_stories/)
+- [User Stories](/docs/topics/user_stories/)
 - [Activity Vocabulary Examples](/doc/examples/)
 
diff --git a/doc/user_stories/README.md b/doc/user_stories/README.md
diff --git a/docs/about/acknowledgements.md b/docs/about/acknowledgements.md
@@ -0,0 +1 @@
+{% include-markdown "../../Acknowledgements.md" %}
diff --git a/docs/about/contributing.md b/docs/about/contributing.md
@@ -0,0 +1,5 @@
+{% include-markdown "../../CONTRIBUTING.md" %}
+
+## Contribution Instructions
+
+{% include-markdown "../../ContributionInstructions.md" heading-offset=2 %}
diff --git a/FAQ.md → docs/about/faq.md b/FAQ.md → docs/about/faq.md
@@ -1,6 +1,6 @@
-# Vultron Frequently Asked Questions
+# Vultron Protocol Frequently Asked Questions
 
-## What do we need to move Vultron to widespread use?
+## What do we need to move the Vultron Protocol to widespread use?
 
 First, we need to finish the protocol and get it to a sufficiently stable state that we can start to use it even in 
 test environments.  We're not there yet.
@@ -11,13 +11,13 @@ In the meantime, there are a number of other things that can help. We're looking
 ## How do we apply encryption to ActivityPub messages to enable end-to-end encryption?
 
 We're of the opinion that encrypted messaging is a feature that should be available to all users of
-ActivityPub, not just those using Vultron to coordinate vulnerability cases.
+ActivityPub, not just those using the Vultron Protocol to coordinate vulnerability cases.
 Therefore, our position is that end-to-end encryption would be better implemented as a layer on top of the ActivityPub
 protocol, rather
-than as a specific feature of the Vultron protocol.
+than as a specific feature of the Vultron Protocol.
 From what we can tell, the topic has come up before in the ActivityPub community, but there is no
 standardized solution yet.
-We're currently focused on developing the Vultron protocol, but we realize that encryption may be a requirement for
+We're currently focused on developing the Vultron Protocol, but we realize that encryption may be a requirement for
 widespread adoption, so we're keeping an eye on the topic.
 
 Some relevant links include:
@@ -42,7 +42,7 @@ Some relevant links include:
 We are interested in any developments in this space, please let us know if you are aware of more recent developments.
 We'd be interested to know how we could help with efforts to bring encrypted messaging to ActivityPub.
 
-## What are the requirements for the participants?
+## What are the requirements for contributing?
 
-See [CONTRIBUTING.md](CONTRIBUTING.MD)
+See [CONTRIBUTING](contributing.md)
 
diff --git a/docs/about/license.md b/docs/about/license.md
@@ -0,0 +1 @@
+{% include-markdown "../../LICENSE.md" %}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Please note: Pull request submissions are subject to our [Contribution Instructions](https://github.com/CERTCC/Vultron/blob/main/ContributionInstructions.md).
-Original file line number
+Diff line change
@@ Expand Up / @@ -128,3 +128,4 @@ dmypy.json @@
     # Pyre type checker
     .pyre/
     /tmp/
+    /TODO.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{% include-markdown "../../Acknowledgements.md" %}