From ab89a883dd621fd02928ef345792e62c3ad20faf Mon Sep 17 00:00:00 2001 From: "Allen D. Householder" Date: Fri, 8 Sep 2023 14:08:45 -0400 Subject: [PATCH] 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 --- .../pull_request_template.md | 1 + .github/workflows/deploy_site.yml | 60 ++ .gitignore | 1 + Acknowledgements.md | 12 +- CONTRIBUTING.md | 5 +- ContributionInstructions.md | 2 +- VERSION | 1 + doc/README.md | 2 +- doc/user_stories/README.md | 36 - docs/about/acknowledgements.md | 1 + docs/about/contributing.md | 5 + FAQ.md => docs/about/faq.md | 14 +- docs/about/license.md | 1 + docs/assets/cert_seal.svg | 1 + docs/howto/case_object.md | 280 ++++++ docs/howto/em_icalendar.md | 168 ++++ docs/howto/general_implementation.md | 89 ++ docs/howto/index.md | 42 + docs/howto/process_implementation.md | 88 ++ docs/includes/curr_ver.md | 3 + docs/includes/do_not_start_here.md | 5 + docs/includes/normative.md | 4 + docs/includes/not_normative.md | 4 + docs/index.md | 87 ++ docs/javascripts/mathjax.js | 16 + docs/javascripts/tablesort.js | 6 + docs/reference/formal_protocol/conclusion.md | 169 ++++ docs/reference/formal_protocol/index.md | 86 ++ docs/reference/formal_protocol/messages.md | 262 +++++ docs/reference/formal_protocol/states.md | 928 ++++++++++++++++++ docs/reference/formal_protocol/transitions.md | 397 ++++++++ docs/reference/glossary.md | 235 +++++ docs/reference/index.md | 21 + docs/reference/iso_29147_2018.md | 60 ++ docs/reference/iso_30111_2019.md | 35 + docs/reference/iso_5895_2022.md | 33 + docs/reference/iso_crosswalk.md | 12 + docs/reference/ssvc_crosswalk.md | 326 ++++++ docs/stylesheets/extra.css | 5 + docs/topics/background/cvd_success.md | 151 +++ docs/topics/background/index.md | 139 +++ docs/topics/background/interoperability.md | 92 ++ docs/topics/background/notation.md | 179 ++++ docs/topics/background/overview.md | 75 ++ docs/topics/background/terms.md | 69 ++ docs/topics/background/versioning.md | 34 + .../behavior_logic/acquire_exploit_bt.md | 47 + docs/topics/behavior_logic/cvd_bt.md | 57 ++ docs/topics/behavior_logic/deployment_bt.md | 110 +++ docs/topics/behavior_logic/do_work_bt.md | 55 ++ docs/topics/behavior_logic/em_bt.md | 138 +++ docs/topics/behavior_logic/em_eval_bt.md | 42 + docs/topics/behavior_logic/em_propose_bt.md | 66 ++ docs/topics/behavior_logic/em_terminate_bt.md | 72 ++ docs/topics/behavior_logic/fix_dev_bt.md | 35 + .../topics/behavior_logic/id_assignment_bt.md | 45 + docs/topics/behavior_logic/index.md | 153 +++ .../behavior_logic/monitor_threats_bt.md | 65 ++ docs/topics/behavior_logic/msg_cs_bt.md | 167 ++++ docs/topics/behavior_logic/msg_em_bt.md | 204 ++++ docs/topics/behavior_logic/msg_intro_bt.md | 64 ++ docs/topics/behavior_logic/msg_other_bt.md | 38 + docs/topics/behavior_logic/msg_rm_bt.md | 89 ++ docs/topics/behavior_logic/publication_bt.md | 113 +++ docs/topics/behavior_logic/reporting_bt.md | 129 +++ docs/topics/behavior_logic/rm_bt.md | 104 ++ docs/topics/behavior_logic/rm_closure_bt.md | 29 + .../behavior_logic/rm_prioritization_bt.md | 81 ++ .../topics/behavior_logic/rm_validation_bt.md | 71 ++ docs/topics/behavior_logic/vuldisco_bt.md | 53 + docs/topics/formal_protocol/index.md | 8 + docs/topics/formal_protocol/worked_example.md | 386 ++++++++ docs/topics/future_work/cvd_directory.md | 97 ++ docs/topics/future_work/index.md | 13 + docs/topics/future_work/mod_sim.md | 19 + docs/topics/future_work/ontology.md | 24 + docs/topics/future_work/reward_functions.md | 97 ++ docs/topics/index.md | 23 + docs/topics/process_models/cs/cs_model.md | 426 ++++++++ .../process_models/cs/cs_substates_table.md | 13 + docs/topics/process_models/cs/index.md | 175 ++++ docs/topics/process_models/cs/pxa_diagram.md | 26 + .../process_models/cs/pxa_diagram_simple.md | 23 + .../process_models/cs/vfdpxa_diagram.md | 67 ++ .../process_models/dfa_notation_definition.md | 12 + docs/topics/process_models/em/defaults.md | 420 ++++++++ .../process_models/em/early_termination.md | 98 ++ .../process_models/em/em_dfa_diagram.md | 28 + docs/topics/process_models/em/embargo_defn.md | 4 + docs/topics/process_models/em/index.md | 383 ++++++++ docs/topics/process_models/em/nda-sidebar.md | 18 + docs/topics/process_models/em/negotiating.md | 176 ++++ docs/topics/process_models/em/principles.md | 189 ++++ docs/topics/process_models/em/split_merge.md | 95 ++ .../process_models/em/working_with_others.md | 306 ++++++ docs/topics/process_models/index.md | 84 ++ .../model_interactions/cs_global_local.md | 42 + .../model_interactions/index.md | 83 ++ .../model_interactions/rm_em.md | 328 +++++++ .../model_interactions/rm_em_cs.md | 477 +++++++++ docs/topics/process_models/rm/index.md | 706 +++++++++++++ .../process_models/rm/rm_interactions.md | 408 ++++++++ .../rm/rm_state_machine_diagram.md | 28 + docs/topics/user_stories/index.md | 47 + .../topics/user_stories}/story_2022_001.md | 2 +- .../topics/user_stories}/story_2022_002.md | 2 +- .../topics/user_stories}/story_2022_003.md | 2 +- .../topics/user_stories}/story_2022_004.md | 2 +- .../topics/user_stories}/story_2022_005.md | 2 +- .../topics/user_stories}/story_2022_006.md | 2 +- .../topics/user_stories}/story_2022_007.md | 2 +- .../topics/user_stories}/story_2022_008.md | 2 +- .../topics/user_stories}/story_2022_009.md | 2 +- .../topics/user_stories}/story_2022_010.md | 2 +- .../topics/user_stories}/story_2022_011.md | 2 +- .../topics/user_stories}/story_2022_012.md | 2 +- .../topics/user_stories}/story_2022_013.md | 2 +- .../topics/user_stories}/story_2022_014.md | 2 +- .../topics/user_stories}/story_2022_015.md | 2 +- .../topics/user_stories}/story_2022_016.md | 2 +- .../topics/user_stories}/story_2022_017.md | 2 +- .../topics/user_stories}/story_2022_018.md | 2 +- .../topics/user_stories}/story_2022_019.md | 2 +- .../topics/user_stories}/story_2022_020.md | 2 +- .../topics/user_stories}/story_2022_021.md | 2 +- .../topics/user_stories}/story_2022_022.md | 2 +- .../topics/user_stories}/story_2022_023.md | 2 +- .../topics/user_stories}/story_2022_024.md | 2 +- .../topics/user_stories}/story_2022_025.md | 2 +- .../topics/user_stories}/story_2022_026.md | 2 +- .../topics/user_stories}/story_2022_027.md | 2 +- .../topics/user_stories}/story_2022_028.md | 2 +- .../topics/user_stories}/story_2022_029.md | 2 +- .../topics/user_stories}/story_2022_030.md | 2 +- .../topics/user_stories}/story_2022_031.md | 2 +- .../topics/user_stories}/story_2022_032.md | 2 +- .../topics/user_stories}/story_2022_033.md | 2 +- .../topics/user_stories}/story_2022_034.md | 2 +- .../topics/user_stories}/story_2022_035.md | 2 +- .../topics/user_stories}/story_2022_036.md | 2 +- .../topics/user_stories}/story_2022_037.md | 2 +- .../topics/user_stories}/story_2022_038.md | 2 +- .../topics/user_stories}/story_2022_039.md | 2 +- .../topics/user_stories}/story_2022_040.md | 2 +- .../topics/user_stories}/story_2022_041.md | 2 +- .../topics/user_stories}/story_2022_042.md | 2 +- .../topics/user_stories}/story_2022_043.md | 2 +- .../topics/user_stories}/story_2022_044.md | 2 +- .../topics/user_stories}/story_2022_045.md | 2 +- .../topics/user_stories}/story_2022_046.md | 2 +- .../topics/user_stories}/story_2022_047.md | 2 +- .../topics/user_stories}/story_2022_048.md | 2 +- .../topics/user_stories}/story_2022_049.md | 2 +- .../topics/user_stories}/story_2022_050.md | 2 +- .../topics/user_stories}/story_2022_051.md | 2 +- .../topics/user_stories}/story_2022_052.md | 2 +- .../topics/user_stories}/story_2022_053.md | 2 +- .../topics/user_stories}/story_2022_054.md | 2 +- .../topics/user_stories}/story_2022_055.md | 2 +- .../topics/user_stories}/story_2022_056.md | 2 +- .../topics/user_stories}/story_2022_057.md | 2 +- .../topics/user_stories}/story_2022_058.md | 2 +- .../topics/user_stories}/story_2022_059.md | 2 +- .../topics/user_stories}/story_2022_060.md | 2 +- .../topics/user_stories}/story_2022_061.md | 2 +- .../topics/user_stories}/story_2022_062.md | 2 +- .../topics/user_stories}/story_2022_063.md | 2 +- .../topics/user_stories}/story_2022_064.md | 2 +- .../topics/user_stories}/story_2022_065.md | 2 +- .../topics/user_stories}/story_2022_066.md | 2 +- .../topics/user_stories}/story_2022_067.md | 2 +- .../topics/user_stories}/story_2022_068.md | 2 +- .../topics/user_stories}/story_2022_069.md | 2 +- .../topics/user_stories}/story_2022_070.md | 2 +- .../topics/user_stories}/story_2022_071.md | 2 +- .../topics/user_stories}/story_2022_072.md | 2 +- .../topics/user_stories}/story_2022_073.md | 2 +- .../topics/user_stories}/story_2022_074.md | 2 +- .../topics/user_stories}/story_2022_075.md | 2 +- .../topics/user_stories}/story_2022_076.md | 2 +- .../topics/user_stories}/story_2022_077.md | 2 +- .../topics/user_stories}/story_2022_078.md | 2 +- .../topics/user_stories}/story_2022_079.md | 2 +- .../topics/user_stories}/story_2022_080.md | 2 +- .../topics/user_stories}/story_2022_081.md | 2 +- .../topics/user_stories}/story_2022_082.md | 2 +- .../topics/user_stories}/story_2022_083.md | 2 +- .../topics/user_stories}/story_2022_084.md | 2 +- .../topics/user_stories}/story_2022_085.md | 2 +- .../topics/user_stories}/story_2022_086.md | 2 +- .../topics/user_stories}/story_2022_087.md | 2 +- .../topics/user_stories}/story_2022_088.md | 2 +- .../topics/user_stories}/story_2022_089.md | 2 +- .../topics/user_stories}/story_2022_090.md | 2 +- .../topics/user_stories}/story_2022_091.md | 2 +- .../topics/user_stories}/story_2022_092.md | 2 +- .../topics/user_stories}/story_2022_093.md | 2 +- .../topics/user_stories}/story_2022_094.md | 2 +- .../topics/user_stories}/story_2022_095.md | 2 +- .../topics/user_stories}/story_2022_096.md | 2 +- .../topics/user_stories}/story_2022_097.md | 2 +- .../topics/user_stories}/story_2022_098.md | 2 +- .../topics/user_stories}/story_2022_099.md | 2 +- .../topics/user_stories}/story_2022_100.md | 2 +- .../topics/user_stories}/story_2022_101.md | 2 +- .../topics/user_stories}/story_2022_102.md | 2 +- .../topics/user_stories}/story_2022_103.md | 2 +- .../topics/user_stories}/story_2022_104.md | 2 +- .../topics/user_stories}/story_2022_105.md | 2 +- .../topics/user_stories}/story_2022_106.md | 2 +- .../topics/user_stories}/story_2022_107.md | 2 +- .../topics/user_stories}/story_2022_108.md | 2 +- .../topics/user_stories}/story_2022_109.md | 2 +- .../topics/user_stories}/story_2022_110.md | 2 +- .../topics/user_stories}/story_2022_111.md | 2 +- docs/topics/user_stories/table.md | 121 +++ docs/tutorials/index.md | 20 + mkdocs.yml | 173 ++++ requirements.txt | 4 + 219 files changed, 11974 insertions(+), 164 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md create mode 100644 .github/workflows/deploy_site.yml create mode 100644 VERSION delete mode 100644 doc/user_stories/README.md create mode 100644 docs/about/acknowledgements.md create mode 100644 docs/about/contributing.md rename FAQ.md => docs/about/faq.md (84%) create mode 100644 docs/about/license.md create mode 100644 docs/assets/cert_seal.svg create mode 100644 docs/howto/case_object.md create mode 100644 docs/howto/em_icalendar.md create mode 100644 docs/howto/general_implementation.md create mode 100644 docs/howto/index.md create mode 100644 docs/howto/process_implementation.md create mode 100644 docs/includes/curr_ver.md create mode 100644 docs/includes/do_not_start_here.md create mode 100644 docs/includes/normative.md create mode 100644 docs/includes/not_normative.md create mode 100644 docs/index.md create mode 100644 docs/javascripts/mathjax.js create mode 100644 docs/javascripts/tablesort.js create mode 100644 docs/reference/formal_protocol/conclusion.md create mode 100644 docs/reference/formal_protocol/index.md create mode 100644 docs/reference/formal_protocol/messages.md create mode 100644 docs/reference/formal_protocol/states.md create mode 100644 docs/reference/formal_protocol/transitions.md create mode 100644 docs/reference/glossary.md create mode 100644 docs/reference/index.md create mode 100644 docs/reference/iso_29147_2018.md create mode 100644 docs/reference/iso_30111_2019.md create mode 100644 docs/reference/iso_5895_2022.md create mode 100644 docs/reference/iso_crosswalk.md create mode 100644 docs/reference/ssvc_crosswalk.md create mode 100644 docs/stylesheets/extra.css create mode 100644 docs/topics/background/cvd_success.md create mode 100644 docs/topics/background/index.md create mode 100644 docs/topics/background/interoperability.md create mode 100644 docs/topics/background/notation.md create mode 100644 docs/topics/background/overview.md create mode 100644 docs/topics/background/terms.md create mode 100644 docs/topics/background/versioning.md create mode 100644 docs/topics/behavior_logic/acquire_exploit_bt.md create mode 100644 docs/topics/behavior_logic/cvd_bt.md create mode 100644 docs/topics/behavior_logic/deployment_bt.md create mode 100644 docs/topics/behavior_logic/do_work_bt.md create mode 100644 docs/topics/behavior_logic/em_bt.md create mode 100644 docs/topics/behavior_logic/em_eval_bt.md create mode 100644 docs/topics/behavior_logic/em_propose_bt.md create mode 100644 docs/topics/behavior_logic/em_terminate_bt.md create mode 100644 docs/topics/behavior_logic/fix_dev_bt.md create mode 100644 docs/topics/behavior_logic/id_assignment_bt.md create mode 100644 docs/topics/behavior_logic/index.md create mode 100644 docs/topics/behavior_logic/monitor_threats_bt.md create mode 100644 docs/topics/behavior_logic/msg_cs_bt.md create mode 100644 docs/topics/behavior_logic/msg_em_bt.md create mode 100644 docs/topics/behavior_logic/msg_intro_bt.md create mode 100644 docs/topics/behavior_logic/msg_other_bt.md create mode 100644 docs/topics/behavior_logic/msg_rm_bt.md create mode 100644 docs/topics/behavior_logic/publication_bt.md create mode 100644 docs/topics/behavior_logic/reporting_bt.md create mode 100644 docs/topics/behavior_logic/rm_bt.md create mode 100644 docs/topics/behavior_logic/rm_closure_bt.md create mode 100644 docs/topics/behavior_logic/rm_prioritization_bt.md create mode 100644 docs/topics/behavior_logic/rm_validation_bt.md create mode 100644 docs/topics/behavior_logic/vuldisco_bt.md create mode 100644 docs/topics/formal_protocol/index.md create mode 100644 docs/topics/formal_protocol/worked_example.md create mode 100644 docs/topics/future_work/cvd_directory.md create mode 100644 docs/topics/future_work/index.md create mode 100644 docs/topics/future_work/mod_sim.md create mode 100644 docs/topics/future_work/ontology.md create mode 100644 docs/topics/future_work/reward_functions.md create mode 100644 docs/topics/index.md create mode 100644 docs/topics/process_models/cs/cs_model.md create mode 100644 docs/topics/process_models/cs/cs_substates_table.md create mode 100644 docs/topics/process_models/cs/index.md create mode 100644 docs/topics/process_models/cs/pxa_diagram.md create mode 100644 docs/topics/process_models/cs/pxa_diagram_simple.md create mode 100644 docs/topics/process_models/cs/vfdpxa_diagram.md create mode 100644 docs/topics/process_models/dfa_notation_definition.md create mode 100644 docs/topics/process_models/em/defaults.md create mode 100644 docs/topics/process_models/em/early_termination.md create mode 100644 docs/topics/process_models/em/em_dfa_diagram.md create mode 100644 docs/topics/process_models/em/embargo_defn.md create mode 100644 docs/topics/process_models/em/index.md create mode 100644 docs/topics/process_models/em/nda-sidebar.md create mode 100644 docs/topics/process_models/em/negotiating.md create mode 100644 docs/topics/process_models/em/principles.md create mode 100644 docs/topics/process_models/em/split_merge.md create mode 100644 docs/topics/process_models/em/working_with_others.md create mode 100644 docs/topics/process_models/index.md create mode 100644 docs/topics/process_models/model_interactions/cs_global_local.md create mode 100644 docs/topics/process_models/model_interactions/index.md create mode 100644 docs/topics/process_models/model_interactions/rm_em.md create mode 100644 docs/topics/process_models/model_interactions/rm_em_cs.md create mode 100644 docs/topics/process_models/rm/index.md create mode 100644 docs/topics/process_models/rm/rm_interactions.md create mode 100644 docs/topics/process_models/rm/rm_state_machine_diagram.md create mode 100644 docs/topics/user_stories/index.md rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_001.md (83%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_002.md (72%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_003.md (85%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_004.md (86%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_005.md (85%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_006.md (85%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_007.md (86%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_008.md (81%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_009.md (84%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_010.md (63%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_011.md (81%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_012.md (84%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_013.md (88%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_014.md (81%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_015.md (86%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_016.md (85%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_017.md (84%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_018.md (80%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_019.md (82%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_020.md (83%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_021.md (78%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_022.md (80%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_023.md (79%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_024.md (81%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_025.md (80%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_026.md (78%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_027.md (84%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_028.md (82%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_029.md (85%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_030.md (77%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_031.md (78%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_032.md (64%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_033.md (69%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_034.md (82%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_035.md (79%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_036.md (81%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_037.md (85%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_038.md (83%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_039.md (82%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_040.md (82%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_041.md (80%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_042.md (84%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_043.md (87%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_044.md (87%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_045.md (85%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_046.md (86%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_047.md (87%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_048.md (88%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_049.md (87%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_050.md (86%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_051.md (80%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_052.md (86%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_053.md (87%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_054.md (88%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_055.md (84%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_056.md (83%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_057.md (85%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_058.md (86%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_059.md (82%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_060.md (85%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_061.md (85%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_062.md (87%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_063.md (86%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_064.md (80%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_065.md (83%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_066.md (88%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_067.md (83%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_068.md (83%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_069.md (75%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_070.md (79%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_071.md (80%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_072.md (79%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_073.md (78%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_074.md (81%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_075.md (81%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_076.md (90%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_077.md (76%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_078.md (83%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_079.md (75%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_080.md (86%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_081.md (81%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_082.md (76%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_083.md (82%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_084.md (84%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_085.md (86%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_086.md (78%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_087.md (79%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_088.md (82%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_089.md (80%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_090.md (81%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_091.md (81%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_092.md (83%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_093.md (82%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_094.md (82%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_095.md (80%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_096.md (81%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_097.md (73%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_098.md (84%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_099.md (77%) rename {doc/user_stories/Unsupported => docs/topics/user_stories}/story_2022_100.md (76%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_101.md (79%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_102.md (74%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_103.md (80%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_104.md (86%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_105.md (78%) rename {doc/user_stories/Provided => docs/topics/user_stories}/story_2022_106.md (84%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_107.md (86%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_108.md (78%) rename {doc/user_stories/Allowed => docs/topics/user_stories}/story_2022_109.md (87%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_110.md (79%) rename {doc/user_stories/Out-of-scope => docs/topics/user_stories}/story_2022_111.md (77%) create mode 100644 docs/topics/user_stories/table.md create mode 100644 docs/tutorials/index.md create mode 100644 mkdocs.yml create mode 100644 requirements.txt diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md new file mode 100644 index 00000000..098c42e9 --- /dev/null +++ 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). \ No newline at end of file diff --git a/.github/workflows/deploy_site.yml b/.github/workflows/deploy_site.yml new file mode 100644 index 00000000..7746590b --- /dev/null +++ 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 index 4a6e788e..e48df04c 100644 --- 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 index 46848b02..5c500b01 100644 --- 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: +- 2019 Update: ### A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure (MPCVD) - Allen D. Householder and Jonathan Spring -- 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 +- ### Designing Vultron: A Protocol for Multi-Party Coordinated Vulnerability Disclosure (MPCVD) - Allen D. Householder -- 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 +- DM23-0698 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 61c23cc9..95ad910d 100644 --- 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. "1..*" Report: reports +Case *--> "0..*" Message : messages +Case *--> "0..*" LogEvent : log_events +Case *--> "1..*" Participant : participants +Participant *--> "1" Contact : contact +Participant <|-- VendorParticipant +Participant <|-- DeployerParticipant +``` + +With the following supporting enumerations and flags: + +```mermaid +classDiagram + +class CaseRoleFlags { + <> + Finder + Reporter + Vendor + Coordinator + Deployer + Other +} + +class EMStateEnum { + <> + None + Proposed + Accepted + Revise + Exited +} + +class PXAStateEnum { + <> + pxa + pxA + pXa + pXA + Pxa + PxA + PXa + PXA +} + +class RMStateEnum { + <> + Start + Received + Invalid + Valid + Deferred + Accepted + Closed +} + +class VFDStateEnum { + <> + vfd + Vfd + VFd + VFD + ..d + ..D +} + +class MessageTypeEnum { + <> + RS, RI, RV, RD, RA, RC, RK, RE, + EP, ER, EA, EV, EJ, EC, ET, EK, EE, + CV, CF, CD, CP, CX, CA, CK, CE, + GI, GK, GE +} + +``` + +## The `Case` Class + +The `Case` class has attributes to track the [Embargo Management](../topics/process_models/em/index.md) (EM) state and the +[participant-agnostic](../topics/process_models/model_interactions/index.md) portion of the [Case State](../topics/process_models/cs/index.md) (CS) model (i.e., the `pxa` +substates), as outlined in [model interactions](../topics/process_models/model_interactions/index.md). +The `Case` class aggregates one or more `Reports` and `Participants`, and 0 or more `Messages` and `LogEvents`. +We include a `receive_message()` method to allow `Participants` to send messages to the `Case`. +See [below](#the-message-class) for more details. + +## The `Report` Class + +The `Report` class represents the vulnerability report that serves as the impetus for the case. +Since it is possible for multiple reports to arrive that describe the same vulnerability, the cardinality of the +composition relationship allows for a `Case` to have many `Reports`. +In most `Cases`, however, there will be only a single associated `Report`. + +## The `Message` Class + +The `Message` class represents a protocol message as outlined in [Message Types](../reference/formal_protocol/messages.md). +We expect that any implementation of this model will expand this data type to include numerous message-related attributes. +Here, we highlight the minimum requirements that the protocol demands: + +- Each `Message` has an identified sender (who is a `Participant` in the case) and one or more message +types as enumerated in [Message Types](../reference/formal_protocol/messages.md). +- Message types are represented as flags since a single actual message might represent multiple message types. +- For example, a report submission that includes an embargo proposal might have both the _RS_ and _EP_ message type flags set. + +Conceptually, one might think of the `Case` as a shared object among engaged `Participants` and that `Messages` are sent +to the `Case` for all `Participants` to see. +In other words, the `Case` acts as a broadcast domain, a topic queue, or a blackboard pattern (depending on your +preferences for networking or software engineering terminology). +Because of this shared-channel assumption, we could have omitted the `recipient` attribute from the `Message` class, as the `Case` itself +can serve as the recipient of each message emitted by any `Participant`. +Implementations of this model could, of course, choose a more traditional messaging model with specified recipients, so +we leave that choice to implementers. + +## The `LogEvent` Class + +The `LogEvent` class is a placeholder to represent an event log or history for the `Case`. +Although not required for the protocol to operate, it is a good idea for `Case` tracking to include a timestamped +list of events (e.g., state changes or messages sent or received) so that new `Participants` can be brought up to speed +and so that cases can be analyzed for process improvement in the future. + +## The `Participant` Class + +The `Participant` class represents an individual or organization's involvement in the case. +The attributes of the `Participant` class are as follows: + +!!! tip inline end + Flags are used instead of an enumeration to convey that + a `Participant` may have multiple roles in a single `Case`. Roles + may differ for the same actor across different cases. + +`case_role` + +: A set of flags indicating the Role(s) this `Participant` plays in + the `Case` + + +For example, an organization might be the Vendor in one case and the Coordinator in another. + +`rm_state` + +: An enumeration attribute that captures the RM state for this `Participant` + consistent with [Report Management](../topics/process_models/rm/index.md). + +!!! tip inline end + + The `case_engagement` attribute is provided to allow other `Participants` to recognize the + status of other `Participants`. + +`case_engagement` + +: A Boolean attribute that indicates whether the `Participant` should + be included in future communications about the `Case` + + +For example, a Reporter who bows out of a case shortly after reporting it to a Coordinator might be listed as a +`Participant` with `case_engagement=False` and could, therefore, be left out of further communication about the case. + +!!! tip inline end + + As discussed in [Embargo Principles](../topics/process_models/em/principles.md#sec:embargo_engagement), + it is possible for a `Participant` to exit a case while still agreeing to abide by the terms of the extant embargo. + +`embargo_adherence` + +: A Boolean attribute that indicates the expectation that a + `Participant` is adhering to any existing embargo + + +Continuing our example of a Reporter leaving a case early, they might still be cooperative and indicate their +`embargo_adherence=True`. +A more hostile `Participant` exit could warrant setting `embargo_adherence=False`, likely triggering an embargo +teardown procedure as a consequence. + +`Participants` can also emit (send) and receive messages. + +!!! tip + + The `+` on `receive_message` indicates that this capability is accessible to others (i.e., you can send a `Participant` a message). + On the contrary the `-` on `emit_message` conveys that this capability is only accessible to the `Participant` class + itself (i.e., each `Participant` gets to decide if, when, and what messages to send). + +#### `Vendor` and `Deployer` `Participant` Classes. + +The presence of the `VendorParticipant` and `DeployerParticipant` +classes---depicted as implementations of the `Participant` class---is +necessitated by the discussion in [States](../reference/formal_protocol/states.md), +where we describe how Vendors and Deployers have unique parts to play in the creation, delivery, and +deployment of fixes within the CVD process. +These two classes add the `vfd_state` attribute with different possible values. +Vendors can take on one of four possible values (`vfd`, `Vfd`, `VFd`, and `VFD`), +whereas Deployers only have two possible values (`..d` and `..D`). +Other than that, Vendors and Deployers have the same attributes as other `Participants`. + +## The `Contact` Class + +Since a `Participant` is a specific relationship between an individual or organization and the `Case` itself, +we can safely assume that those individuals or organizations exist and persist independently of the `Cases` they +participate in. +Hence, each `Participant` class in a `Case` is associated with a long-lived `Contact` record that represents an +individual or organization. +Defining the `Contact` class is outside the scope of this document, so we will simply say that there is nothing +particularly special about it. +One might reasonably expect `Contacts` to have names, email addresses, phone numbers, etc. + +!!! tip "Directory Services Are (Currently) Out of Scope" + + A separate contact management process and accompanying directory service is a likely candidate for [future integration work](../topics/future_work/cvd_directory.md). + For now, we observe that similar directories already exist, although there is room for improvement: + + - FIRST maintains a [directory of member teams](https://www.first.org/members/teams/) for incident response purposes + + - Disclose.io offers a searchable list of [bug bounty and vulnerability + disclosure programs](https://disclose.io/programs/). + Contributions are solicited as [pull requests](https://github.com/disclose/diodb) on GitHub. + + - Many vulnerability disclosure platform service providers host directories of the programs hosted on their platforms. + +## The Enumeration Classes + +The remainder of the class diagram above consists of classes representing the Role and Message Type flags and various enumerations. + +- The `Role` flags are consistent with the roles we defined in [Terms and Definitions](../topics/background/terms.md), as taken from the [CVD Guide](https://vuls.cert.org/confluence/display/CVD). +- `Message Type` flags are consistent with [Message Types](../reference/formal_protocol/messages.md). +- The other enumeration classes are consistent with the [Report Management](../topics/process_models/rm/index.md), [Embargo Management](../topics/process_models/em/index.md), +and [Case State](../topics/process_models/cs/index.md) process models and their respective state machines. +Note that we split the [CS model](../topics/process_models/cs/cs_model.md) states into two separate enumerations to reflect the participant-agnostic and participant-specific portions of the model +described in [Model Interactions](../topics/process_models/model_interactions/index.md). + diff --git a/docs/howto/em_icalendar.md b/docs/howto/em_icalendar.md new file mode 100644 index 00000000..6097f97a --- /dev/null +++ b/docs/howto/em_icalendar.md @@ -0,0 +1,168 @@ +# Embargo Management and the iCalendar Protocol + +{% include-markdown "../includes/not_normative.md" %} + +We are including this page because the ideas outlined here were instrumental to the development of the more general +[Embargo Management process](../topics/process_models/em/index.md) in the main protocol and may remain of use in future implementations. + +The embargo negotiation process—in terms of the proposal, acceptance, rejection, etc.—is strikingly +parallel to the process of scheduling a meeting in a calendaring system. +To that end, we note the potential application of the [`iCalendar`](https://en.wikipedia.org/wiki/ICalendar) protocol specified in [RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545) to the +[EM process](../topics/process_models/em/index.md) with the semantics described in this section. +While we anticipate that future CVD APIs could adopt an `iCalendar`-compatible syntax like `jCal` ([RFC 7265](https://datatracker.ietf.org/doc/html/rfc7265)), for +this conceptual mapping, we use the basic `iCalendar` syntax from [RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545). + +A CVD Case might have an associated `iCalendar` object. +Embargo schedules can be represented as a single `VEVENT` object. + +A mapping of EM concepts to `iCalendar` field mappings is provided in the table below. + +| Embargo Concept | iCalendar Mapping | EM Msg Type | +|----------------------------------------------------------------|-------------------|-------------| +| Embargo object | `VEVENT` | - | +| Embargo ID | `SUMMARY: embargo expiration` | - | +| Embargo End Time and Date | `DSTART = DTEND` (0 duration event) | - | +| Proposer | `ORGANIZER` | - | +| Participant (proposed) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=NEEDS-ACTION` | _EP_, _EV_ | +| Participant (acknowledge without acceptance) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=TENTATIVE` | _EK_ | +| Participant (accept) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=ACCEPTED` | _EA_, _EC_ | +| Participant (reject) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=DECLINED` | _ER_, _EJ_ | +| Details (link to case trackers, etc.) | `DESCRIPTION` | - | +| Embargo Status $q^{em} \in P$ | `STATUS:TENTATIVE` | _EP_ | +| Embargo Status $q^{em} \in A$ | `STATUS:CONFIRMED` | _EA_, _EC_ | +| Embargo Status $q^{em} \in X$ due to early termination | `STATUS:CANCELLED` | _ET_ | +| Embargo Status $q^{em} \in N$ due to lack of acceptance quorum | `STATUS:CANCELLED` | _ER_ | +| Other | `CATEGORIES:EMBARGO`
`RSVP: TRUE` | - | + + + +!!! note "" + + Reflecting the non-binding nature of embargoes, each `ATTENDEE` SHOULD be marked as `ROLE=OPT-PARTICIPANT` in the invitation. + +!!! note "" + + Vulnerability details MUST NOT appear in the iCalendar data. + +!!! note "" + + A case or vulnerability identifier SHOULD appear in the `VEVENT` + `SUMMARY` along with the words "embargo expiration." + +!!! note "" + + Case or vulnerability identifiers SHOULD NOT carry any information + that reveals potentially sensitive details about the vulnerability. + +!!! note "" + + An embargo proposal SHALL set `RSVP:True` for all attendees. + +A Participant response with `ATTENDEE:partstat=TENTATIVE` serves as a +basic acknowledgment that the embargo proposal has been received, but it +does not represent agreement to the proposal. + +The `iCalendar` `ATTENDEE:partstat=DELEGATED` value has no semantic equivalent in the EM process. + +## Proposing an Embargo + +Following the model of inviting a group of attendees to a meeting, a +proposed embargo can be achieved as follows: + +1. An `ORGANIZER` sends an embargo invitation, represented by a + `VEVENT` with `STATUS:TENTATIVE` listing Participants as `ATTENDEE`s + ($q^{em} \in N \xrightarrow{p} P$). + +2. Each `ATTENDEE` has `partstat=NEEDS-ACTION` set on the invitation, + indicating that they have not yet accepted it. + +3. Individual `ATTENDEE`s acknowledge (`partstat=TENTATIVE`), accept + (`partstat=ACCEPTED`), or decline (`partstat=DECLINED`). Their + response is sent to the `ORGANIZER`. + +4. If the `ORGANIZER` determines that there is a quorum of accepts, + they mark the `VEVENT` as `STATUS:CONFIRMED` + ($q^{em} \in P \xrightarrow{a} A$). + +5. If the `ORGANIZER` determines that there is no sufficient quorum of + accepts, they mark the new `VEVENT` as `STATUS:CANCELLED` + ($q^{em} \in P \xrightarrow{r} N$). + +## Embargo Counterproposals + +Counterproposals can be achieved in two ways: + +1. by declining an initial invitation and then proposing a new one + ($q^{em} \in P \xrightarrow{r} N \xrightarrow{p} P$) + +2. by proposing a new embargo without declining the first one + ($q^{em} \in P \xrightarrow{p} P$) + +Either way, this is analogous to requesting a proposed meeting to be +shifted to a different time or date prior to accepting the original +proposed meeting time. However, following the argument from +[Default Embargoes](../topics/process_models/em/defaults.md), +we suggest that Participants start by (1) accepting the shortest proposed embargo and (2) proposing a +revision to the new embargo instead, which we cover next. + +## Proposing a Change to an Existing Embargo + +!!! tip inline end "Assumption" + + This process assumes that an existing embargo is represented by a `VEVENT` with`STATUS:CONFIRMED`. + +Similar to rescheduling an existing meeting, a proposed change to an +existing embargo can be achieved as follows. + +1. A new proposal is made as a `VEVENT` with `STATUS:TENTATIVE` and the + same `ATTENDEE` list as the existing one + ($q^{em} \in A \xrightarrow{p} R$). + +2. Each `ATTENDEE` on the new invitation has `partstat=NEEDS-ACTION` + set, indicating that they have not yet accepted the new invitation. + +3. Individual `ATTENDEE`s acknowledge (`partstat=TENTATIVE`), accept + (`partstat=ACCEPTED`), or decline (`partstat=DECLINED`). Their + response is sent to the `ORGANIZER`. + +4. If the `ORGANIZER` determines that there is a quorum of accepts + ($q^{em} \in R \xrightarrow{a} A$), they + + 1. mark the new `VEVENT` as `STATUS:CONFIRMED` + + 2. mark the old `VEVENT` as `STATUS:CANCELLED` + +5. If the `ORGANIZER` determines that there is no sufficient quorum of + accepts ($q^{em} \in R \xrightarrow{r} A$), they + + 1. mark the new `VEVENT` as `STATUS:CANCELLED` + + 2. retain the old `VEVENT` as `STATUS:CONFIRMED` + +## Terminating an Existing Embargo + +Terminating an existing embargo ($q^{em} \in \{A,R\} \xrightarrow{t} X$) +can be triggered in one of two ways: + +- A *normal* exit occurs when the planned embargo end time has + expired. + +- An *abnormal* exit occurs when some external event causes the + embargo to fail, such as when the vulnerability or its exploit has + been made public, attacks have been observed, etc., as outlined in + [Early Termination](../topics/process_models/em/early_termination.md). + +Translating this into `iCalendar` semantics, we have the following, +which assumes an existing embargo is represented by a `VEVENT` with +`STATUS:CONFIRMED`. + +1. *Normal termination*: The `VEVENT` retains its `STATUS:CONFIRMED` + and passes quietly from the future through the present into the + past. + +2. *Abnormal termination*: The `ORGANIZER` sets the `VEVENT` to + `STATUS:CANCELLED` and sends it out to the `ATTENDEE` list. + +The above is consistent with our premise in +[Early Termination](../topics/process_models/em/early_termination.md): Embargo Termination ($ET$) messages +are intended to have immediate effect. diff --git a/docs/howto/general_implementation.md b/docs/howto/general_implementation.md new file mode 100644 index 00000000..ec68c23d --- /dev/null +++ b/docs/howto/general_implementation.md @@ -0,0 +1,89 @@ +# General Implementation Notes + +{% include-markdown "../includes/not_normative.md" %} + +Here we provide a few general implementation notes. + +## Message Formats + +We defined a number of [message types](../reference/formal_protocol/messages.md) in the formal protocol, and showed how they +fit into a [case object](case_object.md), but we did not specify any format for these messages. +Message formats can be thought of as two related problems: + +### Structure and Semantic Content of Each Message Type + +In addition to the commentary throughout this section, messages will likely need to have some sort of consistent header +information and some content specifically designed to address the semantic needs of each message type. +Such a format must include fields, datatypes, and an underlying formatting structure. + +### Container Syntax for Messaging and Data Exchange + +While we have a predilection for JSON Schema-defined formats, other format specifications (e.g., XSD or protobuf) could +serve implementers' needs just as well. +In fact, to the degree possible, it seems preferable for the container syntax to remain a late-binding decision in implementation. +As long as the structure and semantics are well defined, most standard data formats should be adaptable to the task. + + +---- + +!!! note "" + + Vultron Protocol Messages SHOULD use well-defined format specifications (e.g., JSON Schema, protobuf, XSD). + +!!! tip "Related formats and ontologies" + + We anticipate that emerging formats like the [OASIS CSAF](https://oasis-open.github.io/csaf-documentation/) and ontologies + like the [NIST Vulnerability Data Ontology](https://github.com/usnistgov/vulntology) ([Vulntology](https://github.com/usnistgov/vulntology)) will play a part. + + +## Transport Protocol + +We have not specified how Vultron Protocol implementations connect to each other. +Presumably, technologies such as REST APIs or WebSockets would be leading candidates to resolve this gap. +However, other system architectures could be adapted as well. +For example, an XMPP message-routing system might be desired, or even blockchain-related technologies might be adaptable +to portions of this protocol as well. + +!!! note "" + + Vultron Protocol Implementations SHOULD use common API patterns (e.g., REST, WebSockets). + + +## Identity Management + +We have not addressed Participant authentication as part of the protocol, but obviously implementers will need to +determine how Participants know who they are talking to. +Individual user accounts with multi-factor authentication are the de facto standard for modern CVD tools, but in +an interoperable MPCVD world, the assumption of centralized identity management may not be practical. + +!!! tip "Related Identity Standards" + + Federated identity protocols such as [OAuth](https://oauth.net/), [SAML](https://saml.xml.org/about-saml), and/or [OpenID Connect](https://openid.net/developers/how-connect-works/) may be useful. + +## Encryption + +The protocol does not specify any encryption requirements, but it is likely that some form of encryption will be +necessary for Vultron Protocol implementations. + +### Protecting Data in Transit + +It may be sufficient for implementations to rely on transport-layer encryption (e.g., TLS), but end-to-end encryption +may be desirable in some cases. +For now at least, we leave this decision to implementers. + +!!! note "" + + Vultron Protocol Implementations SHOULD use transport-layer encryption to protect sensitive data in transit. + +!!! note "" + + Vultron Protocol Implementations MAY use end-to-end encryption to protect sensitive data in transit. + +### Protecting Data at Rest + +Encryption at rest is likely to be a requirement for many implementations. +Again, we leave this decision to implementers. + +!!! note "" + + Vultron Protocol Implementations MAY use encryption to protect sensitive data at rest. diff --git a/docs/howto/index.md b/docs/howto/index.md new file mode 100644 index 00000000..29ac0ae3 --- /dev/null +++ b/docs/howto/index.md @@ -0,0 +1,42 @@ +# Implementing Vultron + +!!! tip inline end "Prerequisites" + + The [Implementing Vultron](index.md) section assumes that you have: + + - an interest in implementing the Vultron Protocol + - basic familiarity with the Vultron Protocol + - familiarity with the CVD process in general + + If you are unfamiliar with the Vultron Protocol, we recommend that you start with [Understanding Vultron](../topics/index.md). + For technical reference, see [Reference](../reference/index.md). + If you're just trying to understand the CVD process, we recommend that you start with the [CERT Guide to Coordinated Vulnerability Disclosure](https://vuls.cert.org/confluence/display/CVD/). + +Here we collect some guidance for potential implementations of Vultron. + +While a complete protocol implementation specification remains a work in progress, we do have a few additional +suggestions for potential implementers. +In this section, you will find: + +- an abstract [case object](case_object.md) for use in tracking MPCVD cases +- Notes on the [core Vultron Protocol subprocesses](process_implementation.md) (RM, EM, and CS), including how the CS model might integrate with +other processes +- A few thoughts on the [Embargo Management Process](em_icalendar.md) and how it might be implemented using the `iCalendar` protocol. +- [General notes](general_implementation.md) on future implementations. + +Over time, we plan to expand this section of the documentation to include: + +- Basic data model examples +- Behavior logic implementation examples +- Simulation examples +- Communication protocol implementation examples +- Other implementation notes as needed + +!!! info "The Vultron Protocol is an interoperability protocol" + + The protocol and data structures outlined in this documentation are intended to facilitate interoperability among individual + organizations' workflow management systems. + As such, they are focused on the exchange of information and data necessary for the MPCVD process to function and will + not likely be sufficient to fully address any individual organization's vulnerability response process. + + diff --git a/docs/howto/process_implementation.md b/docs/howto/process_implementation.md new file mode 100644 index 00000000..7549ac54 --- /dev/null +++ b/docs/howto/process_implementation.md @@ -0,0 +1,88 @@ +# Process Implementation Notes + +{% include-markdown "../includes/not_normative.md" %} + +Integrating the Vultron Protocol into everyday MPCVD operations requires each Participant to consider how their business processes +interact with the individual [RM](../topics/process_models/rm/index.md), [EM](../topics/process_models/em/index.md), +and [CS](../topics/process_models/cs/index.md), process models, respectively. +Here we offer some thoughts on where such integration might begin. + +## RM Implementation Notes + +Roughly speaking, the RM process is very close to a normal [IT Service Management](https://en.wikipedia.org/wiki/IT_service_management) (ITSM) +incident or service request workflow. +As such, the RM process could be implemented as a JIRA ticket workflow, as part of a Kanban process, etc. +The main modifications needed to adapt an existing workflow are to intercept the key milestones and emit the appropriate RM messages: + +- when the reports are received (_RK_) + +- when the report validation process completes (_RI_, _RV_) + +- when the report prioritization process completes (_RA_, _RD_) + +- when the report is closed (_RC_) + +### Vulnerability Draft Pre-Publication Review + +!!! tip inline end "Pre-Publication Drafts in Related Standards" + + [ISO/IEC 29148:2018](https://www.iso.org/standard/72311.html) includes a pre-publication review step in its process. + +MPCVD case Participants often share pre-publication drafts of their advisories during the embargo period. +Our protocol proposal is mute on this subject because it is not strictly necessary for the MPCVD process to complete successfully. +However, as we observe in the [ISO Crosswalk](../reference/iso_crosswalk.md), the _GI_ and _GK_ message types appear to provide sufficient mechanics for this +process to be fleshed out as necessary. +This draft-sharing process could be built into the [*prepare publication*](../topics/behavior_logic/publication_bt.md#prepare-publication-behavior) process, where appropriate. + +## EM Implementation Notes + +### Embargo Management and Calendaring + +In terms of the proposal, acceptance, rejection, etc., the EM process is strikingly parallel to the process of +scheduling a meeting in a calendaring system. +In [EM and iCalendar](em_icalendar.md), we suggest a potential mapping of many of the concepts from the EM process +onto [`iCalendar`](https://en.wikipedia.org/wiki/ICalendar) protocol semantics. + +### Embargo Management Does Not Deliver Synchronized Publication {#sec:pub_sync} + +In our protocol design, we were careful to focus the EM process on establishing when publication restrictions are +lifted. +That is not the same as actually scheduling publications following the embargo termination. +Our experience at the CERT/CC shows that this distinction is rarely a significant problem since many case Participants +simply publish at their own pace shortly after the embargo ends. +However, at times, case Participants may find it necessary to coordinate even more closely on publication scheduling. + +## CS Implementation Notes + +Because part of the CS model is Participant specific and the other is global to the case, we address each part below. + +### The _vfd_ Process + +Similar to the RM process, which is specific to each Participant, the _vfd_ process is +individualized to each Vendor (or Deployer, for the simpler $d \xrightarrow{\mathbf{D}} D$ state transition). +Modifications to the Vendor's development process to implement the Vultron Protocol are expected to be minimal and are +limited to the following: + +- acknowledging the Vendor's role on report receipt with a _CV_ message + +- emitting a _CF_ message when a fix becomes ready (and possibly terminating any active embargo to open the door to publication) + +- (if relevant) issuing a _CD_ message when the fix has been deployed + +Non-Vendor Deployers are rarely involved in MPCVD cases, but when they are, their main integration point is to emit a +_CD_ message when deployment is complete. + +### The _pxa_ Process + +On the other hand, the _pxa_ process hinges on monitoring public and private sources for evidence of information leaks, +research publications, and adversarial activity. +In other words, the _pxa_ process is well positioned to be wired into Participants' threat intelligence and threat +analysis capabilities. +The goal would be to emit _CP_, _CX_, and _CA_ messages as appropriate when such evidence is detected. +Some portions of this process can be automated: + +- Human analysts and/or automated search agents can look for evidence of early publication of vulnerability information. + +- IDS and IPS signatures might be deployed prior to fix availability to act as an early warning of adversary activity. + +- Well-known code publication and malware analysis platforms can be monitored for evidence of exploit publication or use. diff --git a/docs/includes/curr_ver.md b/docs/includes/curr_ver.md new file mode 100644 index 00000000..08e3a216 --- /dev/null +++ b/docs/includes/curr_ver.md @@ -0,0 +1,3 @@ +!!! info "Current Version" + + The current version of the Vultron Protocol is `{%include-markdown "../../VERSION" %}`. \ No newline at end of file diff --git a/docs/includes/do_not_start_here.md b/docs/includes/do_not_start_here.md new file mode 100644 index 00000000..8a6d9329 --- /dev/null +++ b/docs/includes/do_not_start_here.md @@ -0,0 +1,5 @@ +!!! warning "Do Not Start Here" + + If this is your first time reading about the Vultron Protocol, we recommend that you start with [Understanding Vultron](../topics/background/index.md). + This section is heavy on formalism and is intended for readers who are already familiar with the Vultron Protocol + concepts and design principles. diff --git a/docs/includes/normative.md b/docs/includes/normative.md new file mode 100644 index 00000000..6e70ce7c --- /dev/null +++ b/docs/includes/normative.md @@ -0,0 +1,4 @@ +!!! success inline end "This page is normative" + + This page is considered a core part of the Vultron Protocol. + This is a normative section of the documentation. diff --git a/docs/includes/not_normative.md b/docs/includes/not_normative.md new file mode 100644 index 00000000..64b4ab4d --- /dev/null +++ b/docs/includes/not_normative.md @@ -0,0 +1,4 @@ +!!! warning inline end "This page is not normative" + + This page is not considered a core part of the Vultron Protocol as proposed in the main documentation. + Although within the page we might provide guidance in terms of SHOULD, MUST, etc., the content here is **not** normative. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..1fd693cf --- /dev/null +++ b/docs/index.md @@ -0,0 +1,87 @@ +# The Vultron Coordinated Vulnerability Disclosure Protocol + +!!! warning inline end "Work in progress" + + We are currently working on the documentation of the Vultron CVD Protocol. + This documentation is a work in progress and is not yet complete. + Our focus so far is on + + - [Understanding Vultron](topics/background/index.md), which describes the protocol in detail + - [Implementing Vultron](howto/index.md), which provides guidance for potential implementations of Vultron + - [Reference](reference/formal_protocol/index.md), which provides the formal protocol specification + +The Vultron Protocol is a research project to explore the creation of a federated, decentralized, and open source protocol for +coordinated vulnerability disclosure (CVD). +It has grown out of the CERT/CC's decades of experience in coordinating global response to software vulnerabilities. +Our goal is to create a protocol that can be used by any organization to coordinate the disclosure of vulnerabilities in +information processing systems (software, hardware, services, etc.), and to build a community of interoperability across +independent organizations, processes, and policies that can work together to coordinate appropriate responses to vulnerabilities. + +The Vultron Protocol is a collection of ideas, models, code, and work in progress, and is not yet ready for production use. + +{% include-markdown "includes/curr_ver.md" %} + +## How this documentation is organized + + +!!! tip inline "Learning About Vultron" + + The [Learning Vultron](tutorials/index.md) section is intended to eventually include tutorials and other + information about the Vultron Protocol that is oriented towards novice users and getting started with the protocol. + However, because we are still in the early stages of the project, this section is just a placeholder for now. + +!!! abstract inline end "Understanding Vultron" + + The [Understanding Vultron](topics/background/index.md) section includes background information about Vultron, + including the motivation for the project, the problem space that we are trying to address, and the design principles + that we are using to guide our work. It also includes a detailed description of the Vultron Protocol, including + the state machines and behavior logic that we use to model the behavior of the protocol. + +!!! question inline "Implementing Vultron" + + The [Implementing Vultron](howto/index.md) section includes guidance for potential implementations of Vultron. + In the future, we plan to include how-to guides to help you use Vultron, but for now it is focused on guidance for + potential implementers of Vultron. + +!!! info inline end "Vultron Protocol Reference" + + The [Reference](reference/index.md) section includes the formal Vultron Protocol specification, crosswalks the + protocol with other related standards and protocols, etc. + In the future, we plan to include other reference information about Vultron, including code documentation. + +We are in the process of documenting the Vultron CVD Protocol as we work towards a prototype implementation. +We are using the [Diátaxis Framework](https://diataxis.fr/) to organize our documentation into four main categories, +oriented around the different ways that people might need to learn about and use the Vultron Protocol. + +Our current focus is on the [Understanding Vultron](topics/background/index.md) section, which describes the protocol +in detail. + + +## Background + +The Vultron Protocol is a continuation of the CERT/CC's work on improving the coordination of vulnerability disclosure and response. +Our previous work in this area includes: + +- [The CERT Guide to Coordinated Vulnerability Disclosure](https://vuls.cert.org/confluence/display/CVD) +- Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization (SSVC) ([Version 1.0](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=636379), [Version +2.0](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=653459), [github](https://github.com/CERTCC/SSVC)) +- The [Vulnerability Information and Coordination Environment](https://kb.cert.org/vince/) + ([VINCE](https://kb.cert.org/vince/)) + ([blog post](https://insights.sei.cmu.edu/news/certcc-releases-vince-software-vulnerability-collaboration-platform/), + [github](https://github.com/CERTCC/VINCE)) + +along with a variety of related research, including + +- [Cybersecurity Information Sharing: Analysing an Email Corpus of Coordinated Vulnerability Disclosure](https://weis2021.econinfosec.org/wp-content/uploads/sites/9/2021/06/weis21-sridhar.pdf) (WEIS 2021) +- [Historical Analysis of Exploit Availability Timelines](https://www.usenix.org/conference/cset20/presentation/householder) (CSET 2020) + +More recently, the CERT/CC has been working towards formalizing this knowledge into a protocol for CVD. +Our recent work in this area includes: + +- [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) (MPCVD), which also appeared in an +abridged form as [Are We Skillful or Just Lucky? Interpreting the Possible Histories of Vulnerability Disclosures](https://doi.org/10.1145/3477431) in the +ACM Journal Digital Threats: Research and Practice +- A collection of [Coordinated Vulnerability Disclosure User Stories](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=886543) derived from both our process modeling work and from the experience of building VINCE. + These user stories are collected in the [User Stories](topics/user_stories/index.md) section of this documentation. +- [Designing Vultron: A Protocol for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=887198) (MPCVD), + which serves as the basis for the work contained here. \ No newline at end of file diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js new file mode 100644 index 00000000..06dbf38b --- /dev/null +++ b/docs/javascripts/mathjax.js @@ -0,0 +1,16 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.typesetPromise() +}) diff --git a/docs/javascripts/tablesort.js b/docs/javascripts/tablesort.js new file mode 100644 index 00000000..6a5afcf2 --- /dev/null +++ b/docs/javascripts/tablesort.js @@ -0,0 +1,6 @@ +document$.subscribe(function() { + var tables = document.querySelectorAll("article table:not([class])") + tables.forEach(function(table) { + new Tablesort(table) + }) +}) diff --git a/docs/reference/formal_protocol/conclusion.md b/docs/reference/formal_protocol/conclusion.md new file mode 100644 index 00000000..f0239f28 --- /dev/null +++ b/docs/reference/formal_protocol/conclusion.md @@ -0,0 +1,169 @@ +# Formal Vultron Protocol Redux + +{% include-markdown "../../includes/normative.md" %} + +We have [formally defined](../../reference/formal_protocol/index.md) an [MPCVD protocol](../../index.md). +Here we provide a summary of the result. +See the linked sections for more details. + +
+
+ +Recapping the definitions given in the [introduction](index.md), we have: + +!!! note "Formal Protocol Definition" + + $${protocol}_{MPCVD} = + \Big \langle + { \langle S_i \rangle }^N_{i=1}, + { \langle o_i \rangle }^N_{i=1}, + { \langle M_{i,j} \rangle}^N_{i,j=1}, + { succ } + \Big \rangle$$ + +where + +| Symbol | Description | Defined In | +|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------| +| $N$ | Number of MPCVD Participants | [Introduction](index.md) | +| $\langle S_i \rangle_{i=1}^N$ | $N$ disjoint finite sets in which each $S_i$ represents the set of states of a given Participant $i$ | [States](states.md) | +| ${ \langle o_i \rangle }^N_{i=1}$ | the set of starting states across all Participants in which each $o_i$ is an element of $S_i$ representing the initial state of each Participant $i$ | [States](states.md) | +| $\langle M_{ij} \rangle_{i,j=1}^N$ | $N^2$ disjoint finite sets with $M_{ii}$ empty for all $i$. $M_{ij}$ represents the messages that can be sent from process $i$ to process $j$. | [Messages](messages.md) | +| $succ$ | a partial function mapping for each $i$ and $j$, $S_i \times M_{ij} \rightarrow S_i \textrm{ and } S_i \times M_{ji} \rightarrow S_i$ indicating the state changes arising from the sending and receiving of messages between Participants. | [Transitions](transitions.md) | + +!!! note inline end "Legend" + + | Symbol | Description | + |:-------:|:-------------------------| + | ↼ | Message Received | + | ⇀ | Message Sent | + | ⇌ | Message Sent or Received | + +## Summary Diagrams + +A summary of the MPCVD state model $S_i$ for an individual Participant is shown in the diagrams below. + +### Report Management + +The Report Management (RM) state model is shown below. +Note that with the exception of receiving reports, the RM process primarily focuses on Participants communicating +their status to other Participants, as it is primarily emitting messages as opposed to receiving them. + +```mermaid +stateDiagram-v2 + direction LR + S --> R : r (#8636;RS) + R --> I: i (#8640;RI) + R --> V : v (#8640;RV) + I --> V : v (#8640;RV) + V --> A : a (#8640;RA) + V --> D : d (#8640;RD) + A --> D : d (#8640;RD) + D --> A : a (#8640;RA) + A --> C : c (#8640;RC) + D --> C : c (#8640;RC) + I --> C : c (#8640;RC) +``` + + +### Embargo Management + +The Embargo Management (EM) state model is shown below. +The EM process is more interactive than the RM process, as it involves Participants negotiating with each other +to determine the appropriate embargo period for a given vulnerability report. + +```mermaid +stateDiagram-v2 + direction LR + N --> P : p ( #8652;EP) + P --> P : p ( #8652;EP) + P --> N : r ( #8652;ER) + P --> A : a ( #8652;EA) + A --> R : p ( #8652;EV) + R --> A : a ( #8652;EC) + R --> A : r ( #8652;EJ) + R --> R : p ( #8652;EV) + R --> X : t ( #8652;ET) + A --> X : t ( #8652;ET) +``` + +### Case State + +The Case State (CS) model is shown below. +We have divided the CS model into two diagrams: one that is specific to a given Participant, and one that is agnostic +to the Participant, reflecting changes experienced by all Participants. +The CS model is the most complex of the three, as it involves all Participants communicating with each other +about both their own state changes in the fix development and deployment process, as well as the state changes +driven by outside events (e.g., public awareness, exploits in the wild, attacks observed, etc.). + +#### Participant-Specific + +The _Vendor fix path_ is shown below, and is specific to individual Vendor Participants. +It reflects each Participant's state changes in the fix development and deployment process. + +```mermaid +--- +title: Vendor Fix Path +--- +stateDiagram-v2 + direction LR + vfd --> Vfd : V (#8640;CV) + Vfd --> VFd : F (#8640;CF) + VFd --> VFD : D (#8640;CD) +``` + +#### Participant-Agnostic + +The CS pxa model is shown below, and is agnostic to individual Participants. +It reflects the state changes driven by external events that affect all Participants. +Note that the diagram shown below simplifies the $X \implies P$ transitions based on the discussion +in the detailed [CS model](../../topics/process_models/cs/cs_model.md#exploit-publication-causes-public-awareness). + +```mermaid +--- +title: pxa Model +--- +stateDiagram-v2 + direction LR + pxa --> Pxa : P (#8652;CP) + pxa --> PXa : X+P (#8652;CX+CP) + pxa --> pxA : A (#8652;CA) + + pxA --> PxA: P (#8652;CP) + pxA --> PXA: X+P (#8652;CX+CP) + + Pxa --> PxA : A (#8652;CA) + Pxa --> PXa : X (#8652;CX) + + PXa --> PXA : A (#8652;CA) + PxA --> PXA : X (#8652;CX) +``` + +### Ordering Preferences + +!!! tip inline end "Notation" + + The symbol $\prec$ is read as *precedes*. + +In [Defining CVD Success](../../topics/background/cvd_success.md), we defined a set of 12 ordering preferences over the +6 events in the Case State model. The symbols for these preferences refer to the transition events in the Case State +diagrams above. + +| Ordering Preference | Notation | +| :--- | :--- | +| Fix Deployed Before Public Awareness | **D** $\prec$ **P** | +| Fix Ready Before Public Awareness | **F** $\prec$ **P** | +| Fix Deployed Before Exploit Public | **D** $\prec$ **X** | +| Fix Deployed Before Attacks Observed | **D** $\prec$ **A** | +| Fix Ready Before Exploit Public | **F** $\prec$ **X** | +| Vendor Awareness Before Public Awareness | **V** $\prec$ **P** | +| Fix Ready Before Attacks Observed | **F** $\prec$ **A** | +| Public Awareness Before Exploit Public | **P** $\prec$ **X** | +| Exploit Public Before Attacks Observed | **X** $\prec$ **A** | +| Public Awareness Before Attacks Observed | **P** $\prec$ **A** | +| Vendor Awareness Before Exploit Public | **V** $\prec$ **X** | +| Vendor Awareness Before Attacks Observed | **V** $\prec$ **A** | + +!!! tip "Worked Example" + + A [worked example](../../topics/formal_protocol/worked_example.md) of the protocol in action is available. \ No newline at end of file diff --git a/docs/reference/formal_protocol/index.md b/docs/reference/formal_protocol/index.md new file mode 100644 index 00000000..60367265 --- /dev/null +++ b/docs/reference/formal_protocol/index.md @@ -0,0 +1,86 @@ +# A Formal Protocol Definition for MPCVD {#sec:formal_protocol} + +{% include-markdown "../../includes/normative.md" %} + +The MPCVD process can be described as a Communicating Hierarchical State Machine. +In this section, we begin by laying out the requirements for a formal protocol +definition followed by a step-by-step walkthrough of each of those requirements +as they relate to the [RM](../../topics/process_models/rm/index.md), [EM](../../topics/process_models/em/index.md), and [CS](../../topics/process_models/cs/index.md) +models described elsewhere. + +{% include-markdown "../../includes/do_not_start_here.md" %} + +## Communication Protocol Definitions {#sec:protocol_definition} + +A communication protocol allows independent processes, represented as finite state machines, to coordinate their state +transitions through the passing of messages. [Brand and Zafiropulo](https://doi.org/10.1145/322374.322380) defined +a protocol as follows. + +!!! note "_Protocol_ Formally Defined" + + A **protocol** with $N$ processes is a quadruple: + + $$\label{eq:protocol} + protocol = + \Big \langle + { \langle S_i \rangle }^N_{i=1}, + { \langle o_i \rangle }^N_{i=1}, + { \langle M_{i,j} \rangle}^N_{i,j=1}, + { succ } + \Big \rangle$$ + + Where + + - $N$ is a positive integer representing the number of processes. + + - $\langle S_i \rangle_{i=1}^N$ are $N$ disjoint finite sets ($S_i$ + represents the set of states of process $i$). + + - Each $o_i$ is an element of $S_i$ representing the initial state of + process $i$. + + - $\langle M_{ij} \rangle_{i,j=1}^N$ are $N^2$ disjoint finite sets + with $M_{ii}$ empty for all $i$. $M_{ij}$ represents the messages + that can be sent from process $i$ to process $j$, + + - $succ$ is a partial function mapping for each $i$ and $j$, + $$S_i \times M_{ij} \rightarrow S_i \textrm{ and } S_i \times M_{ji} \rightarrow S_i$$ + $succ(s,x)$ is the state entered after a process transmits or + receives message $x$ in state $s$. It is a transmission if $x$ is + from $M_{ij}$ and a reception if $x$ is from $M_{ji}$. + +!!! note "_Global State_ Formally Defined" + + The **global state** of a protocol given by the above is a pair $\langle S, C \rangle$, where + + - $S$ is an $N$-tuple of states $\langle s_1,\dots,s_N \rangle$ with + each $s_i$ representing the current state of process $i$. + + - $C$ is an $N^2$-tuple + $\langle c_{1,1},\dots, c_{1,N}, c_{2,1}, \dots \dots, c_{N,N} \rangle$, + where each $c_{i,j}$ is a sequence of messages from $M_{i,j}$. The + message sequence $c_{i,j}$ represents the contents of the channel + from process $i$ to $j$. (Note that $c_{i,j}$ is empty when $i = j$ + since processes are presumed to not communicate with themselves.) + +We detail each of these below or in subsequent pages: + +- $N$ [below](#number-of-processes) +- ${ \langle S_i \rangle}^N_{i=1}$, and ${ \langle o_i \rangle }^N_{i=1}$ in [States](states.md), +- ${ \langle M_{i,j} \rangle }^N_{i,j=1}$ in [Message Types](messages.md), +- ${ succ }$ in [Transition Functions](transitions.md) + +## Number of Processes + +The processes we are concerned with represent the different Participants +in their roles (Finder, Vendor, Coordinator, Deployer, and Other). Each +Participant has their own process, but Participants might take on +multiple roles in a given case. + +!!! note "_Number of Processes_" + + The total number of processes $N$ is simply the count of unique Participants. + + $$N = |Participants| = | Reporters \cup Vendors \cup Coordinators \cup Deployers \cup Others |$$ + + diff --git a/docs/reference/formal_protocol/messages.md b/docs/reference/formal_protocol/messages.md new file mode 100644 index 00000000..c8c5d3fb --- /dev/null +++ b/docs/reference/formal_protocol/messages.md @@ -0,0 +1,262 @@ +# Message Types + +{% include-markdown "../../includes/normative.md" %} + +In [States](states.md), we identified four main roles in the +MPCVD process: + +- Finder/Reporter +- Vendor +- Coordinator +- Deployer + +Here we will examine the messages passed between them. +Revisiting the definitions from the [Formal Protocol Introduction](index.md): + +!!! note "Formalism" + + $\langle M_{ij} \rangle_{i,j=1}^N$ are $N^2$ disjoint finite sets with + $M_{ii}$ empty for all $i$: $M_{ij}$ represents the messages that can + be sent from process $i$ to process $j$. + +The message types in the Vultron Protocol arise primarily from the following principle taken directly from the +[CVD Guide](https://vuls.cert.org/confluence/display/CVD/2.3.+Avoid+Surprise): + +!!! quote "Avoid Surprise" + + As with most situations in which multiple + parties are engaged in a potentially stressful and contentious + negotiation, surprise tends to increase the risk of a negative + outcome. The importance of clearly communicating expectations across + all parties involved in a CVD process cannot be overemphasized. If we + expect cooperation between all parties and stakeholders, we should do + our best to match their expectations of being "in the loop" and + minimize their surprise. Publicly disclosing a vulnerability without + coordinating first can result in panic and an aversion to future + cooperation from Vendors and Finders alike. CVD promotes continued + cooperation and increases the likelihood that future vulnerabilities + will also be addressed and remedied. + +Now we condense that principle into the following protocol +recommendation: + +!!! note "" + + Participants whose state changes in the RM, EM, or CVD State Models SHOULD send a message to + other Participants for each transition. + +If you are looking for a one-sentence summary of the entire Vultron Protocol, that was it. + +!!! note inline end "State Transitions" + + - RM state transitions $\Sigma^{rm} = \{ r,v,a,i,d,c\}$ + - EM state transitions $\Sigma^{em} = \{ p,a,r,t\}$ + - CVD state transitions + $\Sigma^{cs} = \{\mathbf{V},\mathbf{F},\mathbf{D},\mathbf{P},\mathbf{X},\mathbf{A}\}$ + +As a reminder, those transitions are shown at right. + +We will address the specific circumstances when each message should be emitted in +[Transitions](transitions.md), but first we need to +introduce the message types this recommendation implies. +We cover messages associated with each state model, in turn, below, concluding the section with a few message types not +directly connected to any particular state model. + +## RM Message Types + +!!! tip inline end "Finders have hidden states" + + As we discuss in [RM Interactions](../../topics/process_models/rm/rm_interactions.md#the-secret-lives-of-finders), + the Finder's states $q^{rm} \in \{R,I,V\}$ are not observable to the CVD process because Finders start + coordination only when they have already reached $q^{rm} = A$. + +With the exception of the Finder/Reporter, each Participant's involvement in a CVD case starts with the receipt of a +report from another Participant who is already in the $Accepted$ ($q^{rm} \in A$) state. +The remainder of a Participant's RM process is largely independent of the other Participants' RM processes. +Therefore, the RM message types are primarily used to inform other Participants of the sender's state. + + +--- + +| Message Type | Name | Description | +|:------------:| --- |----------------------------------------------------------------------------------------| +| $RS$ | Report Submission | A message from one Participant to a new Participant containing a vulnerability report. | +| $RI$ | Report Invalid | A message indicating the Participant has designated the report as invalid. | +| $RV$ | Report Valid | A message indicating the Participant has designated the report as valid. | +| $RD$ | Report Deferred | A message indicating the Participant is deferring further action on a report. | +| $RA$ | Report Accepted | A message indicating the Participant has accepted the report for further action. | +| $RC$ | Report Closed | A message indicating the Participant has closed the report. | +| $RK$ | Report Acknowledgement | A message acknowledging the receipt of any RM message listed above. | +| $RE$ | Report Error | A message indicating a Participant received an unexpected RM message. | + + +A summary of the RM message types is shown below. + +!!! note "RM Message Types" + + $$M^{rm} = \{RS,RI,RV,RD,RA,RC,RK,RE\}$$ + +All state changes are from the Participant's (sender's) perspective, not the recipient's perspective. +We will see in [Transitions](transitions.md) that the receipt of a *Report Submission* is the +only message whose *receipt* directly triggers an RM state change in the receiver. +All other RM messages are used to convey the sender's status. + +!!! note "" + + Participants SHOULD act in accordance with their own policy and process in deciding when to transition states in the + RM model. + +!!! note "" + + Participants SHOULD NOT mark duplicate reports as invalid. + +!!! note "" + + Instead, duplicate reports SHOULD pass through $Valid$ ($q^{rm} \in V$), although they MAY be subsequently + (immediately or otherwise) deferred ($q^{rm} \in V \xrightarrow{d} D$) in favor of the original. + +!!! note "" + + Participants SHOULD track the RM states of the other Participants in the case. + +An example object model for such tracking is described in [Case Object](../../howto/case_object.md). +Furthermore, while these messages are expected to inform the receiving Participant's choices in their own RM process, +this protocol intentionally does not specify any other recipient RM state changes upon receipt of an RM message. + +## EM Message Types + +Whereas the RM process is unique to each Participant, the EM process is global to the case. +Therefore, we begin with the list of message types a Participant SHOULD emit when their EM state changes. + +| Message Type | Name | Description | +|:------------:| --- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| $EP$ | Embargo Proposal | A message containing proposed embargo terms (e.g., date/time of expiration). | +| $ER$ | Embargo Proposal Rejection | A message indicating the Participant has rejected an embargo proposal. | +| $EA$ | Embargo Proposal Acceptance | A message indicating the Participant has accepted an embargo proposal. | +| $EV$ | Embargo Revision Proposal | A message containing a proposed revision to embargo terms (e.g., date/time of expiration). | +| $EJ$ | Embargo Revision Rejection | A message indicating the Participant has rejected a proposed embargo revision. | +| $EC$ | Embargo Revision Acceptance | A message indicating the Participant has accepted a proposed embargo revision. | +| $ET$ | Embargo Termination | A message indicating the Participant has terminated an embargo (including the reason for termination). Note that an *Embargo Termination* message is intended to have immediate effect. | +| $EK$ | Embargo Acknowledgement | A message acknowledging receipt of any of the above EM message types. | +| $EE$ | Embargo Error | A message indicating a Participant received an unexpected EM message. | + +!!! note "" + If an early termination is desired but the termination date/time is in the future, this SHOULD be achieved through + an *Embargo Revision Proposal* and additional communication as necessary to convey the constraints on the proposal. + +A summary of the EM message types is shown below. + +!!! note "EM Message Types" + + $$M^{em} = \{EP,ER,EA,EV,EJ,EC,ET,EK,EE\}$$ + +## CS Message Types {#sec:cs_message_types} + +From the [CS process model](../../topics/process_models/cs/index.md), the following is the list of messages associated with CS state +changes: + +| Message Type | Name | Description | +|:------------:| --- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| $CV$ | Vendor Awareness | A message to other Participants indicating that a report has been delivered to a specific Vendor. Note that this is an announcement of a state change for a Vendor, not the actual report to the Vendor, which is covered in the *Report Submission* ($RS$) above. | +| $CF$ | Fix Readiness | A message from a Participant (usually a Vendor) indicating that a specific Vendor has a fix ready. | +| $CD$ | Fix Deployed | A message from a Participant (usually a Deployer) indicating that they have completed their fix deployment process. This message is expected to be rare in most MPCVD cases because Deployers are rarely included in the coordination effort. | +| $CP$ | Public Awareness | A message from a Participant indicating that they have evidence that the vulnerability is known to the public. This message might be sent after a Participant has published their own advisory or if they have observed public discussion of the vulnerability. | +| $CX$ | Exploit Public | A message from a Participant indicating that they have evidence that an exploit for the vulnerability is publicly available. This message might be sent after a Participant has published their own exploit code, or if they have observed exploit code available to the public. | +| $CA$ | Attacks Observed | A message from a Participant indicating that they have evidence that attackers are exploiting the vulnerability in attacks. | +| $CK$ | CS Acknowledgement | A message acknowledging receipt of any of the above CS message types. | +| $CE$ | CS Error | A message indicating a Participant received an unexpected CS message. | + +!!! note "" + **Vendor Awareness** ($CV$) messages SHOULD be sent only by Participants with direct knowledge of the notification (i.e., + either by the Participant who sent the report to the Vendor or by the Vendor upon receipt of the report). + + + +A summary of the CS message types is shown below. + +!!! note "CS Message Types" + + $$M^{cs} = \{CV,CF,CD,CP,CX,CA,CK,CE \}$$ + +## Other Message Types {#sec:gen_message_types} + +Finally, there are a few additional message types required to tie the coordination process together. +Most of these message types are *not* associated with a specific state change, although they might trigger activities or +events that could cause a state change in a Participant (and therefore trigger one or more of the above message types to +be sent). + +| Message Type | Name | Description | +|:------------:| --- |-------------------------------------------------------------------------------------------------------------| +| $GI$ | General Inquiry | A message from a Participant to one or more other Participants to communicate non-state-change information. | +| $GK$ | General Acknowledgement | A message from a Participant indicating their receipt of a GI message. | +| $GE$ | General Error | A message indicating a general error has occurred. | + + +Examples of general inquiry messages include but are not limited to + +- asking or responding to a question +- requesting an update on a Participant's status +- requesting review of a draft publication +- suggesting a potential Participant to be added to a case +- coordinating other events +- resolving a loss of Participant state synchronization + +A summary of the General message types is shown below. + +!!! note "General Message Types" + + $$M^{*} = \{ GI,GK,GE \}$$ + +## Message Type Redux + +Thus, the complete set of possible messages between processes is +$M_{i,j} = M^{rm} \cup M^{em} \cup M^{cs} \cup M^{*}$. +For convenience, we collected these into the table below. + +| Process Model | $M_{i,j}$ | Message Type | Emit When | +| :---: | :---: | --- | | +| RM | $RS$ | Report Submission | sender $\in A$ | +| RM | $RI$ | Report Invalid | $R \xrightarrow{i} I$ | +| RM | $RV$ | Report Valid | $\{R,I\} \xrightarrow{v} V$ | +| RM | $RD$ | Report Deferred | $\{V,A\} \xrightarrow{d} D$ | +| RM | $RA$ | Report Accepted | $\{V,D\} \xrightarrow{a} A$ | +| RM | $RC$ | Report Closed | $\{I,D,A\} \xrightarrow{c} C$ | +| RM | $RK$ | Report Acknowledgement | any valid RM message | +| RM | $RE$ | Report Error | any unexpected RM message | +| EM | $EP$ | Embargo Proposal | $\{N,P\} \xrightarrow{p} P$ | +| EM | $ER$ | Embargo Proposal Rejection | $P \xrightarrow{r} N$ | +| EM | $EA$ | Embargo Proposal Acceptance | $P \xrightarrow{a} A$ | +| EM | $EV$ | Embargo Revision Proposal | $A \xrightarrow{p} R$ | +| EM | $EJ$ | Embargo Revision Rejection | $R \xrightarrow{r} A$ | +| EM | $EC$ | Embargo Revision Acceptance | $R \xrightarrow{a} A$ | +| EM | $ET$ | Embargo Termination | $\{A,R\} \xrightarrow{t} X$ | +| EM | $EK$ | Embargo Acknowledgement | any valid EM message | +| EM | $EE$ | Embargo Error | any unexpected EM message | +| CS | $CV$ | Vendor Awareness | $vfd \cdot\cdot\cdot \xrightarrow{\mathbf{V}} Vfd \cdot\cdot\cdot$ | +| CS | $CF$ | Fix Readiness | $Vfd \cdot\cdot\cdot \xrightarrow{\mathbf{F}} VFd \cdot\cdot\cdot$ | +| CS | $CD$ | Fix Deployed | $VFd \cdot\cdot\cdot \xrightarrow{\mathbf{D}} VFD \cdot\cdot\cdot$ | +| CS | $CP$ | Public Awareness | $\cdot\cdot\cdot p \cdot\cdot \xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot$ | +| CS | $CX$ | Exploit Public | $\cdot\cdot\cdot\cdot x \cdot \xrightarrow{\mathbf{X}} \cdot\cdot\cdot\cdot X \cdot$ | +| CS | $CA$ | Attacks Observed | $\cdot\cdot\cdot\cdot\cdot a \xrightarrow{\mathbf{A}} \cdot\cdot\cdot\cdot\cdot A$ | +| CS | $CK$ | CS Acknowledgement | any valid CS message | +| CS | $CE$ | CS Error | any unexpected CS message | +| * | $GI$ | General Inquiry | any time | +| * | $GK$ | General Acknowledgement | any valid GI message | +| * | $GE$ | General Error | any unexpected GI message | + +!!! note "Message Types Formally Defined" + + $$ M_{i,j} = + \left\{ + \begin{array}{l} + RS,RI,RV,RD,RA,RC,RK,\\ + RE,EP,ER,EA,EV,EJ,EC,\\ + ET,EK,EE,CV,CF,CD,CP,\\ + CX,CA,CK,CE,GI,GK,GE\\ + \end{array} + \right\}\textrm{ where $i \neq j$; $\varnothing$ otherwise; for $i,j \leq N$}$$ + + +Message _formats_ are left as [future work](../../topics/future_work/index.md). + + diff --git a/docs/reference/formal_protocol/states.md b/docs/reference/formal_protocol/states.md new file mode 100644 index 00000000..6ee28892 --- /dev/null +++ b/docs/reference/formal_protocol/states.md @@ -0,0 +1,928 @@ +# States {#sec:protocol_states} + +{% include-markdown "../../includes/normative.md" %} + +Each Participant in an MPCVD case has a corresponding RM state, an EM state, and an overall CS state. +Therefore, we can represent a Participant's state as a triple comprising the state of each of these models. + +!!! note "_Participant State_" + + A Participant's state is a triple comprising the state of each of the RM, EM, and CS models. + + $$q_{Participant} = (q^{rm},q^{em},q^{cs})$$ + +Good Participant situation awareness makes for good CVD decision making. + +!!! note "" + + Participants SHOULD track the state of other Participants in a case + to inform their own decision making as it pertains to the case. + +Elsewhere, we provide an example [Case Object](../../howto/case_object.md) model to facilitate such tracking. +However, the protocol we are developing is expected to function even when incomplete information is available to +any given Participant. + +!!! note "" + + Adequate operation of the protocol MUST NOT depend on perfect information across all Participants. + +A generic state model for a CVD Participant can be composed from the Cartesian product of $\mathcal{Q}^{rm}$, +$\mathcal{Q}^{em}$, and $\mathcal{Q}^{cs}$ as shown below. + +!!! note "_Participant State Space_" + + A Participant's state is a triple comprising the state of each of the RM, EM, and CS models. + The set of all possible Participant states is the Cartesian product of the RM, EM, and CS state sets. + + $$ S_i + % = \mathcal{Q}^{rm} \times \mathcal{Q}^{em} \times \mathcal{Q}^{cs} + = + \underbrace{ + \begin{bmatrix} + S \\ + R \\ + I \\ + V \\ + D \\ + A \\ + C \\ + \end{bmatrix} + }_{\mathcal{Q}^{rm}} + \times + % embargo state + \underbrace{ + \begin{bmatrix} + N \\ + P \\ + A \\ + R \\ + X \\ + \end{bmatrix} + }_{\mathcal{Q}^{em}} + \times + % case state + \underbrace{ + \begin{bmatrix} + \begin{bmatrix} + \varnothing \\ + vfd \\ + Vfd \\ + VFd \\ + VFD \\ + \end{bmatrix} + \times + \begin{bmatrix} + p \\ + P + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + X + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A + \end{bmatrix} + \end{bmatrix} + }_{\mathcal{Q}^{cs}}$$ + +Note that the above definition splits the case state +($\mathcal{Q}^{cs}$) into chunks corresponding to the Vendor fix path +($vfd \xrightarrow{\mathbf{V}} Vfd \xrightarrow{\mathbf{F}} VFd \xrightarrow{\mathbf{D}} VFD$) +and the public-exploit-attack ($pxa \xrightarrow{\dots} PXA$) sub-models +from the [Case State Model](../../topics/process_models/cs/index.md). +This is done for two reasons. +First, it gives us a more compact notation to represent the 32 states of the CS model. +Second, as described in [Model Interactions](../../topics/process_models/model_interactions/index.md), it highlights the fact that +the Vendor fix path represents the state of an individual Participant, whereas the public-exploit-attack sub-model +represents facts about the world at large. +Because not all Participants +are Vendors or Deployers, Participants might not have a corresponding +state on the $vfd \xrightarrow{} VFD$ axis. Therefore, we add a null +element $\varnothing$ to the set of states representing the Vendor fix +path. + +Thus, one might conclude that a total of 1,400 states is possible for each Participant. + +!!! note "Participant State Space Size" + + $$ | S_i | = + % actor rm state + | \mathcal{Q}^{rm} | \cdot + % embargo state + | \mathcal{Q}^{em} | \cdot + % case state + | \mathcal{Q}^{cs} | + % multiply + = 7 \cdot 5 \cdot (5 \cdot 2 \cdot 2 \cdot 2) = 1400$$ + +However, this dramatically overstates the possibilities for individual CVD Participant Roles because many of these +states will be unreachable to individual Participants. +In the remainder of this section, we detail these differences. + +## Unreachable States + +For any Participant, the RM $Closed$ state implies that the EM and CVD Case states do +not matter. +Similarly, for any Participant, the RM $Start$ state represents a case that the +Participant doesn't even know about yet. +Therefore, the $Start$ state also implies that the EM and CVD Case states do not matter. +We use $*$ to represent the "don't care" value. + +???+ note "Unreachable EM and CS States when RM is in _Closed_ or _Start_" + + $$q^{rm} \in \{S,C\} \implies (q^{em} \in *) \cup (q^{cs} \in *)$$ + +A public exploit implies the vulnerability is public as well. In other +words, $q^{cs} \in \cdot\cdot\cdot pX \cdot$ is an ephemeral state that resolves +quickly to $q^{cs} \in \cdot\cdot\cdot PX \cdot$. (As a reminder, dots ($\cdot$) +in CVD case state notation indicate single-character wildcards.) + +???+ note "Unreachable CS States when CS is in _Public_ or _Exploit_" + + $$q^{cs} \in \cdot\cdot\cdot pX \cdot \implies q^{cs} \in \cdot\cdot\cdot PX \cdot$$ + +Furthermore, when a vulnerability becomes public, the EM state no longer matters. + +???+ note "Unreachable EM States when CS is in _Public_" + + $$q^{cs} \in \cdot\cdot\cdot PX \cdot \implies q^{em} \in *$$ + +Taken together, we can modify our state model to reflect these limitations. +The result is shown below. + +!!! note "Participant States With Unreachable States Removed" + + $$ S_i + % = \mathcal{Q}^{rm} \times \mathcal{Q}^{em} \times \mathcal{Q}^{cs} + = + \begin{cases} + (S, *, *)\\ + {}\\ + \begin{bmatrix} + R \\ + I \\ + V \\ + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + N \\ + P \\ + A \\ + R \\ + X \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + \varnothing \\ + vfd \\ + Vfd \\ + VFd \\ + VFD \\ + \end{bmatrix} + \times + \begin{bmatrix} + p \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \\ + {} \\ + \begin{bmatrix} + R \\ + I \\ + V \\ + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + * \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + \varnothing \\ + vfd \\ + Vfd \\ + VFd \\ + VFD \\ + \end{bmatrix} + \times + \begin{bmatrix} + P + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + X + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A + \end{bmatrix} + \end{bmatrix} \\ + {}\\ + (C, *, *) \\ + \end{cases}$$ + +This means that each Participant must be in one of 352 possible states. + +!!! note "Participant State Space Size With Unreachable States Removed" + + $$\begin{split} + |S_i| &= 1 + \big(5 \cdot 5 \cdot (5 \cdot 1 \cdot 1 \cdot 2)\big) + \big(5 \cdot 1 \cdot (5 \cdot 1 \cdot 2 \cdot 2\big) + 1 \\ + % &= 2 + 250 + 100 + &= 352 + \end{split}$$ + +## Vendors (Fix Suppliers) + +Vendors are the sole providers of fixes. +Therefore, they are the only Participants in a CVD case for which the $Vfd \xrightarrow{\mathbf{F}} VFd \xrightarrow{\mathbf{D}} VFD$ +path is possible. +Furthermore, since they are Vendors by definition, they do not have access to the $vfd$ state or the $\varnothing$ +state that was just added. +As a Vendor has a report in $Received$, it is, by definition, at least in the $Vfd$ case state. + +Vendors create fixes only when they are in the $Accepted$ RM state. +Because the $Received$, $Invalid$, and $Valid$ states come strictly *before* the $Accepted$ state in the RM DFA, +there is no way for the Vendor to be in either $VFd$ or $VFD$ while in any of those states. + +???+ note "Vendor CS States When RM is in _Received_, _Invalid_, or _Valid_" + + $$q^{rm}_{Vendor} \in \{R,I,V\} \implies q^{cs}_{Vendor} \in Vfd\cdot\cdot\cdot$$ + +Vendors with the ability to deploy fixes themselves have access to three states in the fix path: $\{Vfd,~VFd,~VFD\}$. +However, this is not always the case. +Vendor Participants without a deployment capability can only create fixes, limiting them to the middle two states in +the fix path: $\{Vfd,~VFd\}$. +Additional discussion of the distinction between Vendors with and without a deployment capability can be found in [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513). + +We apply these caveats to the generic model above to arrive at a Vendor state shown below. + +!!! note "Vendor Participant State Space" + + $$ S_{i_{Vendor}} = + \begin{cases} + (S, *, *)\\ + {}\\ + \begin{bmatrix} + R \\ + I \\ + V \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + N \\ + P \\ + A \\ + R \\ + X \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + Vfd \\ + \end{bmatrix} + \times + \begin{bmatrix} + p \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{unprioritized, maybe embargoed} \\ + {}\\ + \begin{bmatrix} + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + N \\ + P \\ + A \\ + R \\ + X \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + Vfd \\ + VFd \\ + VFD^{\dagger} \\ + \end{bmatrix} + \times + \begin{bmatrix} + p \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + % \begin{bmatrix} + % pxa \\ + % pxA \\ + % pXa \\ + % pXA \\ + % \end{bmatrix} + \end{bmatrix} \textrm{prioritized, maybe embargoed} \\ + {} \\ + \begin{bmatrix} + R \\ + I \\ + V \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + * \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + Vfd \\ + \end{bmatrix} + \times + \begin{bmatrix} + P \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + X \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{unprioritized, embargo irrelevant} \\ + {} \\ + \begin{bmatrix} + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + * \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + Vfd \\ + VFd \\ + VFD^{\dagger}\\ + \end{bmatrix} + \times + \begin{bmatrix} + P \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + X \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{prioritized, embargo irrelevant} \\ + {}\\ + (C, *, *) \\ + \end{cases}$$ + +The $\dagger$ on $VFD$ in the above indicates that the $VFD$ state is accessible only to Vendors with a deployment capability. +As tallied below, there are 128 possible states for a Vendor with deployment capability and 100 for those without. + +!!! note "Vendor State Space Size" + + With deployment capability: + + $$ \begin{split} + |S_{i_{\frac{Vendor}{Deployer}}}| = & 1 + \big(3 \cdot 5 \cdot (1 \cdot 1 \cdot 1 \cdot 2)\big) + \big(2 \cdot 5 \cdot (3 \cdot 1 \cdot 1 \cdot 2)\big) \\ + & + \big(3 \cdot 1 \cdot (1 \cdot 1 \cdot 2 \cdot 2)\big) + \big(2 \cdot 1 \cdot (3 \cdot 1 \cdot 2 \cdot 2)\big) + 1 \\ + % = & 2 + 30 + 60 + 12 + 24 \\ + = & 128 \\ + \end{split}$$ + + Without deployment capability: + + $$ \begin{split} + |S_{i_{Vendor}}| = & 1 + \big(3 \cdot 5 \cdot (1 \cdot 1 \cdot 1 \cdot 2)\big) + \big(2 \cdot 5 \cdot (2 \cdot 1 \cdot 1 \cdot 2)\big) \\ + & + \big(3 \cdot 1 \cdot (1 \cdot 1 \cdot 2 \cdot 2)\big) + \big(2 \cdot 1 \cdot (2 \cdot 1 \cdot 2 \cdot 2)\big) + 1 \\ + % = & 2 + 30 + 40 + 12 + 16 \\ + = & 100 \\ + \end{split}$$ + +## Non-Vendor Deployers + +We just explained that not all Vendors are Deployers. +Likewise, not all Deployers are Vendors. +Most CVD cases leave Non-Vendor Deployers entirely out of the CVD process, so their appearance is expected to be rare in +actual cases. +However, there are scenarios when an MPCVD case may include Non-Vendor Deployers, such as when a vulnerability in some +critical infrastructure component is being handled or when the Vultron Protocol is used in the context of a Vulnerability +Disclosure Program (VDP). +These Non-Vendor Deployers participate only in the $d \xrightarrow{\mathbf{D}} D$ transition on the fix path. +Similar to the [Vendor](#vendors-fix-suppliers) scenario above, it is expected that Deployers actually deploy fixes only when they are in the +RM $Accepted$ state (implying their intent to deploy). +Therefore, their set of possible states is even more restricted than Vendors, as shown below. + +!!! note "Non-Vendor Deployer Participant State Space" + $$ S_{i_{Deployer}} = + \begin{cases} + (S, *, *)\\ + {}\\ + \begin{bmatrix} + R \\ + I \\ + V \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + N \\ + P \\ + A \\ + R \\ + X \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + d \\ + \end{bmatrix} + \times + \begin{bmatrix} + p \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{unprioritized, maybe embargoed} \\ + {}\\ + \begin{bmatrix} + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + N \\ + P \\ + A \\ + R \\ + X \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + d \\ + D \\ + \end{bmatrix} + \times + \begin{bmatrix} + p \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix}\textrm{prioritized, maybe embargoed} \\ + {} \\ + \begin{bmatrix} + R \\ + I \\ + V \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + * \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + d \\ + \end{bmatrix} + \times + \begin{bmatrix} + P \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + X \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{unprioritized, embargo irrelevant} \\ + {} \\ + \begin{bmatrix} + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + * \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + d \\ + D \\ + \end{bmatrix} + \times + \begin{bmatrix} + P \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + X \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{prioritized, embargo irrelevant} \\ + {}\\ + (C, *, *) \\ + \end{cases}$$ + +Thus, Non-Vendor Deployers can be expected to be in 1 of 100 possible +states, as we show next. + +!!! note "Non-Vendor Deployer State Space Size" + $$ \begin{split} + |S_{i_{Deployer}}| = & 1 + \big(3 \cdot 5 \cdot (1 \cdot 1 \cdot 1 \cdot 2)\big) + \big(2 \cdot 5 \cdot (2 \cdot 1 \cdot 1 \cdot 2)\big) \\ + & + \big(3 \cdot 1 \cdot (1 \cdot 1 \cdot 2 \cdot 2)\big) + \big(2 \cdot 1 \cdot (2 \cdot 1 \cdot 2 \cdot 2)\big) + 1 \\ + % = & 2 + 30 + 40 + 12 + 16 \\ + = & 100 \\ + \end{split}$$ + +## Non-Vendor, Non-Deployer Participants + +Finally, CVD cases often involve Participants who are neither Vendors nor Deployers. +Specifically, Finder/Reporters fall into this category, as do Coordinators. +Other roles, as outlined in the [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD), +could be included here as well. +Because they do not participate directly in the Vendor fix path, these Non-Vendor, Non-Deployer CVD Participants fall +into the $\varnothing$ case substate we added above. +Their state model is shown below. + +!!! note "Non-Vendor, Non-Deployer Participant State Space" + + $$ S_{i_{Other}} = + \begin{cases} + (S,*,*) \\ + {} \\ + \begin{bmatrix} + R \\ + I \\ + V \\ + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + N \\ + P \\ + A \\ + R \\ + X \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + \varnothing + \end{bmatrix} + \times + \begin{bmatrix} + p \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{ maybe embargoed}\\ + {}\\ + \begin{bmatrix} + R \\ + I \\ + V \\ + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + * \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + \varnothing + \end{bmatrix} + \times + \begin{bmatrix} + P \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + X \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{ embargo irrelevant} \\ + {} \\ + (C,*,*) \\ + \end{cases}$$ + +Non-Vendor Non-Deployer CVD Participants (Finder/Reporters, Coordinators, etc.) will be in 1 of 72 states, as calculated +below. + +!!! note "Non-Vendor, Non-Deployer Participant State Space Size" + + $$ \begin{split} + |S_{i_{Other}}| = & 1 + \big(5 \cdot 5 \cdot (1 \cdot 1 \cdot 1 \cdot 2)\big) + \big(5 \cdot 1 \cdot (1 \cdot 1 \cdot 2 \cdot 2)\big) + 1 \\ + % = & 2 + 50 + 20\\ + = & 72 \\ + \end{split}$$ + +### Finder-Reporters + +As we discussed in [RM Interactions](../../topics/process_models/rm/rm_interactions.md#the-secret-lives-of-finders), +the early Finder states are largely hidden from view from other CVD Participants unless they choose to engage +in the CVD process in the first place. +Therefore, for a CVD protocol, we only need to care about Finder states once they have reached RM $Accepted$. +Coincidentally, this is also a convenient way to mark the transition from Finder to Reporter. + +!!! note "Finder-Reporter State Space" + + $$ S_{i_{Reporter}} = + \begin{cases} + (S,*,*) \textrm{(hidden)}\\ + (R,*,*) \textrm{(hidden)}\\ + (I,*,*) \textrm{(hidden)}\\ + (V,*,*) \textrm{(hidden)}\\ + {} \\ + \begin{bmatrix} + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + N \\ + P \\ + A \\ + R \\ + X \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + \varnothing + \end{bmatrix} + \times + \begin{bmatrix} + p \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{maybe embargoed} \\ + {}\\ + \begin{bmatrix} + D \\ + A \\ + \end{bmatrix} + \times + % embargo state + \begin{bmatrix} + * \\ + \end{bmatrix} + \times + % case state + \begin{bmatrix} + \begin{bmatrix} + \varnothing + \end{bmatrix} + \times + \begin{bmatrix} + P \\ + \end{bmatrix} + \times + \begin{bmatrix} + x \\ + X \\ + \end{bmatrix} + \times + \begin{bmatrix} + a \\ + A \\ + \end{bmatrix} + \end{bmatrix} \textrm{embargo irrelevant} \\ + {} \\ + (C,*,*) \\ + \end{cases}$$ + +Thus, for all practical purposes, we can ignore the hidden states in the above and conclude that Finders who go on to +become Reporters have only 29 possible states during a CVD case. + +!!! note "Finder-Reporter State Space Size" + $$ \begin{split} + |S_{i_{Reporter}}| = & \big(2 \cdot 5 \cdot (1 \cdot 1 \cdot 1 \cdot 2)\big) + \big(2 \cdot 1 \cdot (1 \cdot 1 \cdot 2 \cdot 2)\big) + 1 \\ + % = & 20 + 8 + 1 \\ + = & 29 \\ + \end{split}$$ + +## A Lower Bounds on MPCVD State Space + +!!! note inline end "Generic MPCVD State Space Size Formula" + + $$|S_{total}| = \prod_{i=1}^{N} |S_i|$$ + +Now we can touch on the lower bounds of the state space of an MPCVD case. +Generically, we would expect the state space for $N$ Participants to +take the form given at right. + + +The upper bound on the MPCVD state space is simply $352^N \approx 10^{2.55N}$. +However, because of the Role-specific limits just described, we already know that this overcounts the possible states +significantly. +We can do better still. +If we ignore transient states while Participants converge on a consistent view of the global state of a case, we can +drastically reduce the state space for an MPCVD case. +Why? +There are two reasons: + +1. Because they represent facts about the outside world, the eight + $\cdot\cdot\cdot pxa \rightarrow \cdot\cdot\cdot PXA$ CS substates are global to the case, not + to individual Participants. This means all Participants should + rapidly converge to the same substate. + +2. Similarly, the five EM states are also global to the case and should converge rapidly. + +Given these two observations, we can pull those Participant-agnostic terms out of the state calculations for individual Participants, + +!!! note "MPCVD State Space With Participant-Agnostic Terms Factored Separately" + + $$|S_{total}| = \prod_{i=1}^{N} |S_i| = |S_{global}| \times \prod_{i=1}^{N} |S_{Participant}|$$ + + where + + $$ |S_{global}| = 8 \times 5 = 40 $$ + +which leaves + +!!! note "Participant-Specific State Spaces" + + $$|S_{Participant}| = + \begin{cases} + Reporter = 1 + 2 = 3 \\ + Vendor = 2 + 3 + (2 \cdot 2) + 3 + (2 \cdot 2 ) = 16 \\ + Vendor/Deployer = 2 + 3 + (2 \cdot 3) + 3 + (2 \cdot 3) = 20 \\ + Coordinator = 2 + 5 = 7 \\ + Deployer = 2 + 3 = 5\\ + Others = 2 + 5 = 7 \\ + \end{cases}$$ + +So our state space looks like + +!!! note "MPCVD State Space Size Formula" + + $$\begin{split} + |S_{total}| = 40 & \times + 3^{N_{Reporter}} \times + 16^{N_{Vendor}} \times + 20^{N_{\frac{Vendor}{Deployer}}} \\ + & \times + 7^{N_{Coordinator}} \times + 5^{N_{Deployer}} \times + 7^{N_{Other}} \\ + \end{split}$$ + +With these values in mind, we see that + +- A two-party (Finder-Vendor) case might have a lower bound state space of $40 \times 3 \times 16 = 1,920$ states. + +- A case like Meltdown/Spectre (with six Vendors and no Coordinators) might have $40 \times 3 \times 16^{6} \approx 10^{9}$ states. + +- A large, but not atypical, 200-Vendor case handled by the CERT/CC might have + $40 \times 3 \times 16^{200} \times 7 \approx 10^{244}$ possible configurations. + +- In the case of the log4j vulnerability [CVE-2021-44228](https://www.kb.cert.org/vuls/id/930724) in December + 2021, the CERT/CC notified around 1,600 Vendors after the vulnerability had been made public. Had this been an + embargoed disclosure, the case would have a total state space around $10^{2000}$. + +That said, while these are dramatic numbers, the reader is reminded that the whole point of the Vultron Protocol is to +*coordinate* the process so that it is not just hundreds or thousands of Participants behaving randomly. + +## Starting States + +Each Participant begins a case in the state where the report management +process is in the start state, there is no embargo in place, and the +case has not made any progress. + +!!! note "Participant Start State Formally Defined" + + $$o_i = (o_i^{rm},~o_i^{em},~o_i^{cs}) = (S,N,vfdpxa)$$ + +Following the discussion above, the starting states for Vendors, +Deployers, and other Participants are shown below. + +!!! note "Participant Start States" + + | Participant Role | Start State ($o_i$)| + |------------------|-------------| + | Vendor | $(S,N,vfdpxa)$ | + | Deployer | $(S,N,dpxa)$ | + | Other | $(S,N,pxa)$ | + | Finder/Reporter | $(A,N,pxa)$ | + + +For a case to really begin, the Finder must at least reach the $A$ state. +Therefore, at the point when a second party finds out about the vulnerability from a Finder, +the Finder/Reporter is presumed to be already at $q_{Finder}=(A, N, pxa)$. + +We will show in [Transitions](transitions.md) how this plays out. +But first, we need to define the message types that can be exchanged between Participants. diff --git a/docs/reference/formal_protocol/transitions.md b/docs/reference/formal_protocol/transitions.md new file mode 100644 index 00000000..9927eb11 --- /dev/null +++ b/docs/reference/formal_protocol/transitions.md @@ -0,0 +1,397 @@ +# Transition Functions {#sec:protocol_transition_functions} + +{% include-markdown "../../includes/normative.md" %} + +In this section, we describe the transition functions for the RM, EM, and CVD Case processes, respectively. +Note that while the RM process is largely independent of the other two process models, the EM and CVD process models +have some noteworthy interactions, which we will cover in detail. + +Revisiting the formal protocol definition from the [introduction](index.md): + +!!! note "Transition Function Defined" + + $succ$ is a partial function mapping for each $i$ and $j$, + + $$S_i \times M_{ij} \rightarrow S_i \textrm{ and } S_i \times M_{ji} \rightarrow S_i$$ + + $succ(s,x)$ is the state entered after a process transmits or receives + message $x$ in state $s$. It is a transmission if $x$ is from $M_{ij}$ + and a reception if $x$ is from $M_{ji}$. + + +!!! tip "Notation Conventions on this Page" + + - By convention, CS states are labeled in the order $vfdpxa$. + - Participant state is a tuple of the individual CS, RM, and EM states $S_i = (q^{cs}, q^{rm}, q^{em})$. + - Dots ($\cdot$) in states indicate single wildcards. For example, $Vfd \cdot \cdot \cdot$ includes $Vfdpxa, VfdPxA, VfdPXA, etc.$ + - Asterisks ($*$) indicate arbitrary wildcards. + - Dashes ($−$) indicate no state change. + - Left-harpoons ($\leftharpoondown$) indicate a message received. + - Right-harpoons ($\rightharpoonup$) indicate a message sent. + + +## RM Transition Functions + +Because it only reflects an individual Participant's report handling status, +the RM process operates largely independent of both the EM and CS processes. +Otherwise, + +!!! note "" + + Participants MUST be in RM $Accepted$ to send a report ($RS$) to + someone else. + +!!! note "" + + Participants SHOULD send $RI$ when the report validation process + ends in an $invalid$ determination. + +!!! note "" + + Participants SHOULD send $RV$ when the report validation process + ends in a $valid$ determination. + +!!! note "" + + Participants SHOULD send $RD$ when the report prioritization process + ends in a $deferred$ decision. + +!!! note "" + + Participants SHOULD send $RA$ when the report prioritization process + ends in an $accept$ decision. + +!!! note "" + + Participants SHOULD send $RC$ when the report is closed. + +!!! note "" + + Participants SHOULD send $RE$ regardless of the state when any error + is encountered. + +!!! note "" + + Recipients MAY ignore messages received on $Closed$ cases. + +!!! note "" + + Recipients SHOULD send $RK$ in acknowledgment of any $R*$ message + except $RK$ itself. + +!!! note "" + + Vendor Recipients should send both $CV$ and $RK$ in response to a + report submission ($RS$). If the report is new to the Vendor, it + MUST transition $q^{cs} \xrightarrow{\mathbf{V}}Vfd\cdot\cdot\cdot$. + +!!! note "" + + Any $R*$ message, aside from $RS$, received by recipient in + $q^{rm} \in S$ is an error because it indicates the sender thought + the receiver was aware of a report they had no knowledge of. The + Recipient SHOULD respond with both an $RE$ to signal the error and + $GI$ to find out what the sender expected. + +!!! note "" + + Recipients SHOULD acknowledge $RE$ messages ($RK$) and inquire + ($GI$) as to the nature of the error. + +!!! note inline end "RM Messages Sent and State Transitions" + + $$S_i \times M_{ij}^{rm} \rightarrow S_i$$ + +### RM Messages Sent and State Transitions + +The table below lists each RM message type and the states in which that message is appropriate to send along with the +corresponding sender state transition. + + +| Sender Preconditions
$s_n \in S_i$
$q^{cs},q^{rm},q^{em}$ | Transition
$(s_n \xrightarrow{} s_{n+1})$
$q^{cs},q^{rm},q^{em}$ | Message Type
$\rightharpoonup$
$M_{ij}$ | +|:-----------------------------------------------------------------:|:------------------------------------------------------------------------:|:-------------------------------------------------------:| +| $*,A,*$ | $-, -, -$ | $RS$ | +| $*,\{R,V\},*$ | $-, \xrightarrow{i} I, -$ | $RI$ | +| $*,\{R,I\},*$ | $-, \xrightarrow{v} V, -$ | $RV$ | +| $*,\{V,A\},*$ | $-, \xrightarrow{d} D, -$ | $RD$ | +| $*,\{V,D\},*$ | $-, \xrightarrow{a} A, -$ | $RA$ | +| $*,\{I,D,A\},*$ | $-, \xrightarrow{c} C, -$ | $RC$ | +| $*,*,*$ | $-, -, -$ | $RE$ | +| $*,*,*$ | $-, -, -$ | $RK$ | + + +!!! note inline end "RM Messages Received and State Transitions" + + $$S_i \times M_{ji}^{rm} \rightarrow S_i$$ + +### RM Messages Received and State Transitions + +The table below lists the effects of receiving RM messages on the receiving Participant's state coupled with the +expected response message. + + +| Received Msg.
$\leftharpoondown$
$M_{ji}$ | Receiver Precondition
$s_n \in S_i$
$q^{cs},q^{rm},q^{em}$ | Receiver Transition
$(s_n \xrightarrow{} s_{n+1})$
$q^{cs},q^{rm},q^{em}$ | Response Msg.
$\rightharpoonup$
$M_{ij}$ | +|:-------------------------------------------------:|:------------------------------------------------------------------:|:---------------------------------------------------------------------------------:|:------------------------------------------------:| +| $*$ | $*,C,*$ | $-,-,-$ | $-$ | +| $RS$ | $vfd \cdot\cdot\cdot,S,*$ | $\xrightarrow{\mathbf{V}} Vfd \cdot\cdot\cdot, \xrightarrow{r} R,-$ | $RK$, $CV$ (vendor) | +| $RS$ | $vfd \cdot\cdot\cdot,\{ R, I, V,D,A\},*$ | $\xrightarrow{\mathbf{V}} Vfd \cdot\cdot\cdot,-,-$ | $RK$, $CV$ (vendor) | +| $RS$ | $V \cdot\cdot\cdot\cdot\cdot,S,*$ | $-,\xrightarrow{r} R,-$ | $RK$, $CV$ (vendor) | +| $RS$ | $V \cdot\cdot\cdot\cdot\cdot,\{ R, I, V,D,A\},*$ | $-,-,-$ | $RK$, $CV$ (vendor) | +| $RS$ | $*,S,*$ | $-,\xrightarrow{r} R,-$ | $RK$ (non-vendor) | +| $RS$ | $*,\{ R, I, V,D,A\},*$ | $-,-,-$ | $RK$ (non-vendor) | +| $\{RI,RV,RD,RA,RC\}$ | $*,\{R,I,V,D,A\},*$ | $-,-,-$ | $RK$ | +| $\{RI,RV,RD,RA,RC\}$ | $*,S,*$ | $-,-,-$ | $RE + GI$ | +| $RE$ | $*,*,*$ | $-,-,-$ | $RK + GI$ | +| $RK$ | $*,*,*$ | $-,-,-$ | $-$ | + +## EM Transition Functions + +The appropriate Participant behavior in the EM process depends on whether the case state +$q^{cs}$ is in $\cdot\cdot\cdot pxa$ or not. + +!!! note "" + + Participants SHALL NOT negotiate embargoes where the vulnerability + or its exploit is public or attacks are known to have occurred. + +!!! note "" + + Participants MAY begin embargo negotiations before sending the + report itself in an $RS$ message. Therefore, it is *not* an error + for an $E*$ message to arrive while the Recipient is unaware of the + report ($q^{rm} \in S$). + +!!! note "" + + Participants MAY reject any embargo proposals or revisions for any + reason. + +!!! note "" + + If information about the vulnerability or an exploit for it has been + made public, Participants SHALL terminate the embargo + ($q^{cs} \in \{\cdot\cdot\cdot P \cdot\cdot, \cdot\cdot\cdot\cdot X \cdot\}$). + +!!! note "" + + If attacks are known to have occurred, Participants SHOULD terminate + the embargo ($q^{cs} \in \cdot\cdot\cdot\cdot\cdot A$). + +!!! note "" + + Participants SHOULD send $EK$ in acknowledgment of any other $E*$ + message except $EK$ itself. + +!!! note "" + + Participants SHOULD acknowledge ($EK$) and inquire ($GI$) about the + nature of any error reported by an incoming $EE$ message. + + +!!! note inline end "EM Messages Sent and State Transitions" + + $$S_i \times M_{ij}^{em} \rightarrow S_i$$ + + +### EM Messages Sent and State Transitions + +The following table lists each EM message type and the states in which that message is appropriate to send along with +the corresponding sender state transition. + +| Sender Precondition
$(s_n \in S_i)$
$q^{cs},q^{rm},q^{em}$ | Sender Transition
$(s_n \xrightarrow{} s_{n+1})$
$q^{cs},q^{rm},q^{em}$ | Message Type
$\rightharpoonup$
$M_{ij}$ | +|:-------------------------------------------------------------------:|:--------------------------------------------------------------------------------:|:-----------------------------------------------:| +| $\cdot\cdot\cdot pxa,\lnot C,N$ | $-,-,\xrightarrow{p} P$ | $EP$ | +| $\cdot\cdot\cdot pxa,\lnot C,P$ | $-,-,\xrightarrow{p} P$ | $EP$ | +| $\cdot\cdot\cdot pxa,\lnot C,P$ | $-,-,\xrightarrow{a} A$ | $EA$ | +| $\cdot\cdot\cdot pxa,\lnot C,A$ | $-,-,\xrightarrow{p} R$ | $EV$ | +| $\cdot\cdot\cdot pxa,\lnot C,R$ | $-,-,\xrightarrow{p} R$ | $EV$ | +| $\cdot\cdot\cdot pxa,\lnot C,R$ | $-,-,\xrightarrow{r} A$ | $EJ$ | +| $\cdot\cdot\cdot pxa,\lnot C,R$ | $-,-,\xrightarrow{a} A$ | $EC$ | +| $*,\lnot C,P$ | $-,-,\xrightarrow{r} N$ | $ER$ | +| $*,\lnot C,A$ | $-,-,\xrightarrow{t} X$ | $ET$ | +| $*,\lnot C,R$ | $-,-,\xrightarrow{t} X$ | $ET$ | +| $*,\lnot C,*$ | $-,-,-$ | $EK$ | +| $*,\lnot C,*$ | $-,-,-$ | $EE$ | + + +!!! note inline end "EM Messages Received and State Transitions" + + $$S_i \times M_{ji}^{em} \rightarrow S_i$$ + +### EM Messages Received and State Transitions + +The next table lists the effects of receiving an EM message to the receiving Participant's state, grouped by the EM message type received. + +!!! tip "Notes on Embargo Messages Received and State Transitions" + + Incoming EM Messages do not trigger any change in $q^{cs}$ or $q^{rm}$. + When CS is $q^{cs} \not \in \cdot\cdot\cdot pxa$, embargoes are not viable. + + +| Received Msg.
$\leftharpoondown$
$M_{ji}$ | Receiver Precondition
$s_n \in S_i$
$q^{cs},q^{rm}$ | Receiver Transition
$(s_n \xrightarrow{} s_{n+1})$
$q^{cs},q^{rm},q^{em}$ | Response Msg.
$\rightharpoonup$
$M_{ij}$ | +|:--------------------------------------------------------:|:-----------------------------------------------------------:|:---------------------------------------------------------------------------------:|:------------------------------------------------:| +| $EP$ | $\cdot\cdot\cdot pxa, \lnot C, N$ | $-,-,\xrightarrow{p} P$ | $EK$ | +| $EP$ | $\cdot\cdot\cdot pxa, \lnot C, P$ | $-,-,-$ | $EK$ | +| $EA$ | $\cdot\cdot\cdot pxa, \lnot C, P$ | $-,-,\xrightarrow{a} A$ | $EK$ | +| $EV$ | $\cdot\cdot\cdot pxa, \lnot C, A$ | $-,-,\xrightarrow{p} R$ | $EK$ | +| $EV$ | $\cdot\cdot\cdot pxa, \lnot C, R$ | $-,-,-$ | $EK$ | +| $EJ$ | $\cdot\cdot\cdot pxa, \lnot C, R$ | $-,-,\xrightarrow{r} A$ | $EK$ | +| $EC$ | $\cdot\cdot\cdot pxa, \lnot C, R$ | $-,-,\xrightarrow{a} A$ | $EK$ | +| $ER$ | $*, \lnot C, P$ | $-,-,\xrightarrow{r} N$ | $EK$ | +| $ET$ | $*, \lnot C, A$ | $-,-,\xrightarrow{t} X$ | $EK$ | +| $ET$ | $*, \lnot C, R$ | $-,-,\xrightarrow{t} X$ | $EK$ | +| $ET$ | $*, \lnot C, X$ | $-,-,-$ | $EK$ | +| $EP$ | $\lnot \cdot\cdot\cdot pxa,\lnot C, N$ | $-,-,-$ | $ER$ | +| $EP$ | $\lnot \cdot\cdot\cdot pxa,\lnot C, P$ | $-,-,\xrightarrow{r} N$ | $ER$ | +| $EA$ | $\lnot \cdot\cdot\cdot pxa,\lnot C, P$ | $-,-,\xrightarrow{r} N$ | $ER$ | +| $EV$ | $\lnot \cdot\cdot\cdot pxa,\lnot C, A$ | $-,-,\xrightarrow{t} X$ | $ET$ | +| $EV$ | $\lnot \cdot\cdot\cdot pxa,\lnot C, R$ | $-,-,\xrightarrow{t} X$ | $ET$ | +| $EJ$ | $\lnot \cdot\cdot\cdot pxa,\lnot C, R$ | $-,-,\xrightarrow{t} X$ | $ET$ | +| $EC$ | $\lnot \cdot\cdot\cdot pxa,\lnot C, R$ | $-,-,\xrightarrow{t} X$ | $ET$ | +| $EE$ | $*,\lnot C,*$ | $-,-,-$ | $EK+GI$ | +| $EK$ | $*,\lnot C,*$ | $-,-,-$ | $-$ | +| Any EM msg. not
addressed above | $*,\lnot C,*$ | $-,-,-$ | $EE$ | + + +## CVD Transition Functions + +!!! tip inline end "Participant-Specific State Messages Promote Shared Situation Awareness" + + Effective coordination is usually improved with Participants' mutual awareness of each other's state, of course. + +The Vendor-specific portions of the CS (*Vendor Awareness*, *Fix Ready*, and +*Fix Deployed*) are per-Participant states. +Therefore, the receiver of a message indicating another Participant has changed their $\{v,V\}$, $\{f,F\}$ or $\{d,D\}$ +status is not expected to change their own state as a result. + +However, this is not the case for the remainder of the CS substates. +As above, the appropriate Participant response to receiving CS messages (namely, those surrounding *Public Awareness*, +*Exploit Public*, or *Attacks Observed*) depends on the state of the EM process. + +!!! note "" + + Participants SHALL initiate embargo termination upon becoming aware + of publicly available information about the vulnerability or its + exploit code. + + +!!! note "" + + Participants SHOULD initiate embargo termination upon becoming aware + of attacks against an otherwise unpublished vulnerability. + +!!! note inline end "CS Messages Sent and State Transitions" + + $$S_i \times M_{ij}^{cs} \rightarrow S_i$$ + +### CS Messages Sent and State Transitions + +The following table lists each CVD message type and the states in which that message is appropriate to send along with +the corresponding sender state transition. + + + +!!! tip "Notes on CS Messages Sent and State Transitions" + + Note that when a CS message induces a $q^{rm}$ or $q^{em}$ state change, the corresponding RM or EM message should + be sent as indicated in the tables above. + + +| Sender Precondition
$(s_n \in S_i)$
$q^{cs},q^{rm},q^{em}$ | Sender Transition
$(s_n \xrightarrow{} s_{n+1})$
$q^{cs},q^{rm},q^{em}$ | Message Type
$\rightharpoonup$
$M_{ij}$ | +|:------------------------------------------------------------------:|:-------------------------------------------------------------------------------:|:-----------------------------------------------:| +| $vfd \cdot\cdot\cdot,S,*$ | $\xrightarrow{\mathbf{V}} Vfd \cdot\cdot\cdot, \xrightarrow{r} R,-$ | $CV$ | +| $Vfd \cdot\cdot\cdot,\lnot C,*$ | $\xrightarrow{\mathbf{F}} VFd \cdot\cdot\cdot, -,-$ | $CF$ | +| $VFd \cdot\cdot\cdot,\lnot C,*$ | $\xrightarrow{\mathbf{D}} VFD \cdot\cdot\cdot, -,-$ | $CD$ | +| $\cdot\cdot\cdot p \cdot\cdot,\lnot C,\{N,X\}$ | $\xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot, -,-$ | $CP$ | +| $\cdot\cdot\cdot p \cdot\cdot,\lnot C,P$ | $\xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot, -,\xrightarrow{r} N$ | $CP$ | +| $\cdot\cdot\cdot p \cdot\cdot,\lnot C,\{A,R\}$ | $\xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot, -,\xrightarrow{t} X$ | $CP$ | +| $\cdot\cdot\cdot px \cdot,\lnot C,\{N,X\}$ | $\xrightarrow{\mathbf{X+P}} \cdot\cdot\cdot PX \cdot, -,-$ | $CX+CP$ | +| $\cdot\cdot\cdot px \cdot,\lnot C,P$ | $\xrightarrow{\mathbf{X+P}} \cdot\cdot\cdot PX \cdot, -,\xrightarrow{r} N$ | $CX+CP$ | +| $\cdot\cdot\cdot px \cdot,\lnot C,\{A,R\}$ | $\xrightarrow{\mathbf{X+P}} \cdot\cdot\cdot PX \cdot, -,\xrightarrow{t} X$ | $CX+CP$ | +| $\cdot\cdot\cdot Px \cdot,\lnot C,\{N,X\}$ | $\xrightarrow{\mathbf{X}} \cdot\cdot\cdot PX \cdot, -,-$ | $CX$ | +| $\cdot\cdot\cdot Px \cdot,\lnot C,P$ | $\xrightarrow{\mathbf{X}} \cdot\cdot\cdot PX \cdot, -,\xrightarrow{r} N$ | $CX$ | +| $\cdot\cdot\cdot Px \cdot,\lnot C,\{A,R\}$ | $\xrightarrow{\mathbf{X}} \cdot\cdot\cdot PX \cdot, -,\xrightarrow{t} X$ | $CX$ | +| $\cdot\cdot\cdot\cdot\cdot a,\lnot C,\{N,X\}$ | $\xrightarrow{\mathbf{A}} \cdot\cdot\cdot\cdot\cdot A, -,-$ | $CA$ | +| $\cdot\cdot\cdot\cdot\cdot a,\lnot C,P$ | $\xrightarrow{\mathbf{A}} \cdot\cdot\cdot\cdot\cdot A, -,\xrightarrow{r} N$ | $CA$ | +| $\cdot\cdot\cdot\cdot\cdot a,\lnot C,\{A,R\}$ | $\xrightarrow{\mathbf{A}} \cdot\cdot\cdot\cdot\cdot A, -,\xrightarrow{t} X$ | $CA$ | + + +!!! note inline end "CS Messages Received and State Transitions" + + $$S_i \times M_{ji}^{cs} \rightarrow S_i$$ + + +### CS Messages Received and State Transitions + +The following table lists the effects of receiving a +CS message to the receiving Participant's state coupled with the expected response message. + + +| Received Msg.
$\leftharpoondown$
$M_{ji}$ | Receiver Precondition
$s_n \in S_i$
$q^{cs},q^{rm},q^{em}$ | Receiver Transition
$(s_n \xrightarrow{} s_{n+1})$
$q^{cs},q^{rm},q^{em}$ | Response Msg.
$\rightharpoonup$
$M_{ij}$ | +|:-------------------------------------------------:|:------------------------------------------------------------------:|:---------------------------------------------------------------------------------:|:------------------------------------------------:| +| $CV$ | $*,\lnot C,*$ | $-,-,-$ | $CK$ | +| $CF$ | $*,\lnot C,*$ | $-,-,-$ | $CK$ | +| $CD$ | $*,\lnot C,*$ | $-,-,-$ | $CK$ | +| $CP$ | $\cdot\cdot\cdot p \cdot\cdot,\lnot C,P$ | $\xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot,-,\xrightarrow{r} N$ | $CK$ | +| $CP$ | $\cdot\cdot\cdot p \cdot\cdot,\lnot C,\{A,R\}$ | $\xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot,-,\xrightarrow{t} X$ | $CK$ | +| $CP$ | $\cdot\cdot\cdot p \cdot\cdot,\lnot C,\{N,X\}$ | $\xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot,-,-$ | $CK$ | +| $CP$ | $\cdot\cdot\cdot P \cdot\cdot,\lnot C,*$ | $-,-,-$ | $CK$ | +| $CX$ | $\cdot\cdot\cdot px \cdot,\lnot C,P$ | $\xrightarrow{\mathbf{X+P}} \cdot\cdot\cdot PX \cdot,-,\xrightarrow{r} N$ | $CK$ | +| $CX$ | $\cdot\cdot\cdot px \cdot,\lnot C,\{A,R\}$ | $\xrightarrow{\mathbf{X+P}} \cdot\cdot\cdot PX \cdot,-,\xrightarrow{t} X$ | $CK$ | +| $CX$ | $\cdot\cdot\cdot px \cdot,\lnot C,\{N,X\}$ | $\xrightarrow{\mathbf{X+P}} \cdot\cdot\cdot PX \cdot,-,-$ | $CK$ | +| $CX$ | $\cdot\cdot\cdot Px \cdot,\lnot C,*$ | $\xrightarrow{\mathbf{X}} \cdot\cdot\cdot PX \cdot,-,-$ | $CK$ | +| $CX$ | $\cdot\cdot\cdot PX \cdot,\lnot C,*$ | $-,-,-$ | $CK$ | +| $CA$ | $\cdot\cdot\cdot p \cdot a,\lnot C,P$ | $\xrightarrow{\mathbf{A}} \cdot\cdot\cdot P \cdot A,-,\xrightarrow{r} N$ | $CK$ | +| $CA$ | $\cdot\cdot\cdot p \cdot a,\lnot C,\{A,R\}$ | $\xrightarrow{\mathbf{A}} \cdot\cdot\cdot P \cdot A,-,\xrightarrow{t} X$ | $CK$ | +| $CA$ | $\cdot\cdot\cdot p \cdot a,\lnot C,\{N,X\}$ | $\xrightarrow{\mathbf{A}} \cdot\cdot\cdot P \cdot A,-,-$ | $CK$ | +| $CA$ | $\cdot\cdot\cdot P \cdot a,\lnot C,*$ | $\xrightarrow{\mathbf{A}} \cdot\cdot\cdot P \cdot A,-,-$ | $CK$ | +| $CA$ | $\cdot\cdot\cdot\cdot\cdot A,\lnot C,*$ | $-,-,-$ | $CK$ | +| $CE$ | $*,\lnot C,*$ | $-,-,-$ | $CK+GI$ | +| $CK$ | $*,\lnot C,*$ | $-,-,-$ | $-$ | + + +## General Transition Functions + +Finally, for the sake of completeness, we show that general inquiries, acknowledgments, and errors are otherwise independent +of the rest of the processes. +No state changes are expected to occur based on the receipt of a General message. + +!!! tip "General Messages are not a *No-Op*" + + We do not mean to imply that the *content* of a general message is expected to have no effect on the progression + of a case, merely that the act of sending or receiving a general message itself does not imply any necessary protocol + state change to either the sender or receiver Participants. + +!!! note inline end "General Messages Sent and State Transitions" + + $$S_i \times M_{ij}^{gen} \rightarrow S_i$$ + +### General Messages Sent and State Transitions + +The following table lists each general message and the states in which it is appropriate to send along with the +corresponding sender state. + + + +| Sender Precondition
$(s_n \in S_i)$
$q^{cs},q^{rm},q^{em}$ | Sender Transition
$(s_n \xrightarrow{} s_{n+1})$
$q^{cs},q^{rm},q^{em}$ | Message Type
$\rightharpoonup$
$M_{ij}$ | +|:------------------------------------------------------------------:|:-------------------------------------------------------------------------------:|:-----------------------------------------------:| +| $*,*,*$ | $-,-,-$ | $GI$ | +| $*,*,*$ | $-,-,-$ | $GK$ | +| $*,*,*$ | $-,-,-$ | $GE$ | + +!!! note inline end "General Messages Received and State Transitions" + + $$S_i \times M_{ji}^{gen} \rightarrow S_i$$ + +### General Messages Received and State Transitions + +The next table lists the effects of receiving a general message to the receiving Participant's state coupled with the +expected response message. + + + +| Received Msg.
$\leftharpoondown$
$M_{ji}$ | Receiver Precondition
$s_n \in S_i$
$q^{cs},q^{rm},q^{em}$ | Receiver Transition
$(s_n \xrightarrow{} s_{n+1})$
$q^{cs},q^{rm},q^{em}$ | Response Msg.
$\rightharpoonup$
$M_{ij}$ | +|:-------------------------------------------------:|:------------------------------------------------------------------:|:---------------------------------------------------------------------------------:|:------------------------------------------------:| +| $GI$ | $*,*,*$ | $-,-,-$ | $GK$ | +| $GK$ | $*,*,*$ | $-,-,-$ | $-$ | +| $GE$ | $*,*,*$ | $-,-,-$ | $GI$ | \ No newline at end of file diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md new file mode 100644 index 00000000..9ca2b8eb --- /dev/null +++ b/docs/reference/glossary.md @@ -0,0 +1,235 @@ +# Glossary + +!!! note "TODO" + We don't necessarily need all these acronyms in the glossary. We could just link the text to the thing they refer to. + E.g., in the rest of the site `CISA` should just be a link to `https://www.cisa.gov/` + +`ACM` + +: Association for Computing Machinery + + +`AI` + +: Artificial Intelligence + + +`API` + +: Application Programming Interface + + +`CERT/CC` + +: CERT Coordination Center at the Software Engineering Institute (SEI) + +`CISA` + +: Cybersecurity and Infrastructure Security Agency, part of the United States of America + (US) Department of Homeland Security (DHS) + + +`CNA` + +: Common Vulnerabilities and Exposures (CVE) Numbering Authority CS Coordinated Vulnerability Disclosure (CVD) Case State + + +`CSAF` + +: Common Security Advisory Framework by OASIS + + +`CVD` + +: Coordinated Vulnerability Disclosure + + +`CVE` + +: Common Vulnerabilities and Exposures by The MITRE Corporation (MITRE) + + +`CVSS` + +: Common Vulnerability Scoring System, maintained by Forum of Incident Response + and Security Teams (FIRST) +`DAG` + +: Directed Acyclic Graph + + +`DFA` + +: Deterministic Finite Automaton + + +`DHS` + +: US Department of Homeland Security + + +`DTRAP` + +: Digital Threats: Research and Practice, an Association for Computing + Machinery (ACM) journal + +`EM` + +: Embargo Management + + +`FFRDC` + +: Federally Funded Research and Development Center + +`FIRST` + +: Forum of Incident Response and Security Teams + +`FSM` + +: Finite State Machine + +`IDS` + +: Intrusion Detection System + + +`IETF` +: Internet Engineering Task Force + + +`IPS` + +: Intrusion Prevention System + + +`ITSM` + +: Information Technology Service Management + + +`JSON` + +: JavaScript Object Notation + + +`MITRE` + +: The MITRE Corporation + + +`MPCVD` + +: Multi-Party Coordinated Vulnerability Disclosure + + +`NDA` + +: Non-Disclosure Agreement + + +`NIST` + +: National Institute of Standards and Technology, part of the US Department of + Commerce + +`NPC` + +: Non-Player Character + + +`OEM` + +: Original Equipment Manufacturer + + +`OT` + +: Operational Technology + + +`OWL` + +: Web Ontology Language, a World Wide Web Consortium (W3C) standard + + +`PoC` + +: Proof of Concept + + +`protobuf` + +: Protocol Buffers + + +`REST` + +: Representational State Transfer + + +`RM` + +: Report Management + + +`SAAS` + +: Software-as-a-Service + + +`SAML` + +: Security Assertion Markup Language + + +`SBOM` + +: Software Bill of Materials + + +`SEI` + +: Software Engineering Institute, a Federally Funded Research and Development Center + (FFRDC) operated by Carnegie Mellon University + +`SSVC` + +: Stakeholder-Specific Vulnerability Categorization + + +`UML` + +: Unified Modeling Language + + +`US` + +: United States of America + + +`VDP` + +: Vulnerability Disclosure Program + + +`W3C` + +: World Wide Web Consortium + + +`XML` + +: Extensible Markup Language, a W3C standard + + +`XMPP` + +: Extensible Messaging and Presence Protocol, an Internet Engineering Task + Force (IETF) standard + +`XSD` + +: Extensible Markup Language (XML) Schema Definition, a W3C standard + diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 00000000..36c9feb9 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,21 @@ +# Vultron Protocol Reference + +!!! tip inline end "Prerequisites" + + The [Reference](index.md) section assumes that you have + + - specific questions about or a desire for a detailed understanding of the Vultron Protocol + - familiarity with the [Understanding Vultron](../topics/index.md) section + - familiarity with the CVD process in general + + If you are unfamiliar with the Vultron Protocol, we recommend that you start with [Understanding Vultron](../topics/index.md). + If you are familiar enough with the Vultron Protocol that you're interested in implementing it, see [Implementing Vultron](../howto/index.md). + And finally, if you're just trying to understand the CVD process, we recommend that you start with the [CERT Guide to Coordinated Vulnerability Disclosure](https://vuls.cert.org/confluence/display/CVD/). + + +The Vultron Protocol Reference includes the formal Vultron Protocol specification, and crosswalks the +protocol with other related standards and protocols, including: + +- [Formal Protocol](formal_protocol/index.md) +- [ISO Crosswalk](iso_crosswalk.md) +- [SSVC Crosswalk](ssvc_crosswalk.md) \ No newline at end of file diff --git a/docs/reference/iso_29147_2018.md b/docs/reference/iso_29147_2018.md new file mode 100644 index 00000000..f4bf2a39 --- /dev/null +++ b/docs/reference/iso_29147_2018.md @@ -0,0 +1,60 @@ +# ISO/IEC 29147:2018 Crosswalk + +{% include-markdown "../includes/not_normative.md" %} + +[ISO/IEC 29147:2018](https://www.iso.org/standard/72311.html) +**Information technology — Security techniques — Vulnerability disclosure** +also overlaps with the Vultron Protocol. + +
+
+ + +Perhaps unsurprisingly, clauses 5 through 9 of ISO/IEC 29147:2018 overlap significantly with the Vultron Protocol. + +!!! tip "Consistent Terminology" + + Our use of the following terms is consistent with ISO/IEC 29147:2018 + _§5.4 Systems, components, and services_: Systems, Components, Products, Services, Vulnerability, and Product interdependency. + + ISO/IEC 29147:2018 _§5.5 Stakeholder Roles_ includes _User_, _Vendor_, _Reporter_, and _Coordinator_. + We generally use _Deployer_ instead of _User_, but the rest are consistent. + +See the table below for a thorough cross-reference. + +| ISO/IEC
29147:2018
Clause | Sub-Clause | Vultron Protocol Mapping | +|:---------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 5.6 Vulnerability Handling Process Summary | 5.6.1 General
5.6.2 Preparation
5.6.3 Receipt
5.6.4 Verification
5.6.5 Remediation development
5.6.6 Release
5.6.7 Post-release | The first few subsections of ISO/IEC 29147:2018 §5.6 are recapitulated in [ISO/IEC 30111:2019](iso_30111_2019.md). Accordingly, see the corresponding rows on that page | +| | 5.6.8 Embargo period | [EM Discussion](../topics/process_models/em/principles.md) +| 5.7 Information exchange during vulnerability disclosure | send-report-to | [Message Types](formal_protocol/messages.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
$q^{rm} \in A + RS$ sender
$q^{rm} \in S \xrightarrow{r} R + RS$ receiver | +| | release-advisory-to | [Message Types](formal_protocol/messages.md)
[Prepare Publication Behavior](../topics/behavior_logic/publication_bt.md)
$q^{rm} \in A + GI$ sender
$q^{rm} \in \{R,V,A,D\} + GI$ receiver | +| 5.8 Confidentiality | | [Embargo Management Model](../topics/process_models/em/index.md)
[Transport Protocol](../howto/general_implementation.md#transport-protocol) | +| 5.9 Vulnerability advisories | | the [Public Awareness](../topics/process_models/cs/index.md#the-public-awareness-substate-p-p) substate
[Publication Behavior](../topics/behavior_logic/publication_bt.md) | +| 5.10 Vulnerability exploitation | | the [Exploit Public](../topics/process_models/cs/index.md#the-exploit-public-substate-x-x) substate
the [Attacks Observed](../topics/process_models/cs/index.md#the-attacks-observed-substate-a-a) substate
[Monitor Threats Behavior](../topics/behavior_logic/monitor_threats_bt.md) | +| 5.11 Vulnerabilities and risk | | [Interactions between the Vultron Protocol and SSVC](ssvc_crosswalk.md) +| 6 Receiving vulnerability reports | 6.1 General | the [Report Management Model](../topics/process_models/rm/index.md)
the [Vendor Awareness](../topics/process_models/cs/index.md#the-vendor-awareness-substate-v-v) substate
[Process RM Messages Behavior](../topics/behavior_logic/msg_rm_bt.md) | +| 6.2 Vulnerability reports | 6.2.1 General | the [Report Management Model](../topics/process_models/rm/index.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md) | +| | 6.2.2 Capability to receive reports | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
[Process RM Messages Behavior](../topics/behavior_logic/msg_rm_bt.md) | +| | 6.2.3 Monitoring | [Receiving and Processing Messages Behavior](../topics/behavior_logic/msg_intro_bt.md) | +| | 6.2.4 Report Tracking | the [Report Management Model](../topics/process_models/rm/index.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
[Case Object](../howto/case_object.md) | +| | 6.2.5 Report Acknowledgement | [RM Message Types](formal_protocol/messages.md#rm-message-types)
[Process RM Messages Behavior](../topics/behavior_logic/msg_rm_bt.md) | +| 6.3 Initial assessment | | [RM Message Types](formal_protocol/messages.md#rm-message-types)
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md) | +| 6.4 Further investigation | | [RM Message Types](formal_protocol/messages.md#rm-message-types)
[Do Work Behavior](../topics/behavior_logic/do_work_bt.md) | +| 6.5 On-going communication | | [Message Types](formal_protocol/messages.md) | +| 6.6 Coordinator involvement | - | [RM Interactions Between CVD Participants](../topics/process_models/rm/rm_interactions.md)
[Inviting Others to and Embargoed Case](../topics/process_models/em/working_with_others.md)
[Coordination with a Coordinator](../topics/formal_protocol/worked_example.md#coordinating_with_coordinator)
[Notify Others Behavior](../topics/behavior_logic/reporting_bt.md) | +| 6.7 Operational security | - | [Transport Protocol](../howto/general_implementation.md#transport-protocol) | +| 7 Publishing vulnerability advisories | all | [Publication Behavior](../topics/behavior_logic/publication_bt.md)
[CVD Case Substates](../topics/process_models/cs/index.md#cvd-case-substates) | +| | 7.3 Advisory publication timing | [Embargo Principles](../topics/process_models/em/principles.md) | +| | 7.4 Advisory elements | [Message Formats](../howto/general_implementation.md#message-formats) | +| | 7.5 Advisory communication | [Publication Behavior](../topics/behavior_logic/publication_bt.md) | +| | 7.6 Advisory format | [Message Formats](../howto/general_implementation.md#message-formats) | +| | 7.7 Advisory authenticity | [Identity Management](../howto/general_implementation.md#identity-management) | +| | 7.8 Remediations | [Deployment Behavior](../topics/behavior_logic/deployment_bt.md) | +| 8 Coordination | 8.1 General | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
the [Accepted](../topics/process_models/rm/index.md#the-accepted-a-state) state
[RM Interactions Between CVD Participants](../topics/process_models/rm/rm_interactions.md)
[Inviting Others to an Embargoed Case](../topics/process_models/em/working_with_others.md)
[Modeling an MPCVD AI Using Behavior Trees](../topics/behavior_logic/cvd_bt.md) | +| | 8.2 Vendors playing multiple roles | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
the [Accepted](../topics/process_models/rm/index.md#the-accepted-a-state) state
the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) Substate
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md) | +| 9 Vulnerability disclosure policy | 9.2.2 Preferred contact mechanism | [Receiving and Processing Messages Behavior](../topics/behavior_logic/msg_intro_bt.md) | +| | 9.3.2 Vulnerability report contents | [Case Object](../howto/case_object.md) | +| | 9.3.3 Secure communication options | [Transport Protocol](../howto/general_implementation.md#transport-protocol) | +| | 9.3.4 Setting communication expectations | [Default Embargoes](../topics/process_models/em/defaults.md)
[Transition Functions](formal_protocol/transitions.md)
[Report Management Behavior Tree](../topics/behavior_logic/rm_bt.md) | +| | 9.3.6 Publication | [Publication Behavior](../topics/behavior_logic/publication_bt.md) | +| | 9.4.3 Disclosure timeline | [Embargo Management Model](../topics/process_models/em/index.md) | diff --git a/docs/reference/iso_30111_2019.md b/docs/reference/iso_30111_2019.md new file mode 100644 index 00000000..f52fbcd6 --- /dev/null +++ b/docs/reference/iso_30111_2019.md @@ -0,0 +1,35 @@ +# ISO/IEC 30111:2019 Crosswalk + +{% include-markdown "../includes/not_normative.md" %} + +Clause 7 of [ISO/IEC 30111:2019](https://www.iso.org/standard/69725.html) +**Information technology — Security techniques — Vulnerability handling processes** +closely relates to the Vultron Protocol. + +
+
+The table below provides a mapping of ISO/IEC 30111:2019 onto the relevant concepts and sections of this documentation. + + +| ISO/IEC
30111:2019
Clause | Sub-Clause | Vultron Protocol Mapping | +|:---------------------------------|:-------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 7.1.1 General | - | See details below | +| 7.1.2 Preparation | - | See details below | +| 7.1.3 Receipt | a) Internally Found Vulnerabilities | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
[RM Message Types](formal_protocol/messages.md#rm-message-types)
[Vulnerability Discovery Behavior](../topics/behavior_logic/vuldisco_bt.md)
$q^{rm} \in S \xrightarrow{r} R$ | +| | b) Externally Found Vulnerabilities | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
[RM Message Types](formal_protocol/messages.md#rm-message-types)
[Process RM Messages Behavior](../topics/behavior_logic/msg_rm_bt.md)
$q^{rm} \in S \xrightarrow{r} R$ | +| | c) Publicly Disclosed Vulnerabilities | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
[RM Message Types](formal_protocol/messages.md#rm-message-types)
[CS Message Types](formal_protocol/messages.md#cs-message-types)
[Monitor Threats Behavior](../topics/behavior_logic/monitor_threats_bt.md)
[Process RM Messages Behavior](../topics/behavior_logic/msg_rm_bt.md)
[Process CS Messages Behavior](../topics/behavior_logic/msg_cs_bt.md)
$q^{rm} \in S \xrightarrow{r} R$
$q^{cs} \in \cdot\cdot\cdot p \cdot\cdot \xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot$ | +| 7.1.4 Verification | a) Initial Investigation | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
[Report Validation Behavior](../topics/behavior_logic/rm_validation_bt.md)
$q^{rm} \in R \xrightarrow{v} V$ if valid
$q^{rm} \in R \xrightarrow{i} I$ if invalid | +| | b) Possible Process Exit
  1) Duplicate | attach to the original report | +| | b) Possible Process Exit
  2) Obsolete product | $q^{rm} \in I \xrightarrow{c} C$ if invalid
$q^{rm} \in V \xrightarrow{d} D \xrightarrow{c} C$ if valid | +| | b) Possible Process Exit
  3) Non-security | $q^{rm} \in I \xrightarrow{c} C$ | +| | b) Possible Process Exit
  4) Other vendor | [Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
$q^{rm} \in V \xrightarrow{a} A$ | +| | c) Root Cause Analysis | [Do Work Behavior](../topics/behavior_logic/do_work_bt.md)
$q^{rm} \in A$ | +| | d) Further investigation | [Do Work Behavior](../topics/behavior_logic/do_work_bt.md)
$q^{rm} \in A$ | +| | e) Prioritization | the [Valid](../topics/process_models/rm/index.md#the-valid-v-state) state
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md)
$q^{rm} \in V \xrightarrow{d} D$ on defer
$q^{rm} \in V \xrightarrow{a} A$ on accept | +| | f) Inform reporter | [Report Validation Behavior](../topics/behavior_logic/rm_validation_bt.md)
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md)
Emit _RV_, _RI_, _RA_, _RD_ messages as appropriate | +| 7.1.5 Remediation Development | all| the [Accepted](../topics/process_models/rm/index.md#the-accepted-a-state) state
the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) substate
[Fix Ready](../topics/process_models/model_interactions/rm_em_cs.md#fix-ready)
[Fix Development Behavior](../topics/behavior_logic/fix_dev_bt.md)
$q^{rm} \in A$
$q^{cs} \in Vfd\cdot\cdot\cdot \xrightarrow{\mathbf{V}} VFd\cdot\cdot\cdot$ | +| 7.1.6 Release | - | the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) substate
[Publication Behavior](../topics/behavior_logic/publication_bt.md)
$q^{cs} \in VFdp\cdot\cdot \xrightarrow{\mathbf{P}} VFdP \cdot\cdot$ | +| 7.1.7 Post-release | all | [Report Closure Behavior](../topics/behavior_logic/rm_closure_bt.md)
[Deployment Behavior](../topics/behavior_logic/deployment_bt.md)
$q^{cs} \in VF\cdot P \cdot\cdot$
$q^{rm} \in \{A,D\}$ | +| 7.2 Process Monitoring | all | [Deployment Behavior](../topics/behavior_logic/deployment_bt.md) | +| 7.3 Confidentiality | - | [Embargo Management Behavior](../topics/behavior_logic/em_bt.md) | +| 8 Supply chain considerations| - | [Reporting Behavior](../topics/behavior_logic/reporting_bt.md) | \ No newline at end of file diff --git a/docs/reference/iso_5895_2022.md b/docs/reference/iso_5895_2022.md new file mode 100644 index 00000000..c4cad6af --- /dev/null +++ b/docs/reference/iso_5895_2022.md @@ -0,0 +1,33 @@ +# ISO/IEC TR 5895:2022 Crosswalk + +{% include-markdown "../includes/not_normative.md" %} + +[ISO/IEC TR 5895:2022](https://www.iso.org/standard/81807.html) +**Cybersecurity — Multi-party coordinated vulnerability disclosure and handling** +intersects most directly with our topic. + +
+
+ +The table below contains our mapping of relevant sections of that technical report to our protocol model. + +| ISO/IEC TR 5895:2022 Clause | Sub-Clause | Vultron Protocol Model | +|:----------------------------------------------------|:----------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 4 Concepts | 4.2.3 Risk Reduction Effectiveness | [Early Termination](../topics/process_models/em/early_termination.md#early-termination)
[Adding Participants to an Embargoed Case](../topics/process_models/em/working_with_others.md) | +| 5 MPCVD Scenarios in Scope | all | [Adding Participants to an Embargoed Case](../topics/process_models/em/working_with_others.md) | +| 6 MPCVD Stakeholders | all | [Terms and Definitions](../topics/background/terms.md) | +| 7 MPCVD Lifecycle | 7.2 Policy Development | the [Report Management Model](../topics/process_models/rm/index.md)
the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
[Default Embargoes](../topics/process_models/em/defaults.md)
[CVD Directory](../topics/future_work/cvd_directory.md) | +| | 7.3 Strategy development | [RM Interactions between CVD Participants](../topics/process_models/rm/rm_interactions.md)
[EM Discussion](../topics/process_models/em/principles.md) | +| | 7.4 Know your customers | [RM Interactions between CVD Participants](../topics/process_models/rm/rm_interactions.md)
[Adding Participants to an Embargoed Case](../topics/process_models/em/working_with_others.md) | +| | 7.5 Encrypted Communication Methods and Conference Calls | [Transport Protocol](../howto/general_implementation.md#transport-protocol) | +| | 7.6 Processes and Controls | See NDA Note in [Embargo Management Model](../topics/process_models/em/index.md) | +| 8 MPCVD lifecycle for each product | all | [Deployment Behavior](../topics/behavior_logic/deployment_bt.md)
[Fix Development Behavior](../topics/behavior_logic/fix_dev_bt.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
[Publication Behavior](../topics/behavior_logic/publication_bt.md)
$q^{rm} \in A$ | +| 9 MPCVD lifecycle for each vulnerability | 9.1 Receipt | the [Start](../topics/process_models/rm/index.md#the-start-s-state) state
the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
the [Vendor Awareness](../topics/process_models/cs/index.md#the-vendor-awareness-substate-v-v) substate
[Process RM Messages Behavior](../topics/behavior_logic/msg_rm_bt.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
$q^{rm} \in S \xrightarrow{r} R$
$q^{cs} \in vfd\cdot\cdot\cdot \xrightarrow{\mathbf{V}} Vfd\cdot\cdot\cdot$ | +| | 9.2 Verification | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
the [Valid](../topics/process_models/rm/index.md#the-valid-v-state) state
the [Valid](../topics/process_models/rm/index.md#the-invalid-i-state) state
[Embargo Principles](../topics/process_models/em/principles.md)
[Report Validation Behavior](../topics/behavior_logic/rm_validation_bt.md)
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
$q^{rm} \in R \xrightarrow{v} V$ (valid)
$q^{rm} \in R \xrightarrow{i} I$ (invalid)
Emit _RV_. _RI_, _RA_, _RD_ as appropriate | +| | 9.3 Remediation development | the [Accepted](../topics/process_models/rm/index.md#the-accepted-a-state) state
the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) substate
[Fix Ready](../topics/process_models/model_interactions/rm_em_cs.md#sec:cs_f_em/index.md)
[Fix Development Behavior](../topics/behavior_logic/fix_dev_bt.md)
$q^{rm} \in A$
$q^{cs} \in Vfd\cdot\cdot\cdot \xrightarrow{\mathbf{F}}VFd\cdot\cdot\cdot$ | +| | 9.4 Release | the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) substate
[Publication Behavior](../topics/behavior_logic/publication_bt.md)
$q^{cs} \in VFdp\cdot\cdot \xrightarrow{\mathbf{P}} VFDP\cdot\cdot$ | +| | 9.5 Post-release | [Report Closure Behavior](../topics/behavior_logic/rm_closure_bt.md)
[Deployment Behavior](../topics/behavior_logic/deployment_bt.md)
$q^{rm} \in \{A,D\}$
$q^{cs} \in VF\cdot P \cdot\cdot$ | +| | 9.6 Embargo Period | [RM Interactions between CVD Participants](../topics/process_models/rm/rm_interactions.md)
[EM Discussion](../topics/process_models/em/principles.md)
[Interactions Between the RM and EM Models](../topics/process_models/model_interactions/rm_em.md)
$q^{em} \not \in X$ | +| 10 Information exchange | - | [RM Interactions between CVD Participants](../topics/process_models/rm/rm_interactions.md)
[Message Types](formal_protocol/messages.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md) | +| 11 Disclosure | - | [Adding Participants to an Embargoed Case](../topics/process_models/em/working_with_others.md)
[Coordination with a Coordinator](../topics/formal_protocol/worked_example.md#sec:coordinating_with_coordinator)
[Publication Behavior](../topics/behavior_logic/publication_bt.md) | +| 12 Use case for hardware and further considerations | - | [Adding Participants to an Embargoed Case](../topics/process_models/em/working_with_others.md)
[Interactions Between the RM and EM Models](../topics/process_models/model_interactions/rm_em.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md) | \ No newline at end of file diff --git a/docs/reference/iso_crosswalk.md b/docs/reference/iso_crosswalk.md new file mode 100644 index 00000000..d5598881 --- /dev/null +++ b/docs/reference/iso_crosswalk.md @@ -0,0 +1,12 @@ +# ISO Crosswalk + +Three ISO standards are relevant to the Vultron Protocol. +We cross-reference them here to help readers understand how they relate to the Vultron Protocol. + +| ISO Document | ISO Title | Vultron Protocol Crosswalk | +| --- | --- |--------------------------------| +| [ISO/IEC 30111:2019](https://www.iso.org/standard/69725.html) | **Information technology — Security techniques — Vulnerability handling processes** | [ISO 30111](iso_30111_2019.md) | +| [ISO/IEC 29147:2018](https://www.iso.org/standard/72311.html) | **Information technology — Security techniques — Vulnerability disclosure** | [ISO 29147](iso_29147_2018.md) | +| [ISO/IEC TR 5895:2022](https://www.iso.org/standard/81807.html) | **Cybersecurity — Multi-party coordinated vulnerability disclosure and handling** | [ISO 5898](iso_5895_2022.md) | + + diff --git a/docs/reference/ssvc_crosswalk.md b/docs/reference/ssvc_crosswalk.md new file mode 100644 index 00000000..eadfe29f --- /dev/null +++ b/docs/reference/ssvc_crosswalk.md @@ -0,0 +1,326 @@ +# Interactions Between the Vultron Protocol and SSVC + +{% include-markdown "../includes/not_normative.md" %} + +In the context of the Vultron Protocol, once a report has been validated +(i.e., it is in the RM [_Valid_](../topics/process_models/rm/index.md#the-valid-v-state) state, $q^{rm} \in V$), it must be prioritized to +determine what further effort, if any, is necessary. +While any prioritization scheme might be used, here we demonstrate an application of the [SSVC](https://github.com/CERTCC/SSVC) model. + +## SSVC Supplier and Deployer Trees + +The default outcomes for both the SSVC [_Supplier_](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_supplier.pdf) +and [_Deployer_](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_deployer_SeEUMss.pdf) Trees are +_Defer_, _Scheduled_, _Out of Cycle_, and _Immediate_. +The mapping from SSVC outcomes to RM states is straightforward, as shown below for the _Supplier Tree_ and +the _Deployer Tree_. + +!!! note "SSVC _Supplier Tree_ Mapping to RM States" + + $$\label{eq:ssvc_supplier_tree_output} + q^{rm} \in + \begin{cases} + \xrightarrow{d} D & \text{when } SSVC(Supplier~Tree) = Defer \\ + \\ + \xrightarrow{a} A & \text{when } SSVC(Supplier~Tree) \in + \begin{Bmatrix} + Scheduled \\ + Out~of~Cycle \\ + Immediate \\ + \end{Bmatrix} \\ + \end{cases}$$ + +!!! note "SSVC _Deployer Tree_ Mapping to RM States" + + $$\label{eq:ssvc_deployer_tree_output} + q^{rm} \in + \begin{cases} + \xrightarrow{d} D & \text{when } SSVC(Deployer~Tree) = Defer \\ + \\ + \xrightarrow{a} A & \text{when } SSVC(Deployer~Tree) \in + \begin{Bmatrix} + Scheduled \\ + Out~of~Cycle \\ + Immediate \\ + \end{Bmatrix} \\ + \end{cases}$$ + +The +SSVC _Defer_ +output maps directly onto the RM [_Deferred_](../topics/process_models/rm/index.md#the-deferred-d-state) state. +Otherwise, the three outputs that imply further action is necessary—Scheduled_, +_Out-of-Cycle_, and _Immediate_—all proceed to the RM [_Accepted_](../topics/process_models/rm/index.md#the-accepted-a-state) state. +The different categories imply different processes within the _Accepted_ state. +But because the RM model does not dictate internal organizational processes, further description of what those processes +might look like is out of scope for this crosswalk. + +We remind readers of a key takeaway from the protocol requirements in +the main part of this documentation: + +!!! note "" + + Vendors SHOULD communicate their prioritization choices when making + either a _defer_ ($\{V,A\} \xrightarrow{d} D$) or _accept_ + ($\{V,D\} \xrightarrow{a} A$) transition out of the _Valid_, + _Deferred_, or _Accepted_ states. + +## SSVC Coordinator Trees + +SSVC version 2 offers two decision trees for Coordinators: A [_Coordinator Triage Tree_](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_coord-triage.pdf) +and a [_Coordinator Publish Tree_](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_coord-publish.pdf). +The outputs for the _Coordinator Triage_ Decision Tree are _Decline_, _Track_, and _Coordinate_. +Similar to the _Supplier Tree_ mapping above, the mapping here is simple, as shown below. + +!!! note "SSVC _Coordinator Triage Tree_ Mapped to RM States" + + $$\label{eq:ssvc_coordinator_triage_tree_output} + q^{rm} \in + \begin{cases} + \xrightarrow{d} D & \text{when } SSVC(Coord.~Triage~Tree) = Decline \\ + \\ + \xrightarrow{a} A & \text{when } SSVC(Coord.~Triage~Tree) \in + \begin{Bmatrix} + Track \\ + Coordinate \\ + \end{Bmatrix} \\ + \end{cases}$$ + + +Again, whereas the _Decline_ output maps directly to the RM [_Deferred_](../topics/process_models/rm/index.md#the-deferred-d-state) state, the remaining two +states (_Track_ and _Coordinate_) imply the necessity for distinct processes within the Coordinator's RM [_Accepted_](../topics/process_models/rm/index.md#the-accepted-a-state) state. + +On the other hand, the SSVC _Coordinator Publish Tree_ falls entirely within the Coordinator's _Accepted_ state, so its +output does not directly induce any Coordinator RM state transitions. +However, a number of its decision points *do* touch on the protocol models, which we cover next. + +## SSVC Decision Points and the Vultron Protocol + +Additional connections between the protocol and the SSVC decision trees are possible. +We now examine how individual SSVC tree decision points can inform or be informed by Participant states in the +Vultron Protocol. + +### Exploitation + +The SSVC _Exploitation_ decision point permits three possible values: + +- _None_ +- _PoC_ +- _Active_ + +These values map directly onto state subsets in the [Case State (CS) model](../topics/process_models/cs/index.md), as shown below. + +!!! note "SSVC _Exploitation_ Decision Point Mapped to CS States" + + $$ SSVC(exploitation) = + \begin{cases} + None & \iff q^{cs} \in \cdot\cdot\cdot\cdot xa \\ + PoC & \iff q^{cs} \in \cdot\cdot\cdot\cdot Xa \\ + Active & \iff q^{cs} \in \cdot\cdot\cdot\cdot\cdot A \\ + \end{cases}$$ + +A value of _None_ implies that no exploits have been made public, and no attacks have been observed +(i.e., $q^{cs} \in \cdot\cdot\cdot\cdot xa$). +The _PoC_ value means that an exploit is public, but no attacks have been observed +(i.e., $q^{cs} \in \cdot\cdot\cdot\cdot Xa$). +Finally, the _Active_ value indicates attacks are occurring +(i.e., $q^{cs} \in \cdot\cdot\cdot\cdot\cdot A$). +These case states and SSVC values are equivalent in both directions, hence our use of the "if-and-only-if" ($\iff$) symbol. + + +### Report Public + +The SSVC _Report Public_ decision point also maps directly onto the [CS model](../topics/process_models/cs/index.md). +A value of _Yes_ means that the report is public, equivalent to $q^{cs} \in \cdot\cdot\cdot P \cdot\cdot$. +On the other hand, a _No_ value is the same as $q^{cs} \in \cdot\cdot\cdot p \cdot\cdot$. +As above, "$\iff$" indicates the bidirectional equivalence. + +!!! note "SSVC _Report Public_ Decision Point Mapped to CS States" + + $$SSVC(report~public) = + \begin{cases} + Yes & \iff q^{cs} \in \cdot\cdot\cdot P \cdot\cdot \\ + No & \iff q^{cs} \in \cdot\cdot\cdot p \cdot\cdot \\ + \end{cases}$$ + +### Supplier Contacted + +If the Supplier (Vendor) has been notified (i.e., there is reason to believe they are at least in the RM [_Received_](../topics/process_models/rm/index.md#the-received-r-state) +state, equivalent to the $V\cdot\cdot\cdot\cdot\cdot$ CS state subset) the _Supplier Contacted_ value should be _Yes_, +otherwise it should be _No_. + +!!! note "SSVC _Supplier Contacted_ Decision Point Mapped to RM States" + + $$SSVC(supp.~contacted) = + \begin{cases} + Yes & \iff q^{rm}_{Vendor} \not \in S \text{ or } q^{cs}_{Vendor} \in V\cdot\cdot\cdot\cdot\cdot \\ + \\ + No & \iff q^{rm}_{Vendor} \in S \text{ or } q^{cs}_{Vendor} \in vfd \cdot\cdot\cdot \\ + \end{cases}$$ + + +### Report Credibility + +Unlike most of the other SSVC decision points covered here that form a part of a Participant's report prioritization +process *after* report validation, the _Report Credibility_ decision point forms an important step in the Coordinator's +validation process. +In fact, it is often the only validation step possible when the Coordinator lacks the ability to reproduce a +vulnerability whether due to constraints of resources, time, or skill. +Thus, a value of _Credible_ can be expected to lead to an RM transition to [_Valid_](../topics/process_models/rm/index.md#the-valid-v-state) ($q^{rm} \in R \xrightarrow{v} V$), +assuming any additional validation checks also pass. +On the contrary, _Not-Credible_ always implies the RM transition to [_Invalid_](../topics/process_models/rm/index.md#the-invalid-i-state) ($q^{rm} \in R \xrightarrow{i} I$) +because "Valid-but-not-Credible" is a contradiction. + +!!! note "SSVC _Report Credibility_ Decision Point Mapped to RM States" + + $$SSVC(report~cred.) = + \begin{cases} + Credible & \text{implies }q^{rm} \xrightarrow{v} V \textrm{ (if validation also passes)}\\ + Not~Credible & \text{implies } q^{rm} \xrightarrow{i} I \\ + \end{cases}$$ + +### Supplier Engagement + +The possible values for the _Supplier_ (Vendor) _Engagement_ decision point are _Active_ or _Unresponsive_. +From the Coordinator's perspective, if enough Suppliers in a CVD case have communicated their engagement in a case +(i.e., enough Vendors are in the RM _Accepted_ state already or are expected to make it there soon from either the +_Received_ or _Valid_ states), then the SSVC value would be _Active_. + +Vendors in _Invalid_ or _Closed_ can be taken as disengaged, and it might be appropriate to select _Unresponsive_ for +the SSVC _Engagement_ decision point. + +Vendors in either _Received_ or _Deferred_ might be either _Active_ or _Unresponsive_, depending on the specific report +history. + +This mapping is formalized below and in the figure that follows. + +!!! note "SSVC _Supplier Engagement_ Decision Point Mapped to RM States" + + $$ SSVC(supp.~eng.) = + \begin{cases} + Active & \text{if } q^{rm} \in \{A,V\} \\ + \\ + \begin{cases} + Active \\ + Unresponsive + \end{cases} & \text{if } q^{rm} \in \{R,D\} \\ + \\ + Unresponsive & \text{if } q^{rm} \in \{I,C,S\} \\ + \end{cases}$$ + +```mermaid +--- +title: "RM States and SSVC Supplier Engagement" +--- +graph LR + subgraph ssvc_se[SSVC Supplier Engagement] + Active + Unresponsive + end + subgraph rm_states[RM States] + S[Start] + R[Received] + I[Invalid] + V[Valid] + D[Deferred] + A[Accepted] + C[Closed] + end + A --> Active + V --> Active + R --> Active + D --> Active + R--> Unresponsive + D --> Unresponsive + I --> Unresponsive + C --> Unresponsive + S --> Unresponsive +``` + +### Supplier Involvement + +The _Supplier Involvement_ decision point can take on the values _Fix-Ready_, _Cooperative_, or _Uncooperative/Unresponsive_. +We begin by noting the equivalence of the _Fix-Ready_ value with the similarly named substate of the CS model. + +!!! note "SSVC _Supplier Involvement_ Decision Point Mapped to CS States" + + $$\begin{aligned} + \label{eq:ssvc_supplier_involvement_fr} + SSVC(supp.~inv.) = Fix~Ready \iff q^{cs} \in VF \cdot\cdot\cdot\cdot + \end{aligned}$$ + +The Vendor RM states map onto these values as formalized below and shown in the figure below. + +!!! note "SSVC Supplier Involvement Decision Point Mapped to Vendor RM States" + + $$\begin{aligned} + \label{eq:ssvc_supplier_involvement} + SSVC(supp.~inv.) = + \begin{cases} + \begin{cases} + Fix~Ready \\ + Cooperative + \end{cases} & \text{if } q^{rm} \in A \\ + \\ + Cooperative & \text{if } q^{rm} \in V \\ + \\ + Uncoop./Unresp. & \text{if } q^{rm} \in \{R,I,D,C,S\} \\ + \end{cases} + \end{aligned}$$ + +```mermaid +--- +title: "RM States and SSVC Supplier Involvement" +--- +graph LR + subgraph rm_states[RM States] + S[Start] + R[Received] + I[Invalid] + V[Valid] + D[Deferred] + A[Accepted] + C[Closed] + end + + subgraph ssvc_si[SSVC Supplier Involvement] + fr[Fix-Ready] + co[Cooperative] + un[Uncooperative/Unresponsive] + end + A --> fr + A --> co + V --> co + R --> un + D --> un + I --> un + C --> un + S --> un +``` + +!!! tip "_Engagement_ vs. _Involvement_: What's the Difference?" + + Note the discrepancy between the mappings given for SSVC _Supplier Engagement_ versus those for _Supplier Involvement_. + This distinction is most prominent in the connections from the _Received_ and _Deferred_ RM states in the two figures above. + These differences are the result of the relative timing of the two different decisions they support within a CVD case. + + The decision to Coordinate (i.e., whether the Coordinator should move from RM _Valid_ to RM _Accept_ + ($q^{rm} \in V \xrightarrow{a} A$) occurs early in the Coordinator's RM process. + The SSVC _Supplier Engagement_ decision point is an attempt to capture this information. + This early in the process, allowances must be made for Vendors who may not have completed their own validation or + prioritization processes. + Hence, the mapping allows Vendors in any valid yet unclosed state ($q^{rm} \in \{R,V,A,D\}$) to be categorized as + _Active_ for this decision point. + + + On the other hand, the decision to Publish—a choice that falls entirely within the Coordinator's RM _Accepted_ + state—occurs later, at which time, more is known about each Vendor's level of involvement in the case + to that point. + By the time the publication decision is made, the Vendor(s) have had ample opportunity to engage in the CVD process. + They might already have a _Fix-Ready_ ($q^{cs} \in VF \cdot\cdot\cdot\cdot$), or they might be working toward it + (i.e., SSVC _Cooperative_). + However, if the Coordinator has reached the point where they are making a publication decision, and the Vendor has + yet to actively engage in the case for whatever reason—as indicated by their failure to reach the RM + _Accepted_ state or demonstrate progress toward it by at least getting to RM _Valid_ + ($q^{rm} \in \{A,V\}$)—then they can be categorized as _Uncooperative/Unresponsive_. + + diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..1d82685e --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,5 @@ +[data-md-color-scheme="cmu"] { + --md-primary-fg-color: #C41230; + --md-primary-fg-color--light: #E0E0E0; + --md-primary-fg-color--dark: #6D6E71; +} diff --git a/docs/topics/background/cvd_success.md b/docs/topics/background/cvd_success.md new file mode 100644 index 00000000..e433ace0 --- /dev/null +++ b/docs/topics/background/cvd_success.md @@ -0,0 +1,151 @@ +# What Does *Success* Mean in CVD? + + +We take as a base set of criteria the ordering preferences given in the +2021 report +[A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure (MPCVD)](https://doi.org/10.1184/R1/16416771) +by Householder and Spring. + +While we incorporate this model fully [later](../process_models/cs/index.md) in this documentation, +some notation is necessary to proceed here. +The [Case State model](../process_models/cs/index.md) is built on the idea that there are six events of significance +in the lifespan of every vulnerability, shown in the table below. + +| Event | Notation | Event | Notation | +| :--- |:--------:| :--- |:--------:| +| Vendor Awareness | **V** | Public Awareness | **P** | +| Fix Ready | **F** | Exploit Public | **X** | +| Fix Deployed | **D** | Attacks Observed | **A** | + +Our 2021 [report](https://doi.org/10.1184/R1/16416771) +defines a set of 12 ordering preferences over these 6 events. +We present them in roughly descending order of desirability according to the partial +order developed in that report. +Items closer to the top of the list are indicators of CVD skill. + +!!! note inline end "Formalism" + + The symbol $\prec$ is read as *precedes*. + + | Ordering Preference | Notation | + | :--- | :--- | + | Fix Deployed Before Public Awareness | **D** $\prec$ **P** | + | Fix Ready Before Public Awareness | **F** $\prec$ **P** | + | Fix Deployed Before Exploit Public | **D** $\prec$ **X** | + | Fix Deployed Before Attacks Observed | **D** $\prec$ **A** | + | Fix Ready Before Exploit Public | **F** $\prec$ **X** | + | Vendor Awareness Before Public Awareness | **V** $\prec$ **P** | + | Fix Ready Before Attacks Observed | **F** $\prec$ **A** | + | Public Awareness Before Exploit Public | **P** $\prec$ **X** | + | Exploit Public Before Attacks Observed | **X** $\prec$ **A** | + | Public Awareness Before Attacks Observed | **P** $\prec$ **A** | + | Vendor Awareness Before Exploit Public | **V** $\prec$ **X** | + | Vendor Awareness Before Attacks Observed | **V** $\prec$ **A** | + +## Fix Deployed Before Public Awareness + +For a fix to be deployed prior to public awareness, a lot has to go +right in the CVD process: The vendor has to know about +the vulnerability, create a fix, and deploy it—all without +public knowledge—and has to achieve all that prior to any +exploits being published or attacks becoming known to the public. +Furthermore, it requires that the Vendor has the capability to +deploy fixes without intervention by the system owner or user, which +is a rare engineering feat unattainable by many software supply +chains. + +More often, fix deployment (**D**) requires users +and/or system owners (Deployers) to take action. The need to inform +Deployers implies a need for public awareness of the vulnerability, +making this criteria impossible to achieve in those scenarios. + +## Fix Ready Before Public Awareness + +Deployers (i.e., the public) can take no action until a fix is +ready. Because public awareness also implies adversary awareness, +the vendor-adversary race becomes even more critical when this +condition is not met. Only Vendors who can receive *and act* on +vulnerability reports---whether those reports originate from inside +or outside of the organization---are able to achieve this goal. + +## Fix Deployed Before Exploit Public + +Deploying a fix before an exploit is made public helps reduce the +net risk to end users. + +## Fix Deployed Before Attacks Observed + +Attacks occurring before a fix has been deployed are when there's +maximum risk to users; therefore, we wish to avoid that situation. + +## Fix Ready Before Exploit Public + +Exploit publication prior to fix readiness represents a period of +increased threat to users since it means that attackers can exploit +the vulnerability even if they lack exploit development skills. When +fixes are ready before exploits are made public, defenders are +better positioned to protect their users. + +## Vendor Awareness Before Public Awareness + +Public awareness prior to vendor awareness can cause increased +support costs for vendors at the same time they are experiencing +increased pressure to prepare a fix. + +## Fix Ready Before Attacks Observed + +As in the case with published exploits, when fixes exist before +attacks are observed, defenders are in a substantially better +position to protect their users. + +## Public Awareness Before Exploit Public + +There is broad agreement that it is better for the public to find +out about a vulnerability via a CVD process rather than because someone +published an exploit for any adversary to use. + +## Exploit Public Before Attacks Observed + +This criterion is not about whether exploits should be published or +not. It is about whether we should prefer histories in which +exploits are published *before* attacks happen over histories in +which exploits are published *after* attacks happen. Because +attackers have more advantages in the latter case than the former, +histories in which **X** $\prec$ **A** are preferable to +those in which **A** $\prec$ **X**. + +## Public Awareness Before Attacks Observed + +Similar to the exploit case above, public awareness via +CVD is +generally preferred over public awareness resulting from incident +analysis that results from attack observations. + +## Vendor Awareness Before Exploit Public + +If public awareness of the vulnerability prior to vendor awareness +is bad, then a public exploit is at least as bad because it +encompasses the former and makes it readily evident that adversaries +have exploit code available for use. + +## Vendor Awareness Before Attacks Observed + +Attacks prior to vendor awareness represent a complete failure of +the vulnerability remediation process because they indicate that +adversaries are far ahead of defenders. + +--- + +## Summary + + +Taken together, these twelve ordering preferences constitute the minimum +set of outcomes we hope to facilitate with the Vultron protocol. + +| $a \prec b$ | $a \prec b$ | $a \prec b$ | +|:-----------------------------:|:-----------------------------:|:-----------------------------:| +| $\mathbf{V} \prec \mathbf{P}$ | $\mathbf{F} \prec \mathbf{P}$ | $\mathbf{D} \prec \mathbf{P}$ | +| $\mathbf{V} \prec \mathbf{X}$ | $\mathbf{F} \prec \mathbf{X}$ | $\mathbf{D} \prec \mathbf{X}$ | +| $\mathbf{V} \prec \mathbf{A}$ | $\mathbf{F} \prec \mathbf{A}$ | $\mathbf{D} \prec \mathbf{A}$ | +| $\mathbf{P} \prec \mathbf{X}$ | $\mathbf{P} \prec \mathbf{A}$ | $\mathbf{X} \prec \mathbf{A}$ | + diff --git a/docs/topics/background/index.md b/docs/topics/background/index.md new file mode 100644 index 00000000..2b521ec8 --- /dev/null +++ b/docs/topics/background/index.md @@ -0,0 +1,139 @@ +# Introduction + +!!! tip inline end "Prerequisites" + + The [Understanding Vultron](index.md) section assumes that you have: + + - an interest in learning about the Vultron Protocol + - familiarity with the CVD process in general + + If you are already familiar with the Vultron Protocol, and are looking for implementation advice, + see [Implementing Vultron](../../howto/index.md). + For technical reference, see [Reference](../../reference/index.md). + If you're just trying to understand the CVD process, we recommend that you start with the [CERT Guide to Coordinated Vulnerability Disclosure](https://vuls.cert.org/confluence/display/CVD/). + +The CVD process +addresses a human coordination problem that spans individuals and +organizations. As we wrote in [*The CERT* *Guide to Coordinated +Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD): + +!!! quote "Excerpt from *The CERT Guide to Coordinated Vulnerability Disclosure*" + + Perhaps the simplest description of the CVD process is that it starts with at least one individual becoming aware of a vulnerability in a product. + This discovery event immediately divides the world into two sets of people: those who know about the vulnerability, and those who don't. + From that point on, those belonging to the set that knows about the vulnerability iterate on two questions: + + 1. What actions should I take in response to this knowledge? + 2. Who else needs to know what, and when? + + The CVD process continues until the answers to these questions are "nothing," and "nobody." + +### CVD *Is* MPCVD, and MPCVD *Is* CVD + +Any given CVD case is made up of many individual disclosure events, for example, + +- from a Finder to one or more Vendors and/or Coordinators +- from Vendors and Coordinators to other Vendors and Coordinators +- from Finders, Vendors, and Coordinators to Deployers and the Public + +In recent years, software supply chains have evolved such that software library and component vulnerabilities have +become just as much a part of the everyday CVD process as vulnerabilities in Vendors' proprietary code. +This means that many CVD cases we encounter require coordination across multiple vendors. +As a result, we find it decreasingly useful to differentiate between "traditional" (i.e., two-party) CVD and MPCVD. +In this documentation, we use both terms interchangeably. + +$$CVD \iff MPCVD$$ + +Practically speaking, this means that readers should not infer from our use of _CVD_ in one place that we meant to +exclude the multi-party scenario, nor that our use of _MPCVD_ implies the exclusion of the single-vendor CVD scenario. +Instead, our intent is to construct a protocol that adequately addresses the MPCVD scenario where +$N_{vendors} \geq 1$ +and for which the "traditional" CVD case is merely a special (and often simpler) case where +$N_{vendors} = 1$. + +### Context of Our Recent Work + +This documentation, in the context of recent CVD work at the +[CERT/CC](https://www.sei.cmu.edu/about/divisions/cert/index.cfm), +is one of four foundational documents aimed at increasing the +professionalization of the CVD process. The following is the full set of +foundational documents (thus far): + +- *The CERT Guide to Coordinated Vulnerability Disclosure* (the + *CVD Guide*) in both its [original](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=503330) + and [updated](https://vuls.cert.org/confluence/display/CVD) forms, provides a "field guide" perspective to the + CVD process and its natural extension into MPCVD. + +- The [*Stakeholder-Specific Vulnerability Categorization*](https://github.com/CERTCC/SSVC) + provides decision support for prioritizing vulnerability response activities + closely associated with the CVD process. + +- [*A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure*](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) + describes a model that encompasses all possible CVD case histories into a set of measures and metrics for the + efficacy of CVD processes. That report is an expanded version of [*Are We Skillful or Just Lucky? Interpreting the Possible + Histories of Vulnerability Disclosures*](https://dl.acm.org/doi/10.1145/3477431), an article published in the ACM Journal [Digital Threats: Research and Practice](https://dl.acm.org/journal/dtrap). + +- *Designing Vultron*, the report on which this documentation was based, proposes an abstract formal protocol for + MPCVD, ties together various concepts from all three of the above. + +Whereas the [*CVD Guide*](https://vuls.cert.org/confluence/display/CVD) offers a narrative description of both the CVD +process and the many scenarios one can expect to encounter as a Participant therein, in this documentation we provide an +additional layer of formality in the form of a *protocol* for MPCVD. + +### What We Mean by *Protocol* + +We first define what we mean by our use of the term *protocol* by +providing a few common usages from the [Oxford English Dictionary](https://www.oed.com/). + +!!! quote "Oxford English Dictionary on [*protocol*](https://www.oed.com/dictionary/protocol_n?tab=meaning_and_use)" + + (Computing and Telecommunications) A (usually standardized) set of + rules governing the exchange of data between given devices, or the + transmission of data via a given communications channel. + + (In extended use) the accepted or established code of behavior in + any group, organization, or situation; an instance of this. + +!!! question inline end "Why *Vultron*?" + + The working name for our protocol is *Vultron*, an homage to the + fictional robot Voltron. In the Voltron animated series, a team of + protectors joins forces to defend the universe from their adversaries. + Their defensive mission requires a combination of independent defenders + coordinating their efforts to achieve their goals. Like Voltron, our + Vultron Protocol + comprises a combination of humans and the technical processes and + mechanisms that empower them. Together, those humans, processes, and + mechanisms must function both individually and in coordination and + cooperation with others to protect information systems and the people + who depend on them from exploitation by adversaries. + +Both usages are relevant to this effort. +First, insofar as we seek to scale the MPCVD process through the use of automation and software-augmented human +processes, we wish to propose a formal technical protocol that can serve as the basis of such technical tools. +The [Formal Protocol](../../reference/formal_protocol/index.md) section of this documentation addresses this first definition in +specific detail after explicating its component parts and their interactions in +[Report Management](../process_models/rm/index.md), [Embargo Management](../process_models/em/index.md), [Case State](../process_models/cs/index.md), +and [Model Interactions](../process_models/model_interactions). + +Second, recognizing that MPCVD is primarily a coordination process among +human Participants with the goal of remediating extant vulnerabilities +in deployed information systems, a protocol must not only address the +technical formalities of communicating code but also extend to the +expected behaviors of the human Participants that rely on it. In this +second sense, we address the term *protocol* in these ways: + +- The [*CVD Guide*](https://vuls.cert.org/confluence/display/CVD) + offers a *narrative* protocol for practitioners to follow based on + decades of accumulated experience and observation of the + CVD process at the CERT/CC. + +- The [Case State model](../process_models/cs/index.md) from [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) + offers a *prescriptive* protocol outlining the high-level goals of the CVD process, as derived from a first-principles approach to possible + CVD case histories. + +- This documentation and the [report](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=887198) it is based + on describes a *normative* protocol designed to structure and guide practitioners toward those goals. + +To that end, we offer this documentation as a proposal for such an MPCVD protocol. + diff --git a/docs/topics/background/interoperability.md b/docs/topics/background/interoperability.md new file mode 100644 index 00000000..61411395 --- /dev/null +++ b/docs/topics/background/interoperability.md @@ -0,0 +1,92 @@ +# The Need for Interoperability in Coordinated Vulnerability Disclosure + +The overall goal of our Vultron Protocol effort is to achieve *interoperability* among CVD process implementations according to the +broad definition of that term found in the 2004 report, [*Current Perspectives on Interoperability*](https://doi.org/10.1184/R1/6572852.v1) by Brownsword et al.: + +!!! note inline "Brownsword et al. on *Interoperability*" + + The ability of a collection of communicating entities to (a) share + specified information and (b) operate on that information according + to an agreed operational semantics + +This definition encompasses both (a) *syntactic* and (b) *semantic* +interoperability. The goal of this documentation is to lay the foundation for +the *semantic* interoperability of CVD processes across Participants. +*Syntactic* interoperability, in the form of message formats and the +like, is the focus of our ongoing effort. + +Addressing *semantic interoperability* first is a deliberate choice. +If we were to go in the reverse order, we might wind up with systems that +exchange data quickly and accurately yet still fail to accomplish the +mutually beneficial outcomes that MPCVD sets out to achieve. +Carney et al. illustrate the importance of semantic interoperability in their 2005 report +[*Some Current Approaches to Interoperability*](https://doi.org/10.1184/R1/6584258.v1): + +!!! quote "Carney et al. on semantic interoperability" + + There is a limited number of ways that agreements on meaning can be + achieved. In the context of design-time interoperability, semantic + agreements are reached in the same manner as interface agreements + between the constituent systems... However, in the context of run-time + interoperability, the situation is more complex, since there is need + for some manner of universal agreement, so that a new system can join, + ad-hoc, some other group of systems. The new system must be able to + usefully share data and meaning with those other systems, and those + other systems must be able to share data and meaning from an + unfamiliar newcomer. + +In this excerpt, replace the word "system" with the concept of a +"CVD Case Participant," and the need for semantic interoperability as a means of +achieving coordination in MPCVD becomes clear: + +!!! quote "Paraphrasing Carney et al. in the context of CVD" + + \[...\] However, in the context of run-time interoperability, the + situation is more complex, since there is need for some manner of + universal agreement, so that a new CVD Participant can join, ad-hoc, some + other group of CVD Participants \[in a CVD Case\]. The new CVD Case + Participant must be able to usefully share data and meaning with those + other CVD Case Participants, and those other Participants must be able to share data + and meaning from an unfamiliar newcomer. + +Elsewhere in the same [report](https://doi.org/10.1184/R1/6584258.v1), Carney et al. +write, + +!!! quote "Carney et al. on the necessity of trust in interoperability" + + In the hoped-for context of unbounded systems of systems, trust in the + actions and capabilities provided by interoperating parties is + essential. Each party to an interaction must have, develop, or + perceive a sense of whether the actions of interoperating parties can + be trusted. This sense of trust is not Boolean (e.g., parties can be + trusted to varying degrees), is context dependent (Party A can be + trusted in a particular context but not in another), and is time + sensitive (Party A can be trusted for a certain period). Further, the + absence of trust-----distrust-----is less dangerous than misplaced + trust: it is better to know that you cannot trust a particular party + than to misplace trust in a party + +The protocol we propose is intended to promote trust between MPCVD Participants both within an individual case as well +as over time and across cases. + +## Objectives + +The objectives of this documentation are as follows: + +1. Provide a set of common primitives to serve as an ontological + foundation for CVD process definitions across + organizations. + +2. Construct abstract workflows that support the inter-organizational + coordination and synchronization required for the + CVD process to + be successful. + +3. From those primitives and workflows, identify a set of message types + needed for the CVD process to function. + +4. Provide high-level requirements for the semantic content of those + message types. + +5. Explore options for the syntactic representation of those message + types. diff --git a/docs/topics/background/notation.md b/docs/topics/background/notation.md new file mode 100644 index 00000000..cab3f8c1 --- /dev/null +++ b/docs/topics/background/notation.md @@ -0,0 +1,179 @@ +# Notation + +{% include-markdown "../../includes/not_normative.md" %} + +Defining the Vultron Protocol involves a lot of notation. +This page provides a reference for the conventions and notation used throughout the documentation. + +## Documentation Conventions + +We are using the [_Admonitions_](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) (call-outs) provided by +[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to highlight specific types of information in this +documentation. + +!!! note "" + + Statements in boxes like this are normative requirements. + Use of SHOULD, MUST, MAY, etc. follow the [RFC 2119](https://tools.ietf.org/html/rfc2119) conventions. + +!!! note "Formalisms" + + Formalisms are used to define the behavior of the Vultron Protocol. + + $$A = A$$ + + Readers should generally be able to understand the protocol description in the text without understanding the formalisms, + but the formalisms are included for completeness. + +!!! info + + Statements in boxes like this are informative notes. + They provide additional information that may be helpful in understanding the normative requirements. + +!!! tip + + Statements in boxes like this are tips. + They provide additional information that might point to other resources, or provide additional context that may be + helpful in understanding the protocol. + +!!! quote + + This is a quote. + +!!! example + + This is an example. + It is also an example example. + +!!! question + + What is a question? This is. + +!!! success + + We use this (as you'll see below) as an indicator that a page contains + normative content. + +!!! warning + + This is a warning. + +Material for MkDocs supports a number of other [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/). +We're generally trying to keep our usage consistent with the admonition names used in the Material for MkDocs +[documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/), but we'd also like to list the +ones we use here for completeness and clarity. +If you spot us using one that is not listed here, or being inconsistent with the above in our usage, please let us +know by [opening an issue](https://github.com/CERTCC/Vultron/issues). + +### Normative and Non-Normative Pages + +Not everything we say about the Vultron Protocol is a normative requirement. +We use the following conventions to indicate whether a page contains normative requirements or not. + +!!! info "Recognizing Normative Pages" + + {% include-markdown "../../includes/normative.md" %} + + Pages that contain normative requirements are marked with a banner at or near the top of the page: + +!!! info "Recognizing Non-Normative Pages" + + {% include-markdown "../../includes/not_normative.md" %} + + Pages that do not contain normative requirements are marked with a banner at or near the top of the page (Like this one). + This banner may be omitted if the page is clearly non-normative. + We include it on pages where that may not be clear, for example on pages where we are describing a specific implementation + in terms of SHOULD, MUST, MAY, etc. statements, but those statements are not intended to be normative requirements. + + +## Mathematical Notation + +In all of these definitions, we take the standard [Zermelo-Fraenkel set theory](https://en.wikipedia.org/wiki/Zermelo%E2%80%93Fraenkel_set_theory). +We adopt the following notation: + +!!! info "Set Theory Symbols" + + | Symbol | Meaning | + | :--- | :--- | + | $\{ \dots \}$ | depending on the context: (1) an ordered set in which the items occur in that sequence, or (2) a tuple of values | + | \|$x$\| | the count of the number of elements in a list, set, tuple, or vector $x$ | + | $\subset,=,\subseteq$ | the normal proper subset, equality, and subset relations between sets | + | $\in$ | the membership (is-in) relation between an element and the set it belongs to | + | $\prec$ | the precedes relation on members of an ordered set: $\sigma_i \prec \sigma_j \textrm{ if and only if } \sigma_i,\sigma_j \in s \textrm{ and } i < j$ where $s$ is an ordered set | + | \|$X$\| | the size of (the number of elements in) a set $X$ | + | $\langle X_i \rangle^N_{i=1}$ | a set of $N$ sets $X_i$, indexed by $i$; used in the [Formal Protocol](../../reference/formal_protocol/index.md) in the context of Communicating Finite State Machines, taken from the article [On Communicating Finite State Machines](https://doi.org/10.1145/322374.322380) by Brand and Zafiropulo | + +!!! info "Logic Symbols" + + | Symbol | Meaning | + | :--- | :--- | + | $\implies$ | implies | + | $\iff$ | if-and-only-if (bi-directional implication) | + | $\wedge$ | the logical AND operator | + | $\lnot$ | the logical NOT operator | + +!!! info "Directional Messaging Symbols" + + | Symbol | Meaning | + | :--- | :--- | + | $\rightharpoonup{}$ | a message emitted (sent) by a process | + | $\leftharpoondown{}$ | a message received by a process | + +!!! info "DFA Symbols" + + | Symbol | Meaning | + | :--- | :--- | + | $\xrightarrow{}$ | a transition between states, usually labeled with the transition type (e.g., $\xrightarrow{a}$) | + | $(\mathcal{Q},q_0,\mathcal{F},\Sigma,\delta)$ | specific symbols for individual DFA components that are introduced when needed in Chapters | + | $\Big \langle { \langle S_i \rangle }^N_{i=1}, { \langle o_i \rangle }^N_{i=1}, { \langle M_{i,j} \rangle}^N_{i,j=1}, { succ } \Big \rangle$ | formal protocol symbols that are introduced at the beginning of the [Formal Protocol](../../reference/formal_protocol/index.md) | + +## Diagram Notation + +We use a variety of diagramming techniques throughout the documentation. + +### State Diagrams + +Our depictions of DFA as figures use common state diagram symbols as shown in the example below. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> q0 + q0 --> q1 : a + q0 --> q2 : b + q1 --> q2 : a + q1 --> q1 : b + q2 --> q0 : a + q2 --> q1 : b + q2 --> [*] +``` + +### Sequence and Class Diagrams + +We follow UML conventions for sequence and class diagrams + +```mermaid +--- +title: Sequence Diagram Example +--- +sequenceDiagram + participant A as Alice + participant B as Bob + A ->> B: Authentication Request + B->>A: Authentication Response +``` + +```mermaid +--- +title: Class Diagram Example +--- +classDiagram + Class01 <|-- Class02 + Class03 *-- Class04 + Class05 o-- Class06 + Class07 .. Class08 +``` + +### Behavior Tree Diagrams + +We introduce a few additional notation details specific to [Behavior Trees](../behavior_logic/index.md) when needed. diff --git a/docs/topics/background/overview.md b/docs/topics/background/overview.md new file mode 100644 index 00000000..cffbf6a3 --- /dev/null +++ b/docs/topics/background/overview.md @@ -0,0 +1,75 @@ +# Documentation Overview + +MPCVD is comprised of independent Participants performing their own CVD-related processes. + +## Process Models + +Those processes can be represented by Finte State Machines (FSMs), specifically as Deterministic Finite Automata (DFAs). +CVD processes (and the DFAs representing them) can be decomposed hierarchically. +We propose three main DFAs as the core of our Vultron Protocol: + +1. A [Report Management](../process_models/rm/index.md) DFA represents each CVD Participant's engagement with a particular report +2. An [Embargo Management](../process_models/em/index.md) DFA negotiates and establishes the timing of future disclosures and publications +3. A [Case State](../process_models/cs/index.md) DFA tracks the events in [CVD Substates](../process_models/cs/index.md#cvd-case-substates), + as originally described in [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513). + +[Model Interactions](../process_models/model_interactions/index.md) contains a discussion of the interactions +among these three state machine models. + +## Formal Protocol + +However, a set of agents independently executing processes is not coordinated, and if they are not coordinated, +then whatever they are doing does not deserve the name CVD. +Hence, there is a need for a protocol to describe the interactions necessary to coordinate these processes. +[Communicating FSMs](https://doi.org/10.1145/322374.322380) provide a formal way to define a communications protocol, which coordinates the activities of +independent DFAs through the interchange (e.g., sending and receiving) of messages. +We map our multiple DFA model onto a formal protocol definition in [Formal Protocol](../../reference/formal_protocol/index.md). + +### Behavior Logic + +An MPCVD protocol needs to do more than just provide formally defined communication mechanisms. +It also needs to normalize the expected behaviors and activities that the communication protocol enables. +In this sense, our protocol expands upon +[ISO/IEC 29147:2018](https://www.iso.org/standard/72311.html), +[ISO/IEC 30111:2019](https://www.iso.org/standard/69725.html), +and +[ISO/IEC TR 5895:2022](https://www.iso.org/standard/81807.html), +which, taken together, provide a high-level normative standard for CVD activities. + +Developed in response to the growing complexity of video game Non-Player Character (NPC) Artificial Intelligence (AI) +Finite State Machines (FSMs), Behavior Trees offer a way to organize and describe agent behaviors in a straightforward, +understandable way. +Using Behavior Trees, agent processes can be modeled as sets of behaviors (e.g., pre-conditions, actions, and +post-conditions) and the logic that joins them together. +Today, Behavior Trees are used in video game software to develop realistic NPCs and in robotics to create reactive and +adaptive behaviors from autonomous agents. +Behavior Trees offer a high potential for automating complex tasks through a hierarchical decomposition of the logic and +actions required to complete those tasks. + +The behaviors we are interested in modeling are the various CVD activities described in the +[*CVD Guide*](https://vuls.cert.org/confluence/display/CVD) (e.g., find contacts, send reports, validate reports, +prioritize reports, create fixes, publish reports, publish fixes, deploy fixes). +We use [Behavior Trees](../behavior_logic/index.md) to describe MPCVD Participant activities and their interactions with +the [formal protocol](../../reference/formal_protocol/index.md). + +## Implementation Notes + +Additional [implementation notes](../../howto/index.md), including a simplified case data model, are provided. + +Future work is discussed in [Future Work](../future_work/index.md). + +## Reference Material + +Reference material includes + +- the [Formal Protocol](../../reference/formal_protocol/index.md) description +- an [ISO Crosswalk](../../reference/iso_crosswalk.md) contains a detailed crosswalk of our + protocol with ISO/IEC 29147:2018 *Vulnerability Disclosure*, ISO/IEC + 30111:2019 *Vulnerability Handling Processes*, and ISO/IEC TR 5895:2022 + *Multi-party coordinated vulnerability disclosure and handling*. +- an [SSVC Crosswalk](../../reference/ssvc_crosswalk.md) provides a mapping between the Vultron Protocol + and relevant portions of the [Stakeholder Specific Vulnerability Categorization](https://github.com/CERTCC/SSVC) + ([SSVC](https://github.com/CERTCC/SSVC)), a vulnerability response prioritization + model also developed by the CERT/CC +- a [Glossary](../../reference/glossary.md) of terms used in this documentation + diff --git a/docs/topics/background/terms.md b/docs/topics/background/terms.md new file mode 100644 index 00000000..830c713b --- /dev/null +++ b/docs/topics/background/terms.md @@ -0,0 +1,69 @@ +# Terms and Definitions + +Throughout this documentation, we refer to CVD Roles from the [*CERT Guide to Coordinated +Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD): + +!!! info "Finder" + + The individual or organization that identifies the vulnerability + +!!! info "Reporter" + + The individual or organization that notifies the vendor of the + vulnerability + +!!! info "Vendor (Supplier)" + + The individual or organization that created or maintains the + vulnerable product + +The *Vendor* role is synonymous with the *Supplier* role as it appears +in [SSVC](https://github.com/CERTCC/SSVC) Version 2 and above. + +!!! info "Deployer (User)" + + The individual or organization that must deploy a patch or take + other remediation action + +The *Deployer* role is synonymous with the *User* role in +[ISO/IEC 29147:2018](https://www.iso.org/standard/72311.html) +and +[ISO/IEC 30111:2019](https://www.iso.org/standard/69725.html), +while the other roles are named consistent with those standards. + +!!! info "Coordinator" + + An individual or organization that facilitates the coordinated + response process + + +We also add a new role in this documentation, which we expect to incorporate +into a future version of the *CVD Guide*: + +!!! info "Exploit Publisher" + + An individual or organization that publishes exploits + +Exploit Publishers might be the same as Finders, Reporters, Coordinators, or +Vendors, but this is not guaranteed. +For example, Vendors that produce tools for Cybersecurity Red Teams might play a combination +of roles: Finder, Reporter, Vendor, Coordinator, and/or Exploit Publisher. + +Finally, we have a few additional terms to define: + +!!! info "CVD Case (Case)" + + The unit of work for the overall CVD process for a specific vulnerability + spanning the individual CVD Case Participants and their respective processes + +!!! info "CVD Case Participant (Participant)" + + Finder, Vendor, Coordinator, Deployer, etc., as defined above + +!!! info "Vulnerability Report (Report)" + + The unit of work for an individual Case Participant's [Report Management (RM) process](../process_models/rm/index.md) + +A diagram showing the relationship between CVD Cases, Participants, and Reports can be +found in [Case Object](../../howto/case_object.md). + diff --git a/docs/topics/background/versioning.md b/docs/topics/background/versioning.md new file mode 100644 index 00000000..fa53f7d0 --- /dev/null +++ b/docs/topics/background/versioning.md @@ -0,0 +1,34 @@ +# Vultron Protocol Version Numbering Scheme + +!!! note inline end "Implementations may have their own versioning scheme" + + The versioning scheme described here applies _only_ to the Vultron Protocol itself. + Implementations of the Vultron Protocol are expected to have their own versioning schemes. + +{% include-markdown "../../includes/curr_ver.md" %} + +While we have not yet mapped out a future release schedule, in +anticipation of future revisions, we have chosen a semantic versioning +scheme for the Vultron Protocol. Specifically, Vultron Protocol versions will be +assigned according to the format `MAJOR.MINOR.MICRO`, where + +- `MAJOR` represents the zero-indexed major version for the release. + +- `MINOR` represents a zero-indexed counter for minor releases that + maintain compatibility with their MAJOR version. + +- `MICRO` represents an optional zero-indexed micro-version (patch) + counter for versions that update a MINOR version. + +Trailing zero values may be omitted (e.g., `3.1` and `3.1.0` denote the +same version, similarly `5` and `5.0`). It may be useful at some point +to use pre-release tags such as `-alpha`, `-beta`, `-rc` (with optional +zero-indexed counters as needed), but we reserve that decision until +their necessity becomes clear. The same goes for build-specific tags; +while we do not currently have a use for them, we do not rule out their +future use. + +Because of the early nature of the current protocol, as of this writing, +no backward compatibility commitments are made or implied within the `0.x` versions. +We anticipate this commitment will change as we get closer to a major release. + diff --git a/docs/topics/behavior_logic/acquire_exploit_bt.md b/docs/topics/behavior_logic/acquire_exploit_bt.md new file mode 100644 index 00000000..9e47bd23 --- /dev/null +++ b/docs/topics/behavior_logic/acquire_exploit_bt.md @@ -0,0 +1,47 @@ +# Acquire Exploit Behavior + +Some Vendors or other CVD Participants might require a proof-of-concept exploit to accompany an incoming report for it +to pass their validation checks. +To that end, an Acquire Exploit Behavior Tree is shown below. + +```mermaid +--- +title: Acquire Exploit Behavior Tree +--- +flowchart LR + fb["?"] + have_exploit(["have exploit?"]) + fb --> have_exploit + seq["→"] + fb --> seq + fb2["?"] + seq --> fb2 + exp_priority(["exploit priority
set?"]) + fb2 --> exp_priority + eval_priority["evaluate
priority"] + fb2 --> eval_priority + exp_desired(["exploit desired?"]) + seq --> exp_desired + fb3["?"] + seq --> fb3 + find_exploit["find exploit"] + fb3 --> find_exploit + dev_exploit["develop exploit"] + fb3 --> dev_exploit + pay_exploit["purchase exploit"] + fb3 --> pay_exploit +``` + +The goal of this behavior is for the Participant to be in possession of an exploit. + +If the Participant does not already have one, the main acquisition +sequence is triggered. The sequence begins by ensuring that the exploit +acquisition activity has sufficient priority to continue. If it does, +the Participant has one of three options to choose from: they can find +one somewhere else, develop it themselves, or pay someone for the +privilege. + +The overall behavior returns *Success* when either an exploit is +acquired or when one is not desired and is therefore deferred. It can +fail in the scenario where an exploit is desired but not acquired. + diff --git a/docs/topics/behavior_logic/cvd_bt.md b/docs/topics/behavior_logic/cvd_bt.md new file mode 100644 index 00000000..ffba0604 --- /dev/null +++ b/docs/topics/behavior_logic/cvd_bt.md @@ -0,0 +1,57 @@ +# CVD Behavior Tree + +We begin at the root node of the CVD Behavior Tree shown in the figure below. +The root node is a simple loop that continues until an interrupt condition is met, representing the idea +that the CVD practice is meant to be continuous. In other words, we are intentionally not specifying the interrupt condition. + +```mermaid +--- +title: CVD Behavior Tree +--- +flowchart LR + root["#8634;"] + seq["→"] + discover_vulnerability["Discover Vulnerability"] + receive_messages["Receive Messages"] + report_management["Report Management"] + embargo_management["Embargo Management"] + root --> seq + seq -->|A| discover_vulnerability + seq -->|B| receive_messages + seq -->|C| report_management + seq -->|D| embargo_management +``` + +The main sequence is comprised of four main tasks: + +- (A) [*Discover Vulnerability.*](vuldisco_bt.md) Although not all Participants have the + ability or motive to discover vulnerabilities, we include it as a + task here to call out its importance to the overall + CVD process. This task returns *Success* regardless of whether a vulnerability is found to allow execution to + pass to the next task. + +- (B) [*Receive Messages*](msg_intro_bt.md). All coordination in CVD between Participants is done through + the exchange of messages, regardless of how those messages are + conveyed, stored, or presented. The receive messages task represents + the Participant's response to receiving the various messages defined + in the [formal protocol](../../reference/formal_protocol/index.md). Due to the degree of detail + required to cover all the various message types, decomposition of + this task node is deferred until [later](msg_intro_bt.md) so we can cover the next two items + first. Before we proceed, it is sufficient to know that a new report arriving in the *receive messages* behavior + sets $q^{rm} \in S \xrightarrow{r} R$ and returns *Success*. + +- (C) [*Report Management*](rm_bt.md). This task embodies the [RM process](../process_models/rm/index.md) + as integrated into the [formal protocol](../../reference/formal_protocol/index.md). + +- (D) [*Embargo Management*](em_bt.md). Similarly, this task represents the + [EM process](../process_models/em/index.md) as integrated into the [formal protocol](../../reference/formal_protocol/index.md). + +A further breakdown of a number of CVD tasks that fall outside the scope of the +[formal protocol](../../reference/formal_protocol/index.md) can be found in +[Do Work](do_work_bt.md). +In that section, we examine a number of behaviors that Participants may include as part of the work they do for reports +in the _Accepted_ RM state ($q^{rm}\in A$). + +Behaviors and state changes resulting from changes to the [CS model](../process_models/cs/index.md) are scattered throughout the other Behavior Trees +where relevant. + diff --git a/docs/topics/behavior_logic/deployment_bt.md b/docs/topics/behavior_logic/deployment_bt.md new file mode 100644 index 00000000..81021e17 --- /dev/null +++ b/docs/topics/behavior_logic/deployment_bt.md @@ -0,0 +1,110 @@ +# Deployment Behavior {#sec:deployment_bt} + +The Deployment Behavior Tree is shown in the figure below. +The goal of this behavior is either for (A) the case to reach the $q^{cs} \in D$ state or (B) for the Participant to be +comfortable with remaining in a *Deferred* deployment state. + +```mermaid +--- +title: Deployment Behavior Tree +--- +flowchart LR + fb["?"] + cs_d(["$CS in D?"]) + fb -->|A| cs_d + rm_d_seq["→"] + fb -->|B| rm_d_seq + rm_d(["RM in D"]) + rm_d_seq --> rm_d + rm_d_no_new_info([no new info?]) + rm_d_seq --> rm_d_no_new_info + dep_seq["→"] + fb -->|C| dep_seq + role_is_deployer(["role is deployer?"]) + dep_seq -->|C1| role_is_deployer + dep_fb["?"] + dep_seq -->|C2| dep_fb + rm_in_d_or_a(["RM in D or A?"]) + dep_fb --> rm_in_d_or_a + da_seq["→"] + dep_fb --> da_seq + prioritize_dep["prioritize deployment"] + da_seq --> prioritize_dep + da_not_deferred(["priority not deferred?"]) + da_seq --> da_not_deferred + da_rm_to_a["RM → A
(emit RA)"] + da_seq --> da_rm_to_a + da_rm_to_d["RM → D
(emit RD)"] + dep_fb --> da_rm_to_d + dep_fb2["?"] + dep_seq -->|C3| dep_fb2 + df2_rm_d(["RM in D?"]) + dep_fb2 --> df2_rm_d + df2_cs_VFD(["CS in VFD...?"]) + dep_fb2 --> df2_cs_VFD + dseq["→"] + dep_fb2 --> dseq + dsfb["?"] + dseq --> dsfb + role_is_vendor(["role is vendor?"]) + dsfb --> role_is_vendor + dsfb_cs_dP(["CS in ..dP..?"]) + dsfb --> dsfb_cs_dP + ds_cs_VFd(["CS in VFd...?"]) + dseq --> ds_cs_VFd + ds_deploy_fix["deploy fix"] + dseq --> ds_deploy_fix + dseq_to_d["CS ..d... → ..D...
(emit CD)"] + dseq --> dseq_to_d + mit_dep(["mitigations deployed?"]) + dep_fb2 --> mit_dep + mseq["→"] + dep_fb2 --> mseq + m_mit_avail(["mitigations available?"]) + mseq --> m_mit_avail + m_deploy_mit(["deploy mitigation"]) + mseq --> m_deploy_mit + mon_seq["→"] + fb -->|D| mon_seq + mon_req(["monitoring required?"]) + mon_seq --> mon_req + mon["monitor deployment"] + mon_seq --> mon +``` + +Assuming neither of these conditions has been met, the main deployment sequence (C) falls to the Deployer role (C1). +It consists of two subprocesses: prioritize deployment and deploy. + +The prioritize deployment behavior is shown in (C2) the fallback node in the center of the diagram. +The subgoal is for the deployment priority to be established, as indicated by the Deployer's RM state $q^{rm} \in \{D,A\}$. +For example, a Deployer might use the [SSVC Deployer Tree](https://github.com/CERTCC/SSVC) to decide whether (and when) +to deploy a fix or mitigation. +If the deployment priority evaluation indicates further action is needed, + +- the report management state is set to $q^{rm} \in A$ +- an $RA$ message is emitted, and +- the overall prioritization behavior succeeds + +Otherwise, when the deployment is *Deferred*, it results in a transition to state $q^{rm} \in D$ and +emission of an $RD$ message. + +(C3) The deploy behavior is shown in the second fallback node of the center sequence (C). +It short-circuits to *Success* if either the deployment is *Deferred* or has already occurred. +The main sequence can fire in two cases: + +1. when the Deployer is also the Vendor and a fix is ready + ($q^{cs} \in F$) +2. when the Deployer is not the Vendor but the fix is both ready and + public ($q^{cs} \in P$ and $q^{cs} \in F$) + +Assuming either of these conditions is met, + +- the deploy fix task can run, +- the case status is updated to $q^{cs} \in D$, and +- $CD$ emits on *Success* + +Should the deployment sequence fail for any reason, a fallback is possible if undeployed mitigations are available. + +(D) Finally, returning to the top part of the tree, Participants might choose to monitor the deployment process should they +have the need to. + diff --git a/docs/topics/behavior_logic/do_work_bt.md b/docs/topics/behavior_logic/do_work_bt.md new file mode 100644 index 00000000..5a0c3240 --- /dev/null +++ b/docs/topics/behavior_logic/do_work_bt.md @@ -0,0 +1,55 @@ +# Do Work Behavior Tree + +Although it is not directly addressed by the [formal Vultron Protocol](../../reference/formal_protocol/index.md), the *do work* node +of the [RM Behavior Tree](rm_bt.md) is where much of the CVD effort happens. +As a result, it is worth spending some time reviewing what some of the underlying work actually entails. + +In this section, we will expand on the set of behaviors shown in the diagram below. + +!!! tip inline end "Why is this a parallel node?" + The *do work* node is a parallel node because it is not necessary for a Participant to complete all of these tasks + in order to complete their CVD work. + We intentionally do not specify any *Success* criteria regarding what fraction of its children must succeed. + Decisions about which (and how many) of the following tasks are necessary for a Participant to complete work + on their $Accepted$ CVD cases are left to the discretion of individual Participants. + +```mermaid +--- +title: Do Work Behavior Tree +--- +flowchart LR + par["#8649;
m/n"] + deployment["deployment"] + par --> deployment + dev_fix["develop fix"] + par --> dev_fix + reporting["report to others"] + par --> reporting + publication["publication"] + par --> publication + monitor["monitor threats"] + par --> monitor + assign_cve["assign CVE ID"] + par --> assign_cve + exploit_acq["acquire exploit"] + par --> exploit_acq + other["other work"] + par --> other +``` + + Specifically, we will cover the following +tasks, each in its own subsection. + +- [Deployment](deployment_bt.md) +- [Developing a fix](fix_dev_bt.md) +- [Reporting to others](reporting_bt.md) +- [Publication](publication_bt.md) +- [Monitoring threats](monitor_threats_bt.md) +- [Assigning CVE IDs](id_assignment_bt.md) +- [Acquiring exploits](acquire_exploit_bt.md) + +The *other work* task is included as a placeholder for any Participant-specific tasks not represented here. + + + + diff --git a/docs/topics/behavior_logic/em_bt.md b/docs/topics/behavior_logic/em_bt.md new file mode 100644 index 00000000..d396a82d --- /dev/null +++ b/docs/topics/behavior_logic/em_bt.md @@ -0,0 +1,138 @@ +# Embargo Management Behavior Tree {#sec:em_bt} + +The Embargo Management Behavior Tree is shown in the figure below. +It follows the state transition function in the +[Embargo Management Process Model](../process_models/em/index.md#em-state-transitions). +Recall that the EM process begins in the $q^{em} \in N$ state and ends in one of two states: + +- in the *eXited* ($q^{em} \in X$) state after having established an + *Active* embargo, or +- in the *None* ($q^{em} \in N$) state after having exhausted all + attempts to reach an agreement + +```mermaid +--- +title: Embargo Management Behavior Tree +--- +flowchart LR + fb[?] + rm_s_or_c(["RM S or C?"]) + fb -->|A| rm_s_or_c + em_x(["EM X?"]) + fb -->|B| em_x + seq1["→"] + fb -->|C| seq1 + cs_not_pxa(["CS not in pxa?"]) + seq1 --> cs_not_pxa + em_none(["EM N?"]) + seq1 --> em_none + n_seq["→"] + fb -->|D| n_seq + n_em_none(["EM N?"]) + n_seq --> n_em_none + n_fb[?] + n_seq --> n_fb + n_stop_trying(["stop trying?"]) + n_fb --> n_stop_trying + n_propose(["propose"]) + n_fb --> n_propose + p_seq["→"] + fb -->|E| p_seq + p_em_prop(["EM P?"]) + p_seq --> p_em_prop + p_fb[?] + p_seq --> p_fb + p_terminate["terminate"] + p_fb --> p_terminate + p_jump["evaluate"] + p_fb --> p_jump + p_fb_seq["→"] + p_fb --> p_fb_seq + p_reject["reject"] + p_fb_seq --> p_reject + p_em_to_n["EM P → N
(emit ER)"] + p_fb_seq --> p_em_to_n + a_seq["→"] + fb -->|F| a_seq + a_em_a(["EM A?"]) + a_seq --> a_em_a + a_fb[?] + a_seq --> a_fb + a_terminate["terminate"] + a_fb --> a_terminate + a_current_terms(["current terms ok?"]) + a_fb --> a_current_terms + a_propose["propose"] + a_fb --> a_propose + r_seq["→"] + fb -->|G| r_seq + r_em_r(["EM R?"]) + r_seq --> r_em_r + r_fb[?] + r_seq --> r_fb + r_terminate["terminate"] + r_fb --> r_terminate + r_jump["evaluate"] + r_fb --> r_jump + r_fb_seq["→"] + r_fb --> r_fb_seq + r_reject["reject"] + r_fb_seq --> r_reject + r_em_to_a["EM R → A
(emit EJ)"] + r_fb_seq --> r_em_to_a +``` + +(A) The tree starts with a check to see whether no report has arrived or +whether the report has already *Closed* ($q^{rm} \in \{S{,}C\}$). If +either of these conditions is met, no further effort is needed, and the +tree succeeds. + +(B) Next, the tree checks whether the embargo has already +*eXited* ($q^{em} \in X$). If it has, that leads the tree to succeed. + +(C) Failing that, the treat checks to see if the case has moved outside the +"habitable zone" for embargoes. The ${q^{cs}\not\in\cdot\cdot\cdot pxa}$ +condition is true when attacks have been observed, an exploit has been +made public, or information about the vulnerability has been made +public. If one of those conditions is met and the embargo state is +*None* ($q^{em} \in N$), the check returns *Success*, and the tree +terminates, consistent with +[Negotiating Embargoes](../process_models/em/negotiating.md). + +!!! tip inline end "See also" + + - [Negotiating Embargoes](../process_models/em/negotiating.md) + - [Propose Embargo Behavior](em_propose_bt.md) + - [Terminate Embargo Behavior](em_terminate_bt.md) + - [Evaluate Embargo Behavior](em_eval_bt.md) + +Otherwise, we continue through each remaining EM state. + +(D) When there is no embargo and there are no outstanding proposals ($q^{em} \in N$), the only options are to +either stop trying or [propose](em_propose_bt.md) a new embargo. +The decision to stop trying to achieve an embargo is left to individual Participants, although we did provide some relevant guidance in +[Negotiating Embargoes](../process_models/em/negotiating.md). + +(E) When there is an outstanding embargo proposal ($q^{em} \in P$), we first attempt the [terminate](em_terminate_bt.md) task. +This task returns *Success* if there is a reason for ${q^{em} \in P \xrightarrow{r} N}$. + +At this point, if there is no reason to [terminate](em_terminate_bt.md), +we proceed to the [evaluate](em_eval_bt.md) task described below. +The evaluate task returns *Success* if either the proposal is accepted or a counterproposal is made. + +Assuming neither of these succeeds, we proceed to reject the proposal, returning to +$q^{em} \in N$ and emitting a corresponding $ER$ message. + +(F) The process within the *Active* ($q^{em} \in A$) state is similarly straightforward. +If there is reason to [terminate](em_terminate_bt.md) the embargo, do so. +Otherwise, either the current embargo terms are acceptable, or a new embargo should be proposed. + +(G) Finally, we handle the *Revise* EM state ($q^{em} \in R$). +The structure of this branch mirrors that of the *Proposed* state discussed above. +Again, we check to see if there is cause to [terminate](em_terminate_bt.md) doing so, if needed. +If termination is not indicated, we proceed once again to [evaluate the proposed revision](em_eval_bt.md), either accepting +or countering the proposal. +When neither of these succeed, the revision is rejected and the EM state returns to $q^{em} \in A$ with the +original embargo terms intact. +An $EJ$ message conveys this information to the other Participants. + diff --git a/docs/topics/behavior_logic/em_eval_bt.md b/docs/topics/behavior_logic/em_eval_bt.md new file mode 100644 index 00000000..edcba2a7 --- /dev/null +++ b/docs/topics/behavior_logic/em_eval_bt.md @@ -0,0 +1,42 @@ +# Evaluate Proposed Embargo Behavior + +The acceptance or counterproposal of an embargo is handled by the Evaluate Proposed Embargo Behavior Tree shown in the +figure below. + +```mermaid +--- +title: Evaluate Proposed Embargo Behavior Tree +--- +flowchart LR + fb[?] + seq1["→"] + fb -->|A| seq1 + eval["evaluate"] + seq1 --> eval + accept["accept"] + seq1 --> accept + em_to_a["EM → A
(emit EA)"] + seq1 --> em_to_a + seq2["→"] + fb -->|B| seq2 + will_counter(["willing to counter?"]) + seq2 --> will_counter + propose["propose"] + seq2 --> propose +``` + +(A) As noted [above](em_bt.md), the same process applies to both the *Proposed* and *Revise* EM states ($q^{em} \in \{P,R\}$). +An evaluation task is followed by an accept task. +These tasks are placeholders for the actual decision-making process, which is left to individual Participants. +In both cases, acceptance leads to an EM state transition to $q^{em} \in A$ and emission of an $EA$ message. + +!!! tip inline end "See also" + + - [Propose Embargo Behavior](em_propose_bt.md) + +(B) On the other hand, the proposed terms may not be acceptable. +In this case, the Participant might be willing to offer a counterproposal. +The counterproposal is covered by the [propose](em_propose_bt.md) behavior. + + + diff --git a/docs/topics/behavior_logic/em_propose_bt.md b/docs/topics/behavior_logic/em_propose_bt.md new file mode 100644 index 00000000..fe774933 --- /dev/null +++ b/docs/topics/behavior_logic/em_propose_bt.md @@ -0,0 +1,66 @@ +# Propose Embargo Behavior + +The Propose Embargo Behavior Tree is shown in the figure below. + +```mermaid +--- +title: Propose Embargo Behavior Tree +--- +flowchart LR + seq["→"] + cs_pxa(["CS in ...pxa?"]) + seq -->|A| cs_pxa + fb1[?] + seq -->|B| fb1 + cs_d(["CS ..d...?"]) + fb1 --> cs_d + other(["other reason"]) + fb1 --> other + select["select terms"] + seq -->|C| select + fb2[?] + seq -->|D| fb2 + pr_seq["→"] + fb2 -->|D1| pr_seq + em_p_or_r(["EM P or R?"]) + pr_seq --> em_p_or_r + no_new_prop(["no new proposal?"]) + pr_seq --> no_new_prop + np_seq["→"] + fb2 -->|D2| np_seq + em_n_or_p(["EM N or P?"]) + np_seq --> em_n_or_p + em_to_p["EM → P
(emit EP)"] + np_seq --> em_to_p + ar_seq["→"] + fb2 -->|D3| ar_seq + em_a_or_r(["EM A or R?"]) + ar_seq --> em_a_or_r + em_to_r["EM → R
(emit EV)"] + ar_seq --> em_to_r +``` + +!!! tip inline end "See also" + + - [Negotiate Embargoes](../process_models/em/negotiating.md) + - [Default Embargoes](../process_models/em/defaults.md) + +It consists of a sequence that begins with (A,B) a check for embargo viability as outlined in +[Negotiating Embargoes](../process_models/em/negotiating.md). + +Once the checks succeed, it proceeds to (C) selecting embargo terms to propose. +Implementations of this task might simply draw from a default policy, as in +[Default Embargoes](../process_models/em/defaults.md), or it might be a case-specific decision made by a Participant. + +(D) Embargo terms can be proposed from any of the non-*eXited* states ($q^{em} \in \{N,P,A,R\}$). + +(D1) If a new or revised embargo has already been proposed ($q^{em} \in \{P,R\}$, the tree then checks whether a counterproposal is desired. +Assuming it is not, no proposal is made, and the behavior succeeds. + +Otherwise, (D2) proposals from state $q^{em} \in N$ emit $EP$ and transition $q^{em} \xrightarrow{p} P$, +whereas (D3) those from $q^{em} \in A$ emit $EV$ and move to $q^{em} \xrightarrow{p} R$. + +Proposals from states $q^{em} \in P$ (D2) or $q^{em} \in R$ (D3) represent counterproposals and, therefore, do not change +the EM state. +They do, however, emit $EP$ or $EV$ messages as appropriate. + diff --git a/docs/topics/behavior_logic/em_terminate_bt.md b/docs/topics/behavior_logic/em_terminate_bt.md new file mode 100644 index 00000000..4c918502 --- /dev/null +++ b/docs/topics/behavior_logic/em_terminate_bt.md @@ -0,0 +1,72 @@ +# Terminate Embargo Behavior + +The Terminate Embargo Behavior Tree is shown in the diagram below. +It consists of two major behaviors depending on whether an embargo has been established or not. + +```mermaid +--- +title: Terminate Embargo Behavior Tree +--- +flowchart LR + fb[?] + em_n_or_x(["EM N or X?"]) + fb -->|A| em_n_or_x + p_seq["→"] + fb -->|B| p_seq + em_p(["EM P?"]) + p_seq --> em_p + p_fb[?] + p_seq --> p_fb + p_cs_not_pxa(["CS not in ...pxa?"]) + p_fb --> p_cs_not_pxa + other(["other reason?"]) + p_fb --> other + p_em_to_n["EM P → N
(emit ER)"] + p_seq --> p_em_to_n + ar_seq["→"] + fb -->|C| ar_seq + em_a_or_r(["EM A or R?"]) + ar_seq --> em_a_or_r + ar_fb[?] + ar_seq --> ar_fb + ar_cs_not_pxa(["CS not in ...pxa?"]) + ar_fb --> ar_cs_not_pxa + ar_timer_expired(["timer expired?"]) + ar_fb --> ar_timer_expired + ar_other(["other reason?"]) + ar_fb --> ar_other + ar_exit_embargo["exit embargo"] + ar_seq --> ar_exit_embargo + ar_em_to_x["EM → X
(emit ET)"] + ar_seq --> ar_em_to_x +``` + +(A) If the EM state is *None* or *eXited*, ($q^{em} \in \{N{,}X\}$), the tree succeeds immediately. + +(B) The next node handles the scenario where no embargo has been established. +The behavior descends into a sequence that checks whether we are in $Proposed$ ($q^{em} \in P$). +If we are, we check to see if there is a reason to exit the embargo negotiation process. +One such reason is that the case state is outside the embargo "habitable zone," but there may be others that we leave +unspecified. +If any reason is found, then the proposal is rejected, the state returns to *None*, and an $ER$ message is sent. + +(C) Should that branch fail, we still need to handle the situation where an embargo has already been established. +Following a confirmation that we are in either *Active* or *Revise*, we again look for reasons to exit, this time +adding the possibility of timer expiration to the conditions explicitly called out. +Terminating an existing embargo might have some other teardown procedures to be completed, which we represent as the +*exit embargo* task. +Finally, the EM state is updated to *eXited* and an $ET$ message is emitted. + +!!! tip inline end "See also" + + - [Early Termination](../process_models/em/early_termination.md) + - [Threat Monitoring Behavior](monitor_threats_bt.md) + - [Message Handling Behavior](msg_intro_bt.md) + + +The Terminate Embargo Behavior Tree appears in multiple locations in the +larger tree. +We will encounter it again as a possible response to evidence collected via +[threat monitoring](monitor_threats_bt.md) +as well as in response to certain [CS or EM messages](msg_intro_bt.md) +in states when an embargo is no longer viable. diff --git a/docs/topics/behavior_logic/fix_dev_bt.md b/docs/topics/behavior_logic/fix_dev_bt.md new file mode 100644 index 00000000..5d3d2880 --- /dev/null +++ b/docs/topics/behavior_logic/fix_dev_bt.md @@ -0,0 +1,35 @@ +# Fix Development Behavior + +The Fix Development Behavior Tree is shown below. + +```mermaid +--- +title: Fix Development Behavior Tree +--- +flowchart LR + fb["?"] + role_not_vendor(["role is not vendor?"]) + fb -->|A| role_not_vendor + cs_in_VF(["CS in VF...?"]) + fb -->|B| cs_in_VF + seq["→"] + fb -->|C| seq + rm_in_a(["RM in A?"]) + seq --> rm_in_a + create_fix["create fix"] + seq --> create_fix + fix_ready(["fix ready?"]) + seq --> fix_ready + cs_to_VF["CS → VFd...
(emit CF)"] + seq --> cs_to_VF +``` + +(A) Fix development is relegated to the Vendor role, so Non-Vendors just return *Success* since they have nothing further to do. + +(B) For Vendors, if a fix is ready (i.e., the case is in $q^{cs} \in VF\cdot\cdot\cdot\cdot$), the tree returns *Success*. + +(C) Otherwise, engaged Vendors ($q^{rm} \in A$) can + +- create fixes +- set $q^{cs} \in Vfd\cdot\cdot\cdot \xrightarrow{\mathbf{F}} VFd\cdot\cdot\cdot$ +- emit $CF$ upon completion diff --git a/docs/topics/behavior_logic/id_assignment_bt.md b/docs/topics/behavior_logic/id_assignment_bt.md new file mode 100644 index 00000000..32e58638 --- /dev/null +++ b/docs/topics/behavior_logic/id_assignment_bt.md @@ -0,0 +1,45 @@ +# CVE ID Assignment Behavior + +Many CVD practitioners want to assign identifiers to the vulnerabilities they coordinate. +The most common of these is a CVE ID, so we provide an example CVE ID Assignment Behavior Tree, shown below. + +```mermaid +--- +title: CVE ID Assignment Behavior Tree +--- +flowchart LR + fb["?"] + check_assigned(["ID assigned?"]) + fb --> check_assigned + seq["→"] + fb --> seq + check_in_scope(["in scope?"]) + seq --> check_in_scope + fb2["?"] + seq --> fb2 + seq2["→"] + fb2 --> seq2 + is_cna(["Is CNA?"]) + seq2 --> is_cna + assignable(["assignable?"]) + seq2 --> assignable + cna_assign["assign CVE ID"] + seq2 --> cna_assign + request["request CVE ID"] + fb2 --> request +``` + +While this tree is constructed around the [CVE ID assignment process](https://www.cve.org/About/Process), +it could be easily adapted to any other identifier process as well. + +The goal is to end with an ID assigned. +If that has not yet happened, the first check is whether the vulnerability is in scope for an ID assignment. +If it is, the Participant might be able to assign IDs directly, assuming they are a [CVE Numbering Authority](https://www.cve.org/ProgramOrganization/CNAs) +([CNA](https://www.cve.org/ProgramOrganization/CNAs)) and the vulnerability meets the [criteria +for assigning an ID](https://www.cve.org/ResourcesSupport/AllResources/CNARules#section_7_assignment_rules). + +Otherwise, if the Participant is not a CNA, they will have to [request an ID from a CNA](https://www.cve.org/About/Process). + +Should both assignment branches fail, the behavior fails. +Otherwise, as long as one of them succeeds, the behavior succeeds. + diff --git a/docs/topics/behavior_logic/index.md b/docs/topics/behavior_logic/index.md new file mode 100644 index 00000000..10c4f0f0 --- /dev/null +++ b/docs/topics/behavior_logic/index.md @@ -0,0 +1,153 @@ +# Modeling an MPCVD AI Using Behavior Trees {#ch:behavior_trees} + +With the formal definition of the Vultron Protocol behind us, we now turn our +attention to reflect on one of many possible paths toward +implementation. We find that Behavior Trees have a number of desirable +properties when it comes to automating the kinds of complex behaviors +our protocol demands. + +!!! tip inline end "For more about Behavior Trees" + + For more about Behavior Trees, see + + - [*Behavior Trees in Robotics and AI: An Introduction*](https://arxiv.org/abs/1709.00084) + - [A behavior language for story-based believable agents](https://doi.org/10.1109/MIS.2002.1024751) + - [GDC 2005 Proceeding: Handling Complexity in the Halo 2 AI](https://www.gamedeveloper.com/programming/gdc-2005-proceeding-handling-complexity-in-the-i-halo-2-i-ai) + - [Increasing Modularity of UAV Control Systems using Computer Game Behavior Trees](https://doi.org/10.2514/6.2012-4458) + - [An integrated system for autonomous robotics manipulation](https://doi.org/10.1109/IROS.2012.6385888) + +Behavior Trees are a way of designing and programming hierarchical behaviors. +They originated in the computer gaming industry to develop realistic AIs to control NPCs in games. +More recently, Behavior Trees have been used in robotics to create adaptive behaviors using autonomous AI agents. +Behavior Trees offer a high potential for automating complex tasks. +Agent processes can be modeled as sets of behaviors (pre-conditions, actions, and post-conditions) and the logic that joins them. +Behavior Trees offer a way to organize and describe agent behaviors in a straightforward, understandable way. + +In this section, we use Behavior Trees as a method for describing +MPCVD Participant activities and their interactions with the [formal protocol](../../reference/formal_protocol/index.md). +These behaviors map approximately to the activities described in the [*CVD Guide*](https://vuls.cert.org/confluence/display/CVD) +(e.g., validate report, prioritize report, create fix, publish report, publish fix, deploy fix). + +If Behavior Trees were merely a notational convention, they would +already have been useful enough to include here to structure the +high-level business logic of the Vultron Protocol. But they also offer a way to +prototype software agents that reflect the activities of +CVD Participants. +Because Behavior Trees are inherently hierarchical, they are composable. +Both conditions and actions can be composed into small task-oriented +behaviors, which can, in turn, be composed to represent more complex +agent behaviors. As a result, independent agents using Behavior Trees +can be composed into multi-agent behaviors that achieve goals. + +## A Brief Introduction to Behavior Tree Notation + +Behavior Trees consist of a hierarchy of nodes represented as a +Directed Acyclic Graph (DAG). +A Behavior Tree execution always begins at the root node, and execution is passed +along the tree by *ticking* each child node according to the logic built +into the tree. When *ticked*, each node does its job and returns one of +three statuses: *Success*, *Failure*, or *Running*. A full introduction +to Behavior Trees can be found in Colledanchise and Ögren's book +[*Behavior Trees in Robotics and AI: An +Introduction*](https://arxiv.org/abs/1709.00084). + +!!! info "Behavior Tree Node Types" + + | Node Type | Shape or Symbol | Description | + | :--- |:----------------------| :--- | + | Root | any control flow type | has no parent nodes, has one or more child nodes, and can be of any of the control-flow types. | + | Condition | rounded oval | does not change the state of the world, has no child nodes, and returns only *Success* or *Failure*. | + | Task | rectangle | has no child nodes; performs a task, which might change the state of the world; and returns *Success*, *Failure*, or *Running*. | + | Sequence | → | ticks each child node, returning the last *Success* or the first *Failure*, or *Running* if a child returns *Running*. | + | Fallback | ? | ticks each child node, returning the first *Success* or the last *Failure*, or *Running* if a child returns *Running*. | + | Loop | ↺ | repeatedly ticks child nodes until an exit condition is met. | + | Parallel | ⇉ | ticks all child nodes simultaneously, and returns *Success* when $m$ of $n$ children have returned *Success*. | + + +A basic Behavior Tree is shown below. +When a tree is presented in the vertical orientation, each node's children should be read left to right. +In the example below, we see two motifs that come up through the remainder of this section. +On the left side is a Fallback node ($\boxed{?}$), which short-circuits to *Success* when the $postcondition$ is already met. +Otherwise, some activity will occur in $task_a$ and, assuming that it succeeds, the $postcondition$ is set. +As a result, the fallback node ensures that *Success* means that the $postcondition$ is met. + + +```mermaid +--- +title: A Basic Behavior Tree +--- +flowchart TD + root["→"] + l[?] + root --> l + r["→"] + root --> r + l0([postcondition]) + l --> l0 + l1["→"] + l --> l1 + l10[task_a] + l1 --> l10 + l11[set postcondition] + l1 --> l11 + r0([precondition]) + r --> r0 + r1[task_b] + r --> r1 + r2[?] + r --> r2 + r20[task_c] + r2 --> r20 + r21[task_d] + r2 --> r21 +``` + +On the right side is a sequence ($\boxed{\rightarrow}$) that hinges on a +$precondition$ being met prior to some set of actions being taken. +Assuming the $precondition$ is met, $task_b$ fires and, assuming it +succeeds execution, proceeds to another fallback node. This fallback +node represents a set of tasks in which one only needs to succeed for +the fallback to return *Success*. If $task_c$ succeeds, then $task_d$ +does not run. + +Behavior Trees can sometimes be wider than they are tall, so we sometimes +display them in a horizontal orientation to save space. The +semantics remain the same, but each node's children should be read top-to-bottom +rather than left-to-right. The same tree as above is shown below in +horizontal form. + +```mermaid +--- +title: A Basic Behavior Tree (horizontal) +--- +flowchart LR + root["→"] + l[?] + root --> l + r["→"] + root --> r + l0([postcondition]) + l --> l0 + l1["→"] + l --> l1 + l10[task_a] + l1 --> l10 + l11[set postcondition] + l1 --> l11 + r0([precondition]) + r --> r0 + r1[task_b] + r --> r1 + r2[?] + r --> r2 + r20[task_c] + r2 --> r20 + r21[task_d] + r2 --> r21 +``` + + +Behavior Trees are composable—that is, a task node in one tree can be replaced with a more refined Behavior Tree in another. +We leverage this feature throughout the remainder of this chapter to describe an agent model for an MPCVD Participant +as a set of nested Behavior Trees that reflect the protocol described in the previous chapters. + diff --git a/docs/topics/behavior_logic/monitor_threats_bt.md b/docs/topics/behavior_logic/monitor_threats_bt.md new file mode 100644 index 00000000..24fe5232 --- /dev/null +++ b/docs/topics/behavior_logic/monitor_threats_bt.md @@ -0,0 +1,65 @@ +# Monitor Threats Behavior Tree + +The Monitor Threats Behavior Tree is shown below. + +```mermaid +--- +title: Monitor Threats Behavior Tree +--- +flowchart LR + fb["?"] + seq["→"] + fb --> seq + par["#8649; (1)"] + seq --> par + at_seq["→"] + par -->|A| at_seq + mon_attacks["monitor attacks"] + at_seq --> mon_attacks + cs_to_A["CS → A
(emit CA)"] + at_seq --> cs_to_A + ex_seq["→"] + par -->|B| ex_seq + mon_exploits["monitor public exploits"] + ex_seq --> mon_exploits + ex_fb["?"] + ex_seq --> ex_fb + cs_in_P(["CS in P?"]) + ex_fb --> cs_in_P + cs_to_P["CS → P
(emit CP)"] + ex_fb --> cs_to_P + cs_to_X["CS → X
(emit CX)"] + ex_seq --> cs_to_X + rep_seq["→"] + par -->|C| rep_seq + mon_reports["monitor public reports"] + rep_seq --> mon_reports + rep_cs_to_P["CS → P
(emit CP)"] + rep_seq --> rep_cs_to_P + term_embargo["terminate embargo"] + seq --> term_embargo + cs_unchanged(["CS unchanged?"]) + fb --> cs_unchanged +``` + + +For our purposes, monitoring consists of a set of parallel tasks, any one of which can lead to embargo termination. +The three conditions of interest are taken straight from the [embargo exit criteria](../process_models/em/early_termination.md). + +- (A) If attacks are observed, the $q^{cs} \xrightarrow{\mathbf{A}} A$ transition occurs, and a $CA$ message is emitted. + +- (B) If a public exploit is observed, the $q^{cs} \xrightarrow{\mathbf{X}} X$ transition occurs, and a $CX$ message is emitted. + In the special case where the exploit is made public prior to the vulnerability itself being made public,[^1] + there is an additional $q^{cs} \xrightarrow{\mathbf{P}} P$ transition and $CP$ emission. + +- (C) Finally, if the vulnerability information has been made public, then the $q^{cs} \xrightarrow{\mathbf{P}} P$ and emits $CP$. + +In the event that one or more of these events is detected, the [Terminate Embargo Behavior Tree](em_terminate_bt.md) is triggered. + +There are many other good reasons to monitor and maintain awareness of cybersecurity threats. +The behavior shown here is intended as a minimal set of things that CVD Participants should watch out for in the +course of performing their CVD practice. + +See also: [Terminate Embargo Behavior Tree](em_terminate_bt.md) + +[^1]: Corresponding to a Type 3 Zero Day Exploit as defined in §6.5.1 of [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) diff --git a/docs/topics/behavior_logic/msg_cs_bt.md b/docs/topics/behavior_logic/msg_cs_bt.md new file mode 100644 index 00000000..07ebce92 --- /dev/null +++ b/docs/topics/behavior_logic/msg_cs_bt.md @@ -0,0 +1,167 @@ +# Process CS Messages Behavior {#sec:process_cs_messages_bt} + +The Process CS Messages Behavior Tree is shown below. + +```mermaid +--- +title: Process CS Messages Behavior Tree +--- +flowchart LR + seq["→"] + is_C_msg(["is C* msg?"]) + seq --> is_C_msg + fb["?"] + seq --> fb + is_CK_msg(["is CK msg?"]) + fb --> is_CK_msg + seq2["→"] + fb --> seq2 + fb2["?"] + seq2 --> fb2 + cs_global["Handle CS
Participant-agnostic
status msg"] + fb2 -->|A| cs_global + cs_pspec["Handle CS
Participant-specific
status msg"] + fb2 -->|B| cs_pspec + err_seq["→"] + fb2 -->|C| err_seq + is_ce_msg(["is CE msg?"]) + err_seq --> is_ce_msg + emit_gi["emit GI"] + err_seq --> emit_gi + emit_ck["emit CK"] + seq2 --> emit_ck + emit_ce["emit CE"] + fb --> emit_ce +``` + +We are still working through the children of [Receive Messages](msg_intro_bt.md) behavior tree. +And as we've come to expect, a precondition check leads to a fallback node in which CS acknowledgement +messages (_CK_) receive no further attention and return *Success*. + +The main CS message-handling sequence comes next, with all matching incoming messages resulting in emission of an +acknowledgment message (_CK_). +These messages are presented as sub-trees below: + +- (A) [Participant-agnostic CS Status Messages](#participant-agnostic-cs-status-messages) +- (B) [Participant-Specific CS Status Messages](#participant-specific-cs-status-messages) + +Returning from handling regular CS messages, the tree next (C) handles error messages (_CE_) with the familiar motif +of an error (_CE_) triggering a general inquiry (_GI_) to seek resolution. + +Finally, the tree has handled all expected messages, so anything else would result in an error +condition and emission of a _CE_ message accordingly. + + +## Participant-agnostic CS Status Messages + +The tree first handles messages indicating a Participant-agnostic CS change. + +```mermaid +--- +title: Process CS Participant-agnostic Status Messages Behavior Tree +--- +flowchart LR + global_seq["→"] + global_fb["?"] + global_seq -->|A1| global_fb + cp_seq["→"] + global_fb -->|A1a| cp_seq + is_CP_msg(["is CP msg?"]) + cp_seq --> is_CP_msg + cp_fb["?"] + cp_seq --> cp_fb + cp_cs_not_P(["CS not in ...P..?"]) + cp_fb --> cp_cs_not_P + cp_cs_to_P["CS → ...P.."] + cp_fb --> cp_cs_to_P + cx_seq["→"] + global_fb -->|A1b| cx_seq + is_CX_msg(["is CX msg?"]) + cx_seq --> is_CX_msg + cx_fb["?"] + cx_seq --> cx_fb + cx_cs_not_PXA(["CS not in ...PX.?"]) + cx_fb --> cx_cs_not_PXA + cx_seq2["→"] + cx_fb --> cx_seq2 + cx_x_fb["?"] + cx_seq2 --> cx_x_fb + cs_in_x(["CS in ...X..?"]) + cx_x_fb --> cs_in_x + cx_to_x["CS → ....X."] + cx_x_fb --> cx_to_x + cx_p_fb["?"] + cx_seq2 --> cx_p_fb + cs_in_p(["CS in ...PX.?"]) + cx_p_fb --> cs_in_p + cx_to_p["CS → ...PX.
(emit CP)"] + cx_p_fb --> cx_to_p + ca_seq["→"] + global_fb -->|A1c| ca_seq + is_CA_msg(["is CA msg?"]) + ca_seq --> is_CA_msg + ca_fb["?"] + ca_seq --> ca_fb + ca_cs_not_a(["CS not in .....A?"]) + ca_fb --> ca_cs_not_a + ca_cs_to_a["CS → .....A"] + ca_fb --> ca_cs_to_a + terminate["terminate embargo"] + global_seq -->|A2| terminate +``` + + +(A1a) Information that the vulnerability has been made public (_CP_) is met +with a transition to the *Public Aware* state in the CS model when +necessary. + +(A1b) Similarly, information that an exploit has been made public +forces both the __X__ and __P__ transitions, as necessary. +Because the __P__ transition, should it occur in response to a +_CX_ message, represents possibly new information to the case, it +triggers the emission of a _CP_ message to convey this information to +the other Participants. + +(A1c) Likewise, a message indicating attacks underway +triggers the __A__ transition. + +Again, we note that any of the __P__, __X__, or +__A__ transitions in the CS model imply that no new embargo should be +entered, and any existing embargo should be terminated. Hence, the +sequence described in the previous paragraph leads to the [embargo +termination tree](em_terminate_bt.md). + +## Participant-Specific CS Status Messages + +Next, we see that messages indicating *Vendor Awareness* (_CV_), *Fix +Readiness* (_CF_), and *Fix Deployed* (_CD_) are treated as mere status +updates for the Participant because they are participant-specific. +They are recognized and acknowledged but trigger no further action directly. + +```mermaid +--- +title: Process CS Participant-Specific Messages Behavior Tree +--- +flowchart LR + seq["→"] + is_C_msg(["is CV, CF, or CD msg?"]) + seq --> is_C_msg + update_status["update sender status"] + seq --> update_status +``` + + +Recall from +[Model Interactions](../process_models/model_interactions/index.md) and +the [Formal Protocol](../../reference/formal_protocol/index.md) that the +$vfd\cdot\cdot\cdot \rightarrow \dots \rightarrow VFD\cdot\cdot\cdot$ portion of the +CS model is unique to each Vendor Participant, and similarly that the +$\cdot\cdot d \cdot\cdot\cdot \rightarrow \cdot\cdot D \cdot\cdot\cdot$ portion is unique to +each Participant in the Deployer role. +Therefore, messages representing another Participant's status change for this portion of the +CS do not directly affect the receiving Participant's status. +This is not to say that the Participant might not choose to take some action based on their knowledge of a +Vendor's (or Deployer's) status. +Rather, such follow-up would be expected to occur as part of the Participant's [*do work* process](do_work_bt.md). + + diff --git a/docs/topics/behavior_logic/msg_em_bt.md b/docs/topics/behavior_logic/msg_em_bt.md new file mode 100644 index 00000000..8c4a534b --- /dev/null +++ b/docs/topics/behavior_logic/msg_em_bt.md @@ -0,0 +1,204 @@ +# Process EM Messages Behavior {#sec:process_em_messages_bt} + +The Process EM Messages Behavior Tree is shown below. + +```mermaid +--- +title: Process EM Messages Behavior Tree +--- +flowchart LR + seq["→"] + is_E_msg(["is E* msg?"]) + seq --> is_E_msg + fb["?"] + seq --> fb + is_EK_msg(["is EK msg?"]) + fb --> is_EK_msg + seq2["→"] + fb --> seq2 + fb2["?"] + seq2 --> fb2 + ee_seq["→"] + fb2 -->|A| ee_seq + is_EE_msg(["is EE msg?"]) + ee_seq --> is_EE_msg + ee_emit_GI["emit GI"] + ee_seq --> ee_emit_GI + et_seq["→"] + fb2 -->|B| et_seq + is_ET_msg(["is ET msg?"]) + et_seq --> is_ET_msg + et_fb["?"] + et_seq --> et_fb + em_x(["EM in X?"]) + et_fb --> em_x + et_seq2["→"] + et_fb --> et_seq2 + em_a_r(["EM in A or R?"]) + et_seq2 --> em_a_r + et_em_to_X["EM → X"] + et_seq2 --> et_em_to_X + er_seq["→"] + fb2 -->|C| er_seq + is_ER_msg(["is ER msg?"]) + er_seq --> is_ER_msg + er_fb["?"] + er_seq --> er_fb + em_none(["EM in N?"]) + er_fb --> em_none + er_seq2["→"] + er_fb --> er_seq2 + em_p(["EM in P?"]) + er_seq2 --> em_p + er_em_to_n["EM → N"] + er_seq2 --> er_em_to_n + viable_seq["→"] + fb2 -->|D| viable_seq + cs_in_pxa(["CS in ...pxa?"]) + viable_seq -->|D1| cs_in_pxa + handle_viab["handle viable embargo"] + viable_seq -->|D2| handle_viab + non_viable_seq["→"] + fb2 -->|E| non_viable_seq + cs_not_in_pxa(["CS not in ...pxa?"]) + non_viable_seq --> cs_not_in_pxa + terminate["terminate embargo"] + non_viable_seq --> terminate + emit_ek["emit EK"] + seq2 --> emit_ek + emit_ee["emit EE"] + fb --> emit_ee +``` + + +It is a child of the fallback node started in [Receiving Messages Behavior](msg_intro_bt.md). +A precondition check for EM message types is followed by a fallback node. +EM acknowledgment messages (_EK_) receive no further attention and return *Success*. + +## Messages That Lead to a Simple Acknowledgment. + +Next is a branch handling all the messages that will result in a simple acknowledgment (_EK_). + +(A) First, we handle embargo error messages (_EE_), which additionally trigger a general inquiry (_GI_) message to attempt +to resolve the problem. + +(B) Second are embargo termination messages (_ET_). +If the Participant is already in the EM *eXited* state (_X_), no further action is taken (aside from the _EK_). +Otherwise, if the Participant is in either *Active* or *Revise* EM states, the _ET_ message triggers a state +transition $q^{em} \xrightarrow{t} X$. + +(C) Embargo rejections are handled next in a simple sequence that returns the state from *Proposed* to *None*. + +### Handling Viable Embargo Messages + +(D) The final chunk of the simple acknowledge branch handles EM messages received when the case state permits embargo viability +($q^{cs} \in \cdot\cdot\cdot pxa$). +A variety of actions can be taken in this case state, as shown in the next diagram. + +```mermaid +--- +title: Handling Viable Embargo Messages +--- +flowchart LR + fb["?"] + ep_seq["→"] + fb -->|D2a| ep_seq + is_EP_msg(["is EP msg?"]) + ep_seq --> is_EP_msg + ep_fb["?"] + ep_seq --> ep_fb + ep_em_p(["EM in P?"]) + ep_fb --> ep_em_p + ep_seq2["→"] + ep_fb --> ep_seq2 + em_none(["EM in N?"]) + ep_seq2 --> em_none + ep_em_to_p["EM → P"] + ep_seq2 --> ep_em_to_p + ea_seq["→"] + fb -->|D2b| ea_seq + is_EA_msg(["is EA msg?"]) + ea_seq --> is_EA_msg + ea_fb["?"] + ea_seq --> ea_fb + em_a(["EM in A?"]) + ea_fb --> em_a + ea_seq2["→"] + ea_fb --> ea_seq2 + ea_em_p(["EM in P?"]) + ea_seq2 --> ea_em_p + ea_em_to_a["EM → A"] + ea_seq2 --> ea_em_to_a + ev_seq["→"] + fb -->|D2c| ev_seq + is_EV_msg(["is EV msg?"]) + ev_seq --> is_EV_msg + ev_fb["?"] + ev_seq --> ev_fb + ev_em_r(["EM in R?"]) + ev_fb --> ev_em_r + ev_seq2["→"] + ev_fb --> ev_seq2 + ev_em_a(["EM in A?"]) + ev_seq2 --> ev_em_a + ev_em_to_r["EM → R"] + ev_seq2 --> ev_em_to_r + ej_ec_seq["→"] + fb -->|D2d| ej_ec_seq + is_EJ_msg(["is EJ or EC msg?"]) + ej_ec_seq --> is_EJ_msg + ej_ec_fb["?"] + ej_ec_seq --> ej_ec_fb + ej_ec_em_A(["EM in A?"]) + ej_ec_fb --> ej_ec_em_A + ej_ec_seq2["→"] + ej_ec_fb --> ej_ec_seq2 + ej_ec_em_r(["EM in R?"]) + ej_ec_seq2 --> ej_ec_em_r + ej_ec_fb2["?"] + ej_ec_seq2 --> ej_ec_fb2 + ej_seq["→"] + ej_ec_fb2 --> ej_seq + ej_is_EJ_msg(["is EJ msg?"]) + ej_seq --> ej_is_EJ_msg + ej_em_to_A["EM → A"] + ej_seq --> ej_em_to_A + ec_seq["→"] + ej_ec_fb2 --> ec_seq + ec_is_EC_msg(["is EC msg?"]) + ec_seq --> ec_is_EC_msg + ec_em_to_A["EM → A"] + ec_seq --> ec_em_to_A +``` + +(D2a) An embargo proposal (_EP_) +results in either a move from *None* to *Proposed* or stays in +*Proposed*, if that was already the case. + +(D2b) An embargo acceptance (_EA_) +transitions from *Proposed* to *Active*. + +(D2c) Similar to the _EP_ behavior, +an embargo revision proposal (_EV_) either moves from *Active* to +*Revise* or stays in *Revise*, as appropriate. + +(D2d) Finally, we deal with +revision rejection (_EJ_) or acceptance (_EC_) when in the *Revise* +state. + +Climbing back up the tree, we see that *Success* in any of the +branches in this or the previous paragraph results in an acknowledgment +message _EK_. + +## Messages That Require More than a Simple Acknowledgment. + +(E) Returning to the the tree at the top of the page, we come to a branch focused on +handling EM messages when an embargo is no longer viable---in other words, when the case has +reached a point where attacks are occurring, or either the exploit or the vulnerability has been made public +($q^{cs} \not \in \cdot\cdot\cdot pxa$). +This branch takes us to the [Terminate Embargo tree](em_terminate_bt.md), which may lead to +other messages being emitted. + +Finally, back at the end of the tree at the top of the page, when no other branch has succeeded, +we emit an embargo error (_EE_) message to relay the failure. + diff --git a/docs/topics/behavior_logic/msg_intro_bt.md b/docs/topics/behavior_logic/msg_intro_bt.md new file mode 100644 index 00000000..75009ec2 --- /dev/null +++ b/docs/topics/behavior_logic/msg_intro_bt.md @@ -0,0 +1,64 @@ +# Receiving and Processing Messages Behavior + +Now we return to the [CVD Behavior Tree](cvd_bt.md) to pick up the last unexplored branch, Receive Messages. +The Receive Messages Behavior Tree is shown below. + +```mermaid +--- +title: Receive Messages Behavior Tree +--- +flowchart LR + loop["#8634;
(until fail)"] + seq["→"] + loop --> seq + rm_in_C(["RM in C?"]) + seq --> rm_in_C + msg_avail(["msg queue
not empty?"]) + seq --> msg_avail + fb["?"] + seq --> fb + seq2["→"] + fb --> seq2 + pop_msg["pop msg"] + seq2 --> pop_msg + fb2["?"] + seq2 --> fb2 + proc_rm_msg["process RM messages"] + fb2 --> proc_rm_msg + proc_em_msg["process EM messages"] + fb2 --> proc_em_msg + proc_cs_msg["process CS messages"] + fb2 --> proc_cs_msg + proc_other_msg["process other messages"] + fb2 --> proc_other_msg + push_msg["push msg"] + fb --> push_msg + +``` + +!!! tip inline end "All models are wrong, some models are useful" + + At this level, the behavior tree is modeling a basic queue servicing loop. + There is nothing particularly special about this loop, and we probably wouldn't recommend + implementing a queue servicing loop with a behavior tree anyway. Instead, we're using this loop to represent + that there is _some_ process by which individual messages are received and processed. + The important part of this tree are the message-type specific behaviors that follow. + +The tree represents a loop that continues until all currently received messages have been processed. +Each iteration checks for unprocessed messages and handles them. + +First, we encounter a case closure check. We assume that messages to +existing cases will have a case ID associated with all messages about +that case and that new report submissions will not have a case ID +assigned yet, implying they are in the RM *Start* state ($q^{rm} \in S$). +Therefore, new reports will pass this check every time. However, +messages received on an already *Closed* case will short-circuit here +and take no further action. + +Assuming the message is regarding a new or unclosed case and the message +has not yet been processed, each message type is handled by a +process-specific Behavior Tree, which we discuss in the following +sections. Although each process-specific behavior is described in a +subsection and shown in its own figure, they are all part of the same +fallback node shown here. + diff --git a/docs/topics/behavior_logic/msg_other_bt.md b/docs/topics/behavior_logic/msg_other_bt.md new file mode 100644 index 00000000..e198d498 --- /dev/null +++ b/docs/topics/behavior_logic/msg_other_bt.md @@ -0,0 +1,38 @@ +# Process Other Messages Behavior {#sec:process_gen_messages_bt} + +The Process Other Messages Behavior Tree is shown below. + +```mermaid +--- +title: Process Other Messages Behavior Tree +--- +flowchart LR + seq["→"] + is_G_msg(["is G* msg?"]) + seq --> is_G_msg + fb["?"] + seq --> fb + is_GK_msg(["is GK msg?"]) + fb --> is_GK_msg + seq2["→"] + fb --> seq2 + fb2["?"] + seq2 --> fb2 + is_GI_msg(["is GI msg?"]) + fb2 --> is_GI_msg + gi_seq["→"] + fb2 --> gi_seq + is_GE_msg(["is GE msg?"]) + gi_seq --> is_GE_msg + ge_emit_GI["emit GI"] + gi_seq --> ge_emit_GI + gi_emit_GK["emit GK"] + seq2 --> gi_emit_GK +``` + +This tree represents the final chunk of the fallback node in the [Receive Messages Behavior](msg_intro_bt.md). +And here, for the final time, we see a message type check and that general acknowledgment messages (_GK_) +receive no further attention and return *Success*. +General inquiries (_GI_) get at least an acknowledgment, with any follow-up to be handled by [*do work*](do_work_bt.md). +As usual, errors (_GE_) also trigger follow-up inquiries (_GI_) in the interest of resolution. + diff --git a/docs/topics/behavior_logic/msg_rm_bt.md b/docs/topics/behavior_logic/msg_rm_bt.md new file mode 100644 index 00000000..e5586856 --- /dev/null +++ b/docs/topics/behavior_logic/msg_rm_bt.md @@ -0,0 +1,89 @@ +# Process RM Messages Behavior {#sec:process_rm_messages_bt} + +The Process RM Messages Behavior Tree is shown below. + +```mermaid +--- +title: Process RM Messages Behavior Tree +--- +flowchart LR + seq["→"] + is_R_msg(["is R* msg?"]) + seq --> is_R_msg + fb["?"] + seq --> fb + is_RK_msg(["is RK msg?"]) + fb --> is_RK_msg + seq2["→"] + fb --> seq2 + fb2["?"] + seq2 --> fb2 + rs_seq["→"] + fb2 -->|A| rs_seq + is_RS_msg(["is RS msg?"]) + rs_seq --> is_RS_msg + rs_fb["?"] + rs_seq --> rs_fb + rm_not_S(["RM not in S?"]) + rs_fb --> rm_not_S + rm_to_R["RM → R"] + rs_fb --> rm_to_R + rs_fb2["?"] + rs_seq --> rs_fb2 + role_not_vendor(["role != vendor?"]) + rs_fb2 --> role_not_vendor + cs_in_V(["CS in V.....?"]) + rs_fb2 --> cs_in_V + cs_to_V["CS → Vfd...
(emit CV)"] + rs_fb2 --> cs_to_V + re_seq["→"] + fb2 -->|B| re_seq + is_RE_msg(["is RE msg?"]) + re_seq --> is_RE_msg + emit_GI["emit GI"] + re_seq --> emit_GI + other_seq["→"] + fb2 -->|C| other_seq + o_rm_not_S(["RM not in S?"]) + other_seq --> o_rm_not_S + update_sender_status["update sender status"] + other_seq --> update_sender_status + emit_RK["emit RK"] + seq2 --> emit_RK + emit_RE["emit RE"] + fb --> emit_RE +``` + +This tree is a child of the fallback node started in [Receiving Messages Behavior](msg_intro_bt.md). +Beginning with a precondition check for any RM message type, the tree proceeds to a fallback node. +RM acknowledgment messages (_RK_) receive no further attention and return *Success*. + +Next comes the main RM message processing sequence. +A fallback node covers three major cases: + +- (A) First comes a sequence that handles new reports (_RS_ when + $q^{rm} \in S$). This branch changes the recipient's + RM state + regardless of the Participant's role. If the Participant happens to + be a Vendor and the Vendor was previously unaware of the + vulnerability described by the report, the Vendor would also note + the CS + transition from $q^{cs} \in vfd \xrightarrow{\mathbf{V}} Vfd$ and + emit a corresponding _CV_ message. + +- (B) Next, we see that an RM Error (_RE_) results in the emission + of a general inquiry (_GI_) for Participants to sort out what the + problem is, along with an _RK_ to acknowledge receipt of the error. + +- (C) Finally, recall that the RM process is unique to each + CVD + Participant, so most of the remaining RM messages are simply informational + messages about other Participants' statuses that do not directly + affect the receiver's status. Therefore, if there is already an + associated case ($q^{rm} \not\in S$), the recipient might update + their record of the sender's state, but no further action is needed. + +For all three cases, an _RK_ message acknowledges receipt of the +message. Any unhandled message results in an _RE_ response, indicating +an error. + diff --git a/docs/topics/behavior_logic/publication_bt.md b/docs/topics/behavior_logic/publication_bt.md new file mode 100644 index 00000000..13ad3042 --- /dev/null +++ b/docs/topics/behavior_logic/publication_bt.md @@ -0,0 +1,113 @@ +# Publication Behavior + +The Publication Behavior Tree is shown in the following diagram. +(A) It begins by ensuring that the Participant knows what they intend to publish (A1), followed by a check to +see if that publication has been achieved (A2). +Assuming that work remains to be done, the main publish sequence commences on the second branch (B). + +```mermaid +--- +title: Publication Behavior Tree +--- +flowchart LR + fb["?"] + seq1["→"] + fb -->|A| seq1 + fb2["?"] + seq1 -->|A1| fb2 + pub_intents(["publication intents set?"]) + fb2 --> pub_intents + prioritize_pub["prioritize publication intents"] + fb2 --> prioritize_pub + all_pub["all published?"] + seq1 -->|A2| all_pub + seq2["→"] + fb -->|B| seq2 + prep_pub["prepare publication"] + seq2 -->|B1| prep_pub + emb_mgt["embargo management"] + seq2 -->|B2| emb_mgt + em_n_or_x(["EM in N or X?"]) + seq2 -->|B3| em_n_or_x + publish["publish"] + seq2 -->|B4| publish + cs_to_P["CS → P
(emit CP)"] + seq2 -->|B5| cs_to_P +``` + +!!! tip inline end "Embargoes and Publication" + + The [embargo management](em_bt.md) task here is intended as a simple check to ensure that no + embargo remains active prior to publication. + However, since we describe that behavior [elsewhere](em_bt.md), we will not repeat it here. + Note that the [EM](../process_models/em/index.md) process may result in [early termination](../process_models/em/early_termination.md) of an existing embargo + if the Participant has sufficient cause to do so. + +(B1) The publication process begins with [preparation for publication](#prepare-publication-behavior), +described below, followed by a pre-publication [embargo check](em_bt.md) (B2 and B3 combined). + +Once these subprocesses complete, the publish task (B4) fires, the case state +is updated to $q^{cs} \in P$, and a $CP$ message emits (B5). + +## Prepare Publication Behavior + +The Prepare Publication Behavior Tree is shown below. +Note that it continues branch (B1) from the [Publication Behavior Tree](#publication-behavior) above. + +```mermaid +--- +title: Prepare Publication Behavior Tree +--- +flowchart LR + seq["→"] + x_fb["?"] + seq -->|B1a| x_fb + no_pub_exploit(["no publish
exploit?"]) + x_fb --> no_pub_exploit + exp_ready(["exploit ready?"]) + x_fb --> exp_ready + x_seq["→"] + x_fb --> x_seq + acquire_exploit["acquire exploit"] + x_seq --> acquire_exploit + prep_exploit["prepare exploit"] + x_seq --> prep_exploit + x_reprioritize["reprioritize exploit
publication intent"] + x_fb --> x_reprioritize + f_fb["?"] + seq -->|B1b| f_fb + no_pub_fix(["no publish
fix?"]) + f_fb --> no_pub_fix + cs_in_VF(["CS in VF...?"]) + f_fb --> cs_in_VF + f_seq["→"] + f_fb --> f_seq + fix_dev["fix development"] + f_seq --> fix_dev + prep_fix["prepare fix
for publication"] + f_seq --> prep_fix + f_reprioritize["reprioritize fix
publication intent"] + f_fb --> f_reprioritize + r_fb["?"] + seq -->|B1c| r_fb + no_pub_report(["no publish
report?"]) + r_fb --> no_pub_report + r_ready(["report ready?"]) + r_fb --> r_ready + prep_report["prepare report
for publication"] + r_fb --> prep_report + r_reprioritize["reprioritize report
publication intent"] + r_fb --> r_reprioritize +``` + +There are separate branches for +publishing exploits, fixes, and reports. + +- (B1a) The publish exploit branch succeeds if either no exploit publication is intended, if it is [intended + and ready](acquire_exploit_bt.md), or if it can be acquired and prepared for publication. +- (B1b) The publish fix branch succeeds if the Participant does not intend to publish a fix (e.g., if they are not the Vendor), if a [fix is ready](fix_dev_bt.md), or + if it can be developed and prepared for publication. +- (B1c) The publish report branch is the simplest and succeeds if either no publication is intended or if the report is ready to go. + +Once all three branches have completed, the behavior returns *Success*. + diff --git a/docs/topics/behavior_logic/reporting_bt.md b/docs/topics/behavior_logic/reporting_bt.md new file mode 100644 index 00000000..b04ac5a7 --- /dev/null +++ b/docs/topics/behavior_logic/reporting_bt.md @@ -0,0 +1,129 @@ +# Reporting Behavior + +The [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD) +describes the reporting phase as the process of identifying parties that need to be informed about the vulnerability +and then notifying them. +Reporting only works if the intended recipient has the ability to receive reports, as outlined in +our introduction of the [RM _Received_ state](../process_models/rm/index.md#the-received-r-state). + +The Reporting Behavior Tree is shown in the figure below. + +```mermaid +--- +title: Reporting Behavior Tree +--- +flowchart LR + loop["#8634;"] + identify_participants["identify participants"] + loop --> identify_participants + notify_others["notify others"] + loop --> notify_others +``` + +The tree describes a Participant that performs reporting until either their effort limit is met, or they run out of +Participants to notify. + +## Identify Participants Behavior + +!!! tip inline end "Participant Inclusion Choices are left to Participants" + + Note that we are intentionally avoiding setting any requirements about *who* is relevant to a case. + We leave that decision to each Participant's judgment. + Further discussion of this topic is available in [Adding Participants](../process_models/em/working_with_others.md). + +The Identify Participants Behavior Tree, shown in the following diagram, ends when all relevant parties have been +identified. +Until that condition is met, the Participant can proceed with identifying Vendors, Coordinators, or other +parties relevant to the coordination of the case. + +```mermaid +--- +title: Identify Participants Behavior Tree +--- +flowchart LR + fb["?"] + all_known(["all relevant
parties known?"]) + fb --> all_known + seq["→"] + fb --> seq + identify_vendor["identify vendor(s)"] + seq --> identify_vendor + identify_coordinator["identify coordinator(s)"] + seq --> identify_coordinator + identify_other["identify other(s)"] + seq --> identify_other +``` + +## Notify Others Behavior {#sec:notify_others} + +The Notify Others Behavior Tree is shown in the figure below. + +```mermaid +--- +title: Notify Others Behavior Tree +--- +flowchart LR + fb["?"] + all_notified(["all notified
RM not in S?"]) + fb -->|A| all_notified + seq["→"] + fb -->|B| seq + choose_recipient["choose recipient"] + seq -->|B1| choose_recipient + fb2["?"] + seq -->|B2| fb2 + seq2["→"] + fb2 -->|B2a| seq2 + fb3["?"] + seq2 --> fb3 + recp_not_in_S(["recipient RM not in S?"]) + fb3 --> recp_not_in_S + effort_exceeded(["effort limit
exceeded?"]) + fb3 --> effort_exceeded + remove_recp["remove recipient"] + seq2 --> remove_recp + seq3["→"] + fb2 -->|B2b| seq3 + fb4["?"] + seq3 --> fb4 + em_n_p_x(["EM in N,P,X?"]) + fb4 --> em_n_p_x + seq4["→"] + fb4 --> seq4 + em_a_r(["EM in A,R?"]) + seq4 --> em_a_r + rcp_policy_compatible(["recipient policy
compatible?"]) + seq4 --> rcp_policy_compatible + find_contact["find contact info"] + seq3 --> find_contact + send_report["send report
(emit RS)"] + seq3 --> send_report + recp_rm_to_r["recipient RM → R"] + seq3 --> recp_rm_to_r +``` + +(A) The goal of this behavior tree is for all intended recipients to receive the report, thereby reaching the $q^{rm} \in R$ state. + +(B) Each pass through this part of the tree chooses a Participant from a list of eligible recipients constructed in the Identify +Participants Behavior. +(B1) The method for choosing the recipient is left unspecified since Participants can prioritize recipients how they see fit. + +The process proceeds to (B2a) clean up the eligible recipients list when either the recipient is already believed to be in +$q^{rm} \in R$ or if the effort expended in trying to reach the recipient has exceeded the Participant's limit. +Such limits are entirely left to the discretion of each Participant. +If the chosen recipient is pruned by this branch, the branch returns *Success*. + +If the chosen recipient was not pruned, then the cleanup branch fails and execution transfers to the second branch to +notify the recipient. + +(B2b) The first step in the notification branch is a check for an existing embargo. +If the embargo management state is one of $q^{em} \in \{ N,P,X\}$, there is no active embargo, and the Participant +can proceed with notification. + +Otherwise, in the case of an already active embargo (i.e., $q^{em} \in \{A,R\}$), there is an additional check to +ensure that the potential recipient's policy is compatible with any existing embargo. +This check allows for a reporting Participant to skip a recipient if they are likely to cause premature termination of +an extant embargo. + +Once at least one of these checks is passed, the notification sequence proceeds through finding the recipient's contact +information, sending the report, and updating the Participant's knowledge of the recipient's report management state. diff --git a/docs/topics/behavior_logic/rm_bt.md b/docs/topics/behavior_logic/rm_bt.md new file mode 100644 index 00000000..5a17972c --- /dev/null +++ b/docs/topics/behavior_logic/rm_bt.md @@ -0,0 +1,104 @@ +# Report Management Behavior Tree {#sec:rm_bt} + +A Behavior Tree for the Report Management model is shown in the figure below. +The Report Management process is represented by a Fallback node. Note +that we assume that completing the process will require multiple *ticks* +of the Behavior Tree since each tick can complete, at most, only one +branch. + +```mermaid +--- +title: Report Management Behavior Tree +--- +flowchart LR + fb["?"] + check_closed(["RM in C?"]) + fb -->|A| check_closed + r_seq["→"] + fb -->|B| r_seq + check_received(["RM in R?"]) + r_seq --> check_received + r_seq --> validate + i_seq["→"] + fb -->|C| i_seq + check_invalid(["RM in I?"]) + i_seq --> check_invalid + i_fb["?"] + i_seq --> i_fb + i_close["close"] + i_fb --> i_close + i_validate["validate"] + i_fb --> i_validate + v_seq["→"] + fb -->|D| v_seq + check_valid(["RM in V?"]) + v_seq --> check_valid + v_prioritize[prioritize] + v_seq --> v_prioritize + d_seq["→"] + fb -->|E| d_seq + check_deferred(["RM in D?"]) + d_seq --> check_deferred + d_fb["?"] + d_seq --> d_fb + d_close["close"] + d_fb --> d_close + d_prioritize["prioritize"] + d_fb --> d_prioritize + a_seq["→"] + fb -->|F| a_seq + check_accepted(["RM in A?"]) + a_seq --> check_accepted + a_fb["?"] + a_seq --> a_fb + a_close["close"] + a_fb --> a_close + a_fb_seq["→"] + a_fb --> a_fb_seq + a_prioritize["prioritize"] + a_fb_seq --> a_prioritize + a__do_work["do work"] + a_fb_seq --> a__do_work +``` + +(A) The first check is to see whether the case is already $Closed$ +($q^{rm} \in C$). If that check succeeds, the branch returns *Success*, +and we're done. If it doesn't, we move on to the next branch (B), which +addresses reports in the *Received* state ($q^{rm} \in R$). + +!!! tip inline end "See also" + + - [Report Validation Behavior](rm_validation_bt.md) + - [Report Prioritization Behavior](rm_prioritization_bt.md) + - [Report Closure Behavior](rm_closure_bt.md) + - [Do Work Behavior](do_work_bt.md) + +The only action to be taken from $q^{rm} \in R$ is to validate the report. +We address [report validation](rm_validation_bt.md) shortly, but, for now, it is +sufficient to say that the validate report behavior returns *Success* +after moving the report to either *Valid* ($q^{rm} \xrightarrow{v} V$) +or *Invalid* ($q^{rm} \xrightarrow{i} I$). + +The next branch (C) covers reports in the *Invalid* state ($q^{rm} \in I$). +Here we have two options: either close the report (move to +$q^{rm} \xrightarrow{c} C$, as described in [report closure](rm_closure_bt.md), or retry the validation. + +(D) For reports that have reached the *Valid* state ($q^{rm} \in V$), our +only action is to prioritize the report. [Report prioritization](rm_prioritization_bt.md) is +addressed in detail elsewhere, but returns *Success* after moving the report to either *Accepted* +($q^{rm} \xrightarrow{a} A$) or *Deferred* ($q^{rm} \xrightarrow{d} D$). + +(E) Next, we reach behaviors associated with reports that have been both validated +and prioritized. *Deferred* reports ($q^{rm} \in D$) can be *Closed* or +have their priority reevaluated, but otherwise are not expected to +receive additional work. + +(F) Similarly, *Accepted* reports ($q^{rm} \in A$) can also be *Closed* or +have their priority reevaluated. However, they are also expected to +receive more effort---the *do work* task node, which we explore further +in [Do Work Behaviors](do_work_bt.md). +We are taking advantage of the composability of Behavior Trees to +simplify the presentation. Behaviors that appear in multiple places can +be represented as their own trees. We explore the most relevant of these +subtrees in the next few subsections. + diff --git a/docs/topics/behavior_logic/rm_closure_bt.md b/docs/topics/behavior_logic/rm_closure_bt.md new file mode 100644 index 00000000..5a49b27b --- /dev/null +++ b/docs/topics/behavior_logic/rm_closure_bt.md @@ -0,0 +1,29 @@ +# Report Closure Behavior + +The Report Closure Behavior Tree is shown below. +As usual, the post-condition is checked before proceeding. +(A) If the case is already *Closed* ($q^{rm} \in C$), we're done. +Otherwise, (B) the main close sequence begins with a check for whether the report closure criteria have been met. +Report closure criteria are Participant-specific and are, therefore, out of scope for this specification. +Nevertheless, once those closure criteria are met, the actual *close report* task is activated (e.g., an `OnClose` callback). +The sequence ends with setting the state to *Closed* ($q^{rm} \xrightarrow{c} C$) and emitting an $RC$ message. + +```mermaid +--- +title: Report Closure Behavior Tree +--- +flowchart LR + fb["?"] + check_closed(["RM in C?"]) + fb -->|A| check_closed + seq["→"] + fb -->|B| seq + close_criteria_met(["close criteria met?"]) + seq --> close_criteria_met + close["close report"] + seq --> close + close_to_c["RM → C
(emit RC)"] + seq --> close_to_c +``` + + diff --git a/docs/topics/behavior_logic/rm_prioritization_bt.md b/docs/topics/behavior_logic/rm_prioritization_bt.md new file mode 100644 index 00000000..f51b066f --- /dev/null +++ b/docs/topics/behavior_logic/rm_prioritization_bt.md @@ -0,0 +1,81 @@ +# Report Prioritization Behavior + +The Report Prioritization Behavior Tree is shown in the figure below. +It bears some structural similarity to the Report Validation Behavior Tree just described: An initial +post-condition check (A) falls back to the main process (B) leading toward +$accept$, which, in turn, falls back to the deferral process (C). + +In more detail, (A) if the report is already in either the *Accepted* or *Deferred* states and no +new information is available to prompt a change, the behavior ends. + +```mermaid +--- +title: Report Prioritization Behavior Tree +--- +flowchart LR + fb["?"] + seq1["→"] + fb -->|A| seq1 + rm_d_or_a(["RM in D or A?"]) + seq1 --> rm_d_or_a + seq1fb["?"] + seq1 --> seq1fb + enough_info(["enough info?"]) + seq1fb --> enough_info + gather_seq["→"] + seq1fb --> gather_seq + gather_info["gather info"] + gather_seq --> gather_info + no_info["no new info"] + gather_seq --> no_info + seq2["→"] + fb -->|B| seq2 + rm_v_d_a(["RM in V, D, or A?"]) + seq2 --> rm_v_d_a + eval_priority["evaluate priority"] + seq2 --> eval_priority + priority_not_defer(["priority is not defer?"]) + seq2 --> priority_not_defer + accept_fb["?"] + seq2 --> accept_fb + rm_a(["RM in A?"]) + accept_fb --> rm_a + accept_seq["→"] + accept_fb --> accept_seq + accept["accept"] + accept_seq --> accept + accept_to_a["RM → A
(emit RA)"] + accept_seq --> accept_to_a + defer_fb["?"] + fb -->|C| defer_fb + rm_d(["RM in D?"]) + defer_fb --> rm_d + defer_seq["→"] + defer_fb --> defer_seq + defer["defer"] + defer_seq --> defer + defer_to_d["RM → D
(emit RD)"] + defer_seq --> defer_to_d +``` + + +Failing that, we enter the main prioritization sequence (B). The +preconditions of the main sequence are that either the report has not +yet been prioritized out of the *Valid* state ($q^{rm} \in V$) or new +information has been made available to a report in either +$q^{rm} \in \{ D, A \}$ to trigger a reevaluation. + +Assuming the preconditions are met, the report priority is evaluated. +For example, a Participant using [SSVC](https://github.com/CERTCC/SSVC) could insert +that process here. The evaluation task is expected to always set the +report priority. The subsequent check returns *Failure* on a defer +priority or *Success* on any non-deferral priority. On *Success*, an +*accept* task is included as a placeholder for any intake process that a +Participant might have for *Accepted* reports. Assuming that it +succeeds, the report is explicitly moved to the *Accepted* +($q^{rm} \xrightarrow{a} A$) state, and an $RA$ message is emitted. + +(C) Should any item in the main sequence fail, the case is deferred, its +state set to $q^{rm} \xrightarrow{d} D$, and an $RD$ message is emitted +accordingly. Similarly, a *defer* task is included as a callback +placeholder. diff --git a/docs/topics/behavior_logic/rm_validation_bt.md b/docs/topics/behavior_logic/rm_validation_bt.md new file mode 100644 index 00000000..d4037042 --- /dev/null +++ b/docs/topics/behavior_logic/rm_validation_bt.md @@ -0,0 +1,71 @@ +# Report Validation Behavior + +A Report Validation Behavior Tree is shown in the next figure. To begin with (A), if the report is already +*Valid*, no further action is needed from this behavior. + +```mermaid +--- +title: Report Validation Behavior Tree +--- +flowchart LR + fb["?"] + check_valid(["RM in V?"]) + fb -->|A| check_valid + i_seq["→"] + fb -->|B| i_seq + check_invalid(["RM in I?"]) + i_seq --> check_invalid + i_fb["?"] + i_seq --> i_fb + i_enough(["enough info?"]) + i_fb --> i_enough + i_seq_seq["→"] + i_fb --> i_seq_seq + i_gather_info["gather info"] + i_seq_seq --> i_gather_info + i_no_info["no new info"] + i_seq_seq --> i_no_info + ri_seq["→"] + fb -->|C| ri_seq + check_ri(["RM in R or I?"]) + ri_seq --> check_ri + eval_cred["evaluate credibility"] + ri_seq --> eval_cred + eval_valid["evaluate validity"] + ri_seq --> eval_valid + ri_to_v["RM → V
(emit RV)"] + ri_seq --> ri_to_v + ri_to_i["RM → I
(emit RI)"] + fb -->|D| ri_to_i +``` + +(B) When the report has already been designated as *Invalid*, the necessary +actions depend on whether further information is necessary, or not. If +the current information available in the report is sufficient, no +further action is necessary and the entire behavior returns *Success*. +However, a previous validation pass might have left some indicator that +more information was needed. In that case, execution proceeds to the +sequence in which the *gather info* task runs. If nothing new is found, +the entire branch returns *Success*, and the report remains *Invalid*. +If new information *is* found, though, the branch fails, driving +execution over to the main validation sequence. + +(C) The main validation sequence follows when none of the above conditions +have been met. In other words, the validation sequence is triggered when +the report is in *Received* and its validity has never been evaluated or +when the report was originally determined to be *Invalid* but new +information is available to prompt reconsideration. The validation +process shown here is comprised of two main steps: a credibility check +followed by a validity check as outlined in our introduction of +the [Received (R) state](../process_models/rm/index.md#the-received-r-state). + +As a reminder, a report might be in one of three categories: (a) neither +credible nor valid, (b) credible but invalid, or (c) both credible and +valid. Assuming the report passes both the credibility and validity +checks, it is deemed *Valid*, moved to $q^{rm} \xrightarrow{v} V$, and +an $RV$ message is emitted. + +(D) Should either check fail, the validation sequence fails, the report is +deemed *Invalid* and moves (or remains in) $q^{rm} \in I$. In that case, +an $RI$ message is sent when appropriate to update other Participants on +the corresponding state change. diff --git a/docs/topics/behavior_logic/vuldisco_bt.md b/docs/topics/behavior_logic/vuldisco_bt.md new file mode 100644 index 00000000..071a9365 --- /dev/null +++ b/docs/topics/behavior_logic/vuldisco_bt.md @@ -0,0 +1,53 @@ +# Vulnerability Discovery Behavior + +CVD is built on the idea that vulnerabilities exist to be found. There are two ways for a CVD Participant to +find out about a vulnerability. Either they discover it themselves, or they hear about it from someone else. +The discovery behavior is modeled by the Discover Vulnerability Behavior Tree shown in the figure below. +External reports are covered in the [Receive Messages](msg_intro_bt.md) Behavior Tree. + +```mermaid +--- +title: Discover Vulnerability Behavior Tree +--- +flowchart LR + fallback[?] + rm_not_s([RM not in S]) + fallback -->|A| rm_not_s + seq["→"] + fallback -->|B| seq + no_vul(["no vulnerability found"]) + fallback -->|C| no_vul + capability([discovery capability]) + seq --> capability + priority([discovery priority]) + seq --> priority + discover_vul["discover vulnerability"] + seq --> discover_vul + rm_to_r["RM S → R (emit RS)"] + seq --> rm_to_r + if_vendor[?] + seq --> if_vendor + not_vendor(["not a vendor"]) + if_vendor --> not_vendor + cs_to_V["CS v → V (emit CV)"] + if_vendor --> cs_to_V +``` + + +The goal of the Discover Vulnerability Behavior is for the Participant +to end up outside of the *Start* state of the Report Management process +($q^{rm} \not \in S$, branch A). + +Assuming this has not already occurred, the discovery sequence (branch B) is followed. +If the Participant has both the means and the motive to find a vulnerability, they might discover it +themselves. +Should this succeed, the branch sets $q^{rm} \in S \xrightarrow{r} R$ and returns *Success*. +We also show a report submission ($RS$) message being emitted as a reminder that even internally discovered +vulnerabilities can trigger the CVD process—although, at the point of discovery, the Finder is the only +Participant, so the $RS$ message in this situation might be an internal message within the Finder organization (at most). + +Should no discovery occur (branch C), the branch returns *Success* so that the parent process in +[CVD Behavior Tree](cvd_bt.md) can proceed to receive messages from others. + + + diff --git a/docs/topics/formal_protocol/index.md b/docs/topics/formal_protocol/index.md new file mode 100644 index 00000000..9d19290c --- /dev/null +++ b/docs/topics/formal_protocol/index.md @@ -0,0 +1,8 @@ +# Formal Protocol Summary + +The remainder of this page is a summary of the formal protocol condensed from the full description +provided in the [Formal Protocol](../../reference/formal_protocol/index.md) section. + +--- + +{% include-markdown "../../reference/formal_protocol/conclusion.md" heading-offset=1 %} diff --git a/docs/topics/formal_protocol/worked_example.md b/docs/topics/formal_protocol/worked_example.md new file mode 100644 index 00000000..97c59ac2 --- /dev/null +++ b/docs/topics/formal_protocol/worked_example.md @@ -0,0 +1,386 @@ +# Worked Example + +{% include-markdown "../../includes/not_normative.md" %} + +Here we give a brief worked example showing a few usage scenarios of the [protocol](../../reference/formal_protocol/index.md). +We use UML Sequence Diagrams to show the interaction between Participant roles. + +### A Finder Becomes a Reporter + +As mentioned in +[RM Interactions](../process_models/rm/rm_interactions.md#the-secret-lives-of-finders), Finders have a few hidden state +transitions before the CVD process really begins. An example of this +is shown in the figure below. The Finder must discover, validate, and +prioritize their finding before initiating the CVD process. + +```mermaid +sequenceDiagram + actor Finder + Finder ->> Finder: Discover + Finder ->> Finder: Validate + Finder ->> Finder: Prioritize +``` + +Finders become Reporters when they report a vulnerability to someone +else. The next figure shows a Finder sending a +report (_RS_) in conjunction with an embargo proposal (_EP_) to a +Vendor. The Vendor receives the report and updates their state +accordingly. Then the Vendor replies to acknowledge receipt of the +report and the embargo proposal, and confirms that they (i.e., the +Vendor) are aware of the report (_RK_, _EK_, and _CV_, respectively). +Note that the _EK_ response is intended to convey receipt of the embargo +proposal (_EP_) but does not constitute acceptance of the proposal. We +will discuss that in the next subsection. + +```mermaid +sequenceDiagram + actor Finder + actor Vendor + Finder ->> Finder: Discover, Validate, Prioritize + Finder ->> Vendor: RS, EP + note right of Vendor: Report Received + note right of Vendor: Embargo Proposed + note right of Vendor: Vendor Aware + Vendor -->> Finder: RK, EK, CV +``` + +### Vendor Evaluates Embargo {#sec:vendor_eval_embargo_seq} +In this section, we show a variety of responses a Vendor might have to an embargo proposal. + +#### Vendor Accepts Embargo +First is a basic accept sequence in which the Vendor accepts the proposed embargo and tells the +Reporter this through an _EA_ message. The Reporter acknowledges this with an _EK_ in response. + +```mermaid +sequenceDiagram + actor Reporter + actor Vendor + + Reporter ->> Vendor: EP + note right of Vendor: Embargo Proposed + Vendor -->> Reporter: RK + Vendor ->> Reporter: EA + activate Reporter + activate Vendor + note right of Vendor: Embargo Active + Reporter -->> Vendor: EK + deactivate Reporter + deactivate Vendor +``` + +#### Vendor Rejects Embargo +Next we show a rejected proposal. As above, this is a simple sequence where the Vendor indicates their rejection of the +proposal with an _ER_ message, and the Reporter acknowledges this with an _EK_ message. + +```mermaid +sequenceDiagram + actor Reporter + actor Vendor + + Reporter ->> Vendor: EP + note right of Vendor: Embargo Proposed + Vendor -->> Reporter: EK + Vendor ->> Reporter: ER + note right of Vendor: Embargo Rejected + Reporter -->> Vendor: EK +``` + +#### Vendor Counterproposal + +Here we demonstrate a Vendor embargo counterproposal. The Vendor responds to the Reporter's prior +_EP_ message with an _EP_ message of their own. The Reporter initially +acknowledges the counterproposal with an _RK_ message and then evaluates +it and accepts with an _EA_ message. Finally, the Vendor acknowledges +the acceptance with an _EK_ message. Note, however, that there is no +active embargo until the Reporter accepts it. This method of +counterproposal might delay the establishment of an embargo. + +```mermaid +sequenceDiagram + actor Reporter + actor Vendor + + Reporter ->> Vendor: EP + note right of Vendor: Embargo Proposed + Vendor -->> Reporter: RK + Vendor ->> Reporter: EP + Reporter -->> Vendor: RK + Reporter ->> Vendor: EA + activate Vendor + activate Reporter + note right of Vendor: Embargo Active + Vendor -->> Reporter: EK + deactivate Vendor + deactivate Reporter +``` + +#### Vendor Accepts then Proposes Revision + +!!! tip inline end "Yes, And..." + + "Yes-And" is a heuristic taken from improvisational theatre in which Participants are encouraged to agree with + whatever their counterpart suggests and add to it rather than reject it outright. + It serves as a good model for cooperation among parties who share an interest in a positive outcome. + +Finally, the following diagram offers what we think is a better approach than a simple counterproposal. +In this "Accept-then-Counter" sequence, we see that the Vendor initially accepts the Reporter's proposed embargo and +immediately follows up with a revision proposal of their own. +The difference is that by initially accepting the proposal, the Vendor ensures that they are in an active embargo state +before attempting to renegotiate. +The sequence shown here is intended to be consistent with the previous discussion surrounding [default embargo +strategies](../process_models/em/defaults.md). +One might think of this as the "Yes-And" rule for embargo negotiations. + + + +```mermaid +sequenceDiagram + actor Reporter + actor Vendor + + Reporter ->> Vendor: EP + note right of Vendor: Embargo Proposed + Vendor -->> Reporter: RK + Vendor ->> Reporter: EA + activate Vendor + activate Reporter + note right of Vendor: Embargo Active + Reporter -->> Vendor: EK + Vendor ->> Reporter: EV + note right of Vendor: Embargo Revise + Reporter -->> Vendor: RK + Reporter ->> Vendor: EC + note right of Vendor: Embargo Active + Vendor -->> Reporter: EK + deactivate Vendor + deactivate Reporter +``` + +### Vendor Sets Priority +Here we show two responses from a Vendor in the course of prioritizing a report. + +#### Vendor Accepts Report +This figure shows a Vendor accepting the report for further work (presumably to develop a patch) with an _RA_ message. + +```mermaid +sequenceDiagram + actor Reporter + actor Vendor + + Vendor ->> Vendor: Receive, Validate, Prioritize + Vendor ->> Reporter: RA + note right of Vendor: Report Accepted + Reporter -->> Vendor: RK +``` + +#### Vendor Defers Report + +On the contrary, this figure shows the Vendor deferring the report with an _RD_ message. +In both cases, the Reporter acknowledges the Vendor's messages with an _RK_ message. + +```mermaid +sequenceDiagram + actor Reporter + actor Vendor + + Vendor ->> Vendor: Receive, Validate, Prioritize + Vendor ->> Reporter: RD + note right of Vendor: Report Deferred + Reporter -->> Vendor: RK +``` + +### Coordination With a Coordinator {#sec:coordinating_with_coordinator} + +The next two diagrams show the process of a Reporter engaging a Coordinator, who, in turn, engages a Vendor. +The process begins in the first diagram with the Reporter sending a report along with an embargo proposal to the Coordinator +($RS,EP$). The Coordinator acknowledges receipt with an $RK,EK$ response. +After evaluating the proposed embargo, the Coordinator accepts it with an _EA_ message. +The Coordinator proceeds to validate and prioritize the report, emitting an _RV_ and _RA_ along the way. + +```mermaid +sequenceDiagram + actor Reporter + actor Coordinator + + Reporter ->> Coordinator: RS,EP + note right of Coordinator: Report Received + note right of Coordinator: Embargo Proposed + Coordinator -->> Reporter: RK,EK + Coordinator ->> Reporter: EA + activate Coordinator + activate Reporter + note right of Coordinator: Embargo Active + Reporter -->> Coordinator: EK + Coordinator ->> Reporter: RV + note right of Coordinator: Report Valid + Reporter -->> Coordinator: RK + Coordinator ->> Reporter: RA + note right of Coordinator: Report Accepted + Reporter -->> Coordinator: RK + deactivate Coordinator + deactivate Reporter +``` + +!!! tip inline end "Coordinator-as-proxy can be sub-optimal" + + In this scenario, we are showing the Coordinator acting as a proxy between the Reporter and the Vendor. + While this reflects the way CVD has been practiced in the past, it is not necessarily the most efficient way to + operate. CVD Platforms like [VINCE](https://kb.cert.org/vince) have demonstrated that bringing CVD case participants + into a shared space can make the process more efficient. + +In the next diagram, the Coordinator now acts as a proxy for the Reporter, notifying the Vendor and passing along +the embargo information through an $RS,EP$ message of its own. +The Vendor accepts the existing embargo (_EA_) and proceeds to validate (_RV_) and prioritize (_RA_) the report. +Relevant responses from the Vendor are passed through to the Reporter. +Having accepted the report for further work, the Vendor continues with creating a fix for the reported vulnerability. +When complete, the Vendor conveys their readiness to the Coordinator, who in turn passes this information along +to the Reporter through the _CF_ message. + +```mermaid +sequenceDiagram + actor Reporter + actor Coordinator + actor Vendor + + Coordinator ->> Vendor: RS,EP + Vendor -->> Coordinator: RK,EK,CV + Coordinator ->> Reporter: CV + Vendor --> Vendor: Evaluate Embargo + Reporter -->> Coordinator: CK + activate Vendor + note right of Vendor: Embargo Active + Vendor ->> Coordinator: EA + activate Coordinator + Coordinator ->> Reporter: EA + activate Reporter + Vendor --> Vendor: Validate Report + Coordinator -->> Vendor: EK + Reporter -->> Coordinator: EK + + note right of Vendor: Report Valid + Vendor ->> Coordinator: RV + Vendor --> Vendor: Prioritize Report + Coordinator -->> Vendor: RK + + note right of Vendor: Report Accepted + Vendor ->> Coordinator: RA + Vendor --> Vendor: Create Fix + Coordinator -->> Vendor: RK + + note right of Vendor: Fix Ready + Vendor ->> Coordinator: CF + Coordinator ->> Reporter: CF + + Coordinator -->> Vendor: CK + Reporter -->> Coordinator: CK + deactivate Vendor + deactivate Coordinator + deactivate Reporter +``` + + +### Embargo Teardown, Publish, and Close + +Any Participant can initiate an embargo teardown. +We happened to show the case where the Coordinator initiates it in the following diagram, sending an embargo +termination message (_ET_) to all parties in the case (Reporter and Vendor in this scenario). +Recipients of the _ET_ message acknowledge receipt and update their EM state accordingly. + +!!! tip "Embargo Teardown, Publication, and Closure Can Start with Any Participant" + + Note that for all three scenarios in this section, there is no specific order in which Participants must act. + We could just as easily have shown the Reporter initiating an embargo teardown because of a leaked media report or the + Vendor exiting an embargo early because they had their fix ready sooner than expected. + + +```mermaid +sequenceDiagram + actor Reporter + actor Coordinator + actor Vendor + + Coordinator ->> Reporter: ET + Coordinator ->> Vendor: ET + note right of Vendor: Embargo Terminated + Reporter -->> Coordinator: EK + Vendor -->> Coordinator: EK +``` + +!!! tip inline end "Embargo Termination is not Publication" + + Our protocol only sets a discrete end to the embargo period, it intentionally does *not* address a publication schedule. + Once the embargo has been exited, *any* Participant may publish at any time. + Participants might choose to coordinate publication schedules more closely, but there is nothing in the protocol to require it. + With the recognition that more concise publication scheduling might be needed in some situations, we revisit this + concern in [Process Implementation Notes](../../howto/process_implementation.md). + + +#### Publishing After Embargo Teardown + +Once the embargo has been exited, any Participant may now publish. +In the following figure, we show the Vendor publishing first. +They notify the Coordinator that they have published using a _CP_ message to convey that information about the vulnerability +is now public. +The Coordinator relays this information to the Reporter. +Both the Reporter and the Coordinator publish their own reports shortly thereafter. + +```mermaid +sequenceDiagram + actor Reporter + actor Coordinator + actor Vendor + + Vendor --> Vendor: Publish + note right of Vendor: Public Aware + Vendor ->> Coordinator: CP + Coordinator ->> Reporter: CP + Reporter -->> Coordinator: CK + Reporter --> Reporter: Publish + Reporter ->> Coordinator: CP + Coordinator ->> Vendor: CP + Coordinator -->> Reporter: CK + Vendor -->> Coordinator: CK + Coordinator --> Coordinator: Publish + Coordinator ->> Reporter: CP + Coordinator ->> Vendor: CP + Reporter -->> Coordinator: CK + Vendor -->> Coordinator: CK +``` + +!!! tip inline end "Report Closure is a Per-Participant Choice" + + Report closure is a per-Participant choice. We chose to show a + simple case where all Participants agreed at approximately the same time + that there was nothing further to be done. This will not always be the + case, nor is it necessary. + + +#### Closing the Case + +Having no further work to be done on the case, the Reporter closes their +report and tells the Coordinator using an _RC_ message in the next diagram. +This prompts the Coordinator to review their outstanding tasks and decide to initiate the closure of their own report. +In turn, the Coordinator relays this to the Vendor, who also closes their report. + +```mermaid +sequenceDiagram + actor Reporter + actor Coordinator + actor Vendor + + Reporter --> Reporter: Close + Reporter ->> Coordinator: RC + Coordinator -->> Reporter: RK + Coordinator --> Coordinator: Close + Coordinator ->> Vendor: RC + Vendor -->> Coordinator: RK + Vendor --> Vendor: Close + note right of Vendor: Case Closed + Vendor ->> Coordinator: RC + Coordinator -->> Vendor: RK +``` + + + + + diff --git a/docs/topics/future_work/cvd_directory.md b/docs/topics/future_work/cvd_directory.md new file mode 100644 index 00000000..a7fd071e --- /dev/null +++ b/docs/topics/future_work/cvd_directory.md @@ -0,0 +1,97 @@ +# CVD Directory + +{% include-markdown "../../includes/not_normative.md" %} + +The idea of CVD embargoes implies a means of dividing the world into + +1. those who belong in the embargo +2. those who do not + +Because _authentication_ is not the same as _authorization_, we cannot simply rely on knowing who a Participant +is; we also have to be able to identify *why* they are *relevant* to a particular case. + +Thus, we must ask: + +!!! question + + How do Participants find other relevant potential Participants to invite to a case? + +!!! tip inline end "security.txt" + + Vendors can improve their discoverability by using a + `security.txt` file on their websites. See [securitytxt.org](https://securitytxt.org) and [RFC 9116](https://www.rfc-editor.org/rfc/rfc9116.html) + for more information. + +In small CVD cases, the answer might be straightforward: The affected product comes from a known Vendor, +so the only question to answer is how best to contact them. +As a first approximation, Internet search engines offer a de facto baseline CVD directory service simply because they +allow any potential Reporter to search for ` vulnerability report` or similar terms to find an +individual Vendor contact. + +But in larger MPCVD cases, there are a few entangled +problems: + +1. It can be difficult and inefficient to collect contact information + for all possibly relevant parties. + +2. Even if contact information is widely available using searchable + resources, many Vendors' preferred contact methods might preclude + automation of mass notification (or require customized integration + to ensure interoperability between report senders and receivers). + Some Vendors only want email. Others require Reporters to create an + account on their bespoke bug-tracking system before reporting. + Others ask for submissions via a customized web form. These and [other examples](https://vuls.cert.org/confluence/display/CVD/4.2+Reporting) + hinder the interoperability of MPCVD processes. + +3. It is not always clear which *other* Vendors' products contain the + affected product, which limits the ability for an MPCVD cases to follow the software + supply chain. + +4. Sometimes vulnerabilities arise in protocols or specifications where + multiple implementations are affected. It can be difficult to + identify Vendors whose products implement specific technologies. + Software reverse engineering methods can be used to identify + affected products in some cases. + +5. At the same time, some Vendors treat their product's subcomponents + as proprietary close-hold information for competitive advantage; + this might happen, for example, with OEM or white label licensing agreements. + While it is certainly their prerogative to do so, this desire to + avoid disclosing internal components of a product can inhibit + discovery---and therefore disclosure to the Vendor---that a + vulnerability affects a product. + + +!!! tip inline end "For more information" + + - [FIRST Teams](https://www.first.org/members/teams/) + - Disclose.io [website](https://disclose.io/programs/) and on [GitHub](https://github.com/disclose/diodb) + +When it comes to larger scale MPCVD, the inefficiency of ad hoc contact +collection via search engines is evident. Creating a directory of +software Vendors and Coordinators and their vulnerability disclosure +programs would be a step in the right direction. Community-operated +directories such as the FIRST member list or Disclose.io serve as +proof-of-concept of the value such systems can provide. We +especially like the open source model that [Disclose.io](https://disclose.io/) uses, which +solicits contributions from the community. + +But further improvements to MPCVD contact management could be made by +standardizing the following: + +- contact information records and the APIs to access them + +- contact methods, including common protocols such as the one we just + proposed, in conjunction with common data object models and + vocabularies or ontologies + +- SBOM publication and aggregation services + +- mechanisms for Vendors to register their interest in specific + technologies + +The last of these suggested improvements is not without its challenges. +It is difficult to prevent adversarial parties (including Participants +who might be competitors or have motives incompatible with +CVD principles) from registering interest in receiving vulnerability reports about +technologies in others' products. diff --git a/docs/topics/future_work/index.md b/docs/topics/future_work/index.md new file mode 100644 index 00000000..2a2a20cf --- /dev/null +++ b/docs/topics/future_work/index.md @@ -0,0 +1,13 @@ +# Future Work + +Here we review a number of items remaining as future work. +In the following pages you'll find: + +- A discussion of the need for a [CVD Directory](cvd_directory.md) and some of the difficulties it +might pose +- A few ideas to [reward efficient behavior](reward_functions.md) elaborating on the concept of churn in the RM and EM processes +- Brief thoughts on the potential [use of ontologies](ontology.md) for process interoperability +- Ideas for future [modeling and simulation](mod_sim.md) to further improve the MPCVD process + + + diff --git a/docs/topics/future_work/mod_sim.md b/docs/topics/future_work/mod_sim.md new file mode 100644 index 00000000..f51f8163 --- /dev/null +++ b/docs/topics/future_work/mod_sim.md @@ -0,0 +1,19 @@ +# Modeling and Simulation + +{% include-markdown "../../includes/not_normative.md" %} + +The [protocol formalisms](../../reference/formal_protocol/index.md) and [Behavior Trees](../behavior_logic/index.md) +provided in this documentation combined with the [CS model](../process_models/cs/index.md) described in +[A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) +point the way toward improvements in MPCVD modeling and simulation. +Given the complexity of the protocol state interactions described in +the [formal protocol](../../reference/formal_protocol/index.md) +and the corresponding behaviors described in [CVD Behaviors](../behavior_logic/cvd_bt.md), we anticipate that modeling +and simulation work will continue progressing toward a reference implementation of the protocol we describe here. + +Furthermore, the [reward functions](reward_functions.md) we outlined can—once fully realized—be used to +evaluate the efficacy of future modifications to the protocol. +This effort could, in turn, lead to future improvements and optimizations of the MPCVD process. +The modularity of [Behavior Trees](../behavior_logic/index.md) provides ready ground for simulated experiments to determine what additional +optimizations to the MPCVD process might be made in the future. + diff --git a/docs/topics/future_work/ontology.md b/docs/topics/future_work/ontology.md new file mode 100644 index 00000000..cd7a4bde --- /dev/null +++ b/docs/topics/future_work/ontology.md @@ -0,0 +1,24 @@ +# Ontology + +{% include-markdown "../../includes/not_normative.md" %} + +The Vultron Protocol does not make its appearance in uncharted territory, where no existing CVD systems or processes +exist. +Rather, we propose it as an improvement to interactions among humans, systems, and business processes that already +perform MPCVD around the world every day. +Thus, for adoption to occur, it will be necessary to map existing systems and processes into the semantics +(and eventually, the syntax) of whatever protocol emerges as a descendant of our proposal. + +Combined with the abstract [case class model](../../howto/case_object.md), an ontology (e.g., using +[OWL](https://www.w3.org/OWL/)) could accelerate +the semantic interoperability between independent Participant processes and tools that we set out to improve at the +beginning of this effort. + +## Related Ontology and Data Definition Work + +It is currently unclear how this work might intersect with the NIST +[Vulnerability Data Ontology](https://github.com/usnistgov/vulntology) (a.k.a. _Vulntology_), but we anticipate that there may be some +opportunity for further collaboration. +Also, we recognize that the OASIS [Common Security Advisory Framework](https://oasis-open.github.io/csaf-documentation/) +is addressing a different abstraction of a closely related problem (representing vulnerability reports and advisories), +so we believe that there may be some opportunity for collaboration there as well. \ No newline at end of file diff --git a/docs/topics/future_work/reward_functions.md b/docs/topics/future_work/reward_functions.md new file mode 100644 index 00000000..c388a839 --- /dev/null +++ b/docs/topics/future_work/reward_functions.md @@ -0,0 +1,97 @@ +# Reward Functions + +{% include-markdown "../../includes/not_normative.md" %} + +Further optimization of the Vultron Protocol can be studied with the +development of reward functions to evaluate preferences for certain +CVD case histories +over others. +In [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513), +we provided a method to measure skill (${\alpha}_d$) in CVD based on a partial order over the CVD success criteria that make up the CS process, as outlined in +[Defining CVD Success](../background/cvd_success.md). +While not yet a fully-realized reward function, we feel that the ${\alpha}_d$ skill measure has potential as the basis +of a reward function for the CS model. + +The following sections describe two additional reward functions. + +## A Reward Function for Minimizing RM Strings + +In [RM State Transitions](../process_models/rm/index.md#rm-state-transitions), we described a grammar that generates +RM histories. +The state machine can generate arbitrarily long histories because of the cycles in the state machine graph; +however, we observed that human Participants in any real CVD case would likely check the amount of churn. +That sort of reliance on human intervention will not scale as well as a more automatable solution might. + +As a result, we suggest that future work might produce a reward function that can be used to optimize RM histories. +Such a function would need to include the following: + +- a preference for shorter paths over longer ones + +- a preference for paths that traverse through $q^{rm} \in A$ over + ones that do not + +- a preference for Vendor attentiveness. + +- a preference for validation accuracy + +!!! tip "Notes on Vendor attentiveness" + + The default path for an organization with no CVD capability is effectively + ${q^{em} \in S \xrightarrow{r} R \xrightarrow{i} I \xrightarrow{c}C}$, + which is short (_good!_). + However, assuming the vulnerability is legitimate, half of the desired CS criteria can never be achieved + (_bad!_). + In other words, $\mathbf{F} \prec \mathbf{P}$, + $\mathbf{F} \prec \mathbf{X}$, $\mathbf{F} \prec \mathbf{A}$, + $\mathbf{D} \prec \mathbf{P}$, $\mathbf{D} \prec \mathbf{X}$, + $\mathbf{D} \prec \mathbf{A}$ are impossible when the Vendor ignores + the report. + No reward function should provide incentive for willful Vendor ignorance. + +!!! tip "Notes on validation accuracy" + + Real vulnerabilities should pass through $q^{rm} \in V$, while bogus reports should pass through $q^{rm} \in I$. + The only RM paths path not involving at least one step through $q^{rm} \in A$ are the following. + + | Path | Description | + | ---- | ----------- | + | $q^{rm} \in S \xrightarrow{r} R \xrightarrow{i} I \xrightarrow{c} C$ | Ignore an invalid case. | + | $q^{rm} \in S \xrightarrow{r} R \xrightarrow{v} V \xrightarrow{d} D \xrightarrow{c} C$ | Defer a valid case. | + | $q^{rm} \in S \xrightarrow{r} R \xrightarrow{i} I \xrightarrow{v} V \xrightarrow{d} D \xrightarrow{c} C$ | Initially ignore an invalid case, then validate, but defer it anyway. | + + To an outside observer, any of these could be interpreted as inattentiveness from an uncommunicative Participant. + Yet any of these paths might be fine, assuming that (1) the Participant communicates about their RM state + transitions, and (2) the $a$ transition was possible but intentionally just not taken. + +!!! tip inline end "On the origin of the *CERT/CC Addendum* field in CERT/CC Vulnerability Notes" + + The problem described at left is why the individual Vendor records in + CERT/CC Vulnerability Notes contain a *CERT/CC Addendum* field. + +These last two imply some capacity for independent validation of +reports, which, on the surface, seems poised to add cost or complexity +to the process. However, in any MPCVD case with three or more Participants, a +consensus or voting heuristic could be applied. For example, should a +quorum of Participants agree that a Vendor's products are affected even +if the Vendor denies it, an opportunity exists to capture this +information as part of the case. + + + +## A Reward Function for Minimizing EM Strings + +Similarly, the EM process also has the potential to generate arbitrarily long histories, +as shown in [A Regular Grammar for EM](../process_models/em/index.md#sec:em_grammar). +Again, reliance on humans to resolve this shortcoming may be acceptable for now; +however, looking to the future, we can imagine a reward function to be optimized. +The EM reward function might include the following: + +- a preference for short paths + +- a preference for quick agreement (i.e., the $a$ transition appearing + early in the EM + history) + +- a limit on how long an EM history can get without reaching + $q^{em} \in A$ at all (i.e., How many proposal-rejection cycles are + tolerable before giving up?) diff --git a/docs/topics/index.md b/docs/topics/index.md new file mode 100644 index 00000000..8fef7950 --- /dev/null +++ b/docs/topics/index.md @@ -0,0 +1,23 @@ +# Understanding the Vultron Protocol + +!!! tip inline end "Prerequisites" + + The [Understanding Vultron](index.md) section assumes that you have: + + - an interest in learning about the Vultron Protocol + - familiarity with the CVD process in general + + If you are already familiar with the Vultron Protocol, and are looking for implementation advice, + see [Implementing Vultron](../howto/index.md). + For technical reference, see [Reference](../reference/index.md). + If you're just trying to understand the CVD process, we recommend that you start with the [CERT Guide to Coordinated Vulnerability Disclosure](https://vuls.cert.org/confluence/display/CVD/). + + +This section provides an overview of the Vultron Protocol, including: + +- [Background](background/index.md) +- [Behavior Logic](behavior_logic/index.md) +- [Formal Protocol overview](formal_protocol/index.md) +- [Future Work](future_work/index.md) +- [Process Models](process_models/index.md) +- [User Stories](user_stories/index.md) \ No newline at end of file diff --git a/docs/topics/process_models/cs/cs_model.md b/docs/topics/process_models/cs/cs_model.md new file mode 100644 index 00000000..926d3035 --- /dev/null +++ b/docs/topics/process_models/cs/cs_model.md @@ -0,0 +1,426 @@ +# CVD Case State Model + +{% include-markdown "../../../includes/normative.md" %} + +Here we complete the definition of the CVD Case State (CS) model begun in the [previous page](index.md). +As a reminder, this model provides a high-level view of the state of a CVD case and is +derived from [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513). + +--- + +{% include-markdown "../dfa_notation_definition.md" %} + +As in the [RM](../rm/index.md) and [EM](../em/index.md) process models, we wish to define a 5-tuple +$(\mathcal{Q},\Sigma,\delta,q_0,F)$, this time for the CS model. + +!!! example inline "Example CS State" + + The state $q^{cs} \in VFdpXa$ represents that: + + - the Vendor is aware + - the fix is ready + - the fix is not deployed + - no public awareness + - an exploit is public + - no attacks have been observed + +In the CS model, a state $q^{cs}$ represents the status of each of the six [substates](index.md). +State labels use the substate notation given in the table below. + +The order in which the events occurred does not matter when defining the state. +However, we will observe a notation convention keeping the letter names in the same case-insensitive order +$(v,f,d,p,x,a)$. + +The CS model builds upon the CVD substates defined in the [Case State introduction](index.md), summarized +in the table below. + + +{% include-markdown "cs_substates_table.md" %} + +???+ note inline end "Vendor Fix Path Formalism" + + $$D \implies F \implies V$$ + +CS states can be any combination of statuses, provided that a number of caveats elaborated in +[CS Transitions](#cs-transitions) are met. +One such caveat worth noting here is that valid states must follow what we call the *Vendor fix path*. + + +The reason is causal: For a fix to be deployed (_D_), it must have been ready (_F_) for deployment. +And for it to be ready, the Vendor must have already known (_V_) about the vulnerability. +As a result, valid states must begin with one of the following strings: _vfd_, _Vfd_, _VFd_, or _VFD_. + +!!! tip inline end "See also" + + See §2.4 of [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) + for an expanded explanation of the *Vendor fix path*. + + +```mermaid +--- +title: Vendor Fix Path +--- +stateDiagram-v2 + vfd : Vendor is unaware (vfd) + Vfd : Vendor is aware (Vfd) + VFd : Vendor is aware and fix is ready (VFd) + VFD : Vendor is aware and fix is deployed (VFD) + vfd --> Vfd : vendor becomes aware + Vfd --> VFd : fix is ready + VFd --> VFD : fix is deployed +``` + + +The CS model is thus +composed of 32 possible states, which we define as $\mathcal{Q}^{cs}$. + +???+ note "CS Model States ($\mathcal{Q}^{cs}$) Defined" + + $$ + \mathcal{Q}^{cs} = + \begin{Bmatrix} + vfdpxa, & vfdPxa, & vfdpXa, & vfdPXa, \\ + vfdpxA, & vfdPxA, & vfdpXA, & vfdPXA, \\ + Vfdpxa, & VfdPxa, & VfdpXa, & VfdPXa, \\ + VfdpxA, & VfdPxA, & VfdpXA, & VfdPXA, \\ + VFdpxa, & VFdPxa, & VFdpXa, & VFdPXa, \\ + VFdpxA, & VFdPxA, & VFdpXA, & VFdPXA, \\ + VFDpxa, & VFDPxa, & VFDpXa, & VFDPXa, \\ + VFDpxA, & VFDPxA, & VFDpXA, & VFDPXA + \end{Bmatrix}$$ + +???+ note inline end "CS Model Start and End States ($q^{cs}_0$ and $\mathcal{F}^{cs}$) Defined" + + $$q^{cs}_0 = vfdpxa$$ + + $$\mathcal{F}^{cs} = \{ VFDPXA \}$$ + +## CS Start and End States + +All vulnerability cases start in the base state _vfdpxa_ in which no +events have occurred. + +The lone final state in which all events have occurred is _VFDPXA_. + + +!!! tip "The Map is not the Territory" + + Note that this is a place where our + model of the vulnerability lifecycle diverges from what we expect to + observe in CVD + cases in the real world. There is ample evidence that most + vulnerabilities never have exploits published or attacks observed. + See for example: + + - [Historical Analysis of Exploit Availability Timelines](https://www.usenix.org/conference/cset20/presentation/householder) + - [Exploit Prediction Scoring System (EPSS)](https://dl.acm.org/doi/pdf/10.1145/3436242) + + Therefore, practically speaking, we might expect vulnerabilities to wind up in one of + + $$\mathcal{F}^\prime = \{ {VFDPxa}, {VFDPxA}, {VFDPXa}, {VFDPXA} \}$$ + + at the time a report is closed (i.e., when $q^{rm} \xrightarrow{c} C$). In + fact, most count a CVD as successful when reports are closed in + $q^{cs} \in VFDPxa$ because it means that the defenders won the race + against adversaries. The distinction between the [RM](../rm/index.md) and CS processes is important; Participants can + close cases whenever their [RM](../rm/index.md) process dictates, independent of the + CS state. In other + words, it remains possible for exploits to be published or attacks to be + observed long after the [RM](../rm/index.md) process has closed a case. + + +We frequently need to refer to subsets of $\mathcal{Q}^{cs}$. To do so, +we will use a dot ($\cdot$) to represent a single character wildcard. + +!!! example "CS Model Wildcard Notation Example" + + For example, $VFdP \cdot \cdot$ refers to the subset of $\mathcal{Q}^{cs}$ in + which the Vendor is aware, a fix is ready but not yet deployed, and the + public is aware of the vulnerability, yet we are indifferent to whether + exploit code has been made public or attacks have been observed. + Specifically, + + $${VFdP\cdot\cdot} = \{{VFdPxa}, {VFdPxA}, {VFdPXa}, {VFdPXA}\} \subset{\mathcal{Q}}^{cs}$$ + +## CS Transitions + +In this section, we elaborate on the input symbols and transition functions for our CS DFA. +A row-wise reading of the [CVD Case Substates](#cs-model-states-defined) table above +implies a set of events corresponding to each specific substate change, which we correspond to the symbols in the DFA. + +| Symbol | Description | Formalism | +|:------:| :--- |:------------------------------------------------------------------------------------:| +| **V** | A Vendor becomes aware of a vulnerability | $vfd\cdot\cdot\cdot \xrightarrow{\mathbf{V}} Vfd\cdot\cdot\cdot$ | +| **F** | A Vendor readies a fix for a vulnerability | $Vfd\cdot\cdot\cdot \xrightarrow{\mathbf{F}} VFd\cdot\cdot\cdot$ | +| **D** | A Deployer deploys a fix for a vulnerability | $VFd\cdot\cdot\cdot \xrightarrow{\mathbf{D}} VFD\cdot\cdot\cdot$ | +| **P** | Information about a vulnerability becomes known to the public | $\cdot\cdot\cdot p \cdot\cdot \xrightarrow{\mathbf{P}} \cdot\cdot\cdot P \cdot\cdot$ | +| **X** | An exploit for a vulnerability is made public | $\cdot\cdot\cdot\cdot x \cdot \xrightarrow{\mathbf{X}} \cdot\cdot\cdot\cdot X \cdot$ | +| **A** | Attacks exploiting a vulnerability are observed | $\cdot\cdot\cdot\cdot\cdot a \xrightarrow{\mathbf{A}} \cdot\cdot\cdot\cdot\cdot A$ | + + +???+ note inline end "CS Model Input Symbols ($\Sigma^{cs}$) Defined" + + $$\Sigma^{cs} = \{\mathbf{V},\mathbf{F},\mathbf{D},\mathbf{P},\mathbf{X},\mathbf{A}\}$$ + + Here we diverge somewhat from the notation used for the + [RM](../rm/index.md) and [EM](../em/index.md) models, which use lowercase letters for transitions and + uppercase letters for states. Because CS state names already use both lowercase + and uppercase letters, here we use a bold font for the symbols of the + CS DFA to differentiate the transition from the corresponding substate it leads + to: e.g., $vfd\cdot\cdot\cdot \xrightarrow{\mathbf{V}} Vfd\cdot\cdot\cdot$. + +We define the set of symbols for our CS DFA as $\Sigma^{cs}$ at right. + + +For the CS model, an input symbol $\sigma^{cs} \in \Sigma^{cs}$ is "read" when a Participant +observes a change in status (a Vendor is notified and exploit code has +been published, etc.). +For the sake of simplicity, we begin with the +assumption that observations are globally known—that is, a status +change observed by any CVD Participant is known to all. In the real +world, we believe the [Formal Vultron Protocol](../../../reference/formal_protocol/index.md) +is poised to ensure eventual +consistency with this assumption through the communication of perceived +case state across coordinating parties. + +### CS Transitions Defined + +Here we define the allowable transitions between states in the +CS model. +Transitions in the CS model follow a few rules described in +detail in §2.4 of [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) which we summarize here: + +- Because states correspond to the status of events that have or have + not occurred, and all state transitions are irreversible (i.e., we + assume history is immutable), the result will be an acyclic directed + graph of states beginning at $q^{cs}_0={vfdpxa}$ and ending at + $\mathcal{F}^{cs}=\{VFDPXA\}$ with allowed transitions as the edges. + In practical terms for the CS model, this means there is an arrow + of time from _vfdpxa_ through _VFDPXA_ in which each individual + state transition changes exactly one letter from lowercase to + uppercase. + +- The *Vendor fix path* + ($vfd \cdot\cdot\cdot \xrightarrow{\mathbf{V}} Vfd \cdot\cdot\cdot \xrightarrow{\mathbf{F}} VFd \cdot\cdot\cdot \xrightarrow{\mathbf{D}} VFD \cdot\cdot\cdot$) + is a causal requirement as outlined in [substates](cs_model.md). + +```mermaid +stateDiagram-v2 + direction LR + vfd: vfd... + Vfd: Vfd... + VFd: VFd... + VFD: VFD... + + [*] --> vfd + vfd --> Vfd + Vfd --> VFd + VFd --> VFD + VFD --> [*] +``` + + +- Vendors are presumed to know at least as much as the public does; + therefore, $v\cdot\cdot P \cdot\cdot$ can only lead to $V\cdot\cdot P \cdot\cdot$. + +```mermaid +stateDiagram-v2 + direction LR + vP: v..P.. + VP: V..P.. + vP --> VP +``` + + +#### Exploit Publication Causes Public Awareness + +Exploit publication is tantamount to public awareness; therefore, +$\cdot\cdot\cdot pX \cdot$ can only lead to $\cdot\cdot\cdot\cdot PX \cdot$. + +```mermaid +stateDiagram-v2 + direction LR + pX: ...pX. + PX: ...PX. + pX --> PX +``` + +Therefore, for all practical purposes, we can simplify the full $pxa \rightarrow PXA$ diagram: + + +{% include-markdown "pxa_diagram.md" %} + +down to the following: + +{% include-markdown "pxa_diagram_simple.md" %} + + +#### Attacks Do Not Necessarily Cause Public Awareness + +In this model, attacks observed when a vulnerability is unknown to the +public ($\cdot\cdot\cdot p \cdot A$) need not immediately cause public awareness +($\cdot\cdot\cdot P \cdot A$), although, obviously, that can and does happen. +Our reasoning for allowing states in $\cdot\cdot\cdot p \cdot A$ to persist is +twofold: + +1. The connection between attacks and exploited vulnerabilities + is often made later during incident analysis. While the attack + itself may have been observed much earlier, the knowledge of *which* + vulnerability it targeted may be delayed until after other events + have occurred. +2. Attackers are not a monolithic group. An attack from a niche + set of threat actors does not automatically mean that the knowledge + and capability of exploiting a particular vulnerability is widely + available to all possible adversaries. Publication, in that case, + might assist other adversaries more than it helps defenders. + + +In other words, although $\cdot\cdot\cdot p \cdot A$ does not require an +immediate transition to $\cdot\cdot\cdot P \cdot A$ the way +$\cdot\cdot\cdot pX \cdot \xrightarrow{\mathbf{P}} \cdot\cdot\cdot PX \cdot$ does, it +does seem plausible that the likelihood of **P** occurring +increases when attacks are occurring. + +???+ note "Formalism" + + The probability $P$ of _public awareness_ given _attacks observed_ is + greater than the probability of _public awareness_ without _attacks observed_. + + $$ + P(\mathbf{P} \mid \cdot\cdot\cdot p \cdot A) > P(\mathbf{P} \mid \cdot\cdot\cdot p \cdot a) + $$ + +Logically, this is a result of there being more ways for the public to discover the vulnerability when attacks are +happening than when they are not: + +- For states in $\cdot\cdot\cdot p \cdot a$, public awareness depends on the normal vulnerability discovery and reporting +process. +- States in $\cdot\cdot\cdot p \cdot A$ include that possibility and add the potential for discovery as a result of +security incident analysis. + +Hence, + +!!! note "" + + Once attacks have been observed, fix development SHOULD accelerate, + the embargo teardown process SHOULD begin, and publication and + deployment SHOULD follow as soon as is practical. + + +## A Regular Grammar for the CS model + +Following the complete state machine diagram in above, we can summarize the transition functions of the CS model as a +right-linear grammar $\delta^{cs}$. + +???+ note "CS Transition Function ($\delta^{cs}$) Defined" + + $\delta^{cs} = + \begin{cases} + vfdpxa &\to \mathbf{V}~Vfdpxa~|~\mathbf{P}~vfdPxa~|~\mathbf{X}~vfdpXa~|~\mathbf{A}~vfdpxA \\ + vfdpxA &\to \mathbf{V}~VfdpxA~|~\mathbf{P}~vfdPxA~|~\mathbf{X}~vfdpXA \\ + vfdpXa &\to \mathbf{P}~vfdPXa \\ + vfdpXA &\to \mathbf{P}~vfdPXA \\ + vfdPxa &\to \mathbf{V}~VfdPxa \\ + vfdPxA &\to \mathbf{V}~VfdPxA \\ + vfdPXa &\to \mathbf{V}~VfdPXa \\ + vfdPXA &\to \mathbf{V}~VfdPXA \\ + Vfdpxa &\to \mathbf{F}~VFdpxa~|~\mathbf{P}~VfdPxa~|~\mathbf{X}~VfdpXa~|~\mathbf{A}~VfdpxA \\ + VfdpxA &\to \mathbf{F}~VFdpxA ~|~ \mathbf{P}~VfdPxA ~|~ \mathbf{X}~VfdpXA \\ + VfdpXa &\to \mathbf{P}~VfdPXa \\ + VfdpXA &\to \mathbf{P}~VfdPXA \\ + VfdPxa &\to \mathbf{F}~VFdPxa ~|~ \mathbf{X}~VfdPXa ~|~ \mathbf{A}~VfdPxA \\ + VfdPxA &\to \mathbf{F}~VFdPxA ~|~ \mathbf{X}~VfdPXA \\ + VfdPXa &\to \mathbf{F}~VFdPXa ~|~ \mathbf{A}~VfdPXA \\ + VfdPXA &\to \mathbf{F}~VFdPXA \\ + VFdpxa &\to \mathbf{D}~VFDpxa~|~\mathbf{P}~VFdPxa ~|~ \mathbf{X}~VFdpXa ~|~ \mathbf{A}~VFdpxA \\ + VFdpxA &\to \mathbf{D}~VFDpxA ~|~ \mathbf{P}~VFdPxA ~|~ \mathbf{X}~VFdpXA \\ + VFdpXa &\to \mathbf{P}~VFdPXa \\ + VFdpXA &\to \mathbf{P}~VFdPXA \\ + VFdPxa &\to \mathbf{D}~VFDPxa ~|~ \mathbf{X}~VFdPXa ~|~ \mathbf{A}~VFdPxA \\ + VFdPxA &\to \mathbf{D}~VFDPxA ~|~ \mathbf{X}~VFDPXA \\ + VFdPXa &\to \mathbf{D}~VFDPXa ~|~ \mathbf{A}~VFdPXA \\ + VFdPXA &\to \mathbf{D}~VFDPXA \\ + VFDpxa &\to \mathbf{P}~VFDPxa ~|~ \mathbf{X}~VFDpXa ~|~ \mathbf{A}~VFDpxA \\ + VFDpxA &\to \mathbf{P}~VFDPxA ~|~ \mathbf{X}~VFDpXA \\ + VFDpXa &\to \mathbf{P}~VFDPXa \\ + VFDpXA &\to \mathbf{P}~VFDPXA \\ + VFDPxa &\to \mathbf{X}~VFDPXa ~|~ \mathbf{A}~VFDPxA \\ + VFDPxA &\to \mathbf{X}~VFDPXA \\ + VFDPXa &\to \mathbf{A}~VFDPXA \\ + VFDPXA &\to \varepsilon \\ + \end{cases}$ + +!!! tip "For more information" + + A more thorough examination of the strings generated by this grammar, + their interpretation as the possible histories of all CVD cases, and implications for measuring the efficacy of the + overall CVD process writ large can be found in [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513). + +## CS Model Diagram + +A diagram of the CS process, including its states and transitions, is shown below. + +{% include-markdown "vfdpxa_diagram.md" %} + + +## CS Model Fully Defined + +In combination, the full definition of the Case State DFA $(\mathcal{Q},q_0,\mathcal{F},\Sigma,\delta)^{cs}$ is shown +below. + +???+ note "Case State Model $(\mathcal{Q},q_0,\mathcal{F},\Sigma,\delta)^{cs}$ Fully Defined" + + $CS = + \begin{pmatrix} + \begin{aligned} + \mathcal{Q}^{cs} = & + \begin{Bmatrix} + vfdpxa, & vfdPxa, & vfdpXa, & vfdPXa, \\ + vfdpxA, & vfdPxA, & vfdpXA, & vfdPXA, \\ + Vfdpxa, & VfdPxa, & VfdpXa, & VfdPXa, \\ + VfdpxA, & VfdPxA, & VfdpXA, & VfdPXA, \\ + VFdpxa, & VFdPxa, & VFdpXa, & VFdPXa, \\ + VFdpxA, & VFdPxA, & VFdpXA, & VFdPXA, \\ + VFDpxa, & VFDPxa, & VFDpXa, & VFDPXa, \\ + VFDpxA, & VFDPxA, & VFDpXA, & VFDPXA + \end{Bmatrix}, \\ + q^{cs}_0 = & vfdpxa, \\ + \mathcal{F}^{cs} = &\{VFDPXA\}, \\ + \Sigma^{cs} = & \{\mathbf{V},\mathbf{F},\mathbf{D},\mathbf{P},\mathbf{X},\mathbf{A}\}, \\ + \delta^{cs} = & + \begin{cases} + vfdpxa &\to \mathbf{V}~Vfdpxa~|~\mathbf{P}~vfdPxa~|~\mathbf{X}~vfdpXa~|~\mathbf{A}~vfdpxA \\ + vfdpxA &\to \mathbf{V}~VfdpxA~|~\mathbf{P}~vfdPxA~|~\mathbf{X}~vfdpXA \\ + vfdpXa &\to \mathbf{P}~vfdPXa \\ + vfdpXA &\to \mathbf{P}~vfdPXA \\ + vfdPxa &\to \mathbf{V}~VfdPxa \\ + vfdPxA &\to \mathbf{V}~VfdPxA \\ + vfdPXa &\to \mathbf{V}~VfdPXa \\ + vfdPXA &\to \mathbf{V}~VfdPXA \\ + Vfdpxa &\to \mathbf{F}~VFdpxa~|~\mathbf{P}~VfdPxa~|~\mathbf{X}~VfdpXa~|~\mathbf{A}~VfdpxA \\ + VfdpxA &\to \mathbf{F}~VFdpxA ~|~ \mathbf{P}~VfdPxA ~|~ \mathbf{X}~VfdpXA \\ + VfdpXa &\to \mathbf{P}~VfdPXa \\ + VfdpXA &\to \mathbf{P}~VfdPXA \\ + VfdPxa &\to \mathbf{F}~VFdPxa ~|~ \mathbf{X}~VfdPXa ~|~ \mathbf{A}~VfdPxA \\ + VfdPxA &\to \mathbf{F}~VFdPxA ~|~ \mathbf{X}~VfdPXA \\ + VfdPXa &\to \mathbf{F}~VFdPXa ~|~ \mathbf{A}~VfdPXA \\ + VfdPXA &\to \mathbf{F}~VFdPXA \\ + VFdpxa &\to \mathbf{D}~VFDpxa~|~\mathbf{P}~VFdPxa ~|~ \mathbf{X}~VFdpXa ~|~ \mathbf{A}~VFdpxA \\ + VFdpxA &\to \mathbf{D}~VFDpxA ~|~ \mathbf{P}~VFdPxA ~|~ \mathbf{X}~VFdpXA \\ + VFdpXa &\to \mathbf{P}~VFdPXa \\ + VFdpXA &\to \mathbf{P}~VFdPXA \\ + VFdPxa &\to \mathbf{D}~VFDPxa ~|~ \mathbf{X}~VFdPXa ~|~ \mathbf{A}~VFdPxA \\ + VFdPxA &\to \mathbf{D}~VFDPxA ~|~ \mathbf{X}~VFDPXA \\ + VFdPXa &\to \mathbf{D}~VFDPXa ~|~ \mathbf{A}~VFdPXA \\ + VFdPXA &\to \mathbf{D}~VFDPXA \\ + VFDpxa &\to \mathbf{P}~VFDPxa ~|~ \mathbf{X}~VFDpXa ~|~ \mathbf{A}~VFDpxA \\ + VFDpxA &\to \mathbf{P}~VFDPxA ~|~ \mathbf{X}~VFDpXA \\ + VFDpXa &\to \mathbf{P}~VFDPXa \\ + VFDpXA &\to \mathbf{P}~VFDPXA \\ + VFDPxa &\to \mathbf{X}~VFDPXa ~|~ \mathbf{A}~VFDPxA \\ + VFDPxA &\to \mathbf{X}~VFDPXA \\ + VFDPXa &\to \mathbf{A}~VFDPXA \\ + VFDPXA &\to \varepsilon \\ + \end{cases} + \end{aligned} + \end{pmatrix}$ diff --git a/docs/topics/process_models/cs/cs_substates_table.md b/docs/topics/process_models/cs/cs_substates_table.md new file mode 100644 index 00000000..e302c160 --- /dev/null +++ b/docs/topics/process_models/cs/cs_substates_table.md @@ -0,0 +1,13 @@ +!!! note "CVD Case Substates Defined" + + Lowercase letters designate events that have not occurred, + while uppercase letters designate events that have occurred in a particular state. + + | Substate | Notation | Meaning | + | :--- | :--- | :--- | + | Vendor Awareness | _v_ or _V_ | Vendor is/is not aware of the report | + | Fix Readiness | _f_ or _F_ | Fix is/is not ready | + | Fix Deployment | _d_ or _D_ | Fix is/is not deployed | + | Public Awareness | _p_ or _P_ | Public is/is not aware of the report | + | Exploit Public | _x_ or _X_ | Exploit is/is not public | + | Attacks Observed | _a_ or _A_ | Attacks are/are not observed | diff --git a/docs/topics/process_models/cs/index.md b/docs/topics/process_models/cs/index.md new file mode 100644 index 00000000..70dfea05 --- /dev/null +++ b/docs/topics/process_models/cs/index.md @@ -0,0 +1,175 @@ +# CVD Case State Model Introduction + +{% include-markdown "../../../includes/normative.md" %} + +Here we revisit the CS model from [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513). +The CVD Case State (CS) model provides a high-level view of the state of a CVD case. +In it we model two main aspects of the case: + +1. A Participant-specific _Vendor Fix Path_ from initial vendor awareness through the deployment of a fix. +2. A Participant-agnostic _Public State_ summarizing both public and attacker awareness of the vulnerability. + +These processes run in parallel, and the CS model captures the interactions between them. + +A complete derivation of the CS model can be found in [that report](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513). +Here, we are primarily interested in the final model, which comprises 32 states and their transitions. + +However, due to the size of the final CS model, we begin with some necessary +background on the substates of the model in +[CVD Case Substates](#cvd-case-substates) +prior to defining the Case States in +[CVD Case States](cs_model.md). + +## CVD Case Substates + +In our model, the state of the world is a specification of the current +status of all the events in the vulnerability lifecycle model described +in [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513). +We describe the relevant factors as substates below. +For notational purposes, each substate status is represented by a letter for that part +of the state of the world. For example, _v_ means no Vendor awareness +and _V_ means the Vendor is aware. The complete set of status labels is +shown in the table below. + +{% include-markdown "cs_substates_table.md" %} + +!!! tip "References" + + In defining these substates, we draw on the following sources: + + - [Windows of Vulnerability: A Case Study analysis](https://doi.org/10.1109/2.889093) by Arbaugh, Fithen, and McHugh + - [Modeling the Security Ecosystem—The Dynamics of (In)Security](https://doi.org/10.1007/978-1-4419-6967-5_6) by Frei et al. + - [Before we knew it: an empirical study of zero-day attacks in the real world](https://doi.org/10.1145/2382196.2382284) by Bilge and DumitraÅŸ + +### The _Vendor Awareness_ Substate (_v_, _V_) + +The *Vendor Awareness* substate corresponds to *Disclosure* in the +Arbaugh, Fithen, and McHugh article, [Windows of Vulnerability: A Case +Study analysis](https://doi.org/10.1109/2.889093) and *vulnerability discovered by +Vendor* in Bilge and DumitraÅŸ's article, [Before we knew it: an +empirical study of zero-day attacks in the real +world](https://doi.org/10.1145/2382196.2382284). +In the interest of model simplicity, we are +not concerned with *how* the Vendor finds out about the vulnerability's +existence—whether it was found via internal testing, reported within a +CVD process, or noticed as the result of incident or malware analysis. + +```mermaid +stateDiagram-v2 + direction LR + v : Vendor Unaware (v) + V : Vendor Aware (V) + v --> V : vendor becomes aware +``` + +!!! tip inline end "Software Delivery Models Affect Fix Readiness and Deployment Timing Relative to Public Awareness" + + We chose to include the *Fix Ready*, *Fix Deployed*, and *Public Awareness* events so that our model could better + accommodate two common modes of modern software deployment: + + - *shrinkwrap* is a traditional distribution mode where the Vendor and + Deployer are distinct entities, and Deployers must be made aware of + the fix before it can be deployed. In this case, both *Fix Ready* + and *Public Awareness* are necessary for *Fix Deployment* to occur. + - *SAAS* is a more recent delivery mode where the Vendor also plays the role of + Deployer. In this distribution mode, *Fix Ready* can lead directly + to *Fix Deployed* with no dependency on *Public Awareness*. + + We note that so-called *silent fixes* by Vendors can sometimes result in + a fix being deployed without public awareness even if the Vendor is not + the Deployer. Thus, it is possible (but unlikely) for *Fix Deployed* to + occur before *Public Awareness* even in the shrinkwrap mode above. It is + also possible, and somewhat more likely, for *Public Awareness* to occur + before *Fix Deployed* in the SAAS mode as well. + +### The _Fix Readiness_ Substate (_f_, _F_) + +The *Fix Readiness* substate refers to the Vendor's creation and possession of a fix that *could* be deployed to a +vulnerable system *if* the system owner knew of its existence. +Here we differ somewhat from previous models +([1](https://doi.org/10.1109/2.889093), [2](https://doi.org/10.1007/978-1-4419-6967-5_6), and [3](https://doi.org/10.1145/2382196.2382284))—their +models address the *release* of the fix rather than its *readiness* for release. +This distinction is necessary because we are interested in modeling the activities and states leading up to disclosure. +Fix *release* is a goal of the CVD process, whereas fix *readiness* is a significant process milestone along the way. + +```mermaid +stateDiagram-v2 + direction LR + f : Fix Not Ready (f) + F : Fix Ready (F) + f --> F : fix is ready +``` + +### The _Fix Deployed_ Substate (_d_, _D_) + +The *Fix Deployed* substate reflects the deployment status of an +existing fix. The model in [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) was initially designed to treat this substate as +a singular binary state for a case, but we intend to relax that here to +reflect a more realistic perspective in which each Deployer maintains +their own instance of this state value. It remains a binary state for +each Deployer, which, however, is still a simplification. + +```mermaid +stateDiagram-v2 + direction LR + d : Fix Not Deployed (d) + D : Fix Deployed (D) + d --> D : fix is deployed +``` + + +### The _Public Awareness_ Substate (_p_, _P_) + +The *Public Awareness* substate corresponds to *Publication* in the +Arbaugh, Fithen, and McHugh [article](https://doi.org/10.1109/2.889093), *time of +public disclosure* in Frei et al.'s article [Modeling the Security +Ecosystem—The Dynamics of (In)Security](https://doi.org/10.1007/978-1-4419-6967-5_6) and +*vulnerability disclosed publicly* in Bilge and DumitraÅŸ's [article](https://doi.org/10.1145/2382196.2382284). +The public might find out about a vulnerability through the Vendor's announcement of a fix, a news report about a +security breach, a conference presentation by a researcher, or a variety of other means. +As above, we are primarily concerned with the occurrence of the event itself rather than the details of *how* the public +awareness event arises. + +```mermaid +stateDiagram-v2 + direction LR + p : Public Unaware (p) + P : Public Aware (P) + p --> P : public becomes aware +``` + +### The _Exploit Public_ Substate (_x_, _X_) + +The *Exploit Public* substate reflects whether the method of exploiting +a vulnerability has been made public in sufficient detail to be +reproduced by others. Posting PoC code to a widely available site or +including the exploit code in a commonly available exploit tool meets +this criteria; privately held exploits do not. + +```mermaid +stateDiagram-v2 + direction LR + x : Exploit Not Public (x) + X : Exploit Public (X) + x --> X : exploit is public +``` + +### The _Attacks Observed_ Substate (_a_, _A_) + +The *Attacks Observed* substate reflects whether attacks have been +observed in which the vulnerability was exploited. This substate +requires evidence that the vulnerability was exploited; we can then +presume the existence of exploit code regardless of its availability to +the public. Analysis of malware from an incident might meet +_Attacks Observed_ but not _Exploit Public_, depending on how closely +the attacker holds the malware. Use of a public exploit in an attack +meets both _Exploit Public_ and _Attacks Observed_. + +```mermaid +stateDiagram-v2 + direction LR + a : Attacks Not Observed (a) + A : Attacks Observed (A) + a --> A : attacks are observed +``` + diff --git a/docs/topics/process_models/cs/pxa_diagram.md b/docs/topics/process_models/cs/pxa_diagram.md new file mode 100644 index 00000000..07d594b2 --- /dev/null +++ b/docs/topics/process_models/cs/pxa_diagram.md @@ -0,0 +1,26 @@ +```mermaid +--- +title: pxa State Diagram +--- +stateDiagram-v2 + direction LR + [*] --> pxa + + pxa --> Pxa : P + pxa --> pXa : X + pxa --> pxA : A + + pXa --> PXa : P + pXa --> pXA : A + + pxA --> PxA : P + pxA --> pXA : X + + Pxa --> PxA : A + Pxa --> PXa : X + + pXA --> PXA : P + PXa --> PXA : A + PxA --> PXA : X + PXA --> [*] +``` diff --git a/docs/topics/process_models/cs/pxa_diagram_simple.md b/docs/topics/process_models/cs/pxa_diagram_simple.md new file mode 100644 index 00000000..3d711c81 --- /dev/null +++ b/docs/topics/process_models/cs/pxa_diagram_simple.md @@ -0,0 +1,23 @@ +```mermaid +--- +title: Simplified pxa State Diagram +--- +stateDiagram-v2 + direction LR + [*] --> pxa + + pxa --> Pxa : P + pxa --> PXa : X,P + pxa --> pxA : A + + + pxA --> PxA : P + pxA --> PXA : X,P + + Pxa --> PxA : A + Pxa --> PXa : X + + PXa --> PXA : A + PxA --> PXA : X + PXA --> [*] +``` diff --git a/docs/topics/process_models/cs/vfdpxa_diagram.md b/docs/topics/process_models/cs/vfdpxa_diagram.md new file mode 100644 index 00000000..dc1eeeb4 --- /dev/null +++ b/docs/topics/process_models/cs/vfdpxa_diagram.md @@ -0,0 +1,67 @@ +```mermaid +--- +title: Case State Diagram +--- +stateDiagram-v2 + direction LR + [*] --> vfdpxa + vfdpxa --> vfdPxa : P + vfdpxa --> vfdpXa : X + vfdpXa --> vfdPXa : P + vfdpxa --> vfdpxA : A + vfdpxA --> vfdPxA : P + vfdpxA --> vfdpXA : X + vfdpXA --> vfdPXA : P + vfdpxa --> Vfdpxa : V + vfdpxA --> VfdpxA : V + vfdPxa --> VfdPxa : V + vfdPXa --> VfdPXa : V + vfdPxA --> VfdPxA : V + vfdPXA --> VfdPXA : V + Vfdpxa --> VfdPxa : P + Vfdpxa --> VfdpXa : X + VfdpXa --> VfdPXa : P + Vfdpxa --> VfdpxA : A + VfdpxA --> VfdPxA : P + VfdpxA --> VfdpXA : X + VfdpXA --> VfdPXA : P + VfdPxa --> VfdPxA : A + VfdPxa --> VfdPXa : X + VfdPXa --> VfdPXA : A + VfdPxA --> VfdPXA : X + Vfdpxa --> VFdpxa : F + VfdpxA --> VFdpxA : F + VfdPxa --> VFdPxa : F + VfdPXa --> VFdPXa : F + VfdPxA --> VFdPxA : F + VfdPXA --> VFdPXA : F + VFdpxa --> VFdPxa : P + VFdpxa --> VFdpXa : X + VFdpXa --> VFdPXa : P + VFdpxa --> VFdpxA : A + VFdpxA --> VFdPxA : P + VFdpxA --> VFdpXA : X + VFdpXA --> VFdPXA : P + VFdPxa --> VFdPxA : A + VFdPxa --> VFdPXa : X + VFdPXa --> VFdPXA : A + VFdPxA --> VFdPXA : X + VFdpxa --> VFDpxa : D + VFdpxA --> VFDpxA : D + VFdPxa --> VFDPxa : D + VFdPXa --> VFDPXa : D + VFdPxA --> VFDPxA : D + VFdPXA --> VFDPXA : D + VFDpxa --> VFDPxa : P + VFDpxa --> VFDpXa : X + VFDpXa --> VFDPXa : P + VFDpxa --> VFDpxA : A + VFDpxA --> VFDPxA : P + VFDpxA --> VFDpXA : X + VFDpXA --> VFDPXA : P + VFDPxa --> VFDPxA : A + VFDPxa --> VFDPXa : X + VFDPXa --> VFDPXA : A + VFDPxA --> VFDPXA : X + VFDPXA --> [*] +``` diff --git a/docs/topics/process_models/dfa_notation_definition.md b/docs/topics/process_models/dfa_notation_definition.md new file mode 100644 index 00000000..fb02bd1e --- /dev/null +++ b/docs/topics/process_models/dfa_notation_definition.md @@ -0,0 +1,12 @@ +???+ note inline end "DFA Notation Defined" + + A [Deterministic Finite Automaton](https://en.wikipedia.org/wiki/Deterministic_finite_automaton) is defined as a + 5-tuple $(\mathcal{Q},q_0,\mathcal{F},\Sigma,\delta)$ where + + - $\mathcal{Q}$ is a finite set of states. + - $q_0 \in \mathcal{Q}$ is an initial state. + - $\mathcal{F} \subseteq \mathcal{Q}$ is a set of final (or accepting) + states. + - $\Sigma$ is a finite set of input symbols. + - $\delta$ is a transition function of the form $\delta: \mathcal{Q} \times \Sigma \xrightarrow{} \mathcal{Q}$. + diff --git a/docs/topics/process_models/em/defaults.md b/docs/topics/process_models/em/defaults.md new file mode 100644 index 00000000..10cf5aa4 --- /dev/null +++ b/docs/topics/process_models/em/defaults.md @@ -0,0 +1,420 @@ +# Default Embargoes + +{% include-markdown "../../../includes/normative.md" %} + +As described in the [EM process model](index.md#sec:em_grammar), the EM process has the potential for unbounded +*propose-reject* churn. To reduce the potential for this churn and +increase the likelihood that *some* embargo is established rather than a +stalemate of unaccepted proposals, we offer the following guidance. + +## Declaring Defaults + +First, we note that all CVD Participants (including Reporters) are +free to establish their own default embargo period in a published +vulnerability disclosure policy. In particular, we recommend that +CVD report +recipients (typically Vendors and Coordinators) do so. + +!!! note "" + + Participants MAY include a default embargo period as part of a + published Vulnerability Disclosure Policy. + +!!! note "" + + Report Recipients SHOULD post a default embargo period as part of their + Vulnerability Disclosure Policy to set expectations with potential + Reporters. + +## Using Defaults + +Next, we work through the possible interactions of published policies +with proposed embargoes. Each of the following scenarios assumes a +starting state of $q^{em} \in N$, and a negotiation between two parties. +We cover the extended situation (adding parties to an existing embargo) +in [Adding Participants](working_with_others.md). For now, we begin with the simplest +case and proceed in an approximate order of ascending complexity. + +In each of the following, subscripts on transitions indicate the +Participant whose proposal is being acted upon, not the Participant who +is performing the action. For example, $a_{sender}$ indicates acceptance +of the Sender's proposal, even if it is the Receiver doing the +accepting. + +### No Defaults, No Proposals + +???+ note inline end "Formalism" + + $$q^{em} \in N$$ + +We begin with the simplest case, in which neither party has a default and no +embargo has been proposed. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> N +``` + +!!! note "" + + If neither Sender nor Receiver proposes an embargo, _and_ no policy + defaults apply, no embargo SHALL exist. + + +### Sender Proposes When Receiver Has No Default Embargo + +Next, we consider the case where the Sender has a default embargo or otherwise proposes an embargo +and the Receiver has no default embargo specified by policy. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> N + N --> P : sender proposes + P --> A : receiver accepts + A --> R : receiver proposes revision +``` + +!!! note "" + + ???+ note inline end "Formalism" + + $$q^{em} \in N \xrightarrow{p_{sender}} P \xrightarrow{a_{sender}} A$$ + + If the Sender proposes an embargo and the Receiver has no default + embargo specified by policy, the Receiver SHOULD accept the Sender's + proposal. + + +!!! note "" + + ???+ note inline end "Formalism" + + $$q^{em} \in A \xrightarrow{p_{receiver}} R$$ + + The Receiver MAY then propose a revision. + + +### Receiver Has Default Embargo, Sender Implies Acceptance + +The next scenario is where the Receiver has a default embargo specified by +policy and the Sender does not propose an embargo. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> N + N --> P : receiver default proposal + P --> A : sender accepts +``` + + +!!! note "" + + ???+ note inline end "Formalism" + + $$q^{em} \in N \xrightarrow{p_{receiver}} P$$ + + A Receiver's default embargo specified in its vulnerability + disclosure policy SHALL be treated as an initial embargo proposal. + + +!!! note "" + + ???+ note inline end "Formalism" + + $$q^{em} \in N \xrightarrow{p_{receiver}} P \xrightarrow{p_{sender}} P$$ + + If the Receiver has declared a default embargo in its vulnerability + disclosure policy and the Sender proposes nothing to the contrary, + the Receiver's default embargo SHALL be considered as an accepted + proposal. + + + +### Sender Proposes an Embargo Longer than the Receiver Default + +Now we consider the case where the Sender proposes an embargo longer +than the Receiver's default. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> N + N --> P : receiver
proposes
default
(shorter) + P --> A : sender
accepts
(shorter) + A --> R : sender
proposes
(longer) + R --> A : receiver
accepts
(longer) + R --> A : receiver rejects
(shorter default persists) +``` + +!!! note "" + + If the Sender proposes an embargo *longer* than the Receiver's + default embargo, the Receiver's default SHALL be taken as accepted + and the Sender's proposal taken as a proposed revision. + + ???+ note "Formalism" + + $$q^{em} \in N \xrightarrow{p_{receiver}} P \xrightarrow{p_{sender}} P \xrightarrow{a_{receiver}} A \xrightarrow{r_{sender}} R$$ + + +!!! note "" + + ???+ note inline end "Formalism" + + $$q^{em} \in \begin{cases} + R \xrightarrow{a_{sender}} A \\ + R \xrightarrow{r_{sender}} A + \end{cases}$$ + + The Receiver MAY then *accept* or *reject* the proposed extension. + + +### Sender Proposes an Embargo Shorter than the Receiver Default + +Finally, we reach a common scenario in which the Sender proposes an +embargo shorter than the Receiver's default. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> N + N --> P : sender
proposes
(shorter) + P --> A : receiver
accepts
(shorter) + A --> R : receiver
proposes
(longer default) + R --> A : sender
accepts
(longer default)) + R --> A : sender rejects
(shorter persists) +``` + +!!! note "" + + If the Sender proposes an embargo *shorter* than the Receiver's + default embargo, the Sender's proposal SHALL be taken as accepted + and the Receiver's default taken as a proposed revision. + + ???+ note "Formalism" + + $$q^{em} \in N \xrightarrow{p_{receiver}} P \xrightarrow{p_{sender}} P \xrightarrow{a_{sender}} A \xrightarrow{r_{receiver}} R$$ + + +!!! note "" + + ???+ note inline end "Formalism" + + $$q^{em} \in \begin{cases} + R \xrightarrow{a_{receiver}} A \\ + R \xrightarrow{r_{receiver}} A + \end{cases}$$ + + The Sender MAY then *accept* or *reject* the proposed extension. + +## Rationale for Accepting the Shortest Proposed Embargo + +Here we provide two arguments for why a Participant should accept the +shorter of two proposed embargoes, with the option to propose a revision +to lengthen it. + +!!! info "A Game Theory Argument for Accepting the Shortest Proposed Embargo" + + Readers may notice that we have taken a _shortest proposal wins_ + approach to the above guidance. This is intentional, and it results + directly from the asymmetry mentioned in + [Negotiating Embargoes](#negotiating-embargoes) + The Receiver is faced with a + choice to either *accept* the Reporter's proposal and attempt to extend + it or to *reject* the proposal and end up with no embargo at all. + Therefore, if we take the stance that for a vulnerability with no fix + available, *any* embargo is better than *no* embargo, it should be + obvious that it is in the Receiver's interest to *accept* even a short + proposed embargo before immediately working to revise it. + + The alternative is impractical because the Reporter is not obligated to + provide the report to the Receiver at all. In the scenario where a + Reporter *proposes* a short embargo and the Receiver *rejects* it + because it is not long enough, the Reporter might choose to exit the + negotiation entirely and publish whenever they choose without ever + providing the report to the Receiver. That is not to say that we + recommend this sort of behavior from Reporters. In fact, we specifically + recommend the opposite in + [Negotiating Embargoes](#negotiating-embargoes). Rather, it once more + acknowledges the time-dependent informational asymmetry inherent to the + CVD process. + + + +!!! info "A Logical Argument for Accepting the Shortest Proposed Embargo" + + Perhaps the above reasoning comes across as too Machiavellian for some + readers. Here is a different perspective: Say a Reporter proposes an + embargo of _n_ days, while the Vendor would prefer _m_ days. If _n_ and + _m_ are given in units of days, we can look at them as a series of + individual agreements, each of 1 day in length. We will represent each + Participant as a vector representing that Participant's willingness to + perpetuate the embargo on each day. Embargo willingness will be + represented as a _1_ if the Participant is willing to commit to keeping + the embargo on that day, and a _0_ if they are not. For simplicity's + sake, we assume that each Participant is willing to maintain the embargo + up to a certain point, and then their willingness goes away. In other + words, each vector will be a series of zero or more _1_s followed by + zero or more _0_s. For example, $[1,1,1,1,0,0,0]$ represents a + Participant's willingness to engage in a 4-day embargo. + + For our two Participants, let $\mathbf{x}_ and _\mathbf{y}$ be + zero-indexed vectors of length $max(n,m)$. + + $$\begin{aligned} + |\mathbf{x}| &= max(n,m) \\ + |\mathbf{y}| &= max(n,m) + \end{aligned}$$ + + The elements of each vector represent each respective Participant's + willingness for the embargo to persist on each consecutive day. + + $$\begin{aligned} + \label{eq:x_i} + \mathbf{x} = + \begin{bmatrix} x_i : + x_i = + \begin{cases} + 1 &\text{if }i < n \\ + 0 &\text{otherwise} \\ + \end{cases} + & \text{for } 0 \leq i < max(n,m) + \end{bmatrix} \\ + \label{eq:y_i} + \mathbf{y} = + \begin{bmatrix} y_i : + y_i = + \begin{cases} + 1 &\text{if }i < m \\ + 0 &\text{otherwise} + \end{cases} + & \text{ for } 0 \leq i < max(n,m) + \end{bmatrix} + \end{aligned}$$ + + Note that we have constructed these vectors so that each vector's scalar + sum is just the length of embargo they prefer. + + $$\begin{aligned} + \Sigma(\mathbf{x}) &= n \\ + \Sigma(\mathbf{y}) &= m + \end{aligned}$$ + + Now we can define an agreement vector $\mathbf{z}$ as the pairwise + logical *AND* ($\wedge$) of elements from $\mathbf{x}_ and _\mathbf{y}$: + + $$\begin{aligned} + \label{eq:z_i} + \mathbf{z} = + \begin{bmatrix} z_i : + z_i = x_i \land y_i + & \text{for }0 \leq i < max(n,m) + \end{bmatrix} + \end{aligned}$$ + + For example, if one party prefers an embargo of length $n=4$ days while + another prefers one of length $m=7$ days, we can apply + [\[eq:x_i\]](#eq:x_i){reference-type="eqref" reference="eq:x_i"}, + [\[eq:y_i\]](#eq:y_i){reference-type="eqref" reference="eq:y_i"}, and + [\[eq:z_i\]](#eq:z_i){reference-type="eqref" reference="eq:z_i"} as + follows: + + $$\begin{split} + \mathbf{x} &= [1,1,1,1,0,0,0] \\ + \wedge~\mathbf{y} &= [1,1,1,1,1,1,1] \\ + \hline + \mathbf{z} &= [1,1,1,1,0,0,0] + \end{split}$$ + + From this, we can see that the scalar sum of the agreement vector---and + therefore the longest embargo acceptable to both parties---is simply the + lesser of _n_ and _m_: + + $$\Sigma ( \mathbf{z} ) = min(n,m)$$ + + +As an example: + +!!! example "The Shortest Proposed Embargo Wins" + + If a Reporter proposes a 90-day embargo, but the Vendor + prefers a 30-day embargo, we can think of this as a series of 1-day + agreements in which both parties agree to the first 30 days of the + embargo and disagree beyond that. By accepting the shorter 30-day + embargo, the Reporter now has 30 days to continue negotiations with the + Vendor to extend the embargo. Even if those continued negotiations fail, + both parties get at least the 30-day embargo period they agreed on in + the first place. This should be preferable to both parties versus the + alternative of no embargo at all were they to simply reject the shorter + proposal. + + ```mermaid + --- + title: Embargo Agreement in a Nutshell + --- + stateDiagram-v2 + direction LR + dots: ... + state Agreement { + direction LR + [*] --> 1 + 1 --> 2 + 2 --> dots + dots --> 30 + negotiate: negotiate extension + [*] --> negotiate + negotiate --> 30 + } + 30 --> 31 + state Disagreement { + dots2: ... + 31 --> dots2 + dots2 --> 90 + } + ``` + + Typically it is the Reporter who desires a shorter embargo than the Vendor. + We chose our example to demonstrate that this analysis works between any two parties, regardless of which party wants the + shorter embargo. + +!!! info "Resolving Multiple Proposals at Once" + + On our way to making this principle explicit, we immediately came across + a second scenario worth a brief diversion: What to do when multiple + revisions are up for negotiation simultaneously? Based on the idea of + extending the above to an efficient pairwise evaluation of multiple + proposals, we suggest the following heuristic: + + 1. Sort the proposals in order from earliest to latest according to + their expiration date. + 2. Set the current candidate to the earliest proposal. + 3. Loop over each remaining (later) proposal, evaluating it against the + current candidate. + 4. If the newly evaluated proposal is accepted, it becomes the current + candidate and the loop repeats. + 5. Otherwise, the loop exits at the first *reject*ed proposal. + 6. The current candidate (i.e., the latest *accept*ed proposal) becomes + the new *Active* embargo. + 7. If the earliest proposed revision is rejected---implying that none + of the later ones would be acceptable either---then the existing + *Active* embargo remains intact. + +## Resolving Proposals and Revisions + +Summarizing the principles just laid out as rules + +!!! note "" + + When two or more embargo proposals are open (i.e., none have yet + been accepted) and $q^{em} \in P$, Participants SHOULD accept the + shortest one and propose the remainder as revisions. + +!!! note "" + + When two or more embargo revisions are open (i.e., an embargo is + active yet none of the proposals have been decided) and + $q^{em} \in R$, Participants SHOULD *accept* or *reject* them + individually, in earliest to latest expiration order. diff --git a/docs/topics/process_models/em/early_termination.md b/docs/topics/process_models/em/early_termination.md new file mode 100644 index 00000000..93e53361 --- /dev/null +++ b/docs/topics/process_models/em/early_termination.md @@ -0,0 +1,98 @@ +# Early Termination + +{% include-markdown "../../../includes/normative.md" %} + +Embargoes sometimes terminate prior to the agreed date and time. This is +an unavoidable, if inconvenient, fact arising from three main causes: + +1. Vulnerability discovery capability is widely distributed across the + world, and not all Finders become cooperative Reporters. + +2. Even among otherwise cooperative CVD Participants, leaks sometimes happen. + +3. Adversaries are unconstrained by CVD in their vulnerability discovery, + exploit code development, and use of exploit code in attacks. + +## Be Prepared for Embargo Termination + +While many leaks are unintentional and due to miscommunication or errors in a Participant's CVD process, the effect is +the same regardless of the cause. As a result, + +!!! note "" + + Participants SHOULD be prepared with contingency plans in the event + of early embargo termination. + +## Reasons to Terminate an Embargo Early + +Some reasons to terminate an embargo before the agreed date include the +following: + + +!!! note "" + + ???+ note inline end "Formalism" + + $q^{cs} \in \{ \cdot\cdot\cdot P \cdot\cdot, \cdot\cdot\cdot\cdot X \cdot \}$ + + Embargoes SHALL terminate immediately when information about the + vulnerability becomes public. Public information may include reports + of the vulnerability or exploit code. + + +!!! note "" + + ???+ note inline end "Formalism" + + $q^{cs} \in \{ \cdot\cdot\cdot\cdot\cdot A \}$ + + Embargoes SHOULD terminate early when there is evidence that the + vulnerability is being actively exploited by adversaries. + +!!! note "" + + Embargoes SHOULD terminate early when there is evidence that + adversaries possess exploit code for the vulnerability. + +!!! note "" + + Embargoes MAY terminate early when there is evidence that + adversaries are aware of the technical details of the vulnerability. + +The above is not a complete list of acceptable reasons to terminate an +embargo early. Note that the distinction between the *SHALL* in the +first item and the *SHOULD* in the second is derived from the reasoning +given in the [CS model](../cs/cs_model.md#cs-transitions) +, where we describe the CS model's transition function. +Embargo termination is the set of transitions described in the [EM model](index.md#terminate-embargo). + +## Waiting for All Vendors to Reach _Fix Ready_ May Be Impractical. + +???+ note inline end "Fix Ready Definition" + + $$q^{cs} \in VF\cdot\cdot\cdot\cdot$$ + +It is not necessary for all Vendor Participants to reach _Fix Ready_ before publication or embargo termination. +Especially in larger MPCVD cases, there comes a point where the net +benefit of waiting for every Vendor to be ready is outweighed by the +benefit of delivering a fix to the population that can deploy it. No +solid formula for this exists, but factors to consider include + +- the market share of the Vendors in _Fix Ready_ ($q^{cs} \in VF \cdot \cdot \cdot \cdot$) compared to +those that are not ($q^{cs} \in \cdot f \cdot \cdot \cdot \cdot$) +- the software supply chain for fix delivery to Deployers +- the potential impact to critical infrastructure, public safety/health, or national security + +!!! note "" + + Embargoes MAY terminate early when a quorum of Vendor Participants + is prepared to release fixes for the vulnerability + ($q^{cs} \in VF\cdot\cdot\cdot\cdot$), even if some Vendors remain + unprepared ($q^{cs} \in \cdot f \cdot\cdot\cdot\cdot$). + +!!! note "" + + Participants SHOULD consider the software supply chain for the + vulnerability in question when determining an appropriate quorum for + release. + diff --git a/docs/topics/process_models/em/em_dfa_diagram.md b/docs/topics/process_models/em/em_dfa_diagram.md new file mode 100644 index 00000000..0ef9f4cc --- /dev/null +++ b/docs/topics/process_models/em/em_dfa_diagram.md @@ -0,0 +1,28 @@ + +```mermaid +--- +title: Embargo Management State Diagram +--- +stateDiagram-v2 + direction LR + [*] --> None + state Pre-Embargo { + None --> Proposed : propose + Proposed --> Proposed : propose + Proposed --> None : reject + Proposed --> Active : accept + } + state Active_Embargo { + Active --> Revise : propose + Revise --> Active : accept + Revise --> Active : reject + Revise --> Revise : propose + Revise --> eXited : terminate + Active --> eXited : terminate + } + state Post-Embargo { + eXited + } + eXited --> [*] +``` + diff --git a/docs/topics/process_models/em/embargo_defn.md b/docs/topics/process_models/em/embargo_defn.md new file mode 100644 index 00000000..c5accefd --- /dev/null +++ b/docs/topics/process_models/em/embargo_defn.md @@ -0,0 +1,4 @@ +!!! note "Embargo Definition" + + An **embargo** is an *informal* agreement among peer CVD case Participants to refrain from publishing information + about a vulnerability until some future point in time. diff --git a/docs/topics/process_models/em/index.md b/docs/topics/process_models/em/index.md new file mode 100644 index 00000000..ea96d923 --- /dev/null +++ b/docs/topics/process_models/em/index.md @@ -0,0 +1,383 @@ +# Embargo Management Process Model + +{% include-markdown "../../../includes/normative.md" %} + +Here we describe the basic primitives necessary for the CVD Embargo Management (EM) process. + +For our purposes, an embargo is an *informal* agreement among peer +CVD case Participants to refrain from publishing information about a vulnerability until some future point in time +relative to the report at hand. Once an embargo has expired, there is no further restriction on publishing information +about the vulnerability. + + + +!!! tip inline end "Reminder" + + Exploits are information about vulnerabilities too. + + +CVD case Participants must be able to propose, accept, and reject embargo timing +proposals according to their individual needs. +Additionally, Participants may want to attempt to gain agreement that enables specific +details about a vulnerability to be shared with other Participants or +made public. +Such content considerations are outside the scope of this proposal. +We focus our discussion on the *when* of an embargo, not the *what*. + +{% include-markdown "embargo_defn.md" %} + +Unlike the [RM](../rm/) model, in which each Participant has their own instance of the +[RM](../rm/) DFA, EM states are a global property of a CVD case. + +!!! note "" + A CVD case SHALL NOT have more than one active embargo at a time. + +(We define the term *active* below.) + +Even in an MPCVD case having a [vertical supply chain](https://vuls.cert.org/confluence/display/CVD/5.4+Multiparty+CVD)—in which Vendors must wait on their upstream suppliers to produce fixes before they can take action on +their own, as in the figure below—our intent is that the embargo +period terminates when as many Vendors as possible have been given an +adequate opportunity to produce a fix. + +```mermaid +--- +title: A Vertical Supply Chain +--- +stateDiagram-v2 + direction LR + v1: Originating
Vendor + v2: Vendor 2 + v3: Vendor 3 + v4: Vendor 4 + v5: Vendor 5 + v6: Vendor 6 + + v1 --> v2 + v1 --> v3 + v2 --> v4 + v3 --> v5 + v2 --> v5 + v5 --> v6 +``` + + +{% include-markdown "nda-sidebar.md" %} + +## EM State Machine + +As with our definition of the [RM](../rm/) model, we describe our +EM model using DFA notation. + +{% include-markdown "../dfa_notation_definition.md" %} + +### EM States + +CVD cases are either subject to an active embargo or they are not. +We begin with a simple two-state model for the embargo state: + +```mermaid +stateDiagram-v2 + direction LR + [*] --> None + None --> Active + Active --> [*] +``` + +However, because embargo management is a process of coordinating across +Participants, it will be useful to distinguish between the _None_ state +and an intermediate state in which an embargo has been proposed but not +yet accepted or rejected. We might call this the _None + Proposed_ +state, but we shortened it to _Proposed_. + +???+ note inline end "EM States ($\mathcal{Q}^{em}$) Defined" + + $\begin{split} + \mathcal{Q}^{em} = \{ & \underline{N}one, \\ + & \underline{P}roposed, \\ + & \underline{A}ctive, \\ + & \underline{R}evise, \\ + & e\underline{X}ited \} + \end{split}$ + +Similarly, we want to be able to discriminate between an _Active_ +embargo state and one in which a revision has been proposed but is not +yet accepted or rejected, which we will denote as the _Active + Revise_ +state, shortened to _Revise_. Finally, we wish to distinguish between +the state in which no embargo has ever been established (_None_), and +the final state after an active embargo has ended (_eXited_). Combining +these, we get the following set of EM states, which we denote as +$\mathcal{Q}^{em}$. + +```mermaid +--- +title: Embargo Management States +--- +stateDiagram-v2 + direction LR + [*] --> None + None --> Proposed + Proposed --> None + Proposed --> Active + Active --> Revise + Revise --> Active + Revise --> eXited + Active --> eXited + eXited --> [*] +``` + +We address the [state transitions](#em-state-transitions) in detail below. + +As a reminder, we use the underlined capital letters as shorthand for +EM state names later in this documentation. + +!!! Warning "Note on Shorthand Notation" + + Note that $q^{em} \in A$ is distinct from + $q^{rm} \in A$. An embargo can be _Active_, while a Report can be + [_Accepted_](../rm/index.md#the-accepted-a-state), and these are independent states. Be sure to check which + model a state's shorthand notation is referring to. + + +#### Start and Final States. + +???+ note inline end "EM Start and Final States Defined" + $q^{em}_0 = None$ + + $\mathcal{F}^{em} = \{None,~eXited\}$ + +The EM process starts in the _None_ state. The process ends in one of two states: If an +embargo agreement is eventually reached, the EM process ends in the _eXited_ state. +Otherwise, if no agreement is ever reached, the EM process ends in the _None_ state. Formal +definitions of each are shown in the box at right. + + +### EM State Transitions + +{% include-markdown "em_dfa_diagram.md" %} + +The symbols of our EM DFA correspond to the actions that cause transitions between the states: + +!!! note "" + An embargo MAY be _proposed_. + +!!! note "" + Once proposed, it MAY be _accepted_ or _rejected_. + +!!! note "" + Once accepted, revisions MAY be _proposed_, which MAY, in turn, be + _accepted_ or _rejected_. + +!!! note "" + Finally, accepted embargoes MUST eventually _terminate_. + +A summary of the available actions is shown as $\Sigma^{em}$ below. + +???+ note "EM Symbols ($\Sigma^{em}$) Defined" + + $$ \begin{split} + \Sigma^{em} = \{ + ~\underline{p}ropose, + ~\underline{r}eject, + ~\underline{a}ccept, + ~\underline{t}erminate + \} + \end{split}$$ + +Once again, the underlined lowercase letters will be used as shorthand +for the EM +transition names in the remainder of this documentation. + +#### EM Transitions Defined + +Now we define the possible state transitions. +The diagram below summarizes the EM process DFA states and transitions. + +{% include-markdown "./em_dfa_diagram.md" %} + +We will discuss each of the transitions in turn. + +##### Propose Embargo + +Propose a new embargo when none exists: + +```mermaid +stateDiagram-v2 + direction LR + dots: ... + [*] --> None + None --> Proposed: propose + Proposed --> dots + dots --> [*] +``` + + +##### Accept or Reject Embargo Proposal + +Once proposed, Participants can accept or reject the proposed embargo. +Although we do not show it in the diagram, Participants can also +propose a second embargo while the first is still pending. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> None + None --> Proposed + state Proposed { + direction LR + eval: Accept or reject? + state choose <> + [*] --> eval + eval --> choose + } + choose --> Active: accept + choose --> None: reject +``` + +##### Embargo Revision + +An existing embargo can also be renegotiated by proposing a new embargo. +The existing embargo remains active until it is replaced by accepting +the revision proposal. +If the newly proposed embargo is accepted, then the old one is +abandoned. On the other hand, if the newly proposed embargo is rejected, +the old one remains accepted. + + +```mermaid +stateDiagram-v2 + direction LR + dots: ... + [*] --> dots + dots --> Active + state Revise { + direction LR + state choose <> + eval: Change embargo? + [*] --> eval + eval --> choose + } + Active --> Revise: revise + choose --> Active: accept + choose --> Active: reject +``` + +!!! tip "Revisions do not interrupt active embargoes" + + The revision process laid out here ensures that there is no break in active embargo coverage. + The existing active embargo remains in effect until it is replaced by an accepted revision proposal. + + +##### Terminate Embargo + +Existing embargoes can terminate due to timer expiration or other reasons discussed in [Early Termination](early_termination.md). +Termination can occur even if there is an open revision proposal. + +```mermaid +stateDiagram-v2 + direction LR + dots: ... + [*] --> dots + dots --> Active + dots --> Revise + Active --> eXited: terminate + Revise --> eXited: terminate + eXited --> [*] +``` + +#### A Regular Grammar for EM {#sec:em_grammar} + +???+ note inline end "EM Transition Function ($\delta^{em}$) Defined" + + $\delta^{em} = + \begin{cases} + % \epsilon \to & N \\ + N \to ~pP~|~\epsilon \\ + P \to ~pP~|~rN~|~aA \\ + A \to ~pR~|~tX \\ + R \to ~pR~|~aA~|~rA~|~tX \\ + X \to ~\epsilon \\ + \end{cases}$ + +Based on the actions and corresponding state transitions just described, +we define the transition function $\delta^{em}$ for the +EM process as a set of production rules for the right-linear grammar using our +single-character shorthand in the box at right. +For convenience, we repeat the resulting state machine below using our shorthand notation. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> N + N --> P: p + P --> P: p + P --> N: r + P --> A: a + A --> R: p + A --> X: t + R --> R: p + R --> A: a + R --> A: r + R --> X: t + X --> [*] +``` + +Due to the numerous loops in the DFA shown in the state machine diagram above, +the EM grammar is capable of generating arbitrarily long strings of _propose_-_propose_ and _propose_-_reject_ +histories matching the regular expression `(p*r)*(pa(p*r)*(pa)?t)?`. As +an example, here is an exhaustive list of all the possible traces of +length seven or fewer: + +> _pr_, _pat_, _ppr_, _ppat_, _papt_, _prpr_, _pppr_, _ppppr_, _pprpr_, +> _prppr_, _pappt_, _ppapt_, _pppat_, _papat_, _paprt_, _prpat_, +> _pppppr_, _papppt_, _prpppr_, _ppprpr_, _ppappt_, _pppapt_, _prprpr_, +> _papapt_, _pprppr_, _pappat_, _paprpt_, _prppat_, _prpapt_, _ppaprt_, +> _pprpat_, _ppapat_, _papprt_, _ppppat_, _pprprpr_, _prprppr_, +> _paprppt_, _prpprpr_, _pappprt_, _papppat_, _ppppapt_, _prpaprt_, +> _papappt_, _pappapt_, _pppappt_, _pprpppr_, _pppprpr_, _prppppr_, +> _ppprppr_, _ppapppt_, _ppaprpt_, _papprpt_, _ppapprt_, _ppappat_, +> _prpppat_, _prpapat_, _ppprpat_, _ppppppr_, _pprppat_, _papapat_, +> _paprpat_, _ppapapt_, _prprpat_, _paprprt_, _prppapt_, _pppapat_, +> _pprpapt_, _pppaprt_, _pppppat_, _prpappt_, _papaprt_, _pappppt_ + +However, because EM +is a human-oriented scheduling process, our experience suggests that we +should expect there to be a natural limit on CVD Participants' tolerance for churn during +embargo negotiations. Hence, we expect most paths through the +EM DFA to be on the short end of this list in practice. We offer some thoughts on a +potential reward function over EM DFA strings in [Future Work](../../future_work/reward_functions.md). + +For example, it is often preferable for a Vendor to accept whatever embargo the Reporter initially proposes followed +closely by proposing a revision to their preferred timeline than it is for the Vendor and Reporter to ping-pong +proposals and rejections without ever establishing an embargo in the first place. +In the worst case (i.e., where the Reporter declines to extend their embargo), a short embargo is usually preferable to +none at all. +This implies a preference for strings starting with _par_ over strings starting with _ppa_ or _prpa_, among others. +We will come back to this idea in [Default Embargoes](#default-embargoes) and in the +[worked protocol example](../../formal_protocol/worked_example#vendor-accepts-then-proposes-revision). + +### EM DFA Fully Defined + +Taken together, the complete DFA specification for the EM process is shown below. + +???+ note "EM DFA $(\mathcal{Q},q_0,\mathcal{F},\Sigma,\delta)^{em}$ Fully Defined" + + $EM = + \begin{pmatrix} + \begin{aligned} + \mathcal{Q}^{em} = & \{ N,P,A,R,X \}, \\ + q^{em}_0 = & N, \\ + \mathcal{F}^{em} = &\{ N,X \}, \\ + \Sigma^{em} = &\{ p,r,a,t \}, \\ + \delta^{em} = & + \begin{cases} + N \to ~pP~|~\epsilon \\ + P \to ~pP~|~rN~|~aA \\ + A \to ~pR~|~tX \\ + R \to ~pR~|~aA~|~rA~|~tX \\ + X \to ~\epsilon \\ + \end{cases} + \end{aligned} + \end{pmatrix}$ + + + diff --git a/docs/topics/process_models/em/nda-sidebar.md b/docs/topics/process_models/em/nda-sidebar.md new file mode 100644 index 00000000..cff66586 --- /dev/null +++ b/docs/topics/process_models/em/nda-sidebar.md @@ -0,0 +1,18 @@ + +!!! info "CVD Embargoes Are Not NDAs" + + CVD embargoes are *not* Non-Disclosure Agreements (NDAs). + An NDA (also known as a Confidentiality agreement) is a legally binding contract between parties, often accompanied + by a reward for compliance and/or some penalty in the event of unauthorized disclosure. + NDAs do, on occasion, have a place in CVD processes, but the relatively rapid pace and scale of most MPCVD embargoes + makes per-case NDAs prohibitively difficult. + As a result, we are intentionally setting aside NDA negotiation as beyond the scope of this proposal. + + On the surface, many bug bounty programs may appear to fall outside our scope because they are often structured as + NDAs in which compliance is rewarded. + For some bounty programs, the penalty for non-compliance or early disclosure is limited to the loss of the reward. + For others, non-compliance can lead to the forfeiture of a promise of amnesty from the pursuit of civil or criminal + charges that might otherwise apply because of security or acceptable-use policy violations. + Nevertheless, we are optimistic that the bulk of this protocol (i.e., the parts that do not interfere with the + contractual provisions of bounty-associated NDAs) will be found to be compatible with the full variety of + bounty-oriented CVD programs existing now and in the future. diff --git a/docs/topics/process_models/em/negotiating.md b/docs/topics/process_models/em/negotiating.md new file mode 100644 index 00000000..1af78701 --- /dev/null +++ b/docs/topics/process_models/em/negotiating.md @@ -0,0 +1,176 @@ +# Negotiating Embargoes + +{% include-markdown "../../../includes/normative.md" %} + +Negotiating and entering into a new embargo for a case is only possible +within an embargo "habitable zone" defined in terms of the +[Case State model](../cs/index.md) as laid out below. + +The notation for CS model states is explained in +[Case State model](../cs/index.md), but the contextual explanation below should +suffice for now. + +!!! note "" + + CVD Participants MUST NOT *propose* or *accept* a new embargo + negotiation when any of the following conditions are true: + + 1. Information about the vulnerability is already known to the + public (${q^{cs} \in \cdot\cdot\cdot P \cdot\cdot}$). + + 2. An exploit for the vulnerability is publicly available + (${q^{cs} \in \cdot\cdot\cdot\cdot X \cdot}$). + + 3. There is evidence that the vulnerability is being actively + exploited by adversaries (${q^{cs} \in \cdot\cdot\cdot\cdot\cdot A}$). + +!!! note "" + + CVD Participants SHOULD NOT *propose* or *accept* a new embargo + negotiation when the fix for a vulnerability has already been + deployed ($q^{cs} \in VFDpxa$). + +Counterexamples include + +- when an embargo is desired to allow for a downstream Vendor to synchronize +their fix delivery or deployment +- when a Vendor has deployed a fix but wants to complete their root cause analysis prior to +releasing information about the vulnerability. + +!!! note "" + + CVD Participants MAY *propose* or *accept* a new embargo when the fix + for a vulnerability is ready but has neither been made public nor + deployed ($q^{cs} \in VFdpxa$). Such an embargo SHOULD be brief and + used only to allow Participants to prepare for timely publication or + deployment. + +!!! note "" + + CVD Participants MAY *propose* or *accept* an embargo in all other case + states (${q^{cs} \in \cdot\cdot\cdot pxa}$). + + +## Asymmetry in Embargo Negotiation + +Asymmetry is inherent in the CVD process because those who currently have the vulnerability information get to decide +with whom they will share it. +This asymmetry puts Reporters at somewhat of an advantage when it comes +to the initial report submission to another Participant. +We discuss some ways to improve (but not fully remove) this asymmetry in [Default Embargoes](#default-embargoes), +but for now we just need to acknowledge that it exists. + +!!! note "" + + Participants MAY *accept* or *reject* any proposed embargo as they + see fit. + +!!! note "" + + Receivers SHOULD *accept* any embargo proposed by Reporters. + +!!! note "" + + Receivers MAY *propose* embargo terms they find more favorable as + they see fit. + +!!! note "" + + Participants MAY withdraw (*reject*) their own unaccepted *Proposed* + embargo. + +## Respond Promptly + +Timely response to embargo proposals is important. Explicit acceptance +is expected. + +!!! note "" + + Participants SHOULD explicitly *accept* or *reject* embargo + proposals in a timely manner. (For example, embargo agreement or + rejection SHOULD NOT be tacit.) + +!!! note "" + Participants MAY interpret another Participant's failure to respond + to an embargo proposal in a timely manner as a *reject*ion of that + proposal. + +!!! note "" + In the absence of an explicit *accept* or *reject* response from a + Receiver in a timely manner, the Sender MAY proceed in a manner + consistent with an EM state of _None_ ($q^{em} \in N$). + +## No Embargo means No Embargo + +Once an embargo negotiation has failed the first time, Participants have +no further obligations. + +!!! note "" + + In a case where the embargo state is _None_ and for which an embargo + has been *proposed* and either explicitly or tacitly *rejected*, + Participants MAY take any action they choose with the report in + question, including immediate publication. + +!!! tip "Incentives Matter" + + We deliberately included the clauses "explicitly or tacitly rejected" and "may take any action" above to provide + incentives for Participants to be declarative and negotiate in good faith. + Were a rejected embargo proposal to carry _any_ implied obligation to refrain from publication, + Participants might be motivated to use delayed or ambiguous responses to impose that obligation on others. + Our goal is to avoid situations where a Participant is incentivized to simply ignore an embargo proposal + while proceeding with an expectation that the other Participants are still bound by the proposed-but-inactive embargo terms. + Therefore we have attempted to be very clear that _only_ active embargoes impose obligations on Participants. + +## Don't Give Up Too Soon + +The above notwithstanding, Participants are encouraged to try again, especially when no explicit rejection has been +communicated (i.e., in the _tacitly rejected_ scenario described above). + +!!! note "" + + Participants SHOULD make reasonable attempts to retry embargo + negotiations when prior proposals have been *reject*ed or otherwise + failed to achieve *accept*ance. + + +## Submitting a Report Before Embargo Negotiations Conclude + +Participants need not wait for embargo negotiations to conclude before +submitting a report. However, by doing so, they might give up some of +their leverage over the Receiver in the embargo negotiations. + +!!! note "" + + Participants MAY withhold a report from a Recipient until an initial + embargo has been accepted. + +!!! note "" + + Submitting a report when an embargo proposal is pending + ($q^{em} \in P$) SHALL be construed as the Sender's acceptance + ($q^{em} \in P \xrightarrow{a} A$) of the terms proposed regardless + of whether the Sender or Receiver was the proposer. + +## Addressing Validation Uncertainty + +Participants might prefer to delay accepting or rejecting a proposed +embargo until after they have had an opportunity to review the report +through the validation and (possibly) prioritization processes. However, +because other Participants are under no obligation to withhold +publication of cases not covered by an active embargo, we recommend that +a short embargo be used until the validation process concludes, at which +point, it can be extended with a revision. + +!!! note "" + + Participants MAY use short embargo periods to cover their report + validation process, and subsequently revise the embargo terms + pending the outcome of their report validation and/or prioritization + processes. + +!!! note "" + + Participants SHOULD remain flexible in adjusting embargo terms as + the case evolves. + diff --git a/docs/topics/process_models/em/principles.md b/docs/topics/process_models/em/principles.md new file mode 100644 index 00000000..b1cea93f --- /dev/null +++ b/docs/topics/process_models/em/principles.md @@ -0,0 +1,189 @@ +# Embargo Principles + +{% include-markdown "../../../includes/normative.md" %} + +Embargoes are a means of inhibiting public disclosure of a vulnerability +while defenses are prepared (e.g., until fix development has completed +for a reasonable quorum of Vendors). + +The goal of the EM process is not to establish an exact publication schedule for every Participant to adhere +to. Rather, + +!!! tip "Embargo Management Process Goal" + + The goal of the Embargo Management process is to establish a window spanning from the present to some future time, during which _Participants + are expected to not publish or otherwise disclose_ information about the vulnerability to non-Participants outside + of the CVD case. + +Hence our definition of an embargo: + +{% include-markdown "embargo_defn.md" %} + +## Embargoes Are a Social Agreement + +An embargo is a social agreement between independent parties acting in +the interest of providing vulnerability fixes to users in a timely +manner while minimizing attacker advantage in the interim. However, +embargoes are not always appropriate or useful within the context of any +given CVD case. + +With that in mind, we offer the following principles as guidance. We +begin with some behavioral norms that define what it means to cooperate +with an embargo. + +!!! note "" + + Embargo Participants SHOULD NOT knowingly release information about + an embargoed case until either + + 1. all proposed embargoes have been explicitly rejected + + 2. no proposed embargo has been explicitly accepted in a timely + manner + + 3. the expiration date/time of an accepted embargo has passed + + 4. an accepted embargo has been terminated prior to the embargo + expiration date and time due to other reasons (e.g., those + outlined in [Early Termination](early_termination.md)) + +!!! note "" + Additional Participants MAY be added to an existing embargo upon + accepting the terms of that embargo. + +!!! note "" + Adding Participants to an existing embargo SHALL NOT constitute + "release" or "publication" so long as those Participants accept the + terms of the embargo. + +See [Adding Participants](working_with_others.md) for more information. + +## Embargoes are Limited Short-Term Agreements + + +Given all other facts about a vulnerability report being equal, there +are two factors that contribute significantly to the success or failure +of an embargo: scale and duration. The more people involved in an +embargo, the more likely the embargo is to fail. + +!!! note "" + Embargo participation SHOULD be limited to the smallest possible set + of individuals and organizations needed to adequately address the + vulnerability report. + +Similarly, the longer an embargo lasts, the more likely it is to fail. + +!!! note "" + Embargo duration SHOULD be limited to the shortest duration possible + to adequately address the vulnerability report. + +Furthermore, we need to establish a few norms related to embargo timing. + +!!! note "" + An embargo SHALL specify an unambiguous date and time as its + endpoint. + +!!! note "" + An embargo SHALL NOT be used to indefinitely delay publication of + vulnerability information, whether through repeated extension or by + setting a long-range endpoint. + +!!! note "" + An embargo SHALL begin at the moment it is accepted. + +!!! note "" + Embargoes SHOULD be of short duration, from a few days to a few + months. + +{% include-markdown "nda-sidebar.md" %} + +## Embargo Participants Are Free to Engage or Disengage {#sec:embargo_engagement} + +As we [just described](#cvd-embargoes-are-not-ndas), an embargo is not the +same thing as an NDA, even if they have similar effects. +Because it is a contract, an NDA can carry civil or even criminal +penalties for breaking it. CVD embargoes have no such legal framework. +Hence, CVD +Participants are free to enter or exit an embargo at any time, for any +reason. In fact, CVD Participants are not obliged to agree to +any embargo at all. However, regardless of their choices, Participants +should be clear about their status and intentions with other +Participants. There are a few good reasons to exit an embargo early. +(See [Early Termination](early_termination.md) for more information.) + +!!! note "" + Participants MAY propose a new embargo or revision to an existing + embargo at any time within the constraints outlined in [Negotiating Embargoes](negotiating.md). + +!!! note "" + Participants MAY reject proposed embargo terms for any reason. + +!!! note "" + Participants in an embargo MAY exit the embargo at any time. + +### Leaving an Embargo is Not Embargo Termination + +Note that a Participant leaving an embargo is not necessarily the same +as the embargo itself terminating. +Embargo termination corresponds to the $q^{em} \in \{A,R\} \xrightarrow{t} X$ transition in the +[EM model](index.md) and reflects a consensus among case Participants that the embargo no longer +applies. A Participant leaving an *Active* embargo means that the +embargo agreement between other Participants remains intact, but that +the leaving Participant is no longer involved in the case. + +!!! note "" + Participants stopping work on a case SHOULD notify remaining + Participants of their intent to adhere to or disregard any existing + embargo associated with the case. + +!!! note "" + Participants SHOULD continue to comply with any active embargoes to + which they have been a part, even if they stop work on the case. + +!!! note "" + Participants who leave an *Active* embargo SHOULD be removed by the + remaining Participants from further communication about the case. + +!!! tip inline end "Embargo Engagement and Adherence" + + We return to these concepts with the `case_engagement` and `embargo_adherence` attributes described in + [Case Object](../../../howto/case_object.md). + +These points imply a need for Participants to track the status of other +Participants with respect to their adherence to the embargo and +engagement with the case. + + +### Leaving an Embargo May Have Consequences + +As we note in the [CVD Guide](https://vuls.cert.org/confluence/display/CVD/5.5+Response+Pacing+and+Synchronization), +CVD is an iterated game, and actions have consequences. +Leaving an embargo early in one case may have repercussions to Participants' willingness to cooperate in later cases. + +!!! note "" + A Participant's refusal to accept embargo terms MAY result in that + Participant being left out of the CVD case entirely. + +!!! note "" + Participants SHOULD consider other Participants' history of + cooperation when evaluating the terms of a proposed embargo. + +## Embargo Termination is Not the Same as Publication + +Finally, embargo termination _removes a constraint_ rather than _adding an +obligation_. + +!!! note "" + Participants SHOULD not publish information about the vulnerability + when there is an active embargo. + +!!! note "" + Participants MAY publish information about the vulnerability when + there is no active embargo. + +!!! note "" + Embargo termination SHALL NOT be construed as an obligation to + publish. + +A discussion of how to decide who to invite to participate in a +CVD case is addressed in [Adding Participants](working_with_others.md). diff --git a/docs/topics/process_models/em/split_merge.md b/docs/topics/process_models/em/split_merge.md new file mode 100644 index 00000000..d5574cfa --- /dev/null +++ b/docs/topics/process_models/em/split_merge.md @@ -0,0 +1,95 @@ +# Case Splitting and Merging + +{% include-markdown "../../../includes/normative.md" %} + +Cases sometimes need to be split into multiple cases or merged into a single case. +Case Splits can happen when a single vulnerability affects multiple products with different fix supply chains. +Case Mergers can happen when two independent reports of vulnerabilities are found to be the same vulnerability. +We discuss the impact of these events on embargoes below. + +## Impact of Case Mergers on Embargoes + +While relatively rare, it is sometimes necessary for two independent CVD cases to be merged into a single case. + +!!! example "Case Merge Example" + + Two Finders independently discover vulnerabilities in separate products and report them to their respective + (distinct) Vendors. + Each Reporter-Vendor pair has already negotiated its own embargo. + On further investigation, it is determined that both reported problems stem from a vulnerability in a library shared + by both products. + The decision is made to merge the cases into a single case. + Once the cases merge, the best option is usually to renegotiate a new embargo for the new case. + +!!! note "" + + A new embargo SHOULD be proposed when any two or more + CVD cases are to be merged into a single case and multiple parties have agreed to + different embargo terms prior to the case merger. + +!!! note "" + + If no new embargo has been proposed, or if agreement has not been + reached, the earliest of the previously accepted embargo dates SHALL + be adopted for the merged case. + +!!! note "" + + Participants MAY propose revisions to the embargo on a merged case + as usual. + +## Impact of Case Splits on Embargoes + +It is also possible that a single case needs to be split into multiple cases after an embargo has been agreed to. + +!!! example "Case Split Example" + + A vulnerability that affects two widely disparate fix supply chains, such as a library used in both Software-as-a-Service (SAAS) and + Operational Technology (OT) environments. + The SAAS Vendors might be well positioned for a quick fix deployment while the OT Vendors might need considerably + longer to work through the logistics of delivering deployable fixes to their customers. + In such a case, the case Participants might choose to split the case into its respective supply chain cohorts to + better coordinate within each group. + +Unlike the relatively simple situation of merging two cases, splitting a case into multiple cases is more complex. +Case splits impose a dependency between the new case embargoes because the earlier embargo on one case might reveal the +existence of a vulnerability in the products allocated to the later case. +In these scenarios, it can be helpful to engage the services of a third party Coordinator (if one is not already involved in the case) +to help navigate the case split. + +!!! note "" + + When a case is split into two or more parts, any existing embargo + SHOULD transfer to the new cases. + +!!! note "" + + Participants approaching a case split MAY engage a Coordinator to act as a trusted third party to help + resolve and coordinate embargo dependencies for the new cases. + +!!! note "" + + If any of the new cases need to renegotiate the embargo inherited + from the parent case, any new embargo SHOULD be later than the + inherited embargo. + +!!! note "" + + In the event that an earlier embargo date is needed for a child + case, consideration SHALL be given to the impact that ending the + embargo on that case will have on the other child cases retaining a + later embargo date. In particular, Participants in each child case + should assess whether earlier publication of one child case might + reveal the existence of or details about other child cases. + +!!! note "" + + Participants in a child case SHALL communicate any subsequently + agreed changes from the inherited embargo to the Participants of the + other child cases. + +Note that it may not always be possible for the split cases to have +different embargo dates without the earlier case revealing the existence +of a vulnerability in the products allocated to the later case. For this +reason, it is often preferable to avoid case splits entirely. + diff --git a/docs/topics/process_models/em/working_with_others.md b/docs/topics/process_models/em/working_with_others.md new file mode 100644 index 00000000..328a7461 --- /dev/null +++ b/docs/topics/process_models/em/working_with_others.md @@ -0,0 +1,306 @@ +# Adding Participants to an Embargoed Case + +{% include-markdown "../../../includes/normative.md" %} + +Here we describe the who and when of adding Participants to +an embargoed case. + +As anyone who has tried to schedule a meeting with multiple attendees +can attest, multi-party scheduling can be difficult. When that schedule +must also accommodate work completion schedules for an +MPCVD case, it becomes even harder. In [Default Embargoes](#default-embargoes), +we laid out a heuristic for resolving multiple embargo proposals, _The Shortest Embargo Proposed +Wins_. +More specifically, we recommended that Participants *accept* the +earliest proposed end date and immediately propose and evaluate the rest +as potential revisions. This principle applies to any +MPCVD case, even at its outset. + + +## Start Early, Start Small + +Embargo negotiations can become contentious in larger cases. Many +MPCVD cases grow over time, and it is usually easier to establish an embargo with a +smaller group than a larger one. Conflict resolution via consensus +agreement is fine if it works. In fact, in scenarios where Participants +who have already agreed to an embargo get to choose who else to add to +the embargo, the existing consensus can be a strong influence for the +new Participant to consent to the existing agreement. + +In other words, it is usually preferable to present an already-accepted +embargo to new Participants and get their agreement before potentially +revising the embargo than it is to wait for a large multi-party +negotiation to succeed before establishing an embargo in the first +place. + +!!! tip inline end "See also" + + [ISO/IEC 29147:2018](https://www.iso.org/standard/72311.html) + +When consensus fails, however, it may be helpful for the group to +appoint a case lead to resolve any conflicts. Such scenarios are often +an opportunity for a third-party Coordinator to be engaged. + +Therefore, + +!!! note "" + + Participants SHOULD attempt to establish an embargo as early in the + process of handling the case as possible. + +!!! note "" + + Participants SHOULD follow consensus agreement to decide embargo + terms. + +!!! note "" + + When consensus fails to reach agreement on embargo terms, + Participants MAY appoint a case lead to resolve conflicts. + +!!! note "" + + Participants MAY engage a third-party Coordinator to act as a + neutral third-party case lead to resolve conflicts between + Participants during the course of handling a case. + +## Who to Invite + +The Finder/Reporter is, by definition, a Participant in any +CVD case by virtue +of their knowledge of the vulnerability in the first place. Additional +Participants usually fall into one of three categories: + +!!! note "" + + All known Vendors of affected software SHOULD be included as + Participants. + +!!! note "" + + Third-party Coordinators MAY be included as Participants. + +!!! note "" + + Other parties MAY be included as Participants when necessary and + appropriate. + +!!! example "Examples of Other Participants" + + Examples of other Participants we have observed in past cases include + + - Deployers + - Subject matter experts + - Government agencies with relevant regulatory oversight or critical infrastructure protection responsibilities. + +## Adding Participants to an Existing Embargo + +Adding new Participants to a case with an existing embargo might require +the new Participant to accept the embargo prior to receiving the report. + +!!! note "" + + When inviting a new Participant to a case with an existing embargo, + the inviting Participant SHALL propose the existing embargo to the + invited Participant. + +!!! note "" + + A newly invited Participant to a case with an existing embargo + SHOULD accept the existing embargo. + +!!! note "" + + The inviting Participant SHOULD NOT share the vulnerability report + with the newly invited Participant unless the new Participant has + accepted the existing embargo. + +!!! note "" + + The inviting Participant MAY interpret the potential Participant's + default embargo contained in their published vulnerability + disclosure policy in accordance with the default acceptance + strategies listed in [Default Embargoes](#default-embargoes). + +!!! note "" + + A newly invited Participant to a case with an existing embargo MAY + propose a revision after accepting the existing embargo. + +## When to Invite Participants + +In MPCVD there are practical considerations to be made regarding the timing of *when* +to notify individual Participants. The primary factor in these decisions +stems from the interaction of the *Active* embargo with the potential +Participant's existing (explicit or implicit) disclosure policy. + +### Participants with Disclosure Policies Shorter Than an Existing Embargo. + +Adding a potential Participant with a known default disclosure policy +*shorter* than an extant embargo leaves Participants with these options +to choose from: + +1. Shorten the existing embargo to match the potential Participant's + policy. + +2. Propose the existing embargo to the potential Participant, and, upon + acceptance, share the report with them. + +3. Delay notifying the potential Participant until their default policy + aligns with the existing embargo. + +4. Avoid including the potential Participant in the embargo entirely. + +!!! example "Example: A Vendor with a short default embargo" + + Say a Vendor has a seven-day maximum public disclosure policy. + Participants in a case with an existing embargo ending in three weeks might choose to notify that Vendor two weeks + from now to ensure that even the default disclosure timeline remains compatible with the extant embargo. + +!!! note "" + + Participants with short default embargo policies SHOULD consider + accepting longer embargoes in MPCVD cases. + +!!! note "" + + Participants in an MPCVD case MAY delay notifying potential + Participants with short default embargo policies until their policy + aligns with the agreed embargo. + +### Participants with Disclosure Policies Longer Than an Existing Embargo. + +Similarly, adding a Participant with a known default disclosure policy +*longer* than an extant embargo leaves Participants with the following +options to choose from: + +1. Lengthen the existing embargo to match the potential Participant's + policy. + +2. Propose the existing embargo to the potential Participant, and, upon + acceptance, share the report with them. + +3. Avoid including the potential Participant in the embargo entirely. + +In the case of a Vendor with a *longer* default policy than the existing +embargo, it is still preferable to give them as much lead time as +possible *even* if it is not possible to extend the embargo to their +preferred timing. + +!!! note "" + + In the interest of receiving the report in the first place, + potential Participants with a longer default policy than an existing + case SHOULD accept the embargo terms offered. + +!!! note "" + + After accepting an existing embargo, newly invited Participants with + a longer default policy than an existing case MAY propose a revision + to the existing embargo, if desired, to accommodate their + preferences. + +!!! note "" + + Existing Participants MAY *accept* or *reject* such a proposed + revision as they see fit. + +!!! note "" + + Participants in a case with an existing embargo SHOULD notify + Vendors with a longer default embargo policy. + +!!! note "" + + Participants in a case with an existing embargo MAY choose to extend + the embargo to accommodate a newly added Participant. + +### Untrustworthy Participants. + +Unfortunately, not all potential CVD Participants are equally trustworthy with +vulnerability information. + +!!! example "Examples of Untrustworthy Participants" + + We can provide a few examples of potentially untrustworthy Participants: + + - A Participant might have sub-par operational security or even business practices that result in adversaries often + finding out about vulnerabilities in their products before the end of an embargo period. + - Participants might be subject to regulatory regimes in which they are required by law to share known + vulnerabilities with government agencies having oversight responsibilities. Depending on the jurisdiction, these + agencies might not be bound by the same embargoes as the other Participants in the case. + - The Participants in a case might consider a government agency to be an adversary itself and therefore not + trustworthy with non-public vulnerability information. + + In these or similar scenarios, these concerns might lead to the exclusion of otherwise trustworthy Participants from an embargo. + + +!!! note "" + + Participants that are known to leak or provide vulnerability + information to adversaries either as a matter of policy or + historical fact SHOULD be treated similar to Participants with brief + disclosure policies. + +!!! tip "My Adversary Is _Not Necessarily_ Your Adversary" + + Trustworthiness has a strong subjective component, and individual perspectives on who is or is not trustworthy + can vary widely. + Thus, while acknowledging that *adversary* is not a universally agreed-upon category, the definition of *adversary* in the above + is left to individual Participants. + +The maximal interpretation of the above is that untrustworthy +Participants are left to be notified by the publication of the +vulnerability report. This is the equivalent of treating them like a +Participant with a default zero-day maximum embargo policy. + +### Coordinators. + +Third-party Coordinators, as Participants who are neither Finders nor +Vendors, often play an important role in MPCVD cases, especially those with broad impact +across the software supply chain or with acute critical infrastructure +or public safety impacts. Most Coordinators strive to be consistent in +their MPCVD +practices and have well-documented disclosure policies along with +significant histories of handling previous cases. All of these factors +make the argument for including third-party Coordinators in +CVD cases of +sufficient complexity, impact, or importance. + +### Other Parties. + +Some Participants in CVD have their own policies that prohibit notification of any parties unable to directly contribute +to the development of a fix for a particular vulnerability. +Typically, these policies take the form of "only Vendors of affected products" or similar such restrictions. + +The CERT/CC's position as a third-party Coordinator in numerous cases is that this approach can be appropriate for +straightforward scenarios, such as those in which a Vendor is in direct contact with their downstream Vendors and can +coordinate the response within that community. + +However, it falls short in some cases, such as the following: + +- Vulnerabilities are found to affect a broad spectrum of Vendors and + products, especially when cases cross industry sectors or otherwise + include Participants having widely divergent operational tempos or + software delivery models. + +- Vulnerabilities affect systems deployed in high-impact niches, such + as critical infrastructure, public safety, and national security. + +- Outside expertise is needed to understand the implications or impact + of a vulnerability beyond the participating Vendors; sometimes the + most knowledgeable parties work for someone else. + +## Consequences of Non-Compliance + +Considering multiple cases over time, MPCVD can be thought of as an [iterated game](https://vuls.cert.org/confluence/display/CVD/5.5+Response+Pacing+and+Synchronization) analogous to the Prisoner's Dilemma. +One notable strategy for the Prisoner's Dilemma is *tit for tat* in which non-cooperation from one party in one round +can be met with non-cooperation from the opposite party in the next. +While MPCVD is usually much bigger than a toy two-player game, we feel it is necessary to encode the possibility that +non-cooperation will have downstream consequences. + +!!! note "" + + Participants MAY decline to participate in future + CVD cases involving parties with a history of violating previous embargoes. + diff --git a/docs/topics/process_models/index.md b/docs/topics/process_models/index.md new file mode 100644 index 00000000..8df56b06 --- /dev/null +++ b/docs/topics/process_models/index.md @@ -0,0 +1,84 @@ +# Vultron Process Models + +!!! info inline end "Vultron Process Models" + + ```mermaid + graph TD + RM[[Report Management]] + EM[[Embargo Management]] + CS[[Case State]] + RM --> EM + RM --> CS + EM --> RM + EM --> CS + CS --> EM + CS --> RM + ``` + +The Vultron Protocol defines three main processes in terms of deterministic finite automata (DFAs): + +- Report Management +- Embargo Management +- Case State + +Each of these processes interacts with the other two processes in the context of a CVD case. + +A CVD case is coordinated by multiple agents (Reporters, Vendors, Coordinators, etc.), +each running these processes in parallel and interacting with each other. + +```mermaid +--- +title: Vultron Protocol Agents Interacting +--- +graph LR + subgraph Agent2 + RM2[[Report Management]] + EM2[[Embargo Management]] + CS2[[Case State]] + end + subgraph Agent1 + RM1[[Report Management]] + EM1[[Embargo Management]] + CS1[[Case State]] + end + RM1 --> EM1 + RM1 --> CS1 + EM1 --> RM1 + EM1 --> CS1 + CS1 --> EM1 + CS1 --> RM1 + RM2 --> EM2 + RM2 --> CS2 + EM2 --> RM2 + EM2 --> CS2 + CS2 --> EM2 + CS2 --> RM2 + Agent1 --> Agent2 + Agent2 --> Agent1 +``` + + + +## [Report Management process](rm/index.md) + +{% include-markdown "./rm/index.md" start="" end="" %} + +{% include-markdown "./rm/rm_state_machine_diagram.md" %} + +[Read More...](rm/index.md) + +## [Embargo Management process](em/index.md) + +{% include-markdown "./em/index.md" start="" end="" %} + +{% include-markdown "./em/em_dfa_diagram.md" %} + +[Read More...](em/index.md) + +## [Case State process](cs/index.md) + +{% include-markdown "./cs/index.md" start="" end="" %} + +{% include-markdown "./model_interactions/cs_global_local.md" %} + +[Read More...](cs/index.md) \ No newline at end of file diff --git a/docs/topics/process_models/model_interactions/cs_global_local.md b/docs/topics/process_models/model_interactions/cs_global_local.md new file mode 100644 index 00000000..b807af76 --- /dev/null +++ b/docs/topics/process_models/model_interactions/cs_global_local.md @@ -0,0 +1,42 @@ +```mermaid +--- +title: Case State Diagram showing Participant-Agnostic and Participant-Specific Aspects +--- +stateDiagram-v2 + direction LR + CS: Case State Model + state CS { + ps: Participant-Specific + state ps { + [*] --> vfd + vfd --> Vfd : V + Vfd --> VFd : F + VFd --> VFD : D + VFD --> [*] + } + g: Participant-Agnostic + state g { + [*] --> pxa + + pxa --> Pxa : P + pxa --> pXa : X + pxa --> pxA : A + + pXa --> PXa : P + pXa --> pXA : A + + pxA --> PxA : P + pxA --> pXA : X + + Pxa --> PxA : A + Pxa --> PXa : X + + pXA --> PXA : P + PXa --> PXA : A + PxA --> PXA : X + PXA --> [*] + } + } + [*] --> CS + CS --> [*] +``` diff --git a/docs/topics/process_models/model_interactions/index.md b/docs/topics/process_models/model_interactions/index.md new file mode 100644 index 00000000..e62087f4 --- /dev/null +++ b/docs/topics/process_models/model_interactions/index.md @@ -0,0 +1,83 @@ +# Model Interactions {#ch:interactions} + +{% include-markdown "../../../includes/normative.md" %} + +Here we reflect on the interactions between the [RM](../rm/), [EM](../em/index.md), and [CS](../cs/index.md) models within the +overall Vultron process. + +## Participant-Agnostic vs Participant-Specific Aspects + +!!! tip inline end "This sounds like SSVC" + + In [SSVC](https://github.com/CERTCC/SSVC), we distinguish between stakeholder-specific and + stakeholder-agnostic decision points when describing vulnerability response decisions. + Here, we carry a similar distinction into the CVD process. + Some facts about a case are participant-specific, while others are global to the case, or participant-agnostic. + +Some aspects of the Vultron process are Participant-agnostic (i.e., they represent a global state of the case), +while others are specific to a Participant. +Specifically, the [RM](../rm/) process is unique to each Participant, while the +[EM](../em/index.md) process is global to all Participants in a case. +The [CS](../cs/index.md) process is a hybrid: some aspects are Participant-agnostic, while others are +Participant-specific, which we will discuss in more detail below. + + +Interactions between all these processes affect the overall MPCVD process for a case. +The following diagram illustrates this distinction. + +```mermaid +stateDiagram-v2 + direction LR + PA: Participant-Agnostic + state PA { + EM + CS_pxa + EM --> CS_pxa + CS_pxa --> EM + } + PS: Participant-Specific + state PS { + RM + CS_vfd + RM --> CS_vfd + CS_vfd --> RM + } + PA --> PS + PS --> PA +``` + +### Global vs. Participant-Specific Aspects of the CS Model. + +The [CS model](../cs/index.md) encompasses both Participant-specific and Participant-agnostic aspects of a +CVD case. In particular, the Vendor fix path substates—Vendor unaware (_vfd_), +Vendor aware (_Vfd_), fix ready (_VFd_), and fix deployed (_VFD_)—are +specific to each Vendor Participant in a case. On the other hand, the +remaining substates represent Participant-agnostic facts about the case +status—public awareness (_p,P_), exploit public (_x,X_), and attacks +observed (_a,A_). This distinction in perspectives will become +important in the [Formal Protocol](../../formal_protocol/index.md) definition. + +{% include-markdown "cs_global_local.md" %} + +## Summary + +!!! note "Participant-Agnostic Aspects" + + Participant-agnostic aspects of the MPCVD process are those that represent facts about the world with respect to a + case. + +!!! example "Participant-Agnostic Examples" + + - The [Embargo Management](../em/index.md) process is global to all Participants in a case + - As is the Public State portion of the [Case State](../cs/index.md) process + +!!! note "Participant-Specific Aspects" + + Participant-specific aspects of the MPCVD process are those that represent facts about a Participant's + internal state with respect to a case. + +!!! example "Participant-Specific Examples" + + - The [Report Management](../rm/) process is unique to each Participant. + - So is the Vendor Fix Path portion of the [Case State](../cs/index.md) process. + diff --git a/docs/topics/process_models/model_interactions/rm_em.md b/docs/topics/process_models/model_interactions/rm_em.md new file mode 100644 index 00000000..5f614b67 --- /dev/null +++ b/docs/topics/process_models/model_interactions/rm_em.md @@ -0,0 +1,328 @@ +# Interactions Between the RM and EM Models {#sec:rm_em_interactions} + +{% include-markdown "../../../includes/normative.md" %} + +There are additional constraints on how the [RM](../rm/index.md) and [EM](../em/index.md) processes interact. + +## Start Embargo Negotiations As Early as Possible + +!!! note "" + + The [EM](../em/index.md) process MAY begin (i.e., the initial _propose_ transition $q^{em} \in N \xrightarrow{p} P$) + prior to the report being sent to a potential Participant ($q^{rm} \in S$) + +!!! question "Why Propose before Reporting?" + + Beginning an embargo negotiation before providing a report can be useful in cases where a Participant wishes to + ensure acceptable embargo terms prior to sharing a report with a potential recipient. + +```mermaid +stateDiagram-v2 + direction LR + state ParticipantSpecific { + state Sender { + state RM { + Accepted + } + } + state Recipient { + RM2: RM + state RM2 { + Start + } + } + } + state Global { + state EM { + None --> Proposed : propose + } + } + Sender --> EM : propose +``` + +!!! note "" + + If it has not already begun, the [EM](../em/index.md) process SHOULD begin when a recipient + is in RM _Received_ ($q^{rm} \in R$) whenever possible. + + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Received + } + state EM { + None --> Proposed : propose + } + RM --> EM : begin if not
already started +``` + +## Negotiate Embargoes for Active Reports + +!!! note "" + + Embargo Management MAY begin in any of the active RM states + ($q^{rm} \in \{ R,V,A \}$). + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Received + Valid + Accepted + } + state EM { + None --> Proposed : propose + } + RM --> EM : ok to
proceed +``` + +!!! note "" + + Embargo Management SHOULD NOT begin in an inactive RM state + ($q^{rm} \in \{ I,D,C \}$). + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Invalid + Deferred + Closed + } + state EM { + None --> Proposed : propose + } + RM --> EM : avoid +``` + + +## Negotiate Embargoes Through Validation and Prioritization + +!!! note "" + + Embargo Management MAY run in parallel to validation + ($q^{rm} \in \{R,I\} \xrightarrow{\{v,i\}} \{V,I\}$) and + prioritization ($q^{rm} \in V \xrightarrow{\{a,d\}} \{A,D\}$) + activities. + + +## Renegotiate Embargoes While Reports Are Valid Yet Unclosed + +!!! note "" + + EM revision proposals ($q^{em} \in A \xrightarrow{p} R$) and + acceptance or rejection of those proposals + (${q^{em} \in R \xrightarrow{\{a,r\}} A}$) MAY occur during any of + the valid yet unclosed RM states (${q_{rm} \in \{ V,A,D \} }$). + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Valid + Accepted + Deferred + } + state EM { + Revise --> Active : accept + Revise --> Active : reject + Active --> Revise : propose + } + RM --> EM : ok to
proceed +``` + +## Avoid Embargoes for Invalid Reports... + +!!! note "" + + Embargo Management SHOULD NOT begin with a proposal from a + Participant in RM _Invalid_ ($q^{rm} \in I$). + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Invalid + } + state EM { + None --> Proposed : propose + } + RM --> EM : avoid +``` + +## ...but Don't Lose Momentum if Validation Is Pending + +!!! note "" + + Outstanding embargo negotiations + ($q^{em} \in P \xrightarrow{\{r,p\}} \{N,P\}$) MAY continue in + RM _Invalid_ + ($q^{rm} \in I$) (e.g., if it is anticipated that additional + information may be forthcoming to promote the report from _Invalid_ + to _Valid_) ($q^{rm} \in I \xrightarrow{v} V$). + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Invalid --> Valid: (anticipated) + } + state EM { + None --> Propose : propose + } + RM --> EM : ok to
proceed +``` + +## Only Accept Embargoes for Possibly Valid Yet Unclosed Reports + +!!! note "" + + Embargo Management MAY proceed from EM _Proposed_ to EM _Accepted_ + ($q^{em} \in P \xrightarrow{a} A$) when RM is neither _Invalid_ nor _Closed_ + ($q^{rm} \in \{R,V,A,D\}$). + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Start + Received + Valid + Accepted + Deferred + } + state EM { + Proposed --> Accepted : accept + } + RM --> EM : ok to
proceed +``` + +!!! note "" + + Embargo Management SHOULD NOT proceed from EM _Proposed_ to EM _Accepted_ when + RM is _Invalid_ + or _Closed_ ($q^{rm} \in \{I,C\}$). + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Invalid + Closed + } + state EM { + Proposed --> Accepted : accept + } + RM --> EM : avoid +``` + +!!! note "" + + Embargo Management MAY proceed from EM _Proposed_ to EM _None_ + ($q^{em} \in P \xrightarrow{r} N$) when RM is _Invalid_ or _Closed_. + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Invalid + Closed + } + state EM { + Proposed --> None : reject + } + RM --> EM : ok to
proceed +``` + +## Report Closure, Deferral, and Active Embargoes + +Participants' individual Report Management processes can interact with the Embargo Management process at the case level +in a number of ways. +We describe these interactions below. + +!!! note "" + + Participants SHOULD NOT close reports ($q^{rm} \in \{I,D,A\} \xrightarrow{c} C$) while an embargo is + active ($q^{em} \in \{ A,R \}$). + +```mermaid +stateDiagram-v2 + direction LR + state RM { + Invalid --> Closed: close + Deferred --> Closed: close + Accepted --> Closed: close + } + state EM { + Active + Revise + } + EM --> RM : avoid +``` + +Instead, + +!!! note "" + + Reports with no further tasks SHOULD be held in either + _Deferred_ or _Invalid_ (${q^{rm} \in \{ D,I\}}$) (depending on the + report validity status) until the embargo has terminated + (${q^{em} \in X}$). + +This allows Participants to stop work on a report but still maintain their participation in an extant embargo. +Notwithstanding the above, + +!!! note "" + + Participants who choose to close a report ($q^{rm} \in \{I,D,A\} \xrightarrow{c} C$) while an embargo remains + in force ($q^{em} \in \{A,R\}$) SHOULD communicate their intent to either continue to adhere to the embargo or + terminate their compliance with it. + + +Report closure or deferral alone does not terminate an embargo. + +!!! note "" + + A Participant's closure or deferral ($q^{rm} \in \{C,D\}$) of a report + while an embargo remains active ($q^{em} \in \{A,R\}$) and while + other Participants remain engaged ($q^{rm} \in \{R,V,A\}$) SHALL NOT + automatically terminate the embargo. + +```mermaid +stateDiagram-v2 + direction LR +state RM { + Invalid --> Closed: close + Deferred --> Closed: close + Accepted --> Closed: close + } + state EM { + Active --> eXited: terminate + Revise --> eXited: terminate + } + RM --> EM : does not imply +``` + +It is expected that Participants will continue to adhere to the embargo until it is explicitly terminated. +However, + +!!! note "" + + Participants MAY choose to terminate their compliance with an embargo at any time. + +While this is usually an undesirable development, it is important that it be clearly communicated to other Participants +so that they can make informed decisions about the viability of the extant embargo. + +!!! note "" + + Any changes to a Participant's intention to adhere to an active + embargo SHOULD be communicated clearly in addition to any necessary + notifications regarding RM or EM state changes. + +!!! note "" + + Upon receipt of a Participant's notification of intent to end their compliance with an embargo, + other Participants MAY choose to terminate the embargo. \ No newline at end of file diff --git a/docs/topics/process_models/model_interactions/rm_em_cs.md b/docs/topics/process_models/model_interactions/rm_em_cs.md new file mode 100644 index 00000000..2d64b58c --- /dev/null +++ b/docs/topics/process_models/model_interactions/rm_em_cs.md @@ -0,0 +1,477 @@ +# CVD Case State Interactions with the RM and EM Process Models + +{% include-markdown "../../../includes/normative.md" %} + + +The [RM](../rm/index.md) and [EM](../em/index.md) models interact with the [Case State Model](../cs/index.md). +Here we will review the constraints arising from the interaction of the [RM](../rm/index.md) and [EM](../em/index.md) +models with each of the CS transition events represented by its symbols. + +We have organized this page according to how each CS model [substate](../cs/index.md) interacts with the +[RM](../rm/index.md) and [EM](../em/index.md) models. + + +???+ note inline end "CS Transition Symbols Defined" + + $\Sigma^{cs} = \{ \mathbf{V},~\mathbf{F},~\mathbf{D},~\mathbf{P},~\mathbf{X},~\mathbf{A} \}$ + +As a reminder, a list of the CS model transition symbols is reproduced in the inset at right. + + +## Vendor Notification + +???+ note inline end "Vendor Notification Formalized" + + $$q^{rm} \in S \xrightarrow{r} R$$ + + $$q^{cs} \in vfd\cdot\cdot\cdot \xrightarrow{\mathbf{V}} Vfd\cdot\cdot\cdot$$ + + +Vendor Awareness (**V**) occurs when a Participant—typically a +Finder, Coordinator, or another Vendor—is in RM _Accepted_ and notifies the Vendor. +In turn, the Vendor starts in $q^{rm} = Received$ and proceeds to follow their validation and prioritization routines. +We previously outlined this in [RM Interactions Between CVD Participants](../rm/rm_interactions.md). + +```mermaid +--- +title: Vendor Notification +--- +stateDiagram-v2 + direction LR + state AnyParticipant { + state RM { + A: Accepted + } + } + state VendorParticipant { + RM2: RM + state RM2 { + direction LR + Start --> Received : Receive report + } + + state CS { + direction LR + vfd: Vendor Unaware + Vfd: Vendor Aware + vfd --> Vfd : Vendor Awareness + } + RM2 --> CS: implies + } + AnyParticipant --> VendorParticipant: enables +``` + +--- + +Depending on which parties are involved in a CVD case, the [EM](../em/index.md) process might already be underway prior +to Vendor notification (e.g., $q^{em} \in \{P,A,R\}$). For example, a +Reporter and Coordinator might have already agreed to a disclosure +timeline. Or, in an MPCVD case, other Vendors may have already been +coordinating the case under an embargo and only recently realized the +need to engage with a new Vendor on the case. The latter example is +consistent with [public narratives](https://www.techtarget.com/searchsecurity/news/252446638/Meltdown-and-Spectre-disclosure-suffered-extraordinary-miscommunication) about the Meltdown/Spectre +vulnerabilities. + + +!!! note "" + + Once a case has reached $q^{cs} \in Vfdpxa$ for at least one Vendor, + if the EM process has not started, it SHOULD begin as soon as possible. + +!!! note "" + + Any proposed embargo SHOULD be decided (_accept_, _reject_) soon + after the first Vendor is notified. + +```mermaid +--- +title: Resolving Embargo Effects of Vendor Awareness +--- +stateDiagram-v2 + direction LR + state Vendor { + state CS { + vfd --> Vfd + } + } + state EM { + None + state Proposed { + + state eval <> + [*] --> eval + eval --> Accepted : accept + eval --> None: reject + } + None --> Proposed : propose + Accepted + } + Vendor --> EM: resolve
ASAP +``` + +???+ note "Embargo Effects of Vendor Awareness Formalized" + + $$q^{cs} \in Vfdpxa \implies q^{em} \in + \begin{cases} + None \xrightarrow{propose} Proposed \\ + Proposed \begin{cases} + \xrightarrow{reject} None \\ + \xrightarrow{accept} Accepted \\ + \end{cases} \\ + Accepted \\ + Revise \\ + \end{cases}$$ + +## Fix Ready {#sec:cs_f_em} + +Fix Readiness (**F**) can occur only when a Vendor is in the +_Accepted_ state. As a reminder, in MPCVD cases, each affected Vendor has their own +[RM](../rm/index.md) state, so this constraint applies to each Vendor individually. + +--- + +With respect to [EM](../em/index.md), when the case state is $q^{cs} \in VF\cdot pxa$, it's usually too late to +start a new embargo. + +!!! note "" + + Once a case has reached _Fix Ready_ ($q^{cs} \in VF\cdot pxa$), + + - New embargo negotiations SHOULD NOT start. + - Proposed but not-yet-agreed-to embargoes SHOULD be rejected. + - Existing embargoes ($q^{em} \in \{Active,~Revise\}$) MAY continue but SHOULD prepare to _terminate_ soon. + +```mermaid +--- +title: Fix Ready +--- +stateDiagram-v2 + direction LR + state CS { + Vfd: Vendor Aware + VFd: Fix Ready + Vfd --> VFd : Fix becomes ready + } + state EM { + state PreEmbargo{ + P: Proposed + N: None + P --> N: reject + } + state ActiveEmbargo { + A: Active + R: Revise + A --> R: propose + R --> A: accept + } + } + CS --> EM: implies +``` + +???+ note "Embargo Effects of Fix Readiness Formalized" + + $$q^{cs} \in VF\cdot pxa \implies q^{em} \in + \begin{cases} + None \\ + Proposed \xrightarrow{reject} None \\ + Accepted \\ + Revise \\ + \end{cases}$$ + +!!! note "" + + In MPCVD cases, where some Vendors are likely to reach $q^{cs} \in VF\cdot\cdot\cdot\cdot$ + before others, + + - Participants MAY propose an embargo extension to allow trailing + Vendors to catch up before publication. + - Participants SHOULD accept reasonable extension proposals for such + purposes when possible (e.g., when other constraints could still be + met by the extended deadline). + +## Fix Deployed + +For vulnerabilities in systems where the Vendor controls deployment, the +Fix Deployment (**D**) event can only occur if the Vendor is in +$q^{rm} = Accepted$. + +```mermaid +--- +title: Fix Deployed RM-CS Interactions +--- +stateDiagram-v2 + direction LR + state RM { + Accepted + } + state CS { + VFd: Fix Ready + VFD: Fix Deployed + + VFd --> VFD : Deploy + } + RM --> CS: enables +``` + +For vulnerabilities in systems whose software delivery model dictates that Public Awareness must precede +Deployment ($\mathbf{P} \prec \mathbf{D}$), the Vendor status at the time of deployment might be +irrelevant—assuming, of course, that they at least passed through $q^{rm} = Accepted$ at some point as is required +for Fix Ready (**F**), which, in turn, is a prerequisite for deployment (**D**). + +--- + +As regards [EM](../em/index.md), + +!!! note "" + + By the time a fix has been deployed ($q^{cs} \in VFD\cdot\cdot\cdot$), + + - New embargoes SHOULD NOT be sought. + - Any existing embargo SHOULD terminate. + +```mermaid +--- +title: Fix Deployed CS-EM Interactions +--- +stateDiagram-v2 + direction LR + state CS { + VFd: Fix Ready + VFD: Fix Deployed + + VFd --> VFD : Deploy + } + state EM { + state PreEmbargo{ + Proposed --> None: reject + } + state ActiveEmbargo { + Accepted --> eXited: terminate + Revise --> eXited: terminate + } + } + CS --> EM: implies +``` + +???+ note "Embargo Effects on reaching Fix Deployment Formalized" + + $$q^{cs} \in {VFD} \cdot\cdot\cdot \implies q^{em} \in + \begin{cases} + None \\ + Proposed \xrightarrow{reject} None \\ + Accepted \xrightarrow{terminate} eXited \\ + Revise \xrightarrow{terminate} eXited \\ + \end{cases}$$ + +As with the *Fix Ready* scenario [above](#sec:cs_f_em), MPCVD cases may have Vendors in varying states of *Fix Deployment*. +Therefore the embargo extension caveats from that section apply to the *Fix Deployed* state as well. + +## Public Awareness + +Within the context of a coordinated publication process, (**P**) +requires at least one Participant to be in the $q^{rm} = Accepted$ state +because Participants are presumed to publish only on cases they have +accepted. Ideally, the Vendor is among those Participants, but as +outlined in the [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD), +that is not strictly necessary. + +That said, the publishing party might be outside of *any* existing +coordination process. For example, this is the situation when a report +is already in the midst of a CVD process and a party outside the +CVD case reveals the vulnerability publicly (e.g., parallel discovery, embargo leaks). + +--- + +As for [EM](../em/index.md), the whole point of an embargo is to prevent **P** from occurring until +other objectives (e.g., $q^{cs} \in VF\cdot px \cdot$) have been met. Therefore, + +!!! note "" + + Once _Public Awareness_ has happened and the case state reaches + $q^{cs} \in \cdot\cdot\cdot P \cdot\cdot$, + + - New embargoes SHALL NOT be sought. + - Any existing embargo SHALL terminate. + +```mermaid +--- +title: Public Awareness CS-EM Interactions +--- +stateDiagram-v2 + direction LR + state CS { + p: Public Unaware (p) + P: Public Aware (P) + + p --> P : Public Awareness + } + state EM { + state PreEmbargo{ + Proposed --> None: reject + } + state ActiveEmbargo { + Accepted --> eXited: terminate + Revise --> eXited: terminate + } + } + CS --> EM: implies +``` + +???+ note "Embargo Effects on reaching Public Awareness Formalized" + + $$q^{cs} \in \cdot\cdot\cdot P \cdot\cdot \implies q^{em} \in + \begin{cases} + None \\ + Proposed \xrightarrow{reject} None \\ + Accepted \xrightarrow{terminate} eXited \\ + Revise \xrightarrow{terminate} eXited \\ + \end{cases}$$ + +## Exploit Public + +Exploit publishers may also be presumed to have a similar [RM](../rm/index.md) state model for their own work. +Therefore, we can expect them to be in an RM _Accepted_ state at the time of exploit code publication (**X**). +However, we cannot presume that those who publish exploit code will be Participants in a pre-public CVD process. +That said, + +!!! note "" + + Exploit Publishers who *are* Participants in pre-public CVD cases ($q^{cs} \in \cdot\cdot\cdot p \cdot\cdot$) + SHOULD comply with the protocol described here, especially when they also fulfill other roles + (e.g., Finder, Reporter, Coordinator, Vendor) in the process. + +For example, as described in +[A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513), +the preference for $\mathbf{P} \prec \mathbf{X}$ dictates that + +!!! note "" + + Exploit Publishers SHOULD NOT release exploit code while an embargo + is active ($q^{em} \in \{A,R\}$). + +```mermaid +--- +title: Exploit Public EM-RM Interactions for Exploit Publishers +--- +stateDiagram-v2 + direction LR + state EM { + state ActiveEmbargo { + direction LR + Accepted + Revise + Revise --> Accepted + Accepted --> Revise + } + } + nox: Do not publish exploit + EM --> nox + +``` + +In the [Case State model](../cs/cs_model.md#cs-transitions-defined), we have already established that +public exploit code is either preceded by Public Awareness (**P**) or immediately leads to it. +Therefore, + +!!! note "" + + Once Exploit Publication has occurred and the case state reaches $q^{cs} \in \cdot\cdot\cdot\cdot X \cdot$, + + - New embargoes SHALL NOT be sought. + - Any existing embargo SHALL terminate. + +```mermaid +--- +title: Exploit Public CS-EM Interactions +--- +stateDiagram-v2 + direction LR + state CS { + x: No Public Exploit (x) + X: Exploit Public (X) + + x --> X : Exploit Publication + } + state EM { + state PreEmbargo{ + Proposed --> None: reject + } + state ActiveEmbargo { + Accepted --> eXited: terminate + Revise --> eXited: terminate + } + } + CS --> EM: implies +``` + +???+ note "Embargo Effects on reaching Exploit Public Formalized" + + $$q^{cs} \in \cdot\cdot\cdot\cdot X \cdot \implies q^{em} \in + \begin{cases} + None \\ + Proposed \xrightarrow{reject} None \\ + Accepted \xrightarrow{terminate} eXited \\ + Revise \xrightarrow{terminate} eXited \\ + \end{cases}$$ + +## Attacks Observed + +Nothing in this or any other CVD process model should be interpreted as +constraining adversary activity. + +!!! note "" + + Participants MUST treat attacks as an event that could occur at any + time and adapt their process as needed in light of the available + information. + +As we outlined in [Early Termination](../em/early_termination.md), when attacks are occurring, +embargoes can often be of more benefit to adversaries than defenders. +However, we also acknowledged in +[CS Transitions](../cs/cs_model.md#attacks-do-not-necessarily-cause-public-awarenesss) that narrowly scoped attacks need +not imply widespread adversary knowledge of the vulnerability. +In such scenarios, it is possible that early embargo termination—leading to publication—might be of more +assistance to other adversaries than it is to defenders. +Thus, we need to allow room for Participant judgment based on their case-specific situation awareness. +Formally, + +!!! note "" + + Once Attacks have been observed and the case state reaches $q^{cs} \in \cdot\cdot\cdot\cdot\cdot A$, + + - New embargoes SHALL NOT be sought. + - Any existing embargo SHOULD terminate. + + +```mermaid +--- +title: Attacks Observed CS-EM Interactions +--- +stateDiagram-v2 + direction LR + state CS { + a: No Attacks Observed + A: Attacks Observed + + a --> A : Attack Observation + } + state EM { + state PreEmbargo{ + Proposed --> None: reject + } + state ActiveEmbargo { + Accepted --> eXited: terminate + Revise --> eXited: terminate + } + } + CS --> EM: implies +``` + +???+ note "Embargo Effects on reaching Attacks Observed Formalized" + $$q^{cs} \in \cdot\cdot\cdot\cdot\cdot A \implies q^{em} \in + \begin{cases} + None \\ + Proposed \xrightarrow{reject} None \\ + Accepted \xrightarrow{terminate} eXited \\ + Revise \xrightarrow{terminate} eXited \\ + \end{cases}$$ diff --git a/docs/topics/process_models/rm/index.md b/docs/topics/process_models/rm/index.md new file mode 100644 index 00000000..934532c7 --- /dev/null +++ b/docs/topics/process_models/rm/index.md @@ -0,0 +1,706 @@ +# Report Management Process Model + +{% include-markdown "../../../includes/normative.md" %} + +Here we describe a high-level workflow for the CVD Report Management (RM) process. + +The RM process should be reasonably familiar to anyone familiar with [IT Service Management](https://en.wikipedia.org/wiki/IT_service_management) (ITSM) workflows such as problem, change, +incident or service request management. +In particular, any workflow in which work items (e.g., incident reports, problem tickets, change requests) are received, validated, prioritized, and work is subsequently +completed, should map onto the RM process outlined here. + + +!!! tip "Vultron Does Not Dictate Internal Processes" + + In the interest of maintaining the potential for interoperability among different organizations' internal processes, our protocol does not + specify intra-organizational subprocesses within each state, although we give examples of such subprocesses in + [Do Work Behavior](../../behavior_logic/do_work_bt.md). + + For further reference, [ISO/IEC 30111:2019(E)](https://www.iso.org/standard/69725.html) provides recommendations for Vendors' *internal* processes + that can be mapped into the RM process. We provide such a mapping in our [ISO Crosswalk](../../../reference/iso_crosswalk.md). + +## RM State Machine + +{% include-markdown "../dfa_notation_definition.md" %} + +In this section, we first cover the states themselves before proceeding +to a discussion of the transitions between them. +[Elsewhere](rm_interactions.md) , we provide a +discussion of the Participant-specific semantics of the state +transitions. We use Deterministic Finite Automata (DFA) notation to describe our +RM model (see inset). + +### RM States + +Our proposed RM DFA models a report lifecycle containing seven states, defined below. + +{% include-markdown "./rm_state_machine_diagram.md" %} + + +???+ note inline end "RM States $\mathcal{Q}^{rm}$ Defined" + + $\begin{split} + \mathcal{Q}^{rm} = \{ & \underline{S}tart, \\ + & \underline{R}eceived,\\ + & \underline{I}nvalid, \\ + & \underline{V}alid, \\ + & \underline{A}ccepted, \\ + & \underline{D}eferred, \\ + & \underline{C}losed \} + \end{split}$ + +By convention, we will use the underlined capital letters in the box at right as a shorthand for +the state names. Each Participant in a CVD case will have their own RM state. + +!!! info "RM States vs. CVD Case States" + + RM states are not the same as CVD case states. Case states follow the Householder-Spring model summarized + in [Case State Model](../cs/index.md). Further discussion of the interactions of the RM and CS models is found + in [Model Interactions](../model_interactions/). + +#### The _Start_ (_S_) State + +The _Start_ state is a simple placeholder state for reports that have +yet to be received. It is, in effect, a null state that no +CVD Participant would be expected to reflect in their report tracking system. We include +it here because it is useful when modeling coordination +that spans multiple Participants in the [formal protocol](../../formal_protocol/index.md). +Otherwise, the discussion until then will mostly ignore it. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> Start +``` + +#### The _Received_ (_R_) State + +Reports initially arrive in the _Received_ state. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> Start + Start --> Received +``` + +Vendors lacking the ability to receive reports will find it exceedingly +difficult if not impossible to participate in the +CVD process. Therefore, + +!!! note "" + + Vendors SHOULD have a clearly defined and publicly available + mechanism for receiving reports. + +Similarly, those who coordinate others' responses to vulnerability +reports also need to have a report receiving capability; otherwise, they +are not capable of coordinating vulnerability disclosures. Hence, + +!!! note "" + + Coordinators MUST have a clearly defined and publicly available + mechanism for receiving reports. + +Exiting the _Received_ state requires a Participant to assess the +validity of a report. Note that validation is distinct from +prioritization, as covered in our description of the [_Valid_](#the-valid-v-state) state. +In other words, the _Received_ state corresponds to the +[Validation phase](https://vuls.cert.org/confluence/display/CVD/4.3+Validation+and+Triage) +of the [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD). + +!!! note "" + + Participants SHOULD subject each _Received_ report to some sort + of validation process, resulting in the report being designated as + _valid_ or _invalid_ based on the Participant's particular criteria. + +Validity criteria need not be limited to technical analysis. For +instance, a Coordinator might only accept reports within their specific +scope of concern and consider reports outside their scope to be +_Invalid_ even if they believe the report accurately describes a real +vulnerability. Alternatively, a Vendor might institute a policy +designating reports unaccompanied by a working proof-of-concept exploit +as _Invalid_ by default. + +!!! note "" + + Participants SHOULD have a clearly defined process for + validating reports in the _Received_ state. + +!!! note "" + + Participants SHOULD have a clearly defined process for + transitioning reports from the _Received_ state to the _Valid_ or + _Invalid_ states. + +!!! note "" + + Participants MAY perform a more technical report validation process + before exiting the _Received_ state. + +!!! note "" + + Regardless of the technical rigor applied in the validation process, + Participants SHOULD proceed only after validating the reports they + receive. + +!!! note "" + + Participants SHOULD transition all valid reports to the _Valid_ + state and all invalid reports to the _Invalid_ state. + +!!! note "" + + Regardless of the content or quality of the initial report, once a + Vendor confirms that a reported vulnerability affects one or more of + their product(s) or service(s), the Vendor SHOULD designate the + report as _Valid_. + +!!! note "" + + Participants MAY create a case object to track any report in the _Received_ state. + +#### The _Invalid_ (_I_) State + +Reports in the _Invalid_ state have been evaluated and found lacking by +the recipient. This state allows time for the Reporter to provide +additional information and for the receiver to revisit the validation +before moving the report to _Closed_. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> Start + Start --> Received + Received --> Invalid +``` + + +The reasons for a report to be put in this state will vary based on each +recipient's validation criteria, and their technical capability and +available resources. The _Invalid_ state is intended to be used as a +temporary holding place to allow for additional evidence to be sought to +contradict that conclusion. + +!!! note "" + + Participants SHOULD temporarily hold reports that they cannot + validate pending additional information. + +!!! note "" + + Participants SHOULD provide Reporters an opportunity to update their + report with additional information in support of its validity before + closing the report entirely. + +!!! note "" + + Participants MAY set a timer to move reports from _Invalid_ to + _Closed_ after a set period of inactivity. + +#### The _Valid_ (_V_) State + +Reports in the _Valid_ state are ready to be prioritized for possible +future work. The result of this prioritization process will be to either +accept the report for follow-up or defer further effort. +The _Valid_ state is equivalent to the [Prioritization +(Triage)](https://vuls.cert.org/confluence/display/CVD/4.3+Validation+and+Triage) phase +of the [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD). +As an example, a Vendor might later choose to _defer_ further response on a _Valid_ report due to other priorities. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> Start + Start --> Received + Received --> Invalid + Received --> Valid + Invalid --> Valid +``` + + +!!! note "" + + For _Valid_ reports, the Participant SHOULD perform a prioritization + evaluation to decide whether to _accept_ or _defer_ the report for + further work. + +!!! note "" + + If one does not already exist, Participants SHOULD create a case from + reports entering the _Valid_ state to track the report's subsequent progress through the CVD process. + +!!! note "" + + Participants MAY choose to + perform a shallow technical analysis on _Valid_ reports to prioritize any further + effort relative to other work. + +!!! note "" + + Participants SHOULD have a bias toward accepting rather than + deferring _Valid_ cases up to their work capacity limits. + +In other words, prioritization is only necessary if the workload +represented by active valid reports exceeds the organization's capacity +to process those reports. + + + +Prioritization schemes, such as [SSVC](https://github.com/CERTCC/SSVC) or the +[CVSS](https://first.org/cvss), are commonly used to +prioritize work within the CVD process; however, specific details are +left to Participant-specific implementation. +The SSVC model is illustrative here, although any prioritization scheme could be +substituted as long as it emits a result that can be mapped onto the +semantics of "continue work" or "defer further +action". +[SSVC Crosswalk](../../../reference/ssvc_crosswalk.md) takes a closer look at how +SSVC fits into the protocol we are defining. + +#### The _Accepted_ (_A_) State + +The _Accepted_ state is where the bulk of the work for a given +CVD Participant +occurs. Reports reach this state for a Participant only once the +Participant has deemed the report to be both valid and of sufficient +priority to warrant further action. The _Accepted_ state has a different +meaning for each different Participant. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> Start + Start --> Received + Received --> Invalid + Received --> Valid + Invalid --> Valid + Valid --> Accepted +``` + + +- For our purposes, Finders/Reporters enter the _Accepted_ state only + for reports that they intend to put through the + CVD process. If + they have no intention of pursuing CVD, there is no need for them to track + their actions using this protocol. See [the secret lives of finders](rm_interactions.md#the-secret-lives-of-finders) for more. + +- Vendors usually do root cause analysis, understand the problem, and + produce a fix or mitigation. + +- Coordinators typically identify potentially affected Vendors, notify + them, and possibly negotiate embargoes. + +We provide additional elaboration on the sorts of activities that might +happen in the _Accept_ state in [Do Work Behavior](../../behavior_logic/do_work_bt.md). + +!!! note "" + + A report MAY enter and exit the _Accepted_ state a number of times + in its lifespan as a Participant resumes or pauses work (i.e., + transitions to/from the _Deferred_ state). + +#### The _Deferred_ (_D_) State + +The _Deferred_ state is reserved for valid, unclosed reports that are +otherwise not being actively worked on (i.e., those in _Accepted_). It +parallels the _Invalid_ state for reports that fail to meet the +necessary validation criteria in that both states are awaiting closure +once it is determined that no further action is necessary. + +```mermaid +stateDiagram-v2 + direction LR + [*] --> Start + Start --> Received + Received --> Invalid + Received --> Valid + Invalid --> Valid + Valid --> Accepted + Valid --> Deferred + Accepted --> Deferred + Deferred --> Accepted +``` + + +For example, a Participant might use the _Deferred_ state when a valid +report fails to meet their [prioritization criteria](#prioritize-report), or when a higher priority task takes +precedence over an active case. + +!!! note "" + + A report MAY enter and exit the _Deferred_ state a number of times + in its lifespan as a Participant pauses or resumes work (i.e., + transitions from/to the _Accepted_ state). + +!!! note "" + + Reports SHOULD exit the _Deferred_ state when work is resumed (to _Accepted_), + or when the Participant has determined that no further action will be taken (to _Closed_). + +!!! note "" + + CVD Participants MAY set a policy timer on reports in the _Deferred_ + state to ensure they are moved to _Closed_ after a set period of + inactivity. + +#### The _Closed_ (_C_) State + +The _Closed_ state implies no further work is to be done; therefore, any +pre-closure review (e.g., for quality assurance purposes) should be +performed before the case moves to the _Closed_ state (i.e., while the +report is in _Invalid_, _Deferred_, or _Accepted_). + +```mermaid +stateDiagram-v2 + direction LR + [*] --> Start + Start --> Received + Received --> Invalid + Received --> Valid + Invalid --> Valid + Valid --> Accepted + Valid --> Deferred + Accepted --> Deferred + Deferred --> Accepted + Accepted --> Closed + Deferred --> Closed + Invalid --> Closed + Closed --> [*] +``` + + +!!! note "" + + Reports SHOULD be moved to the _Closed_ state once a Participant has + completed all outstanding work tasks and is fairly sure that they + will not be pursuing any further action on it. + For example + + - reports or cases that have been in _Invalid_ or _Deferred_ for some length of time, + - cases in _Accepted_ where all necessary tasks are complete. + +???+ note "RM Start and End States ($q^{rm}_0, \mathcal{F}^{rm}$) Defined" + + The RM process + starts in the _Start_ state. + + $$q^{rm}_0 = Start$$ + + The RM process ends + in the _Closed_ state. + + $$\mathcal{F}^{rm} = \{Closed\}$$ + + +### RM State Transitions + +A Participant's RM process begins when the Participant receives a report. +The actions performed in the RM process represent the allowed state +transitions in the corresponding DFA. + +???+ note inline end "RM Symbols ($\Sigma^{rm}$) Defined" + These actions constitute the set of symbols for the + RM DFA. + + $\begin{align*} + \Sigma^{rm} = \{ & \underline{r}eceive, \\ + & \underline{v}alidate, \\ + & \underline{i}nvalidate, \\ + & \underline{a}ccept, \\ + & \underline{d}efer, \\ + & \underline{c}lose \} + \end{align*}$ + +#### RM Transitions Defined + +In this section, we define the allowable transitions between states in +the RM process model. The RM process, including its states and transitions, is depicted in the following diagram. +State transitions represent messaging opportunities to communicate CVD +case status among Participants. This point is the lynchpin that makes the RM model point toward a technical +protocol. Every state transition implies a different message type. + +{% include-markdown "./rm_state_machine_diagram.md" %} + +!!! note "" + + CVD Participants SHOULD announce their RM state transitions to the other + Participants in a case. + +##### Receive Report + +To begin, a Participant must receive a report. Recall that the _Start_ +state is a placeholder, so this action simply puts the receiving +Participant into the _Received_ state at the beginning of their +involvement in the case. + +```mermaid +--- +title: Receive Report +--- +stateDiagram-v2 + direction LR + [*] --> Received: receive report +``` + +##### Validate Report + +The Participant must validate the report to exit the _Received_ state. +Depending on the validation outcome, the report will be in either the +_Valid_ or _Invalid_ state. _Invalid_ reports are often waiting for +additional information from the reporter, but they may also be reports +that are not in scope for the Participant. Some Participants may choose +to close _Invalid_ reports immediately, while others may choose to +periodically revalidate them to see if they have become _Valid_. + +!!! note "" + + Participants SHOULD create a case for all _Valid_ reports. + +!!! note "" + + Paricipants MAY create a case for _Invalid_ reports. + +!!! note "" + + Participants MAY periodically revalidate _Invalid_ reports to + determine if they have become _Valid_. + +```mermaid +--- +title: Validate Report +--- +stateDiagram-v2 + direction LR + state Received { + state validate <> + evaluate: Valid? + [*] --> evaluate + evaluate --> validate + } + state Invalid { + state revalidate <> + await: More info? + [*] --> await + await --> revalidate + revalidate --> await: no change + } + validate --> Valid: validate (create case) + validate --> Invalid: invalidate + revalidate --> Valid: validate (create case) +``` + +##### Prioritize Report + +Once a report has been validated (i.e., it is in the +RM _Valid_ state, +$q^{rm} \in V$), the Participant must prioritize it to determine what +further effort, if any, is necessary. + +!!! note "" + + Participants MUST prioritize _Valid_ cases. + +Our [SSVC Crosswalk](../../../reference/ssvc_crosswalk.md) contains an example of how the +SSVC model can be applied here, although any prioritization scheme could be substituted. +Prioritization ends with the report in either the _Accepted_ or _Deferred_ state. + +A Participant might choose to pause work on a previously _Accepted_ +report after revisiting their prioritization decision. When this +happens, the Participant moves the report to the _Deferred_ state. +Similarly, a Participant might resume work on a _Deferred_ report, +moving it to the _Accepted_ state. + +!!! note "" + + Participants MAY re-prioritize _Accepted_ or _Deferred_ cases. + + + +```mermaid +--- +title: Prioritize Report +--- +stateDiagram-v2 + direction LR + state Valid { + state prioritize <> + evalp: Priority? + [*] --> evalp + evalp --> prioritize + } + state Deferred { + state reprioritize <> + eval: Priority? + wait: Wait + [*] --> wait + wait --> eval + eval --> reprioritize + } + state Accepted { + state reprioritize2 <> + do_work: Do work + evala: Priority? + [*] --> do_work + do_work --> evala + evala --> reprioritize2 + } + + prioritize --> Accepted: accept + prioritize --> Deferred: defer + reprioritize --> Accepted: accept + reprioritize --> wait: defer + reprioritize2 --> do_work: accept + reprioritize2 --> Deferred: defer +``` + + +##### Participants Interact from the Accepted State + +Some Participants (e.g., Finders and Coordinators) need to engage +someone else (e.g., a Vendor) to resolve a case. To do this, the +_sender_ Participants must also be in the _Accepted_ state; otherwise, +why are they working on the case? In the following diagram, we show the interaction between two +instances of the RM model: the left side represents the _sender_ while the right side represents the _recipient_. +Although the _sender_'s state does not change, the _recipient_'s state moves from _Start_ to _Received_. + +!!! note "" + + Participants initiating CVD with others MUST do so from the _Accepted_ state. + +```mermaid +--- +title: Participants Interact from the Accepted State +--- +stateDiagram-v2 + direction LR + state Sender { + direction LR + other: ... + [*] --> other + other --> Accepted: accept + } + state Recipient { + direction LR + [*] --> Received: receive + } + Accepted --> Recipient: send +``` + +##### Case Closure + +Finally, a Participant can complete work on an _Accepted_ report or +abandon further work on an _Invalid_ or _Deferred_ report. + +!!! note "" + + Participants MAY close _Accepted_ or _Deferred_ cases or _Invalid_ reports. + +```mermaid +--- +title: Case Closure +--- +stateDiagram-v2 + direction LR + Accepted --> Closed: close + Deferred --> Closed: close + Invalid --> Closed: close +``` + +Our model assumes that _Valid_ reports cannot be closed directly without +first passing through either _Accepted_ or _Deferred_. It is reasonable +to wonder why _close_ is not a valid transition from the _Valid_ state. +The answer is that we wanted to allow prioritization and closure to be +distinct activities; deferral is reversible, whereas closure is not. +Often a Participant might initially _defer_ a case only to resume work +later, once more information has arrived. However, there is nothing +stopping a Participant from instituting a process that goes from _Valid_ +to _Deferred_ to _Closed_ in rapid (even immediate) succession. + +!!! note "" + + Participants MUST NOT close cases or reports from the _Valid_ state. + + +#### Possible Report Management Histories + +???+ note inline end "RM Transition Function ($\delta^{rm}$) Defined" + + Following the state machine diagram above, we represent the RM process model as a right-linear grammar: + + $$\delta^{rm} = + \begin{cases} + S & \to rR \\ + R & \to vV~|~iI \\ + I & \to vV~|~cC \\ + V & \to aA~|~dD \\ + A & \to dD~|~cC \\ + D & \to aA~|~cC \\ + C & \to \epsilon \\ + \end{cases}$$ + +The strings generated in the language defined by this grammar can be +useful for exploring the possible sequences of states each report might +encounter for each Participant. The 15 shortest paths are _ric_, _rvac_, +_rvdc_, _rivac_, _rivdc_, _rvadc_, _rvdac_, _rivadc_, _rvadac_, +_rvdadc_, _rivdac_, _rivdadc_, _rvdadac_, _rivadac_, and _rvadadc_. Due +to the structure of the RM DFA, longer strings just add more +_defer_-_accept_ (_da_) or _accept_-_defer_ (_ad_) cycles prior to +closure (_c_). The usually limited duration of the +RM process coupled +with the tendency for CVD Participants to prefer to avoid frequent +starts and stops means that we expect the vast majority of reports to +follow one of the above paths, with the remainder falling into marginal +extensions. + + +---- + +!!! tip "See also" + + Further discussion of a [reward function](../../future_work/reward_functions.md) to evaluate RM DFA strings is discussed as future work in + [Reward Functions](../../future_work/reward_functions.md). + +## RM DFA Fully Defined + +The full definition of the RM DFA is given below. + +!!! note "RM DFA Fully Defined" + + Taken in combination, the full definition of the RM DFA is as follows: + + $$ RM = + \begin{pmatrix} + \begin{aligned} + \mathcal{Q}^{rm} = & \{ S,R,I,V,A,D,C \} \\ + q^{rm}_0 = & S \\ + \mathcal{F}^{rm} = & \{ C \} \\ + \Sigma^{rm} = & \{ r,i,v,a,d,c \} \\ + \delta^{rm} = & + \begin{cases} + S \to & rR \\ + R \to & vV~|~iI \\ + I \to & vV~|~cC \\ + V \to & aA~|~dD \\ + A \to & dD~|~cC \\ + D \to & aA~|~cC \\ + C \to & \epsilon \\ + \end{cases} + \end{aligned} + \end{pmatrix}$$ + +???+ note "RM State Subsets Defined" + + Before proceeding, we pause to define a few useful subsets of + RM states + ($\dots \subset \mathcal{Q}^{rm}$) for future use: + + $$ \begin{align} + Open &= \{ R,I,V,D,A \} \\ + Valid~Yet~Unclosed &= \{ V,D,A \} \\ + Potentially~Valid~Yet~Unclosed &= \{ R,V,D,A\} \\ + Active &= \{ R,V,A \} \\ + Inactive &= \{ I,D,C \} + \end{align}$$ + diff --git a/docs/topics/process_models/rm/rm_interactions.md b/docs/topics/process_models/rm/rm_interactions.md new file mode 100644 index 00000000..978206ef --- /dev/null +++ b/docs/topics/process_models/rm/rm_interactions.md @@ -0,0 +1,408 @@ +# Report Management Interactions Between CVD Participants + +Each Participant in a case has their own instance of the RM state model. +Participants can change their local state independent of the state of other Participants. +Events within a CVD case may trigger a state transition in one Participant while no transition occurs in another. +For example, in [particpants interact from the accepted state](#participants-interact-from-the-accepted-state) we showed +that even though the _sender_ is the one taking the action, it is the _recipient_'s state that changes. +The table below lists role-based actions. + +| Finder/Reporter | Vendor | Coordinator | Action | RM Transition | +|:----------------:|:----------------:|:----------------:|-----------------------------------------|:----------------------------------------------------------------------------------------------:| +| :material-check: | | | Discover Vulnerability (hidden) | [Receive Report](index.md#receive-report) | +| :material-check: | | | Analyze Discovery (hidden) | [Validate Report](index.md#validate-report) | +| :material-check: | | | Decide whether to initiate CVD (hidden) | [Prioritize Report](index.md#prioritize-report) | +| :material-check: | :material-check: | :material-check: | Notify Vendor | [Participants Interact from Accepted](index.md#participants-interact-from-the-accepted-state) | +| :material-check: | :material-check: | :material-check: | Notify Coordinator | [Participants Interact from Accepted](index.md#participants-interact-from-the-accepted-state) | +| | :material-check: | :material-check: | Receive Report | [Receive Report](index.md#receive-report) | +| | :material-check: | :material-check: | Validate Report | [Validate Report](index.md#validate-report) | +| :material-check: | :material-check: | :material-check: | Prioritize Report | [Prioritize Report](index.md#prioritize-report) | +| :material-check: | :material-check: | :material-check: | Pause Work | [Prioritize Report](index.md#prioritize-report) | +| :material-check: | :material-check: | :material-check: | Resume Work | [Prioritize Report](index.md#prioritize-report) | +| :material-check: | :material-check: | :material-check: | Close Report | [Case Closure](index.md#case-closure) | + +A few examples of this model applied to common CVD and MPCVD case scenarios follow. + +## The Secret Lives of Finders + +While the Finder's _Received_, _Valid_, and _Invalid_ states are useful +for modeling and simulation purposes, they are less useful to us as part +of a potential CVD protocol. Why? Because for anyone else to know about the vulnerability +(and as a prerequisite to CVD happening at all), the Finder must have +already validated the report and prioritized it as worthy of further +effort to have any reason to attempt to coordinate its disclosure. In +other words, CVD only starts *after* the Finder has already reached the +_Accepted_ state for any given vulnerability to be reported. +Correspondingly, this also represents their transition from *Finder* to +*Reporter*. Nevertheless, for now, we retain these states for +completeness. +We revisit this topic in our [formal derivation](../../../reference/formal_protocol/states.md#finder-reporters) +of a protocol state model for Reporters. + +```mermaid +--- +title: Hidden States of Finders +--- +stateDiagram-v2 + direction LR + state Finder { + direction LR + A: Accepted + state Hidden { + direction LR + R: Received + I: Invalid + V: Valid + D: Deferred + [*] --> R + R --> I + R --> V + V --> D + I --> V + V --> A + D --> A + D --> [*] + I--> [*] + } + state Observable { + direction LR + D2: Deferred + A --> D2 + D2 --> A + A --> [*] + D2 --> [*] + } + + } +``` + + +## Finder-Vendor CVD. + +A simple Finder-Vendor CVD scenario is shown below. +As explained [above](#the-secret-lives-of-finders), many of the Finder's states would be +hidden from view until they reach the _Accepted_ ($A_f$) state. The +_receive_ action bridging $A_f \xrightarrow{r} R_v$ corresponds to the +[participants interact from the accepted state](#participants-interact-from-the-accepted-state) scenario above. + +```mermaid +--- +title: Finder-Vendor CVD +--- +stateDiagram-v2 + direction LR + state Finder { + direction LR + R: Rf + I: If + V: Vf + A: Af + D: Df + [*] --> R + R --> I + R --> V + I --> V + V --> A + V --> D + A --> D + D --> A + D --> [*] + A --> [*] + I --> [*] + } + state Vendor { + direction LR + RV:Rv + IV:Iv + VV:Vv + AV:Av + DV:Dv + [*] --> RV + RV --> IV + RV --> VV + IV --> VV + VV --> AV + VV --> DV + AV --> DV + DV --> AV + DV --> [*] + AV --> [*] + IV --> [*] + } + A --> RV: r +``` + +## Finder-Coordinator-Vendor CVD. + +A slightly more complicated scenario in which a Finder engages a +Coordinator after failing to engage a Vendor is shown in the next diagram. +This scenario is very common in our +experience at the CERT/CC, which should come as no surprise +considering our role as a Coordinator means that we do not participate +in cases following the previous example. Here we see three notification +actions corresponding to [participants interacting from the accepted state](#participants-interact-from-the-accepted-state): + +- First, $A_f \xrightarrow{r_0} R_v$ represents the Finder's initial + attempt to reach the Vendor. + +- Next, $A_f \xrightarrow{r_1} R_c$ is the Finder's subsequent attempt + to engage with the Coordinator. + +- Finally, the Coordinator contacts the Vendor in + $A_c \xrightarrow{r_2} R_v$. + +```mermaid +--- +title: Finder-Coordinator-Vendor CVD +--- +stateDiagram-v2 + direction LR + state Finder { + direction LR + R: Rf + I: If + V: Vf + A: Af + D: Df + + [*] --> R + R --> I + R --> V + I --> V + V --> A + V --> D + A --> D + D --> A + D --> [*] + A --> [*] + I --> [*] + } + state Coordinator { + direction LR + RC:Rc + IC:Ic + VC:Vc + AC:Ac + DC:Dc + [*] --> RC + RC --> IC + RC --> VC + IC --> VC + VC --> AC + VC --> DC + AC --> DC + DC --> AC + DC --> [*] + AC --> [*] + IC --> [*] + } + state Vendor { + direction LR + RV:Rv + IV:Iv + VV:Vv + AV:Av + DV:Dv + [*] --> RV + RV --> IV + RV --> VV + IV --> VV + VV --> AV + VV --> DV + AV --> DV + DV --> AV + DV --> [*] + AV --> [*] + IV --> [*] + } + A --> RV: r0 + A --> RC: r1 + AC --> RV: r2 +``` + + +## MPCVD with a Coordinator and Multiple Vendors. + +A small MPCVD scenario is shown below. As with the other examples, each +notification shown is an instance of [participants interacting from the accepted state](#participants-interact-from-the-accepted-state). +Contrary to the previous example, this scenario starts with the Finder contacting a Coordinator, perhaps +because they recognize the increased complexity of coordinating multiple Vendors' responses. + +- First, $A_f \xrightarrow{r_0} R_c$ represents the Finder's initial + report to the Coordinator. + +- Next, $A_c \xrightarrow{r_1} R_{v_1}$ shows the Coordinator + contacting the first Vendor. + +- Finally, the Coordinator contacts a second Vendor in + $A_c \xrightarrow{r_2} R_{v_2}$. + +```mermaid +--- +title: MPCVD with a Coordinator and Multiple Vendors +--- +stateDiagram-v2 + direction LR + state Finder { + direction LR + R: Rf + I: If + V: Vf + A: Af + D: Df + [*] --> R + R --> I + R --> V + I --> V + V --> A + V --> D + A --> D + D --> A + D --> [*] + A --> [*] + I --> [*] + } + state Coordinator { + direction LR + RC:Rc + IC:Ic + VC:Vc + AC:Ac + DC:Dc + [*] --> RC + RC --> IC + RC --> VC + IC --> VC + VC --> AC + VC --> DC + AC --> DC + DC --> AC + DC --> [*] + AC --> [*] + IC --> [*] + } + state Vendor { + direction LR + RV:Rv1 + IV:Iv1 + VV:Vv1 + AV:Av1 + DV:Dv1 + [*] --> RV + RV --> IV + RV --> VV + IV --> VV + VV --> AV + VV --> DV + AV --> DV + DV --> AV + DV --> [*] + AV --> [*] + IV --> [*] + } + state Vendor2 { + direction LR + RV2:Rv2 + IV2:Iv2 + VV2:Vv2 + AV2:Av2 + DV2:Dv2 + [*] --> RV2 + RV2 --> IV2 + RV2 --> VV2 + IV2 --> VV2 + VV2 --> AV2 + VV2 --> DV2 + AV2 --> DV2 + DV2 --> AV2 + DV2 --> [*] + AV2 --> [*] + IV2 --> [*] + } + A --> RC: r0 + AC --> RV: r1 + AC --> RV2: r2 +``` + + +## A Menagerie of MPCVD Scenarios. + +Other MPCVD RM interaction configurations are possible, of course. We demonstrate a few such +scenarios in the following figures. +This time each node represents a Participant's entire RM model. We have observed all of the +following interactions at the CERT/CC. +We intend the RM model to be sufficiently composable to accommodate all such permutations. + + +### Finder coordinates MPCVD with Multiple Vendors + +A Finder notifies multiple Vendors without engaging a Coordinator. + +```mermaid +--- +title: Finder coordinates MPCVD with Multiple Vendors +--- +stateDiagram-v2 + direction LR + Finder --> Vendor1: r0 + Finder --> Vendor2: r1 + Finder --> Vendor3: r2 +``` + +### Vendor coordinates MPCVD + +A Finder notifies a Vendor, who, in turn, notifies other Vendors. + +```mermaid +--- +title: Vendor coordinates MPCVD +--- +stateDiagram-v2 + direction LR + Finder --> Vendor1: r0 + Vendor1 --> Vendor2: r1 + Vendor1 --> Vendor3: r2 + Vendor1 --> Vendor4: r3 +``` + +### Vendor Engages a Coordinator for MPCVD + +A Finder notifies a Vendor, who, in turn, engages a Coordinator to reach other Vendors. + +```mermaid +--- +title: Vendor Engages a Coordinator for MPCVD +--- +stateDiagram-v2 + direction LR + Finder --> Vendor1: r0 + Vendor1 --> Coordinator: r1 + Coordinator --> Vendor2: r2 + Coordinator --> Vendor3: r3 + Coordinator --> Vendor4: r4 +``` + +### Supply-chain oriented MPCVD. + +Supply-chain oriented MPCVD often has two or more tiers of +Vendors being notified by their upstream component suppliers, with +or without one or more Coordinators' involvement. + +```mermaid +--- +title: Supply-chain oriented MPCVD +--- +stateDiagram-v2 + direction LR + Finder --> Vendor1: r0 + Vendor1 --> Vendor2: r1 + Vendor1 --> Vendor3: r2 + Vendor1 --> Coordinator: r3 + Vendor2 --> Vendor4: r4 + Vendor4 --> Vendor5: r5 + Vendor3 --> Vendor6: r6 + Coordinator --> Vendor7: r7 + Vendor7 --> Vendor8: r8 + Vendor7 --> Vendor9: r9 +``` + diff --git a/docs/topics/process_models/rm/rm_state_machine_diagram.md b/docs/topics/process_models/rm/rm_state_machine_diagram.md new file mode 100644 index 00000000..0fb54be8 --- /dev/null +++ b/docs/topics/process_models/rm/rm_state_machine_diagram.md @@ -0,0 +1,28 @@ +```mermaid +--- +title: Report Management State Diagram +--- +stateDiagram-v2 + direction LR + S: Start + R: Received + I: Invalid + V: Valid + D: Deferred + A: Accepted + C: Closed + + [*] --> S + S --> R : receive + R --> I: invalidate + R --> V : validate + I --> V : validate + V --> A : accept + V --> D : defer + A --> D : defer + D --> A : accept + A --> C : close + D --> C : close + I --> C : close + C --> [*] +``` diff --git a/docs/topics/user_stories/index.md b/docs/topics/user_stories/index.md new file mode 100644 index 00000000..37c14a94 --- /dev/null +++ b/docs/topics/user_stories/index.md @@ -0,0 +1,47 @@ +# User Stories + +{% include-markdown "../../includes/not_normative.md" %} + +The Vultron Protocol is designed to support a variety of use cases. +The following user stories are intended to capture the requirements of these use cases. +While the protocol is designed to support these use cases, it is not required that all use cases be supported by the +protocol. + +Where appropriate, we intend to provide a reference implementation for each applicable user story. + +
+ +!!! info "Original User Stories from 2022 CERT/CC Whitepaper" + + Stories numbered from `2022_001` through `2022_102` originated in + the [Coordinated Vulnerability Disclosure User Stories](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=886543) + whitepaper. + + > These user stories reflect + > internal discussions with the CERT/Coordination Center (CC) based on our own experiences in developing and using the + > VINCE platform as well as our ongoing CVD practices. The user stories are expected to be utilized by the CVD team to + > better understand, create, and implement a CVD Protocol. In addition, the CERT/CC believes that these user cases will + > be useful for any enterprise designing or implementing its own CVD policies, processes, and procedures. + + The remaining stories have been added since that whitepaper was published. + +## Support Levels + + +Each story page indicates a categorization according to the level of support provided +by the originally published Vultron Protocol (version 0.4.0): + + +- _Provided_ - Stories in this category are directly supported by the Vultron Protocol v0.4.0. +- _Allowed_ - Stories in this category are indirectly supported by the Vultron Protocol v0.4.0. +- _Unsupported_ - Stories in this category are not supported by the Vultron Protocol v0.4.0. +- _Out-of-scope_ - Stories in this category are out of scope for the Vultron Protocol v0.4.0. + +In the future, we expect these categories will change toward simply _Supported_, _Unsupported_ and _Out-of-scope_. +We also anticipate that as we learn more about ActivityPub and make progress on the protocol development, some of +the stories in the _Unsupported_ category could move to _Supported_. + + +## User Stories Table + +{% include-markdown "table.md" %} diff --git a/doc/user_stories/Allowed/story_2022_001.md b/docs/topics/user_stories/story_2022_001.md similarity index 83% rename from doc/user_stories/Allowed/story_2022_001.md rename to docs/topics/user_stories/story_2022_001.md index ddb33b84..05033fd3 100644 --- a/doc/user_stories/Allowed/story_2022_001.md +++ b/docs/topics/user_stories/story_2022_001.md @@ -1,6 +1,6 @@ # User Story `2022_001` # -As a Finder I want to discover how to report a vulnerability so that I can notify the affected vendors and start CVD +As a Finder I want to discover how to report a vulnerability so that I can notify the affected vendors and start CVD ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_002.md b/docs/topics/user_stories/story_2022_002.md similarity index 72% rename from doc/user_stories/Provided/story_2022_002.md rename to docs/topics/user_stories/story_2022_002.md index 81db38c5..d79cbf1a 100644 --- a/doc/user_stories/Provided/story_2022_002.md +++ b/docs/topics/user_stories/story_2022_002.md @@ -1,7 +1,7 @@ # User Story `2022_002` # -As a Participant I want to receive vulnerability reports that I have submitted through a platform so that I can participate and track coordination efforts  +As a Participant I want to receive vulnerability reports that I have submitted through a platform so that I can participate and track coordination efforts  ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_003.md b/docs/topics/user_stories/story_2022_003.md similarity index 85% rename from doc/user_stories/Allowed/story_2022_003.md rename to docs/topics/user_stories/story_2022_003.md index 9d7bd60a..fe2e47ab 100644 --- a/doc/user_stories/Allowed/story_2022_003.md +++ b/docs/topics/user_stories/story_2022_003.md @@ -1,7 +1,7 @@ # User Story `2022_003` # -As a Participant I want to Discover others' policies +As a Participant I want to Discover others' policies ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_004.md b/docs/topics/user_stories/story_2022_004.md similarity index 86% rename from doc/user_stories/Unsupported/story_2022_004.md rename to docs/topics/user_stories/story_2022_004.md index a361df45..68c7c00d 100644 --- a/doc/user_stories/Unsupported/story_2022_004.md +++ b/docs/topics/user_stories/story_2022_004.md @@ -1,7 +1,7 @@ # User Story `2022_004` # -As a Participant I want to parse/evaluate others' policies +As a Participant I want to parse/evaluate others' policies ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_005.md b/docs/topics/user_stories/story_2022_005.md similarity index 85% rename from doc/user_stories/Unsupported/story_2022_005.md rename to docs/topics/user_stories/story_2022_005.md index 5aec107d..afe28bb7 100644 --- a/doc/user_stories/Unsupported/story_2022_005.md +++ b/docs/topics/user_stories/story_2022_005.md @@ -1,7 +1,7 @@ # User Story `2022_005` # -As a Participant I want to optimize all of the policies involved +As a Participant I want to optimize all of the policies involved ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_006.md b/docs/topics/user_stories/story_2022_006.md similarity index 85% rename from doc/user_stories/Out-of-scope/story_2022_006.md rename to docs/topics/user_stories/story_2022_006.md index 105f795f..993b50dd 100644 --- a/doc/user_stories/Out-of-scope/story_2022_006.md +++ b/docs/topics/user_stories/story_2022_006.md @@ -1,7 +1,7 @@ # User Story `2022_006` # -As a Participant I want to decide if I will/can engage +As a Participant I want to decide if I will/can engage ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_007.md b/docs/topics/user_stories/story_2022_007.md similarity index 86% rename from doc/user_stories/Allowed/story_2022_007.md rename to docs/topics/user_stories/story_2022_007.md index 2b5e20e2..c51a32f4 100644 --- a/doc/user_stories/Allowed/story_2022_007.md +++ b/docs/topics/user_stories/story_2022_007.md @@ -1,7 +1,7 @@ # User Story `2022_007` # -As a Participant I want to throw a flag if policy trouble detected +As a Participant I want to throw a flag if policy trouble detected ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_008.md b/docs/topics/user_stories/story_2022_008.md similarity index 81% rename from doc/user_stories/Out-of-scope/story_2022_008.md rename to docs/topics/user_stories/story_2022_008.md index a9a86918..f97fa167 100644 --- a/doc/user_stories/Out-of-scope/story_2022_008.md +++ b/docs/topics/user_stories/story_2022_008.md @@ -1,7 +1,7 @@ # User Story `2022_008` # -As a Participant I want to warn Participants and need to invoke other channels/humans. +As a Participant I want to warn Participants and need to invoke other channels/humans. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_009.md b/docs/topics/user_stories/story_2022_009.md similarity index 84% rename from doc/user_stories/Unsupported/story_2022_009.md rename to docs/topics/user_stories/story_2022_009.md index afda09a8..e1522224 100644 --- a/doc/user_stories/Unsupported/story_2022_009.md +++ b/docs/topics/user_stories/story_2022_009.md @@ -1,7 +1,7 @@ # User Story `2022_009` # -As a Participant I want to want to post/publish/advertise my policy +As a Participant I want to want to post/publish/advertise my policy ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_010.md b/docs/topics/user_stories/story_2022_010.md similarity index 63% rename from doc/user_stories/Provided/story_2022_010.md rename to docs/topics/user_stories/story_2022_010.md index 2342b241..ff79fd69 100644 --- a/doc/user_stories/Provided/story_2022_010.md +++ b/docs/topics/user_stories/story_2022_010.md @@ -1,7 +1,7 @@ # User Story `2022_010` # -As a Participant I want to Publish/share/advertise embargo dates, have hard and absolute limits, have a default/starting point, be able to extend, and propose and accept, stop when all accepts  • have a default/starting point  • be able to extend • propose and accept  • stop when all accepts +As a Participant I want to Publish/share/advertise embargo dates, have hard and absolute limits, have a default/starting point, be able to extend, and propose and accept, stop when all accepts  • have a default/starting point  • be able to extend • propose and accept  • stop when all accepts ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_011.md b/docs/topics/user_stories/story_2022_011.md similarity index 81% rename from doc/user_stories/Unsupported/story_2022_011.md rename to docs/topics/user_stories/story_2022_011.md index f3e7e648..5ef9a800 100644 --- a/doc/user_stories/Unsupported/story_2022_011.md +++ b/docs/topics/user_stories/story_2022_011.md @@ -1,7 +1,7 @@ # User Story `2022_011` # -As a Participant, I want to provide information about my bug bounty program to entice reporters to use it +As a Participant, I want to provide information about my bug bounty program to entice reporters to use it ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_012.md b/docs/topics/user_stories/story_2022_012.md similarity index 84% rename from doc/user_stories/Provided/story_2022_012.md rename to docs/topics/user_stories/story_2022_012.md index dc77ee5e..47696b0f 100644 --- a/doc/user_stories/Provided/story_2022_012.md +++ b/docs/topics/user_stories/story_2022_012.md @@ -1,7 +1,7 @@ # User Story `2022_012` # -As a Participant, I want to report a (new) vulnerability +As a Participant, I want to report a (new) vulnerability ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_013.md b/docs/topics/user_stories/story_2022_013.md similarity index 88% rename from doc/user_stories/Allowed/story_2022_013.md rename to docs/topics/user_stories/story_2022_013.md index e8361aad..53886ba9 100644 --- a/doc/user_stories/Allowed/story_2022_013.md +++ b/docs/topics/user_stories/story_2022_013.md @@ -1,7 +1,7 @@ # User Story `2022_013` # -As a Participant I want to Add a Participant? (de-duplicate) +As a Participant I want to Add a Participant? (de-duplicate) ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_014.md b/docs/topics/user_stories/story_2022_014.md similarity index 81% rename from doc/user_stories/Provided/story_2022_014.md rename to docs/topics/user_stories/story_2022_014.md index 3421cb5a..4e1d501d 100644 --- a/doc/user_stories/Provided/story_2022_014.md +++ b/docs/topics/user_stories/story_2022_014.md @@ -1,7 +1,7 @@ # User Story `2022_014` # -As a Participant, I want to negotiate embargo/disclosure schedules, modify/renegotiate them, and know when others have published +As a Participant, I want to negotiate embargo/disclosure schedules, modify/renegotiate them, and know when others have published ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_015.md b/docs/topics/user_stories/story_2022_015.md similarity index 86% rename from doc/user_stories/Allowed/story_2022_015.md rename to docs/topics/user_stories/story_2022_015.md index 3f5f99fb..50249d25 100644 --- a/doc/user_stories/Allowed/story_2022_015.md +++ b/docs/topics/user_stories/story_2022_015.md @@ -1,7 +1,7 @@ # User Story `2022_015` # -As a Participant, I want to notify others of my intent (date) to publish +As a Participant, I want to notify others of my intent (date) to publish ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_016.md b/docs/topics/user_stories/story_2022_016.md similarity index 85% rename from doc/user_stories/Out-of-scope/story_2022_016.md rename to docs/topics/user_stories/story_2022_016.md index a8a57273..5c3af77f 100644 --- a/doc/user_stories/Out-of-scope/story_2022_016.md +++ b/docs/topics/user_stories/story_2022_016.md @@ -1,7 +1,7 @@ # User Story `2022_016` # -As a Participant, I want limited/ACK of vulnerability/and have full/proper advisory +As a Participant, I want limited/ACK of vulnerability/and have full/proper advisory ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_017.md b/docs/topics/user_stories/story_2022_017.md similarity index 84% rename from doc/user_stories/Allowed/story_2022_017.md rename to docs/topics/user_stories/story_2022_017.md index eb04dd33..14c86dce 100644 --- a/doc/user_stories/Allowed/story_2022_017.md +++ b/docs/topics/user_stories/story_2022_017.md @@ -1,7 +1,7 @@ # User Story `2022_017` # -As a Participant, I want to share my draft publication with others +As a Participant, I want to share my draft publication with others ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_018.md b/docs/topics/user_stories/story_2022_018.md similarity index 80% rename from doc/user_stories/Provided/story_2022_018.md rename to docs/topics/user_stories/story_2022_018.md index e3200bdd..d64460d2 100644 --- a/doc/user_stories/Provided/story_2022_018.md +++ b/docs/topics/user_stories/story_2022_018.md @@ -1,7 +1,7 @@ # User Story `2022_018` # -As a Participant, I become aware of the existence of of public exploit (e.g. PoC) and want to tell others +As a Participant, I become aware of the existence of of public exploit (e.g. PoC) and want to tell others ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_019.md b/docs/topics/user_stories/story_2022_019.md similarity index 82% rename from doc/user_stories/Provided/story_2022_019.md rename to docs/topics/user_stories/story_2022_019.md index 4c982c80..01d018d8 100644 --- a/doc/user_stories/Provided/story_2022_019.md +++ b/docs/topics/user_stories/story_2022_019.md @@ -1,7 +1,7 @@ # User Story `2022_019` # -As a Participant, I become aware of exploitation in the wild and want to tell others +As a Participant, I become aware of exploitation in the wild and want to tell others ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_020.md b/docs/topics/user_stories/story_2022_020.md similarity index 83% rename from doc/user_stories/Out-of-scope/story_2022_020.md rename to docs/topics/user_stories/story_2022_020.md index 93909601..95a57544 100644 --- a/doc/user_stories/Out-of-scope/story_2022_020.md +++ b/docs/topics/user_stories/story_2022_020.md @@ -1,7 +1,7 @@ # User Story `2022_020` # -As a Participant, I want to publish a vulnerability (external to protocol) +As a Participant, I want to publish a vulnerability (external to protocol) ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_021.md b/docs/topics/user_stories/story_2022_021.md similarity index 78% rename from doc/user_stories/Unsupported/story_2022_021.md rename to docs/topics/user_stories/story_2022_021.md index 05956d9d..eb7afc94 100644 --- a/doc/user_stories/Unsupported/story_2022_021.md +++ b/docs/topics/user_stories/story_2022_021.md @@ -1,7 +1,7 @@ # User Story `2022_021` # -As a Participant, I want to advertise the locale (language, location, geo-scope, area of authority), aspects of my policy +As a Participant, I want to advertise the locale (language, location, geo-scope, area of authority), aspects of my policy ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_022.md b/docs/topics/user_stories/story_2022_022.md similarity index 80% rename from doc/user_stories/Unsupported/story_2022_022.md rename to docs/topics/user_stories/story_2022_022.md index 127eeace..3d551f96 100644 --- a/doc/user_stories/Unsupported/story_2022_022.md +++ b/docs/topics/user_stories/story_2022_022.md @@ -1,7 +1,7 @@ # User Story `2022_022` # -As a Participant, I want to advertise the scope (e.g., products, version ranges, sites/domains) of my CVD capability +As a Participant, I want to advertise the scope (e.g., products, version ranges, sites/domains) of my CVD capability ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_023.md b/docs/topics/user_stories/story_2022_023.md similarity index 79% rename from doc/user_stories/Allowed/story_2022_023.md rename to docs/topics/user_stories/story_2022_023.md index 7dc582d1..3ad2ec53 100644 --- a/doc/user_stories/Allowed/story_2022_023.md +++ b/docs/topics/user_stories/story_2022_023.md @@ -1,7 +1,7 @@ # User Story `2022_023` # -As a Participant, I want to constrain whom I communicate with because I want to enforce an embargo and communicate only with those who have a need to know. +As a Participant, I want to constrain whom I communicate with because I want to enforce an embargo and communicate only with those who have a need to know. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_024.md b/docs/topics/user_stories/story_2022_024.md similarity index 81% rename from doc/user_stories/Allowed/story_2022_024.md rename to docs/topics/user_stories/story_2022_024.md index 439f4c4d..2a5cbcda 100644 --- a/doc/user_stories/Allowed/story_2022_024.md +++ b/docs/topics/user_stories/story_2022_024.md @@ -1,7 +1,7 @@ # User Story `2022_024` # -As a Finder/Reporter, I want to constrain whom I communicate with because I want to maintain my anonymity. +As a Finder/Reporter, I want to constrain whom I communicate with because I want to maintain my anonymity. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_025.md b/docs/topics/user_stories/story_2022_025.md similarity index 80% rename from doc/user_stories/Allowed/story_2022_025.md rename to docs/topics/user_stories/story_2022_025.md index 86437b2b..a012041f 100644 --- a/doc/user_stories/Allowed/story_2022_025.md +++ b/docs/topics/user_stories/story_2022_025.md @@ -1,7 +1,7 @@ # User Story `2022_025` # -As a Vendor/Deployer, I want to constrain whom I communicate with until a patch or mitigation has been published and released. +As a Vendor/Deployer, I want to constrain whom I communicate with until a patch or mitigation has been published and released. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_026.md b/docs/topics/user_stories/story_2022_026.md similarity index 78% rename from doc/user_stories/Allowed/story_2022_026.md rename to docs/topics/user_stories/story_2022_026.md index db76a059..50da679b 100644 --- a/doc/user_stories/Allowed/story_2022_026.md +++ b/docs/topics/user_stories/story_2022_026.md @@ -1,7 +1,7 @@ # User Story `2022_026` # -As a Coordinator, I want to constrain whom I communicate with to work within an embargo and communicate only with those who have a need to know. +As a Coordinator, I want to constrain whom I communicate with to work within an embargo and communicate only with those who have a need to know. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_027.md b/docs/topics/user_stories/story_2022_027.md similarity index 84% rename from doc/user_stories/Allowed/story_2022_027.md rename to docs/topics/user_stories/story_2022_027.md index 9cc73e64..506b9551 100644 --- a/doc/user_stories/Allowed/story_2022_027.md +++ b/docs/topics/user_stories/story_2022_027.md @@ -1,7 +1,7 @@ # User Story `2022_027` # -As a Participant, I want to Address Participants constraints, e.g., entity lists +As a Participant, I want to Address Participants constraints, e.g., entity lists ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_028.md b/docs/topics/user_stories/story_2022_028.md similarity index 82% rename from doc/user_stories/Unsupported/story_2022_028.md rename to docs/topics/user_stories/story_2022_028.md index c57d65e3..240028df 100644 --- a/doc/user_stories/Unsupported/story_2022_028.md +++ b/docs/topics/user_stories/story_2022_028.md @@ -1,7 +1,7 @@ # User Story `2022_028` # -As a vendor or coordinator, I want others to find my information and reporting intake (duplicate of X) +As a vendor or coordinator, I want others to find my information and reporting intake (duplicate of X) ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_029.md b/docs/topics/user_stories/story_2022_029.md similarity index 85% rename from doc/user_stories/Allowed/story_2022_029.md rename to docs/topics/user_stories/story_2022_029.md index bdbac544..c7e196c3 100644 --- a/doc/user_stories/Allowed/story_2022_029.md +++ b/docs/topics/user_stories/story_2022_029.md @@ -1,7 +1,7 @@ # User Story `2022_029` # -As a Vendor, Deployer, and Other, I want to assign my own ID to a case +As a Vendor, Deployer, and Other, I want to assign my own ID to a case ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_030.md b/docs/topics/user_stories/story_2022_030.md similarity index 77% rename from doc/user_stories/Allowed/story_2022_030.md rename to docs/topics/user_stories/story_2022_030.md index d5fbb46e..3361d723 100644 --- a/doc/user_stories/Allowed/story_2022_030.md +++ b/docs/topics/user_stories/story_2022_030.md @@ -1,7 +1,7 @@ # User Story `2022_030` # -As a Participant , I want to discover and use/map to a global/shared case ID (Might just be a GUID assigned at first notification, CVE is a partial example, vxref) +As a Participant , I want to discover and use/map to a global/shared case ID (Might just be a GUID assigned at first notification, CVE is a partial example, vxref) ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_031.md b/docs/topics/user_stories/story_2022_031.md similarity index 78% rename from doc/user_stories/Allowed/story_2022_031.md rename to docs/topics/user_stories/story_2022_031.md index ece9de71..bfde9c85 100644 --- a/doc/user_stories/Allowed/story_2022_031.md +++ b/docs/topics/user_stories/story_2022_031.md @@ -1,7 +1,7 @@ # User Story `2022_031` # -As a Finder, Reporter, Vendor, Coordinator, Other, I want to get from another Participant a list of cases I am involved in with them +As a Finder, Reporter, Vendor, Coordinator, Other, I want to get from another Participant a list of cases I am involved in with them ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_032.md b/docs/topics/user_stories/story_2022_032.md similarity index 64% rename from doc/user_stories/Allowed/story_2022_032.md rename to docs/topics/user_stories/story_2022_032.md index 5bbe10b7..ec6f74df 100644 --- a/doc/user_stories/Allowed/story_2022_032.md +++ b/docs/topics/user_stories/story_2022_032.md @@ -1,7 +1,7 @@ # User Story `2022_032` # - As a Reporter, Vendor, Coordinator, Other, I want to ask Participant A if Participant D is in a case. Operator may decide/policy, may be based on whether C and D are in the same case. "A" may or may not answer, that is their policy. Participant may decide/policy, may be based on whether C and D are in the same case. +As a Reporter, Vendor, Coordinator, Other, I want to ask Participant A if Participant D is in a case. Operator may decide/policy, may be based on whether C and D are in the same case. "A" may or may not answer, that is their policy. Participant may decide/policy, may be based on whether C and D are in the same case. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_033.md b/docs/topics/user_stories/story_2022_033.md similarity index 69% rename from doc/user_stories/Allowed/story_2022_033.md rename to docs/topics/user_stories/story_2022_033.md index dc9ab7dc..c0897bba 100644 --- a/doc/user_stories/Allowed/story_2022_033.md +++ b/docs/topics/user_stories/story_2022_033.md @@ -1,7 +1,7 @@ # User Story `2022_033` # -As a Finder, Reporter, Vendor, Coordinator, Other, I want to request/state that I do not want others to know I am in a case. Participant still gets to decide their policy. Covers researcher asking for anonymity. Vendor can ask not to be listed and operator can disagree/still list. +As a Finder, Reporter, Vendor, Coordinator, Other, I want to request/state that I do not want others to know I am in a case. Participant still gets to decide their policy. Covers researcher asking for anonymity. Vendor can ask not to be listed and operator can disagree/still list. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_034.md b/docs/topics/user_stories/story_2022_034.md similarity index 82% rename from doc/user_stories/Unsupported/story_2022_034.md rename to docs/topics/user_stories/story_2022_034.md index 76406aaa..e070bb23 100644 --- a/doc/user_stories/Unsupported/story_2022_034.md +++ b/docs/topics/user_stories/story_2022_034.md @@ -1,7 +1,7 @@ # User Story `2022_034` # -As a Participant I want to use my global/federated user ID to interact with other Participants +As a Participant I want to use my global/federated user ID to interact with other Participants ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_035.md b/docs/topics/user_stories/story_2022_035.md similarity index 79% rename from doc/user_stories/Unsupported/story_2022_035.md rename to docs/topics/user_stories/story_2022_035.md index 6b15504e..ce802103 100644 --- a/doc/user_stories/Unsupported/story_2022_035.md +++ b/docs/topics/user_stories/story_2022_035.md @@ -1,7 +1,7 @@ # User Story `2022_035` # -As a Participant I want to have confidence in the identity and group membership of others (and be willing and able to use others' groups) +As a Participant I want to have confidence in the identity and group membership of others (and be willing and able to use others' groups) ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_036.md b/docs/topics/user_stories/story_2022_036.md similarity index 81% rename from doc/user_stories/Unsupported/story_2022_036.md rename to docs/topics/user_stories/story_2022_036.md index 656b20fc..0358a5a1 100644 --- a/doc/user_stories/Unsupported/story_2022_036.md +++ b/docs/topics/user_stories/story_2022_036.md @@ -1,7 +1,7 @@ # User Story `2022_036` # -As a non-vendor Participant I want to determine how integrated authentication/authorization is in the CVD protocol +As a non-vendor Participant I want to determine how integrated authentication/authorization is in the CVD protocol ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_037.md b/docs/topics/user_stories/story_2022_037.md similarity index 85% rename from doc/user_stories/Out-of-scope/story_2022_037.md rename to docs/topics/user_stories/story_2022_037.md index 51cd04b5..2fca0f12 100644 --- a/doc/user_stories/Out-of-scope/story_2022_037.md +++ b/docs/topics/user_stories/story_2022_037.md @@ -1,7 +1,7 @@ # User Story `2022_037` # -As a vendor I want to publish vulnerability advisories +As a vendor I want to publish vulnerability advisories ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_038.md b/docs/topics/user_stories/story_2022_038.md similarity index 83% rename from doc/user_stories/Provided/story_2022_038.md rename to docs/topics/user_stories/story_2022_038.md index acf103e1..88aa529e 100644 --- a/doc/user_stories/Provided/story_2022_038.md +++ b/docs/topics/user_stories/story_2022_038.md @@ -1,7 +1,7 @@ # User Story `2022_038` # -As a vendor or coordinator, I want to receive vulnerability reports +As a vendor or coordinator, I want to receive vulnerability reports ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_039.md b/docs/topics/user_stories/story_2022_039.md similarity index 82% rename from doc/user_stories/Provided/story_2022_039.md rename to docs/topics/user_stories/story_2022_039.md index f98a4125..5c64c21a 100644 --- a/doc/user_stories/Provided/story_2022_039.md +++ b/docs/topics/user_stories/story_2022_039.md @@ -1,7 +1,7 @@ # User Story `2022_039` # -As a Participant I want to ask questions/generally communicate with another case Participant +As a Participant I want to ask questions/generally communicate with another case Participant ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_040.md b/docs/topics/user_stories/story_2022_040.md similarity index 82% rename from doc/user_stories/Allowed/story_2022_040.md rename to docs/topics/user_stories/story_2022_040.md index 61759c33..67bf0711 100644 --- a/doc/user_stories/Allowed/story_2022_040.md +++ b/docs/topics/user_stories/story_2022_040.md @@ -1,7 +1,7 @@ # User Story `2022_040` # -As a Participant I want to ask questions/generally communicate with another case Participant unicast/point-to-point +As a Participant I want to ask questions/generally communicate with another case Participant unicast/point-to-point ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_041.md b/docs/topics/user_stories/story_2022_041.md similarity index 80% rename from doc/user_stories/Provided/story_2022_041.md rename to docs/topics/user_stories/story_2022_041.md index c8da28dc..4864e367 100644 --- a/doc/user_stories/Provided/story_2022_041.md +++ b/docs/topics/user_stories/story_2022_041.md @@ -1,7 +1,7 @@ # User Story `2022_041` # -As a Participant I want to ask questions/generally communicate with all the Participants in a case (broadcast) +As a Participant I want to ask questions/generally communicate with all the Participants in a case (broadcast) ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_042.md b/docs/topics/user_stories/story_2022_042.md similarity index 84% rename from doc/user_stories/Allowed/story_2022_042.md rename to docs/topics/user_stories/story_2022_042.md index da6d1b88..ba23ed4c 100644 --- a/doc/user_stories/Allowed/story_2022_042.md +++ b/docs/topics/user_stories/story_2022_042.md @@ -1,7 +1,7 @@ # User Story `2022_042` # -As a Participant I want to ask questions/generally communicate with a subset of case Participants +As a Participant I want to ask questions/generally communicate with a subset of case Participants ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_043.md b/docs/topics/user_stories/story_2022_043.md similarity index 87% rename from doc/user_stories/Provided/story_2022_043.md rename to docs/topics/user_stories/story_2022_043.md index 5a110dde..14389266 100644 --- a/doc/user_stories/Provided/story_2022_043.md +++ b/docs/topics/user_stories/story_2022_043.md @@ -1,7 +1,7 @@ # User Story `2022_043` # -As a Participant, I want to communicate in a common case channel +As a Participant, I want to communicate in a common case channel ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_044.md b/docs/topics/user_stories/story_2022_044.md similarity index 87% rename from doc/user_stories/Allowed/story_2022_044.md rename to docs/topics/user_stories/story_2022_044.md index 9fd88305..bd7a8160 100644 --- a/doc/user_stories/Allowed/story_2022_044.md +++ b/docs/topics/user_stories/story_2022_044.md @@ -1,7 +1,7 @@ # User Story `2022_044` # -As a Participant I want to communicate with selected case Participants +As a Participant I want to communicate with selected case Participants ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_045.md b/docs/topics/user_stories/story_2022_045.md similarity index 85% rename from doc/user_stories/Allowed/story_2022_045.md rename to docs/topics/user_stories/story_2022_045.md index d29067e5..f927b169 100644 --- a/doc/user_stories/Allowed/story_2022_045.md +++ b/docs/topics/user_stories/story_2022_045.md @@ -1,7 +1,7 @@ # User Story `2022_045` # -As a Participant, I want to produce a shared verified public record of case activity +As a Participant, I want to produce a shared verified public record of case activity ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_046.md b/docs/topics/user_stories/story_2022_046.md similarity index 86% rename from doc/user_stories/Unsupported/story_2022_046.md rename to docs/topics/user_stories/story_2022_046.md index 60c1ad8c..d1724baf 100644 --- a/doc/user_stories/Unsupported/story_2022_046.md +++ b/docs/topics/user_stories/story_2022_046.md @@ -1,7 +1,7 @@ # User Story `2022_046` # -As a Participant, I want the case to have a leader (global case owner, CVD leader) +As a Participant, I want the case to have a leader (global case owner, CVD leader) ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_047.md b/docs/topics/user_stories/story_2022_047.md similarity index 87% rename from doc/user_stories/Unsupported/story_2022_047.md rename to docs/topics/user_stories/story_2022_047.md index 963480b8..c9b250e8 100644 --- a/doc/user_stories/Unsupported/story_2022_047.md +++ b/docs/topics/user_stories/story_2022_047.md @@ -1,7 +1,7 @@ # User Story `2022_047` # -As a Participant, I want to propose a case leader, possibly myself +As a Participant, I want to propose a case leader, possibly myself ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_048.md b/docs/topics/user_stories/story_2022_048.md similarity index 88% rename from doc/user_stories/Unsupported/story_2022_048.md rename to docs/topics/user_stories/story_2022_048.md index dc66551f..6938525a 100644 --- a/doc/user_stories/Unsupported/story_2022_048.md +++ b/docs/topics/user_stories/story_2022_048.md @@ -1,7 +1,7 @@ # User Story `2022_048` # -As a Participant, I want to vote/accept a proposed case leader +As a Participant, I want to vote/accept a proposed case leader ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_049.md b/docs/topics/user_stories/story_2022_049.md similarity index 87% rename from doc/user_stories/Unsupported/story_2022_049.md rename to docs/topics/user_stories/story_2022_049.md index cb60c1b8..1b6fa858 100644 --- a/doc/user_stories/Unsupported/story_2022_049.md +++ b/docs/topics/user_stories/story_2022_049.md @@ -1,7 +1,7 @@ # User Story `2022_049` # -As a Participant I want to announce the case leader to all Participants +As a Participant I want to announce the case leader to all Participants ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_050.md b/docs/topics/user_stories/story_2022_050.md similarity index 86% rename from doc/user_stories/Unsupported/story_2022_050.md rename to docs/topics/user_stories/story_2022_050.md index 91574f2e..32c0051a 100644 --- a/doc/user_stories/Unsupported/story_2022_050.md +++ b/docs/topics/user_stories/story_2022_050.md @@ -1,7 +1,7 @@ # User Story `2022_050` # -As a Participant I want to transfer case leadership to a different Participant +As a Participant I want to transfer case leadership to a different Participant ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_051.md b/docs/topics/user_stories/story_2022_051.md similarity index 80% rename from doc/user_stories/Unsupported/story_2022_051.md rename to docs/topics/user_stories/story_2022_051.md index 7767ec9f..bae475da 100644 --- a/doc/user_stories/Unsupported/story_2022_051.md +++ b/docs/topics/user_stories/story_2022_051.md @@ -1,7 +1,7 @@ # User Story `2022_051` # -As a Participant, I want to depose (or vote down?) a case leader, possibly myself (step down), possibly requiring a suggestion of a replacement +As a Participant, I want to depose (or vote down?) a case leader, possibly myself (step down), possibly requiring a suggestion of a replacement ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_052.md b/docs/topics/user_stories/story_2022_052.md similarity index 86% rename from doc/user_stories/Allowed/story_2022_052.md rename to docs/topics/user_stories/story_2022_052.md index 8a01bfba..548547eb 100644 --- a/doc/user_stories/Allowed/story_2022_052.md +++ b/docs/topics/user_stories/story_2022_052.md @@ -1,7 +1,7 @@ # User Story `2022_052` # -As a Participant I want to add (declare and notify others) new Participants to a case +As a Participant I want to add (declare and notify others) new Participants to a case ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_053.md b/docs/topics/user_stories/story_2022_053.md similarity index 87% rename from doc/user_stories/Allowed/story_2022_053.md rename to docs/topics/user_stories/story_2022_053.md index 7e05ab6c..ca22f15a 100644 --- a/doc/user_stories/Allowed/story_2022_053.md +++ b/docs/topics/user_stories/story_2022_053.md @@ -1,7 +1,7 @@ # User Story `2022_053` # -As a Participant, I want to propose new Participants to a case +As a Participant, I want to propose new Participants to a case ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_054.md b/docs/topics/user_stories/story_2022_054.md similarity index 88% rename from doc/user_stories/Out-of-scope/story_2022_054.md rename to docs/topics/user_stories/story_2022_054.md index f3dc4fc6..559de3d9 100644 --- a/doc/user_stories/Out-of-scope/story_2022_054.md +++ b/docs/topics/user_stories/story_2022_054.md @@ -1,7 +1,7 @@ # User Story `2022_054` # -As a Participant I want to vote/accept new Participants to a case +As a Participant I want to vote/accept new Participants to a case ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_055.md b/docs/topics/user_stories/story_2022_055.md similarity index 84% rename from doc/user_stories/Allowed/story_2022_055.md rename to docs/topics/user_stories/story_2022_055.md index 140866ea..727ba35e 100644 --- a/doc/user_stories/Allowed/story_2022_055.md +++ b/docs/topics/user_stories/story_2022_055.md @@ -1,7 +1,7 @@ # User Story `2022_055` # -As a Participant, I want to state that I paid or received a bounty +As a Participant, I want to state that I paid or received a bounty ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_056.md b/docs/topics/user_stories/story_2022_056.md similarity index 83% rename from doc/user_stories/Allowed/story_2022_056.md rename to docs/topics/user_stories/story_2022_056.md index c88a7a02..36ab750d 100644 --- a/doc/user_stories/Allowed/story_2022_056.md +++ b/docs/topics/user_stories/story_2022_056.md @@ -1,7 +1,7 @@ # User Story `2022_056` # -As a Participant, I want to ask if another Participant paid a reporter +As a Participant, I want to ask if another Participant paid a reporter ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_057.md b/docs/topics/user_stories/story_2022_057.md similarity index 85% rename from doc/user_stories/Allowed/story_2022_057.md rename to docs/topics/user_stories/story_2022_057.md index 044765e0..eca554d0 100644 --- a/doc/user_stories/Allowed/story_2022_057.md +++ b/docs/topics/user_stories/story_2022_057.md @@ -1,7 +1,7 @@ # User Story `2022_057` # -As a Participant, I want to ask a reporter if they were paid +As a Participant, I want to ask a reporter if they were paid ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_058.md b/docs/topics/user_stories/story_2022_058.md similarity index 86% rename from doc/user_stories/Allowed/story_2022_058.md rename to docs/topics/user_stories/story_2022_058.md index 63d01120..ed42a439 100644 --- a/doc/user_stories/Allowed/story_2022_058.md +++ b/docs/topics/user_stories/story_2022_058.md @@ -1,7 +1,7 @@ # User Story `2022_058` # -As a Participant I want to share a draft advisory with others +As a Participant I want to share a draft advisory with others ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_059.md b/docs/topics/user_stories/story_2022_059.md similarity index 82% rename from doc/user_stories/Allowed/story_2022_059.md rename to docs/topics/user_stories/story_2022_059.md index 9d27cdd2..20ed807a 100644 --- a/doc/user_stories/Allowed/story_2022_059.md +++ b/docs/topics/user_stories/story_2022_059.md @@ -1,7 +1,7 @@ # User Story `2022_059` # -As a Participant I want to share a draft advisory with others and request feedback (including status) +As a Participant I want to share a draft advisory with others and request feedback (including status) ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_060.md b/docs/topics/user_stories/story_2022_060.md similarity index 85% rename from doc/user_stories/Allowed/story_2022_060.md rename to docs/topics/user_stories/story_2022_060.md index 71bf75e0..bb499730 100644 --- a/doc/user_stories/Allowed/story_2022_060.md +++ b/docs/topics/user_stories/story_2022_060.md @@ -1,7 +1,7 @@ # User Story `2022_060` # -As a Participant I want to request advisory (draft) from a Participant +As a Participant I want to request advisory (draft) from a Participant ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_061.md b/docs/topics/user_stories/story_2022_061.md similarity index 85% rename from doc/user_stories/Provided/story_2022_061.md rename to docs/topics/user_stories/story_2022_061.md index c02ce746..dfdbbabb 100644 --- a/doc/user_stories/Provided/story_2022_061.md +++ b/docs/topics/user_stories/story_2022_061.md @@ -1,7 +1,7 @@ # User Story `2022_061` # -As a Participant, I want to request someone else’s (vendor) status so I can note changes in others status +As a Participant, I want to request someone else’s (vendor) status so I can note changes in others status ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_062.md b/docs/topics/user_stories/story_2022_062.md similarity index 87% rename from doc/user_stories/Provided/story_2022_062.md rename to docs/topics/user_stories/story_2022_062.md index ca4e406b..7ee473c3 100644 --- a/doc/user_stories/Provided/story_2022_062.md +++ b/docs/topics/user_stories/story_2022_062.md @@ -1,7 +1,7 @@ # User Story `2022_062` # -As a Participant, I want to state my status so others are aware of it. +As a Participant, I want to state my status so others are aware of it. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_063.md b/docs/topics/user_stories/story_2022_063.md similarity index 86% rename from doc/user_stories/Allowed/story_2022_063.md rename to docs/topics/user_stories/story_2022_063.md index db1f98ac..d80bc85b 100644 --- a/doc/user_stories/Allowed/story_2022_063.md +++ b/docs/topics/user_stories/story_2022_063.md @@ -1,7 +1,7 @@ # User Story `2022_063` # -As a Participant, I want to include a non-vendor role Participant in a case +As a Participant, I want to include a non-vendor role Participant in a case ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_064.md b/docs/topics/user_stories/story_2022_064.md similarity index 80% rename from doc/user_stories/Allowed/story_2022_064.md rename to docs/topics/user_stories/story_2022_064.md index 2d95e66d..0d432d1f 100644 --- a/doc/user_stories/Allowed/story_2022_064.md +++ b/docs/topics/user_stories/story_2022_064.md @@ -1,7 +1,7 @@ # User Story `2022_064` # -As a Participant, I want to include the Government (some/any part, could include regulator) so that they may participate in the case. +As a Participant, I want to include the Government (some/any part, could include regulator) so that they may participate in the case. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_065.md b/docs/topics/user_stories/story_2022_065.md similarity index 83% rename from doc/user_stories/Allowed/story_2022_065.md rename to docs/topics/user_stories/story_2022_065.md index e400ba3e..7208bfde 100644 --- a/doc/user_stories/Allowed/story_2022_065.md +++ b/docs/topics/user_stories/story_2022_065.md @@ -1,7 +1,7 @@ # User Story `2022_065` # -As a Participant, I want to include the Industry/trade group so that they may participate in the case. +As a Participant, I want to include the Industry/trade group so that they may participate in the case. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_066.md b/docs/topics/user_stories/story_2022_066.md similarity index 88% rename from doc/user_stories/Allowed/story_2022_066.md rename to docs/topics/user_stories/story_2022_066.md index 155e69ce..b7314828 100644 --- a/doc/user_stories/Allowed/story_2022_066.md +++ b/docs/topics/user_stories/story_2022_066.md @@ -1,7 +1,7 @@ # User Story `2022_066` # -As a Participant, I want to stop participating in the case. +As a Participant, I want to stop participating in the case. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_067.md b/docs/topics/user_stories/story_2022_067.md similarity index 83% rename from doc/user_stories/Allowed/story_2022_067.md rename to docs/topics/user_stories/story_2022_067.md index 9cdef0f1..2d2be61c 100644 --- a/doc/user_stories/Allowed/story_2022_067.md +++ b/docs/topics/user_stories/story_2022_067.md @@ -1,7 +1,7 @@ # User Story `2022_067` # -As a Participant, I want to stop participating in the case and inform others that I am no longer participating. +As a Participant, I want to stop participating in the case and inform others that I am no longer participating. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_068.md b/docs/topics/user_stories/story_2022_068.md similarity index 83% rename from doc/user_stories/Allowed/story_2022_068.md rename to docs/topics/user_stories/story_2022_068.md index b29b379e..73b4764c 100644 --- a/doc/user_stories/Allowed/story_2022_068.md +++ b/docs/topics/user_stories/story_2022_068.md @@ -1,7 +1,7 @@ # User Story `2022_068` # -As a Participant, I want to stop participating in the case and no longer will receive or reply to forwarded queries. +As a Participant, I want to stop participating in the case and no longer will receive or reply to forwarded queries. ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_069.md b/docs/topics/user_stories/story_2022_069.md similarity index 75% rename from doc/user_stories/Provided/story_2022_069.md rename to docs/topics/user_stories/story_2022_069.md index 21c3c53c..fbef5269 100644 --- a/doc/user_stories/Provided/story_2022_069.md +++ b/docs/topics/user_stories/story_2022_069.md @@ -1,7 +1,7 @@ # User Story `2022_069` # -As a Participant, I want to tell others that I published so that they can know about the vulnerability and the mitigation or remediation. +As a Participant, I want to tell others that I published so that they can know about the vulnerability and the mitigation or remediation. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_070.md b/docs/topics/user_stories/story_2022_070.md similarity index 79% rename from doc/user_stories/Allowed/story_2022_070.md rename to docs/topics/user_stories/story_2022_070.md index cfebddad..005a5634 100644 --- a/doc/user_stories/Allowed/story_2022_070.md +++ b/docs/topics/user_stories/story_2022_070.md @@ -1,7 +1,7 @@ # User Story `2022_070` # -As a Participant, I want to convey how information I provide can be used so that others can apply the mitigation or remediation correctly. +As a Participant, I want to convey how information I provide can be used so that others can apply the mitigation or remediation correctly. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_071.md b/docs/topics/user_stories/story_2022_071.md similarity index 80% rename from doc/user_stories/Unsupported/story_2022_071.md rename to docs/topics/user_stories/story_2022_071.md index 4fe603f1..c8c325df 100644 --- a/doc/user_stories/Unsupported/story_2022_071.md +++ b/docs/topics/user_stories/story_2022_071.md @@ -1,7 +1,7 @@ # User Story `2022_071` # -As a Participant, I want to convey how information I provide can be used while obeying the TLP restrictions so that others can apply the mitigation or remediation correctly. +As a Participant, I want to convey how information I provide can be used while obeying the TLP restrictions so that others can apply the mitigation or remediation correctly. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_072.md b/docs/topics/user_stories/story_2022_072.md similarity index 79% rename from doc/user_stories/Unsupported/story_2022_072.md rename to docs/topics/user_stories/story_2022_072.md index 06f0e1a5..a6365e2b 100644 --- a/doc/user_stories/Unsupported/story_2022_072.md +++ b/docs/topics/user_stories/story_2022_072.md @@ -1,7 +1,7 @@ # User Story `2022_072` # -As a Participant, I want to convey what restricted information or degree of restriction I will accept so that I won't be accused of mishandling restricted information. +As a Participant, I want to convey what restricted information or degree of restriction I will accept so that I won't be accused of mishandling restricted information. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_073.md b/docs/topics/user_stories/story_2022_073.md similarity index 78% rename from doc/user_stories/Unsupported/story_2022_073.md rename to docs/topics/user_stories/story_2022_073.md index 03722eb3..57f44340 100644 --- a/doc/user_stories/Unsupported/story_2022_073.md +++ b/docs/topics/user_stories/story_2022_073.md @@ -1,7 +1,7 @@ # User Story `2022_073` # -As a Participant, I want to convey what TLP restricted information or degree of restriction I will accept so that I won't be accused of mishandling TLP restricted information. +As a Participant, I want to convey what TLP restricted information or degree of restriction I will accept so that I won't be accused of mishandling TLP restricted information. ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_074.md b/docs/topics/user_stories/story_2022_074.md similarity index 81% rename from doc/user_stories/Provided/story_2022_074.md rename to docs/topics/user_stories/story_2022_074.md index 84f4dc45..951b011f 100644 --- a/doc/user_stories/Provided/story_2022_074.md +++ b/docs/topics/user_stories/story_2022_074.md @@ -1,7 +1,7 @@ # User Story `2022_074` # -As a Participant, I want to keep track of events and timelines so that I have a complete report and don't miss a deadline. +As a Participant, I want to keep track of events and timelines so that I have a complete report and don't miss a deadline. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_075.md b/docs/topics/user_stories/story_2022_075.md similarity index 81% rename from doc/user_stories/Allowed/story_2022_075.md rename to docs/topics/user_stories/story_2022_075.md index 716dd1cc..69f5a765 100644 --- a/doc/user_stories/Allowed/story_2022_075.md +++ b/docs/topics/user_stories/story_2022_075.md @@ -1,7 +1,7 @@ # User Story `2022_075` # -As a Participant, I want to see response times/states of other Participants so that I can be prepared for the next state in the CVD process. +As a Participant, I want to see response times/states of other Participants so that I can be prepared for the next state in the CVD process. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_076.md b/docs/topics/user_stories/story_2022_076.md similarity index 90% rename from doc/user_stories/Allowed/story_2022_076.md rename to docs/topics/user_stories/story_2022_076.md index 6d10ced5..cdbbc824 100644 --- a/doc/user_stories/Allowed/story_2022_076.md +++ b/docs/topics/user_stories/story_2022_076.md @@ -1,7 +1,7 @@ # User Story `2022_076` # -As a VDP operator, I want the CVD protocol to also support VDP +As a VDP operator, I want the CVD protocol to also support VDP ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_077.md b/docs/topics/user_stories/story_2022_077.md similarity index 76% rename from doc/user_stories/Provided/story_2022_077.md rename to docs/topics/user_stories/story_2022_077.md index 9f7eadae..af9e4b01 100644 --- a/doc/user_stories/Provided/story_2022_077.md +++ b/docs/topics/user_stories/story_2022_077.md @@ -1,7 +1,7 @@ # User Story `2022_077` # -As a Participant, I want to be able to ask further questions about a report, to ensure I fully understand the vulnerability and mitigation or remediation options. +As a Participant, I want to be able to ask further questions about a report, to ensure I fully understand the vulnerability and mitigation or remediation options. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_078.md b/docs/topics/user_stories/story_2022_078.md similarity index 83% rename from doc/user_stories/Allowed/story_2022_078.md rename to docs/topics/user_stories/story_2022_078.md index d203adf9..c33f7a36 100644 --- a/doc/user_stories/Allowed/story_2022_078.md +++ b/docs/topics/user_stories/story_2022_078.md @@ -1,7 +1,7 @@ # User Story `2022_078` # -As a coordinator, I want to drive better (shorter?) embargo timelines, to ensure they are feasible. +As a coordinator, I want to drive better (shorter?) embargo timelines, to ensure they are feasible. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_079.md b/docs/topics/user_stories/story_2022_079.md similarity index 75% rename from doc/user_stories/Allowed/story_2022_079.md rename to docs/topics/user_stories/story_2022_079.md index 8ae203a5..ca393b11 100644 --- a/doc/user_stories/Allowed/story_2022_079.md +++ b/docs/topics/user_stories/story_2022_079.md @@ -1,7 +1,7 @@ # User Story `2022_079` # -As a coordinator, I want to collect and optimize embargo timelines of all Participants (probably duplicate of 103) to ensure the timelines are feasible. +As a coordinator, I want to collect and optimize embargo timelines of all Participants (probably duplicate of 103) to ensure the timelines are feasible. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_080.md b/docs/topics/user_stories/story_2022_080.md similarity index 86% rename from doc/user_stories/Allowed/story_2022_080.md rename to docs/topics/user_stories/story_2022_080.md index a6d609ee..1df20d6e 100644 --- a/doc/user_stories/Allowed/story_2022_080.md +++ b/docs/topics/user_stories/story_2022_080.md @@ -1,7 +1,7 @@ # User Story `2022_080` # -As a Participant, I want to publicly disclose sooner than others but minimize their (the others) exposure/risk +As a Participant, I want to publicly disclose sooner than others but minimize their (the others) exposure/risk ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_081.md b/docs/topics/user_stories/story_2022_081.md similarity index 81% rename from doc/user_stories/Provided/story_2022_081.md rename to docs/topics/user_stories/story_2022_081.md index f20419da..92b724df 100644 --- a/doc/user_stories/Provided/story_2022_081.md +++ b/docs/topics/user_stories/story_2022_081.md @@ -1,7 +1,7 @@ # User Story `2022_081` # -As a Participant I want to communicate important public state change message/information with all Participants. +As a Participant I want to communicate important public state change message/information with all Participants. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_082.md b/docs/topics/user_stories/story_2022_082.md similarity index 76% rename from doc/user_stories/Allowed/story_2022_082.md rename to docs/topics/user_stories/story_2022_082.md index 78f5e18d..ba6b6ead 100644 --- a/doc/user_stories/Allowed/story_2022_082.md +++ b/docs/topics/user_stories/story_2022_082.md @@ -1,7 +1,7 @@ # User Story `2022_082` # -As a non-vendor Participant I want to be informed of CVD in order to perform activities like risk assessment, mitigation, verify mitigation, not be surprised, prepare messaging, etc. +As a non-vendor Participant I want to be informed of CVD in order to perform activities like risk assessment, mitigation, verify mitigation, not be surprised, prepare messaging, etc. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_083.md b/docs/topics/user_stories/story_2022_083.md similarity index 82% rename from doc/user_stories/Allowed/story_2022_083.md rename to docs/topics/user_stories/story_2022_083.md index 125aec90..57eb2488 100644 --- a/doc/user_stories/Allowed/story_2022_083.md +++ b/docs/topics/user_stories/story_2022_083.md @@ -1,7 +1,7 @@ # User Story `2022_083` # -As a Participant, I want to contribute to the creation, modification and publication of an advisory. +As a Participant, I want to contribute to the creation, modification and publication of an advisory. ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_084.md b/docs/topics/user_stories/story_2022_084.md similarity index 84% rename from doc/user_stories/Out-of-scope/story_2022_084.md rename to docs/topics/user_stories/story_2022_084.md index 4f76767e..25a04a99 100644 --- a/doc/user_stories/Out-of-scope/story_2022_084.md +++ b/docs/topics/user_stories/story_2022_084.md @@ -1,7 +1,7 @@ # User Story `2022_084` # -As a vendor I want to reward the reporter by paying a bounty. +As a vendor I want to reward the reporter by paying a bounty. ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_085.md b/docs/topics/user_stories/story_2022_085.md similarity index 86% rename from doc/user_stories/Out-of-scope/story_2022_085.md rename to docs/topics/user_stories/story_2022_085.md index 77ee528a..2930fd93 100644 --- a/doc/user_stories/Out-of-scope/story_2022_085.md +++ b/docs/topics/user_stories/story_2022_085.md @@ -1,7 +1,7 @@ # User Story `2022_085` # -As a reporter I want to be rewarded with a bounty. +As a reporter I want to be rewarded with a bounty. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_086.md b/docs/topics/user_stories/story_2022_086.md similarity index 78% rename from doc/user_stories/Allowed/story_2022_086.md rename to docs/topics/user_stories/story_2022_086.md index 3b1072cd..d24728ab 100644 --- a/doc/user_stories/Allowed/story_2022_086.md +++ b/docs/topics/user_stories/story_2022_086.md @@ -1,7 +1,7 @@ # User Story `2022_086` # -As a Participant I will prioritize my response to requests for information or action so that I contribute to a risk-minimizing CVD process and outcome +As a Participant I will prioritize my response to requests for information or action so that I contribute to a risk-minimizing CVD process and outcome ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_087.md b/docs/topics/user_stories/story_2022_087.md similarity index 79% rename from doc/user_stories/Allowed/story_2022_087.md rename to docs/topics/user_stories/story_2022_087.md index ca554391..0954e49b 100644 --- a/doc/user_stories/Allowed/story_2022_087.md +++ b/docs/topics/user_stories/story_2022_087.md @@ -1,7 +1,7 @@ # User Story `2022_087` # -As a Participant I want to share and receive information I can use to prioritize my work regarding the vulnerability report. +As a Participant I want to share and receive information I can use to prioritize my work regarding the vulnerability report. ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_088.md b/docs/topics/user_stories/story_2022_088.md similarity index 82% rename from doc/user_stories/Provided/story_2022_088.md rename to docs/topics/user_stories/story_2022_088.md index fbc6953c..e3dcf8cf 100644 --- a/doc/user_stories/Provided/story_2022_088.md +++ b/docs/topics/user_stories/story_2022_088.md @@ -1,7 +1,7 @@ # User Story `2022_088` # -As a Participant, I want to avoid missteps by maintaining knowledge of the state of case and what options are available. +As a Participant, I want to avoid missteps by maintaining knowledge of the state of case and what options are available. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_089.md b/docs/topics/user_stories/story_2022_089.md similarity index 80% rename from doc/user_stories/Unsupported/story_2022_089.md rename to docs/topics/user_stories/story_2022_089.md index 46b55812..1b434678 100644 --- a/doc/user_stories/Unsupported/story_2022_089.md +++ b/docs/topics/user_stories/story_2022_089.md @@ -1,7 +1,7 @@ # User Story `2022_089` # -As a Participant I want a mechanism which with assure me of the authentication and verify integrity of messages. +As a Participant I want a mechanism which with assure me of the authentication and verify integrity of messages. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_090.md b/docs/topics/user_stories/story_2022_090.md similarity index 81% rename from doc/user_stories/Unsupported/story_2022_090.md rename to docs/topics/user_stories/story_2022_090.md index 925741ba..303ef8ac 100644 --- a/doc/user_stories/Unsupported/story_2022_090.md +++ b/docs/topics/user_stories/story_2022_090.md @@ -1,7 +1,7 @@ # User Story `2022_090` # -As a Participant we need a mechanism which will ensure the appropriate level of authentication of all Participants +As a Participant we need a mechanism which will ensure the appropriate level of authentication of all Participants ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_091.md b/docs/topics/user_stories/story_2022_091.md similarity index 81% rename from doc/user_stories/Unsupported/story_2022_091.md rename to docs/topics/user_stories/story_2022_091.md index e2bef5d9..367b0957 100644 --- a/doc/user_stories/Unsupported/story_2022_091.md +++ b/docs/topics/user_stories/story_2022_091.md @@ -1,7 +1,7 @@ # User Story `2022_091` # -As a Participant we need a mechanism which will ensure the confidential transport and storage of information. +As a Participant we need a mechanism which will ensure the confidential transport and storage of information. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_092.md b/docs/topics/user_stories/story_2022_092.md similarity index 83% rename from doc/user_stories/Allowed/story_2022_092.md rename to docs/topics/user_stories/story_2022_092.md index aa5a7d51..78abb9c8 100644 --- a/doc/user_stories/Allowed/story_2022_092.md +++ b/docs/topics/user_stories/story_2022_092.md @@ -1,7 +1,7 @@ # User Story `2022_092` # -As a Participant, I want to know who else is participating in a case to ensure I don't void an embargo. +As a Participant, I want to know who else is participating in a case to ensure I don't void an embargo. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_093.md b/docs/topics/user_stories/story_2022_093.md similarity index 82% rename from doc/user_stories/Allowed/story_2022_093.md rename to docs/topics/user_stories/story_2022_093.md index 84742bf2..f154552f 100644 --- a/doc/user_stories/Allowed/story_2022_093.md +++ b/docs/topics/user_stories/story_2022_093.md @@ -1,7 +1,7 @@ # User Story `2022_093` # -As a Participant, in an effort to ensure the Participant list is complete I want to know who else is participating. +As a Participant, in an effort to ensure the Participant list is complete I want to know who else is participating. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_094.md b/docs/topics/user_stories/story_2022_094.md similarity index 82% rename from doc/user_stories/Unsupported/story_2022_094.md rename to docs/topics/user_stories/story_2022_094.md index 38bcf94a..d6d30d75 100644 --- a/doc/user_stories/Unsupported/story_2022_094.md +++ b/docs/topics/user_stories/story_2022_094.md @@ -1,7 +1,7 @@ # User Story `2022_094` # -As a Participant, I want to assess reputation of others so that I can decide to engage again +As a Participant, I want to assess reputation of others so that I can decide to engage again ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_095.md b/docs/topics/user_stories/story_2022_095.md similarity index 80% rename from doc/user_stories/Unsupported/story_2022_095.md rename to docs/topics/user_stories/story_2022_095.md index 9b909f21..7b05508f 100644 --- a/doc/user_stories/Unsupported/story_2022_095.md +++ b/docs/topics/user_stories/story_2022_095.md @@ -1,7 +1,7 @@ # User Story `2022_095` # -As a Participant, I want to provide evidence of/document my reputation to others so they can decide to engage with me +As a Participant, I want to provide evidence of/document my reputation to others so they can decide to engage with me ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_096.md b/docs/topics/user_stories/story_2022_096.md similarity index 81% rename from doc/user_stories/Unsupported/story_2022_096.md rename to docs/topics/user_stories/story_2022_096.md index b671e20a..71f5f995 100644 --- a/doc/user_stories/Unsupported/story_2022_096.md +++ b/docs/topics/user_stories/story_2022_096.md @@ -1,7 +1,7 @@ # User Story `2022_096` # -As a Participant, I want to record/log my trust in/reputation of others so I can decide to engage again +As a Participant, I want to record/log my trust in/reputation of others so I can decide to engage again ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_097.md b/docs/topics/user_stories/story_2022_097.md similarity index 73% rename from doc/user_stories/Unsupported/story_2022_097.md rename to docs/topics/user_stories/story_2022_097.md index 4cdf2b6c..181458a1 100644 --- a/doc/user_stories/Unsupported/story_2022_097.md +++ b/docs/topics/user_stories/story_2022_097.md @@ -1,7 +1,7 @@ # User Story `2022_097` # -As a Participant I want to organize (create, define) my own groups of other Participants so that I can communicate successfully, participate fully and understand their requirements. +As a Participant I want to organize (create, define) my own groups of other Participants so that I can communicate successfully, participate fully and understand their requirements. ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_098.md b/docs/topics/user_stories/story_2022_098.md similarity index 84% rename from doc/user_stories/Provided/story_2022_098.md rename to docs/topics/user_stories/story_2022_098.md index 29fd8f42..4e557d6b 100644 --- a/doc/user_stories/Provided/story_2022_098.md +++ b/docs/topics/user_stories/story_2022_098.md @@ -1,7 +1,7 @@ # User Story `2022_098` # -As a Participant I want to communicate with all Participants associated with this case. +As a Participant I want to communicate with all Participants associated with this case. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_099.md b/docs/topics/user_stories/story_2022_099.md similarity index 77% rename from doc/user_stories/Allowed/story_2022_099.md rename to docs/topics/user_stories/story_2022_099.md index c6aa768d..cb84485e 100644 --- a/doc/user_stories/Allowed/story_2022_099.md +++ b/docs/topics/user_stories/story_2022_099.md @@ -1,7 +1,7 @@ # User Story `2022_099` # -As a Participant I want to communicate with non-vendor Participants, primarily other defenders, providers, CSIRTs, regulators, etc., important information. +As a Participant I want to communicate with non-vendor Participants, primarily other defenders, providers, CSIRTs, regulators, etc., important information. ## Notes ## diff --git a/doc/user_stories/Unsupported/story_2022_100.md b/docs/topics/user_stories/story_2022_100.md similarity index 76% rename from doc/user_stories/Unsupported/story_2022_100.md rename to docs/topics/user_stories/story_2022_100.md index de215a0f..3e55558f 100644 --- a/doc/user_stories/Unsupported/story_2022_100.md +++ b/docs/topics/user_stories/story_2022_100.md @@ -1,7 +1,7 @@ # User Story `2022_100` # -As a vendor, coordinator or other I want to be included on a distribution list for advisories which must be clearly identified as public or non-public +As a vendor, coordinator or other I want to be included on a distribution list for advisories which must be clearly identified as public or non-public ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_101.md b/docs/topics/user_stories/story_2022_101.md similarity index 79% rename from doc/user_stories/Provided/story_2022_101.md rename to docs/topics/user_stories/story_2022_101.md index 8c2b11fe..781f82ed 100644 --- a/doc/user_stories/Provided/story_2022_101.md +++ b/docs/topics/user_stories/story_2022_101.md @@ -1,7 +1,7 @@ # User Story `2022_101` # -As a Coordinator I want to validate the report received from Reporter or Finder before deciding CERT's active involvement for the potential Case +As a Coordinator I want to validate the report received from Reporter or Finder before deciding CERT's active involvement for the potential Case ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_102.md b/docs/topics/user_stories/story_2022_102.md similarity index 74% rename from doc/user_stories/Allowed/story_2022_102.md rename to docs/topics/user_stories/story_2022_102.md index d6043ce0..178ed76f 100644 --- a/doc/user_stories/Allowed/story_2022_102.md +++ b/docs/topics/user_stories/story_2022_102.md @@ -1,7 +1,7 @@ # User Story `2022_102` # -As a Coordinator I want to collect artifacts such as PoC Proof-of-Concept exploit, code control flow analysis (static or dynamic) that can enabled our validation of the security flaw being reported +As a Coordinator I want to collect artifacts such as PoC Proof-of-Concept exploit, code control flow analysis (static or dynamic) that can enabled our validation of the security flaw being reported ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_103.md b/docs/topics/user_stories/story_2022_103.md similarity index 80% rename from doc/user_stories/Allowed/story_2022_103.md rename to docs/topics/user_stories/story_2022_103.md index a1ebe70d..535adea2 100644 --- a/doc/user_stories/Allowed/story_2022_103.md +++ b/docs/topics/user_stories/story_2022_103.md @@ -1,7 +1,7 @@ # User Story `2022_103` # -As a Participant, I want to give the Finder/Reporter an opportunity to confirm that the fix addresses the vulnerability prior to publication. +As a Participant, I want to give the Finder/Reporter an opportunity to confirm that the fix addresses the vulnerability prior to publication. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_104.md b/docs/topics/user_stories/story_2022_104.md similarity index 86% rename from doc/user_stories/Allowed/story_2022_104.md rename to docs/topics/user_stories/story_2022_104.md index 797433ec..d3bca8c4 100644 --- a/doc/user_stories/Allowed/story_2022_104.md +++ b/docs/topics/user_stories/story_2022_104.md @@ -1,7 +1,7 @@ # User Story `2022_104` # -As a Participant, I want to address multiple related vulnerabilities across multiple vendors simultaneously. +As a Participant, I want to address multiple related vulnerabilities across multiple vendors simultaneously. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_105.md b/docs/topics/user_stories/story_2022_105.md similarity index 78% rename from doc/user_stories/Allowed/story_2022_105.md rename to docs/topics/user_stories/story_2022_105.md index 66baa994..c5e6cd00 100644 --- a/doc/user_stories/Allowed/story_2022_105.md +++ b/docs/topics/user_stories/story_2022_105.md @@ -1,7 +1,7 @@ # User Story `2022_105` # -As a Vendor, I want to address the same vulnerability in multiple products but on different timelines so that I can avoid delaying the delivery of a ready fix to a subset of my user base. +As a Vendor, I want to address the same vulnerability in multiple products but on different timelines so that I can avoid delaying the delivery of a ready fix to a subset of my user base. ## Notes ## diff --git a/doc/user_stories/Provided/story_2022_106.md b/docs/topics/user_stories/story_2022_106.md similarity index 84% rename from doc/user_stories/Provided/story_2022_106.md rename to docs/topics/user_stories/story_2022_106.md index 11c65bc7..3bcfd822 100644 --- a/doc/user_stories/Provided/story_2022_106.md +++ b/docs/topics/user_stories/story_2022_106.md @@ -1,7 +1,7 @@ # User Story `2022_106` # -As a Participant, I want the coordination process to be decentralized so that it is robust against individual Participant actions. +As a Participant, I want the coordination process to be decentralized so that it is robust against individual Participant actions. ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_107.md b/docs/topics/user_stories/story_2022_107.md similarity index 86% rename from doc/user_stories/Allowed/story_2022_107.md rename to docs/topics/user_stories/story_2022_107.md index 568788c9..580d4961 100644 --- a/doc/user_stories/Allowed/story_2022_107.md +++ b/docs/topics/user_stories/story_2022_107.md @@ -1,7 +1,7 @@ # User Story `2022_107` # -As a Vendor, I want to convey the vulnerability status of my component(s), product(s), or service(s) to other Participants. +As a Vendor, I want to convey the vulnerability status of my component(s), product(s), or service(s) to other Participants. ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_108.md b/docs/topics/user_stories/story_2022_108.md similarity index 78% rename from doc/user_stories/Out-of-scope/story_2022_108.md rename to docs/topics/user_stories/story_2022_108.md index 0b47c3d8..5558fb69 100644 --- a/doc/user_stories/Out-of-scope/story_2022_108.md +++ b/docs/topics/user_stories/story_2022_108.md @@ -1,7 +1,7 @@ # User Story `2022_108` # -As a Vendor, I want to convey the vulnerability status of my component(s), product(s), or service(s) to Users / the Public +As a Vendor, I want to convey the vulnerability status of my component(s), product(s), or service(s) to Users / the Public ## Notes ## diff --git a/doc/user_stories/Allowed/story_2022_109.md b/docs/topics/user_stories/story_2022_109.md similarity index 87% rename from doc/user_stories/Allowed/story_2022_109.md rename to docs/topics/user_stories/story_2022_109.md index f76b8a63..8f44d279 100644 --- a/doc/user_stories/Allowed/story_2022_109.md +++ b/docs/topics/user_stories/story_2022_109.md @@ -1,7 +1,7 @@ # User Story `2022_109` # -As a Vendor, I want to convey the reason my component is not affected by a vulnerability to other Participants +As a Vendor, I want to convey the reason my component is not affected by a vulnerability to other Participants ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_110.md b/docs/topics/user_stories/story_2022_110.md similarity index 79% rename from doc/user_stories/Out-of-scope/story_2022_110.md rename to docs/topics/user_stories/story_2022_110.md index 104d0fa7..80973013 100644 --- a/doc/user_stories/Out-of-scope/story_2022_110.md +++ b/docs/topics/user_stories/story_2022_110.md @@ -1,7 +1,7 @@ # User Story `2022_110` # -As a Vendor, I want to convey the reason my component is not affected by a vulnerability to Users / the Public +As a Vendor, I want to convey the reason my component is not affected by a vulnerability to Users / the Public ## Notes ## diff --git a/doc/user_stories/Out-of-scope/story_2022_111.md b/docs/topics/user_stories/story_2022_111.md similarity index 77% rename from doc/user_stories/Out-of-scope/story_2022_111.md rename to docs/topics/user_stories/story_2022_111.md index 3d93c981..78737592 100644 --- a/doc/user_stories/Out-of-scope/story_2022_111.md +++ b/docs/topics/user_stories/story_2022_111.md @@ -1,7 +1,7 @@ # User Story `2022_111` # -As a Vendor, I need to know which of my products, components, or services are affected by a vulnerability report so that I know what to fix. +As a Vendor, I need to know which of my products, components, or services are affected by a vulnerability report so that I know what to fix. ## Notes ## diff --git a/docs/topics/user_stories/table.md b/docs/topics/user_stories/table.md new file mode 100644 index 00000000..9cff815e --- /dev/null +++ b/docs/topics/user_stories/table.md @@ -0,0 +1,121 @@ +!!! note "Legend" + + - :material-check: - Allowed + - :material-check-all: - Provided + - :material-close: - Unsupported + - :material-block-helper: - Out-of-scope + + +| ID | Title | Status | +|-------------------------------|--------------------------------------------------------------------------------------------------------------------------|:-----------------------:| +| [2022_001](story_2022_001.md) | {% include-markdown "story_2022_001.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_002](story_2022_002.md) | {% include-markdown "story_2022_002.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_003](story_2022_003.md) | {% include-markdown "story_2022_003.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_004](story_2022_004.md) | {% include-markdown "story_2022_004.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_005](story_2022_005.md) | {% include-markdown "story_2022_005.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_006](story_2022_006.md) | {% include-markdown "story_2022_006.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_007](story_2022_007.md) | {% include-markdown "story_2022_007.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_008](story_2022_008.md) | {% include-markdown "story_2022_008.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_009](story_2022_009.md) | {% include-markdown "story_2022_009.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_010](story_2022_010.md) | {% include-markdown "story_2022_010.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_011](story_2022_011.md) | {% include-markdown "story_2022_011.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_012](story_2022_012.md) | {% include-markdown "story_2022_012.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_013](story_2022_013.md) | {% include-markdown "story_2022_013.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_014](story_2022_014.md) | {% include-markdown "story_2022_014.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_015](story_2022_015.md) | {% include-markdown "story_2022_015.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_016](story_2022_016.md) | {% include-markdown "story_2022_016.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_017](story_2022_017.md) | {% include-markdown "story_2022_017.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_018](story_2022_018.md) | {% include-markdown "story_2022_018.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_019](story_2022_019.md) | {% include-markdown "story_2022_019.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_020](story_2022_020.md) | {% include-markdown "story_2022_020.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_021](story_2022_021.md) | {% include-markdown "story_2022_021.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_022](story_2022_022.md) | {% include-markdown "story_2022_022.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_023](story_2022_023.md) | {% include-markdown "story_2022_023.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_024](story_2022_024.md) | {% include-markdown "story_2022_024.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_025](story_2022_025.md) | {% include-markdown "story_2022_025.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_026](story_2022_026.md) | {% include-markdown "story_2022_026.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_027](story_2022_027.md) | {% include-markdown "story_2022_027.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_028](story_2022_028.md) | {% include-markdown "story_2022_028.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_029](story_2022_029.md) | {% include-markdown "story_2022_029.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_030](story_2022_030.md) | {% include-markdown "story_2022_030.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_031](story_2022_031.md) | {% include-markdown "story_2022_031.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_032](story_2022_032.md) | {% include-markdown "story_2022_032.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_033](story_2022_033.md) | {% include-markdown "story_2022_033.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_034](story_2022_034.md) | {% include-markdown "story_2022_034.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_035](story_2022_035.md) | {% include-markdown "story_2022_035.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_036](story_2022_036.md) | {% include-markdown "story_2022_036.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_037](story_2022_037.md) | {% include-markdown "story_2022_037.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_038](story_2022_038.md) | {% include-markdown "story_2022_038.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_039](story_2022_039.md) | {% include-markdown "story_2022_039.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_040](story_2022_040.md) | {% include-markdown "story_2022_040.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_041](story_2022_041.md) | {% include-markdown "story_2022_041.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_042](story_2022_042.md) | {% include-markdown "story_2022_042.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_043](story_2022_043.md) | {% include-markdown "story_2022_043.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_044](story_2022_044.md) | {% include-markdown "story_2022_044.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_045](story_2022_045.md) | {% include-markdown "story_2022_045.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_046](story_2022_046.md) | {% include-markdown "story_2022_046.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_047](story_2022_047.md) | {% include-markdown "story_2022_047.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_048](story_2022_048.md) | {% include-markdown "story_2022_048.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_049](story_2022_049.md) | {% include-markdown "story_2022_049.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_050](story_2022_050.md) | {% include-markdown "story_2022_050.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_051](story_2022_051.md) | {% include-markdown "story_2022_051.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_052](story_2022_052.md) | {% include-markdown "story_2022_052.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_053](story_2022_053.md) | {% include-markdown "story_2022_053.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_054](story_2022_054.md) | {% include-markdown "story_2022_054.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_055](story_2022_055.md) | {% include-markdown "story_2022_055.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_056](story_2022_056.md) | {% include-markdown "story_2022_056.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_057](story_2022_057.md) | {% include-markdown "story_2022_057.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_058](story_2022_058.md) | {% include-markdown "story_2022_058.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_059](story_2022_059.md) | {% include-markdown "story_2022_059.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_060](story_2022_060.md) | {% include-markdown "story_2022_060.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_061](story_2022_061.md) | {% include-markdown "story_2022_061.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_062](story_2022_062.md) | {% include-markdown "story_2022_062.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_063](story_2022_063.md) | {% include-markdown "story_2022_063.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_064](story_2022_064.md) | {% include-markdown "story_2022_064.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_065](story_2022_065.md) | {% include-markdown "story_2022_065.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_066](story_2022_066.md) | {% include-markdown "story_2022_066.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_067](story_2022_067.md) | {% include-markdown "story_2022_067.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_068](story_2022_068.md) | {% include-markdown "story_2022_068.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_069](story_2022_069.md) | {% include-markdown "story_2022_069.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_070](story_2022_070.md) | {% include-markdown "story_2022_070.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_071](story_2022_071.md) | {% include-markdown "story_2022_071.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_072](story_2022_072.md) | {% include-markdown "story_2022_072.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_073](story_2022_073.md) | {% include-markdown "story_2022_073.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_074](story_2022_074.md) | {% include-markdown "story_2022_074.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_075](story_2022_075.md) | {% include-markdown "story_2022_075.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_076](story_2022_076.md) | {% include-markdown "story_2022_076.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_077](story_2022_077.md) | {% include-markdown "story_2022_077.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_078](story_2022_078.md) | {% include-markdown "story_2022_078.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_079](story_2022_079.md) | {% include-markdown "story_2022_079.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_080](story_2022_080.md) | {% include-markdown "story_2022_080.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_081](story_2022_081.md) | {% include-markdown "story_2022_081.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_082](story_2022_082.md) | {% include-markdown "story_2022_082.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_083](story_2022_083.md) | {% include-markdown "story_2022_083.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_084](story_2022_084.md) | {% include-markdown "story_2022_084.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_085](story_2022_085.md) | {% include-markdown "story_2022_085.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_086](story_2022_086.md) | {% include-markdown "story_2022_086.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_087](story_2022_087.md) | {% include-markdown "story_2022_087.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_088](story_2022_088.md) | {% include-markdown "story_2022_088.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_089](story_2022_089.md) | {% include-markdown "story_2022_089.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_090](story_2022_090.md) | {% include-markdown "story_2022_090.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_091](story_2022_091.md) | {% include-markdown "story_2022_091.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_092](story_2022_092.md) | {% include-markdown "story_2022_092.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_093](story_2022_093.md) | {% include-markdown "story_2022_093.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_094](story_2022_094.md) | {% include-markdown "story_2022_094.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_095](story_2022_095.md) | {% include-markdown "story_2022_095.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_096](story_2022_096.md) | {% include-markdown "story_2022_096.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_097](story_2022_097.md) | {% include-markdown "story_2022_097.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_098](story_2022_098.md) | {% include-markdown "story_2022_098.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_099](story_2022_099.md) | {% include-markdown "story_2022_099.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_100](story_2022_100.md) | {% include-markdown "story_2022_100.md" start="" end="" trailing-newlines=false %} | :material-close: | +| [2022_101](story_2022_101.md) | {% include-markdown "story_2022_101.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_102](story_2022_102.md) | {% include-markdown "story_2022_102.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_103](story_2022_103.md) | {% include-markdown "story_2022_103.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_104](story_2022_104.md) | {% include-markdown "story_2022_104.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_105](story_2022_105.md) | {% include-markdown "story_2022_105.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_106](story_2022_106.md) | {% include-markdown "story_2022_106.md" start="" end="" trailing-newlines=false %} | :material-check-all: | +| [2022_107](story_2022_107.md) | {% include-markdown "story_2022_107.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_108](story_2022_108.md) | {% include-markdown "story_2022_108.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_109](story_2022_109.md) | {% include-markdown "story_2022_109.md" start="" end="" trailing-newlines=false %} | :material-check: | +| [2022_110](story_2022_110.md) | {% include-markdown "story_2022_110.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | +| [2022_111](story_2022_111.md) | {% include-markdown "story_2022_111.md" start="" end="" trailing-newlines=false %} | :material-block-helper: | diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 00000000..3a16e9c8 --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,20 @@ +# Vultron Protocol Tutorials + +!!! info "Coming Soon" + + This page is a placeholder for future tutorials. + We will add tutorials here as we develop them. + If you have a suggestion for a tutorial, please [open an issue](https://github.com/CERTCC/Vultron/issues) to let us know. + + +In the mean time: + +- If you are unfamiliar with the Vultron Protocol, we recommend that you start with [Understanding Vultron](../topics/index.md). +- If you are familiar enough with the Vultron Protocol that you're interested in implementing it, see [Implementing Vultron](../howto/index.md). +- For technical reference material, see [Reference](../reference/index.md). +- And finally, if you're just trying to understand the CVD process, we recommend that you start with the [CERT Guide to Coordinated Vulnerability Disclosure](https://vuls.cert.org/confluence/display/CVD/). + +You might also want to check out: + +- [SEI Blog:Vultron: A Protocol for Coordinated Vulnerability Disclosure](https://insights.sei.cmu.edu/blog/vultron-a-protocol-for-coordinated-vulnerability-disclosure/) - the blog post that introduced the Vultron Protocol +- [SEI Podcast Series: Improving Interoperability in Coordinated Vulnerability Disclosure with Vultron](https://youtu.be/8WiSmhxJ2OM) - a podcast about the Vultron Protocol with Allen Householder and Suzanne Miller diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..d709cf63 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,173 @@ +site_name: Vultron CVD Protocol +copyright: Copyright © 2023 Carnegie Mellon University. +nav: + - Home: 'index.md' + - Learning Vultron: 'tutorials/index.md' + - Understanding Vultron: + - Introduction: + - Background: 'topics/background/index.md' + - Interoperability: 'topics/background/interoperability.md' + - Defining CVD Success: 'topics/background/cvd_success.md' + - Documentation Overview: 'topics/background/overview.md' + - Terms and Definitions: 'topics/background/terms.md' + - Notation: 'topics/background/notation.md' + - Versioning: 'topics/background/versioning.md' + - Process Models: + - Introduction: 'topics/process_models/index.md' + - Report Management: + - RM Process Model: 'topics/process_models/rm/index.md' + - RM Participant Interactions: 'topics/process_models/rm/rm_interactions.md' + - Embargo Management: + - EM Process Model: 'topics/process_models/em/index.md' + - Embargo Principles: 'topics/process_models/em/principles.md' + - Default Embargoes: 'topics/process_models/em/defaults.md' + - Negotiating Embargoes: 'topics/process_models/em/negotiating.md' + - Adding Participants: 'topics/process_models/em/working_with_others.md' + - Early Termination: 'topics/process_models/em/early_termination.md' + - Case Splits and Merges: 'topics/process_models/em/split_merge.md' + - Case State: + - Introduction: 'topics/process_models/cs/index.md' + - CVD Case State Model: 'topics/process_models/cs/cs_model.md' + - Model Interactions: + - Global vs Local Aspects: 'topics/process_models/model_interactions/index.md' + - RM and EM Interactions: 'topics/process_models/model_interactions/rm_em.md' + - RM, EM, CS Interactions: 'topics/process_models/model_interactions/rm_em_cs.md' + - The Vultron Protocol: + - Formal Protocol Summary: 'topics/formal_protocol/index.md' + - Worked Example: 'topics/formal_protocol/worked_example.md' + - Behavior Logic: + - Behavior Tree Intro: 'topics/behavior_logic/index.md' + - CVD Behaviors: 'topics/behavior_logic/cvd_bt.md' + - Vulnerability Discovery Behavior: 'topics/behavior_logic/vuldisco_bt.md' + - RM Behaviors: + - RM BT Intro: 'topics/behavior_logic/rm_bt.md' + - Validation: 'topics/behavior_logic/rm_validation_bt.md' + - Prioritization: 'topics/behavior_logic/rm_prioritization_bt.md' + - Closure: 'topics/behavior_logic/rm_closure_bt.md' + - EM Behaviors: + - EM BT Intro: 'topics/behavior_logic/em_bt.md' + - Evaluate Proposed Embargo Behavior: 'topics/behavior_logic/em_eval_bt.md' + - Propse Embargo Behavior: 'topics/behavior_logic/em_propose_bt.md' + - Terminate Embargo Behavior: 'topics/behavior_logic/em_terminate_bt.md' + - Do Work Behaviors: + - Do Work Intro: 'topics/behavior_logic/do_work_bt.md' + - Deployment: 'topics/behavior_logic/deployment_bt.md' + - Fix Development: 'topics/behavior_logic/fix_dev_bt.md' + - Reporting: 'topics/behavior_logic/reporting_bt.md' + - Publication: 'topics/behavior_logic/publication_bt.md' + - Monitoring Threats: 'topics/behavior_logic/monitor_threats_bt.md' + - ID Assignment: 'topics/behavior_logic/id_assignment_bt.md' + - Exploit Acquisition: 'topics/behavior_logic/acquire_exploit_bt.md' + - Receive Messages Behaviors: + - Receive Msg Intro: 'topics/behavior_logic/msg_intro_bt.md' + - Receive RM Messages: 'topics/behavior_logic/msg_rm_bt.md' + - Receive EM Messages: 'topics/behavior_logic/msg_em_bt.md' + - Receive CS Messages: 'topics/behavior_logic/msg_cs_bt.md' + - Receive Other Messages: 'topics/behavior_logic/msg_other_bt.md' + - User Stories: 'topics/user_stories/index.md' + - Future Work: + - Intro: 'topics/future_work/index.md' + - CVD Directory: 'topics/future_work/cvd_directory.md' + - Reward Functions: 'topics/future_work/reward_functions.md' + - Ontology: 'topics/future_work/ontology.md' + - Modeling and Simulation: 'topics/future_work/mod_sim.md' + - Implementing Vultron: + - Implementation Intro: 'howto/index.md' + - A Case Object: 'howto/case_object.md' + - Process Implementation: 'howto/process_implementation.md' + - EM and iCalendar: 'howto/em_icalendar.md' + - General Notes: 'howto/general_implementation.md' + - Reference: + - Reference Overview: 'reference/index.md' + - Formal Protocol: + - Introduction: 'reference/formal_protocol/index.md' + - States: 'reference/formal_protocol/states.md' + - Messages: 'reference/formal_protocol/messages.md' + - Transitions: 'reference/formal_protocol/transitions.md' + - Protocol Summary: 'reference/formal_protocol/conclusion.md' + - ISO Crosswalk: + - Introduction: 'reference/iso_crosswalk.md' + - ISO 30111: 'reference/iso_30111_2019.md' + - ISO 29147: 'reference/iso_29147_2018.md' + - ISO 5895: 'reference/iso_5895_2022.md' + - SSVC Crosswalk: 'reference/ssvc_crosswalk.md' + - About: + - Contributing: 'about/contributing.md' + - FAQ: 'about/faq.md' + - Acknowledgements: 'about/acknowledgements.md' + - License: 'about/license.md' + - Issue Tracker: 'https://github.com/CERTCC/Vultron/issues' +theme: + logo: 'assets/cert_seal.svg' + name: 'material' + features: + - content.tabs.link + - navigation.footer + - navigation.instant + - navigation.sections + - navigation.tabs + - navigation.top + - navigation.tracking + - search.highlight + - search.suggest + - toc.follow + palette: + scheme: 'cmu' + accent: 'red' + icon: + repo: fontawesome/brands/github +plugins: + - include-markdown: + comments: false + - search +repo_url: 'https://github.com/CERTCC/Vultron' +repo_name: 'CERTCC/Vultron' +markdown_extensions: + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - pymdownx.arithmatex: + generic: true + - pymdownx.critic + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.keys + - pymdownx.mark + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + - tables +extra: + social: + - icon: fontawesome/solid/bug + link: https://github.com/CERTCC/Vultron/issues + name: Report an Issue or Suggest a Change + - icon: fontawesome/brands/github + link: https://github.com/CERTCC/Vultron + name: CERTCC/Vultron on Github + - icon: fontawesome/regular/envelope + link: mailto:cert@cert.org?subject=Vultron%20Protocol%20Feedback + name: Email CERT/CC + - icon: fontawesome/solid/house + link: https://www.sei.cmu.edu/ + name: Software Engineering Institute +extra_javascript: + # to render math + - javascripts/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + # to sort tables + - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js + - javascripts/tablesort.js +extra_css: + - stylesheets/extra.css diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..41b58358 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +mkdocs==1.4.3 +mkdocs-include-markdown-plugin==4.0.4 +mkdocs-material==9.1.19 +mkdocs-material-extensions==1.1.1