Conformance example1 preliminary SEBoK structure and EU CRA statements

[gregshue]

This PR establishes the preliminary structure of source content for the SPDX Conformance Example1.
The structure follows the top-level best practices from the Systems Engineering Body of Knowledge (SEBoK) Wiki.
The content includes a preliminary list of stakeholders and stakeholder requirements from the EU Cyber Resilience Act.
Source content is captured using the StrictDoc tool already adopted by the Linux Foundation's Zephyr Project.

[bennetkl]

Missing and needed by CRA ..

1. SHA-256 of the source-code archive (only binary hash is present)
2.. VEX data – CVE ID + affected/fixed status for every component

3. EU Declaration of Conformity URI (externalRef: conformityDeclaration)
4. Signing of SBOM, need to prove no tamper-evidence on the SBOM itself
5. previousSPDX link for post-market updates
   6. Field-updatable flag – is the component patchable in the field?
   7. support end-of-life date - we have a expired field, is that good enough to add?
6. CE-marking reference is missing

[bennetkl]

Auditors need a machine readable way to list those stakeholders and their specific interests inside the artefact that travels with the software.. In SPDX 3.1 today there is no first-class element or profile that lets you assert: ie. potentially this type of information,
“Which class of stakeholder (end-user, regulator, maintainer, disposer, insurer, …)”
“Has what interest/right/claim (safety, security, IP, privacy, sustainability, …)”
“Against which component or subsystem”
“With priority/validity time-window”
SPDX has supplier, originator, createdBy, verifiedUsing, etc., but no “stakeholderProfile” element that enumerates the full Freeman set and links each one to its concern(s). Until that extension exists, CRA (or any other compliance regime) cannot automatically validate that “all affected parties’ needs and expectations have been addressed.” Something to think of adding to SPDX 3.*

[bennetkl]

Maybe add also, INCOSE Systems Engineering Handbook v4 – “Stakeholder Requirements Definition → System Requirements Definition – transforms user needs into technical specifications.” and NIST SP 800-160 v1

[bennetkl]

In Design compliance profile, do we have verificationActivity
verifiedRequirement (pointer to requirement URI)
verificationResult (PASS/FAIL/NA/ERROR)
verificationEvidence (log file hash, test report hash, metrics)
verifierIdentity (tool + signer)
verificationDate / validityPeriod. I'm assuming that's field level of information that is need to address these standards.

[bennetkl]

Do we plan to make it mandatory to write requirements in "EARS"?

[gregshue]

Missing and needed by CRA ..

1. SHA-256 of the source-code archive (only binary hash is present)
2.. VEX data – CVE ID + affected/fixed status for every component

3. EU Declaration of Conformity URI (externalRef: conformityDeclaration)
4. Signing of SBOM, need to prove no tamper-evidence on the SBOM itself
5. previousSPDX link for post-market updates
   6. Field-updatable flag – is the component patchable in the field?
   7. support end-of-life date - we have a expired field, is that good enough to add?
6. CE-marking reference is missing

My intent is to have all the CRA-specific content traced back to the CRA statements, particularly those in ANNEX I Mandatory Requirements and ANNEX VII Technical Documentation. I expect there will be at least a few solution design decisions needed before we can get to this content (e.g., I think it unlikely that the product would be implemented entirely within one source code archive; the EU declaration of conformity cannot be part of the original product submission for critical or important products; ...)

Each of the items you listed likely need to be covered. We need to show what forces each of these pieces of information to exist, so we should include the tracing for each item as soon as that item is introduced.

[gregshue]

Auditors need a machine readable way to list those stakeholders and their specific interests inside the artefact that travels with the software.. In SPDX 3.1 today there is no first-class element or profile that lets you assert: ie. potentially this type of information, “Which class of stakeholder (end-user, regulator, maintainer, disposer, insurer, …)” “Has what interest/right/claim (safety, security, IP, privacy, sustainability, …)” “Against which component or subsystem” “With priority/validity time-window” SPDX has supplier, originator, createdBy, verifiedUsing, etc., but no “stakeholderProfile” element that enumerates the full Freeman set and links each one to its concern(s). Until that extension exists, CRA (or any other compliance regime) cannot automatically validate that “all affected parties’ needs and expectations have been addressed.” Something to think of adding to SPDX 3.*

Off the top of my head, I am not recalling a specific need for the CRA documentation to include the list of stakeholders, stakeholder needs, or stakeholder requirements. Has anyone else noticed a need for the CRA documentation to include stakeholders?

[gregshue]

Maybe add also, INCOSE Systems Engineering Handbook v4 – “Stakeholder Requirements Definition → System Requirements Definition – transforms user needs into technical specifications.” and NIST SP 800-160 v1

User (Stakeholder) Needs are not specification statements. The subset of Needs that will be addressed by the Product-as-a-System must be covered in the System Requirement statements. In today's SPDX-FuSa discussion we considered consolidating much of the content quoted above into a Systems Engineering Profile. I think that is a very good suggestion and will clarify the System Engineering profile(s) concepts. ;-)

