Skip to content

Commit

Permalink
Add design documentation (#1)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
ahouseholder authored Sep 8, 2023
1 parent f7ed7c4 commit ab89a88
Show file tree
Hide file tree
Showing 219 changed files with 11,974 additions and 164 deletions.
1 change: 1 addition & 0 deletions .github/PULL_REQUEST_TEMPLATE/pull_request_template.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).
60 changes: 60 additions & 0 deletions .github/workflows/deploy_site.yml
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -128,3 +128,4 @@ dmypy.json
# Pyre type checker
.pyre/
/tmp/
/TODO.md
12 changes: 6 additions & 6 deletions Acknowledgements.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion ContributionInstructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions VERSION
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
0.5.0
2 changes: 1 addition & 1 deletion doc/README.md
Original file line number Diff line number Diff line change
@@ -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/)

36 changes: 0 additions & 36 deletions doc/user_stories/README.md

This file was deleted.

1 change: 1 addition & 0 deletions docs/about/acknowledgements.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{% include-markdown "../../Acknowledgements.md" %}
5 changes: 5 additions & 0 deletions docs/about/contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{% include-markdown "../../CONTRIBUTING.md" %}

## Contribution Instructions

{% include-markdown "../../ContributionInstructions.md" heading-offset=2 %}
14 changes: 7 additions & 7 deletions FAQ.md → docs/about/faq.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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:
Expand All @@ -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)

1 change: 1 addition & 0 deletions docs/about/license.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{% include-markdown "../../LICENSE.md" %}
Loading

0 comments on commit ab89a88

Please sign in to comment.