From 4df08f97b01ef2000843866744b6f573a6843dad Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 21 Feb 2023 14:54:43 -0500 Subject: [PATCH] Establish ADRs and Document Public Event Calendar Management for OSCAL Team (#1638) * Add ADR structure for usnistgov/OSCAL#1408. * Add decision record for use of shared calendar for #1408 * Take wording suggestion from @Compton-NIST. Co-authored-by: Chris Compton * Integrate feedback into ADR 2 from @iMichaela. * Update decisions/0002-record-architecture-decisions.md Co-authored-by: Wendell Piez * Update decisions/0002-record-architecture-decisions.md * Rename file per @nikitawooten-nist's feedback. * Update decisions/0002-communicating-nist-oscal-events-to-the-public.md --------- Co-authored-by: Chris Compton Co-authored-by: Wendell Piez --- .../0001-record-architecture-decisions.md | 21 ++++++++ ...icating-nist-oscal-events-to-the-public.md | 51 +++++++++++++++++++ decisions/adr_template.md | 13 +++++ 3 files changed, 85 insertions(+) create mode 100644 decisions/0001-record-architecture-decisions.md create mode 100644 decisions/0002-communicating-nist-oscal-events-to-the-public.md create mode 100644 decisions/adr_template.md diff --git a/decisions/0001-record-architecture-decisions.md b/decisions/0001-record-architecture-decisions.md new file mode 100644 index 0000000000..44e097d7fa --- /dev/null +++ b/decisions/0001-record-architecture-decisions.md @@ -0,0 +1,21 @@ +# 1. Record architecture decisions + +Date: 2023-02-06 + +## Status + +Feedback Requested + +## Context + +We need to record the architectural decisions made on this project. + +We also need the ability to compare architecture decisions regarding OSCAL artifacts, supporting software, and website material (documentation and otherwise). + +## Decision + +We will use Architecture Decision Records, as described by Michael Nygard in his article ["Documenting Architecture Decisions"](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). + +## Consequences + +See Michael Nygard's article, linked above. diff --git a/decisions/0002-communicating-nist-oscal-events-to-the-public.md b/decisions/0002-communicating-nist-oscal-events-to-the-public.md new file mode 100644 index 0000000000..28b168bf36 --- /dev/null +++ b/decisions/0002-communicating-nist-oscal-events-to-the-public.md @@ -0,0 +1,51 @@ +# 2. Communicating NIST's OSCAL Events to the Public + +Date: 2023-02-03 + +## Status + +Feedback Requested + +## Context + +The NIST OSCAL Team has necessary touchpoints with the community, among them structured and unstructured meetings with community stakeholders. Many of these meetings are events occuring at set frequencies, while others do not. In all cases, the community, past and present, has expressed the need for invitations to events that are easily accessible with the most current information possible. + +## Decision + +The NIST OSCAL Team will use [a public shared calendar from a service account in the Office 365 instance for NIST, as documented below](#service-account-with-published-nist-office-365-calendar). The team staff will add, change, and remove event invitations. Community members will have access to the .ics calendar invitation files in the web version. These .ics files are [iCalendar](https://en.wikipedia.org/wiki/ICalendar) files - a standard that many calendar clients support. + +The NIST OSCAL Team will use the shared calendar to send invitations for public events only to [those subscribed to our mailing lists](https://pages.nist.gov/OSCAL/contact/#oscal-mailing-lists). We will not use it to send invitations to named individuals. + +## Consequences + +In the past, NIST staff have sent individual calendar invites from their individual accounts' calendars to specific individuals or the oscal-dev@list.nist.gov mailing list at large. Additionally, the team had published individual iCalendar (ICS) files for two of the long-standing public meetings. The latter had not been updated frequently and were out of sync until removed completely with [pull request usnistgov/OSCAL#1614](https://github.com/usnistgov/OSCAL/pull/1614). The former approach, although convenient, presents a few challenges. + +1. It is difficult to quickly access one or more event invitations after they are sent. +1. Only one staff member in the team, the event's creator, can manage that event's invitation details, often when multiple staff are involved. +1. Community members often accept an invitation email via the mailing list once or several times, but not every time. They lose important updates to event details and contact us for clarification. + +Therefore we need a solution that meets the following requirements for the use case of notifying community members to public meetings. + +1. A system for all members of the NIST OSCAL Team to create +1. A system for all members of the NIST OSCAL Team to modify and remove existing event invitations +1. A system that allows any anonymous community member, without prior or ongoing authentication and authorization to a NIST-hosted service, to access event information +1. A system that has a standards conformant, or largely popular, calendar synchronization mechanism for authorized NIST staff and anonymous community members (iCalendar or otherwise) +1. Manage frequent changes to calendar events efficiently with short notice without waiting upon approval times by team, group, division, or lab leadership + +With these high-level requirements in mind, we have several options. + +## CMS for the NIST Computer Security Resource Center Website and Calendar + +As part of a spike, we evaluated event management [via the content management system that published the csrc.nist.gov website, specifically the Events page](https://csrc.nist.gov/Events). Although this solution partially supports requirements 3 and 4, it does not completely support requirement 1 or 2 at all. The CMS has a permissions system that only works with one group within the respective division for those who manage the content. At this time, the NIST OSCAL Team is composed of staff from teams from two different group's in ITL's Computer Security Division, so requirements 1 and 2 are not easily achievable or unsupported based upon consultation with the web developers that maintain the system. Additionally per requirement 5, there will need to be approval for every change, imposing upon approvers for events where we have historically made frequent changes. + +## NIST Main Website and the Public Events Calendar + +As part of spike, we evaluated using the [CSRC CMS approach](#cms-for-the-nist-computer-security-resource-center-website-and-calendar) and selecting an option in the event creation to request it be added to [the agency-wide public calendar](https://www.nist.gov/news-events/events/calendar). This testing was very limited and had to be immediately deferred. During support consultantions with the web developers, we determined that is an integration between the CSRC CMS and a separate CMS for the [www.nist.gov website](https://www.nist.gov). We were unable to determine if the integration between the two is enabled in a test environment. As this option will publish to one location and not other, not being able to test this change causes indeterminate but high risk around requirements 1, 2, and 5. + +## Sharepoint Group in NIST Office 365 Calendar + +As part of this spike, we evaluated using a Sharepoint site and group for event management. We were unable to share a calendar, so this approach could not completely meet requirements 1, 2, 3, and 4. + +## Service Account with Published NIST Office 365 Calendar + +As part of the spike, we considered and evaluated the creation of a service account, [oscalevt@nist.gov](mailto:oscalevt@nist.gov), with permissions delegated to a private distribution group in NIST's directory containing all staff in the NIST OSCAL Team, and using a shared calendar published for anonymous access for event management. Upon testing, we confirmed that this solution best meets all three requirements. diff --git a/decisions/adr_template.md b/decisions/adr_template.md new file mode 100644 index 0000000000..29f2564963 --- /dev/null +++ b/decisions/adr_template.md @@ -0,0 +1,13 @@ +# N. Brief ADR Title + +Date: + +## Status + +Proposed + +## Context + +## Decision + +## Consequences