Vultron ActivityStreams Examples: docs (#67)

* add activitystream example docs

* update ontology

docs/howto/activitypub/activities/_accept_embargo.md

@@ -0,0 +1,9 @@
+# Accept Embargo
+
+An actor accepts an embargo proposal.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import accept_embargo, json2md
+
+print(json2md(accept_embargo()))
+```

docs/howto/activitypub/activities/_accept_invite_to_case.md

@@ -0,0 +1,9 @@
+# Accept Invite to Case
+
+A coordinator accepts a vendor's invitation to a case.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import accept_invite_to_case, json2md
+
+print(json2md(accept_invite_to_case()))
+```

docs/howto/activitypub/activities/_activate_embargo.md

@@ -0,0 +1,10 @@
+# Activate Embargo
+
+The case owner activates an embargo. This is a special case of adding an embargo to a case,
+performed in reply to an embargo proposal.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import activate_embargo, json2md
+
+print(json2md(activate_embargo()))
+```

docs/howto/activitypub/activities/_add_coordinator_participant_to_case.md

@@ -0,0 +1,9 @@
+# Add Participant to Case
+
+The vendor adds a coordinator participant to the case.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import add_coordinator_participant_to_case, json2md
+
+print(json2md(add_coordinator_participant_to_case()))
+```

docs/howto/activitypub/activities/_add_embargo_to_case.md

@@ -0,0 +1,12 @@
+# Add Embargo to Case
+
+The case owner adds an embargo to the case. This is the generic form of activating an embargo,
+and is mainly included to allow for a case owner to add an embargo to a case without having to
+first propose the embargo to the case.
+In most cases, the case owner will activate an embargo in response to an embargo proposal.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import add_embargo_to_case, json2md
+
+print(json2md(add_embargo_to_case()))
+```

docs/howto/activitypub/activities/_add_note_to_case.md

@@ -0,0 +1,21 @@
+# Add Note to Case
+
+If we think of a case as being a collection of information about a particular
+report or set of reports, then a note can be thought of as a comment on
+that information. Here we show a note being added to a case.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import add_note_to_case, json2md
+
+print(json2md(add_note_to_case()))
+```
+
+!!! note "Add vs Create+Target"
+
+    Creating a Note and adding it to a Case is functionally equivalent to Creating
+    a Note with the Case as the target. We use the `as:Add` activity to represent
+    the addition of an existing object to another object, such as adding a note to 
+    a case. However, it is likely acceptable within an ActivityPub implementation to
+    use the `as:Create` activity, since the `as:Create` activity includes a `target`
+    property that can be used to specify the object to which the newly created object 
+    is being attached.

docs/howto/activitypub/activities/_add_participant_to_case.md

@@ -0,0 +1,30 @@
+# Add Participant to Case
+
+Here we provide two examples of adding a participant to a case.
+
+## Vendor adds self to case
+
+In the first example, the vendor actor adds itself to the case in the vendor role.
+Normally, this might not be done as a separate step, but would be done as part of the
+creation of the case itself.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import add_vendor_participant_to_case, json2md
+
+print(json2md(add_vendor_participant_to_case()))
+```
+
+## Vendor adds finder to case
+
+In the second example, the vendor actor adds the finder to the case in the finder and reporter roles.
+Again, this might not be done as a separate step, and could be done as part of the
+case creation step. But we include it here to show how to add multiple participants to a case.
+
+For example, if a finder reported a vulnerability that was already known to the vendor, the vendor
+might add the finder to the case in the reporter role, but not in the finder role.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import add_finder_participant_to_case, json2md
+
+print(json2md(add_finder_participant_to_case()))
+```

docs/howto/activitypub/activities/_add_report_to_case.md

@@ -0,0 +1,12 @@
+# Add Report to Case
+
+Below we demonstrate how to add a report to a case.
+As noted above, this might more commonly be done in the initial case creation process.
+However, we show it here since there are times it may be necessary to treat it separately.
+For example, when a second report arrives for a case that already has a report.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import add_report_to_case, json2md
+
+print(json2md(add_report_to_case()))
+```

docs/howto/activitypub/activities/_announce_embargo.md

@@ -0,0 +1,18 @@
+# Announce Embargo
+
+The case owner announces an embargo to the case. This is meant to remind case participants of the embargo terms.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import announce_embargo, json2md
+
+print(json2md(announce_embargo()))
+```
+
+!!! tip "Announce Embargo"
+
+    The `AnnounceEmbargo` activity is used to indicate that an embargo has been
+    established or to remind participants of its status. It is used to announce
+    the embargo to the case participants. It is also used to draw attention to
+    significant changes to the embargo status over and above the corresponding 
+    CaseStatus messages, such as when an embargo is deactivated or removed from
+    a case.

docs/howto/activitypub/activities/_choose_preferred_embargo.md

@@ -0,0 +1,9 @@
+# Choose Preferred Embargo
+
+The vendor asks participants to choose an embargo from a list of embargo options.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import choose_preferred_embargo, json2md
+
+print(json2md(choose_preferred_embargo()))
+```

docs/howto/activitypub/activities/_close_case.md

@@ -0,0 +1,7 @@
+# Close Case
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import close_case, json2md
+
+print(json2md(close_case()))
+```

docs/howto/activitypub/activities/_close_report.md

@@ -0,0 +1,10 @@
+# Close Report
+
+The vendor closes an invalid vulnerability report, which implies that they
+will not be taking further action on the vulnerability.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import close_report, json2md
+
+print(json2md(close_report()))
+```

docs/howto/activitypub/activities/_create_case.md

@@ -0,0 +1,12 @@
+# Create Case
+
+A vendor creates a case in response to a vulnerability report.
+Here we show a case creation including a single participant and a pointer to a report.
+In practice, a case may have multiple participants and (less often) multiple reports.
+See also  [Initializing a Case](./initialize_case.md).
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import create_case, json2md
+
+print(json2md(create_case()))
+```

docs/howto/activitypub/activities/_create_participant.md

@@ -0,0 +1,9 @@
+# Create Participant
+
+In the following example, the vendor actor creates a coordinator participant for a case.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import create_participant, json2md
+
+print(json2md(create_participant()))
+```

docs/howto/activitypub/activities/_create_report.md

@@ -0,0 +1,9 @@
+# Create Report
+
+A finder creates a vulnerability report.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import create_report, json2md
+
+print(json2md(create_report()))
+```

docs/howto/activitypub/activities/_defer_case.md

@@ -0,0 +1,7 @@
+# Defer Case
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import defer_case, json2md
+
+print(json2md(defer_case()))
+```

docs/howto/activitypub/activities/_em_blurb.md

@@ -0,0 +1,5 @@
+!!! note inline end "Embargo Management in Vultron"
+
+    The Vultron protocol contains quite a bit of detail about
+    [Embargo Management](../../../topics/process_models/em/index.md) and how participants are expected to
+    interact with embargoes. Please refer to that section for more information.

docs/howto/activitypub/activities/_engage_case.md

@@ -0,0 +1,7 @@
+# Engage Case
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import engage_case, json2md
+
+print(json2md(engage_case()))
+```

docs/howto/activitypub/activities/_invalidate_report.md

@@ -0,0 +1,12 @@
+# Invalidate Report
+
+The vendor invalidates the vulnerability report, which implies that they will
+not be taking further action on the vulnerability. They may choose to hold
+the report open for a period of time before closing it in order to allow the reporter to
+provide additional information that could change the vendor's decision.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import invalidate_report, json2md
+
+print(json2md(invalidate_report()))
+```

docs/howto/activitypub/activities/_invite_to_case.md

@@ -0,0 +1,9 @@
+# Invite to Case
+
+A vendor invites a coordinator to a case.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import rm_invite_to_case, json2md
+
+print(json2md(rm_invite_to_case()))
+```

docs/howto/activitypub/activities/_propose_embargo.md

@@ -0,0 +1,9 @@
+# Propose Embargo
+
+An actor proposes an embargo to a case.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import propose_embargo, json2md
+
+print(json2md(propose_embargo()))
+```

docs/howto/activitypub/activities/_read_report.md

@@ -0,0 +1,9 @@
+# Read Report
+
+The vendor reads the vulnerability report, acknowledging that they have received it.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import read_report, json2md
+
+print(json2md(read_report()))
+```

docs/howto/activitypub/activities/_reengage_case.md

@@ -0,0 +1,7 @@
+# Re-Engage Case
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import reengage_case, json2md
+
+print(json2md(reengage_case()))
+```

docs/howto/activitypub/activities/_reject_embargo.md

@@ -0,0 +1,9 @@
+# Reject Embargo
+
+An actor rejects an embargo proposal.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import reject_embargo, json2md
+
+print(json2md(reject_embargo()))
+```

docs/howto/activitypub/activities/_reject_invite_to_case.md

@@ -0,0 +1,9 @@
+# Reject Invite to Case
+
+A coordinator rejects a vendor's invitation to a case.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import reject_invite_to_case, json2md
+
+print(json2md(reject_invite_to_case()))
+```

docs/howto/activitypub/activities/_remove_embargo_from_case.md

@@ -0,0 +1,7 @@
+# Remove Embargo From Case
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import remove_embargo, json2md
+
+print(json2md(remove_embargo()))
+```

docs/howto/activitypub/activities/_submit_report.md

@@ -0,0 +1,9 @@
+# Submit Report
+
+The finder submits a vulnerability report to the vendor.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import submit_report, json2md
+
+print(json2md(submit_report()))
+```

docs/howto/activitypub/activities/_validate_report.md

@@ -0,0 +1,10 @@
+# Validate Report
+
+The vendor validates the vulnerability report, which implies that they will
+shortly create a case to track the vulnerability response.
+
+```python exec="true" idprefix=""
+from vultron.scripts.vocab_examples import validate_report, json2md
+
+print(json2md(validate_report()))
+```

docs/howto/activitypub/activities/acknowledge.md

@@ -0,0 +1,67 @@
+# Acknowledging Other Messages
+
+The ActivityStreams vocabulary includes several activities that can be used to
+indicate that a message or object has been read or acknowledged. These include:
+
+- `as:Read`
+- `as:View`
+- `as:Listen`
+
+Since most CVD cases are text-centric, we expect that the `as:Read` activity
+will be the most commonly used. However, we also expect that the `as:View` and
+`as:Listen` activities could be used in some cases, such as when a case
+participant views a video or listens to an audio recording.
+
+We specifically defined `RmReadReport` as a subclass of `as:Read` to indicate
+that a report has been read. This allows the receiver of a report to
+acknowledge receipt without indicating anything more than that the report has
+been read. That leaves `RmValidateReport` and `RmInvalidateReport` to indicate
+a more specific action (accept, reject) on the part of the receiver.
+
+```mermaid
+flowchart LR
+    subgraph RM:Received
+        a{Accept?}
+        subgraph as:Read
+            RmReadReport
+        end
+    end
+    subgraph RM:Start
+        subgraph as:Offer
+            RmSubmitReport
+        end
+    end
+    subgraph RM:Accepted
+        subgraph as:Accept
+            RmValidateReport
+        end
+    end
+    subgraph RM:Invalid
+        subgraph as:Reject
+            RmInvalidateReport
+        end
+    end
+    a -->|y| RmValidateReport
+    a -->|undecided| RmReadReport
+    a -->|n| RmInvalidateReport
+    RmSubmitReport --> a
+```
+
+!!! info "More Acknowledgements in the Ontology"
+
+    The [Vultron AS ontology](../../../reference/ontology/vultron_as.md) defines a
+    number of ActivityStreams activities that can serve as the various acknowledgements that are used in the Vultron
+    protocol. These include messages that are specifically `as:inReplyTo` a
+    message defined as one of the core protocol message types.
+
+    For example, it is not necessary to send a separate `RmReadReport` message
+    if the `RmValidateReport` message is sent as a reply to the `RmSubmitReport`
+    message. The `RmValidateReport` message logically indicates that the
+    report has been read in order to have been validated.
+
+!!! tip "Like, Dislike and Flag"
+
+    The ActivityStreams vocabulary also includes actions that indicate an opinion 
+    about a message or object, such as `as:Like`, `as:Dislike`, and `as:Flag`.
+    While these may be relevant to implementations of the Vultron protocol, we
+    do not have specific use cases for them at this time.