I'm not familiar with NIST SP 800-160 v1 so I elected to not use that in this example. A different conformance example may choose to reference this standard. ;-)

[gregshue]

In Design compliance profile, do we have verificationActivity verifiedRequirement (pointer to requirement URI) verificationResult (PASS/FAIL/NA/ERROR) verificationEvidence (log file hash, test report hash, metrics) verifierIdentity (tool + signer) verificationDate / validityPeriod. I'm assuming that's field level of information that is need to address these standards.

Agreed. The example source (StrictDoc grammars) needs to also cover validation and verification items (processes and artifacts). Some content (e.g., test plans/procedures/evaluation criteria) change very slowly and can easily live under the example source (in the same branch). I'm not sure we want to do the same with the test outputs (where each test run generates a new set of data). ;-)

[gregshue]

Do we plan to make it mandatory to write requirements in "EARS"?

For this specific example? Yes.
For any other example or SPDX overall? No, but we may suggest or even recommend it. ;-)

[gregshue]

The traceable items are currently have STATUS: Draft. These will become invariant once they have STATUS: Active. I assume the STATUS: Active change to be in a separate commit with reviewers signing the commit their approval. This may be more overhead than reviewers have time for. Does anyone have alternate suggestions?

[gregshue]

Forced pushed to a commit history where:

• each commit is enhanced with Machine IDs (UUIDs), stkReqs are related to stkNeeds (essentially same order).
• productLine-as-a-system internal name updated to SAMPLE (Solution Artifacts Modelling Product Line Engineering)
• Added a few user needs around automatically applied security updates.

[stanislaw]

As discussed on the call, let's rather use snake_case and never use camelCase.

Rationale: Mixing both styles can reduce the readability.

[gregshue]

Most usage has changed to snake_case.

[stanislaw]

As discussed on the call, here's a note on structuring chapters in requirement specifications:

Splitting by requirement types does not scale as well as splitting by the functional decomposition.

Let's say you have a system with functions F1, F2, F3.

Here's what does not scale very well:

Requirements doc:

- Functional requirements
  - F1
  - F2
  - F3
- Performance requirements
  - F1  
  - F2
  - F3
- Interface requirements
  - F1
  - F2
  - F3

With this kind of decomposition, each function, e.g., F1, get fragmented a lot and understanding the whole function becomes problematic.

The approach that scales better:

Requirements doc:

- F1
  - Functional requirements
  - Performance requirements
  - Interface requirements
- F2
  - Functional requirements
  - Performance requirements
  - Interface requirements
- F3
  - Functional requirements
  - Performance requirements
  - Interface requirements

This way, one can get a better understanding of F1, F2, F3, ... because all their requirements are nicely co-located.

With this approach, the non-functional / cross-cutting requirements can still be arranged by types, forming the structure:

Requirements doc:

(all functional requirements)
- F1
  ... functional, performance, interface
- F2
  ... functional, performance, interface
- F3
  ... functional, performance, interface
...
(cross-cutting, not attached to a single function, applicable to many functions or the entire product)
- Quality requirements 
- Maintainability requirements
- Other cross-cutting

[gregshue]

@stanislaw I think organizing primarily by function makes sense for the system_requirements document(s). The system_architecture process identifies and delegates responsibilities to system elements and the interfaces between system elements.

In many cases a single system function is achieved through the interaction of multiple system elements. Those interactions are internal interfaces shared between participating elements. An interface_specification describes all the interactions across the interface.

It seems to me that the interface_requirements document simply pulls together all the requirements for a single interface. I don't know if this aggregation makes evaluating/selecting or specifying an interface any easier.

[gregshue]

Forced push to 3a0c185 introduced several significant changes:

1. snake_case instead of camelCase for folder and document names, and for git commit header prefixes. camelCase in some prefixes for EU CRA section references.
2. Folder and file names are spelled out rather than abbreviated.
3. Stakeholder-level content is moved into a Problem Space folder.
4. System content is moved into a System-of-Interest Catalog folder (SOI/) with separate sub-folders for each recursive decomposition of the initial system-of-interest (SAMPLE/).
5. Hyperlinks in .sdoc files have been changed to RST syntax to align with the strictdoc configuration setting.
6. Updated to use strictdoc 0.16.1 with a Python-based configuration.
7. Relocated strictdoc grammer files within shared/sdoc/grammars/, set up strictdoc grammar aliases, updated .sdoc files to use the grammar aliases.
8. Simplified the name of the top-level system to SAMPLE.
9. Removed top-level README.md text mentioning the European Space Agency.

[gregshue]

Forced push to fe5d2c introduced the following changes:

1. Addition of system_concept_of_operations grammar.
2. Addition of system_concept_of_operations folder and document with SEBoK definition of 'concept of operations (ConOps)'.
3. In system requirements for EU CRA, updated rationale for rephrased requirements to describe the purpose for the rephrasing and include the original text for reference.