Components representing inter-boundary communication need to declare the direction of data flow

[aj-stein-gsa]

Constraint Task

There must be at least one direction property, with no more than one incoming and no more than one outgoing direction.

Intended Outcome

Check that different kinds of network components for different leveraged authorizations and interconnection scenarios (see #808 (comment)) declare minimally required network traffic directions.

Syntax Type

This is required core OSCAL syntax.

Allowed Values

There are no relevant allowed values.

Metapath(s) to Content

<!-- Metapath context target -->
"//component[ (@type='service'  and not(./prop[@name='leveraged-authorization-uuid']) and ./prop[@name='implementation-point' and @value='external']) or (@type='interconnection') or (@type='service' and ./prop[@name='implementation-point' and @value='internal'] and ./prop[@name='direction']) or (@type='software' and ./prop[@name='asset-type' and @value='cli'] and ./prop[@name='direction']) ]"

<!-- Constraint requirements:   There must be at least one direction property, with no more than one incoming and no more than one outgoing direction -->
count(./prop[@name='direction'])>=1
count(./prop[@name='direction' and @value='incoming']) <= 1
count(./prop[@name='direction' and @value='outgoing']) <= 1


<!-- Constraint requirements:
        If ./prop[@name='direction' and @value='incoming'] 
        If direction is incoming there must be at least one local ipv4 address, ipv6 address, or URI to an API.
-->
count( (./prop[@class='local' and @name=('ipv4-address', 'ipv6-address')]) or (./link[@rel='uri']) ) >=1

<!-- Constraint requirements:
        If ./prop[@name='direction' and @value='incoming'] 
        If direction is incoming there must be at least one local protocol entry.
-->
count(./protocol[@name='local']/port-range/@start)

<!-- Constraint requirements:
        If ./prop[@name='direction' and @value='outgoing']
        If direction is outgoing there must be at least one remote ipv4 address, ipv6 address or URI to an API.
-->
count( (./prop[@class='remote' and @name=('ipv4-address', 'ipv6-address')]) or (./link[@rel='uri']) ) >=1
<!-- Constraint requirements:
       If ./prop[@name='direction' and @value='outgoing']
        If direction is outgoing there must be at least one remote ports entry. -->
count(./protocol[@name='remote']/port-range/@start) >= 1

Purpose of the OSCAL Content

To identify network traffic patterns for reviewers to know if it is properly risk-managed and conforms with FedRAMP requirements and best practices.

Dependencies

No response

Acceptance Criteria

• All OSCAL adoption content affected by the change in this issue have been updated in accordance with the Documentation Standards.
  • Explanation is present and accurate
  • sample content is present and accurate
  • Metapath is present, accurate, and does not throw a syntax exception using oscal-cli metaschema metapath eval -e "expression".
• All constraints associated with the review task have been created
• The appropriate example OSCAL file is updated with content that demonstrates the FedRAMP-compliant OSCAL presentation.
• The constraint conforms to the FedRAMP Constraint Style Guide.
  • All automated and manual review items that identify non-conformance are addressed; or technical leads (David Waltermire; AJ Stein) have approved the PR and “override” the style guide requirement.
• Known good test content is created for unit testing.
• Known bad test content is created for unit testing.
• Unit testing is configured to run both known good and known bad test content examples.
• Passing and failing unit tests, and corresponding test vectors in the form of known valid and invalid OSCAL test files, are created or updated for each constraint.
• A Pull Request (PR) is submitted that fully addresses the goals section of the User Story in the issue.
• This issue is referenced in the PR.

Other information

This is part of #807 and #808.

[brian-ruf]

@aj-stein-gsa / @DimitriZhurkin - it would be best to pause any constraint work dealing with /component/protocol until I finish my analysis of the "Ports, Protocols, and Services" section.
I am seeing some evidence that I need to rethink how this is represented for "interconnection" components.

In particular, I am expecting to make the following changes:

• eliminate the use of "local" and "remote" in the protocol/@name attribute. That should be used for the IANA registered service name. (i.e. "http", "https", "smtp", etc.)
• Move the "remote" protocol entry from the "interconnection" component to the "system" component that represents the far end of the interconnection.
• sever the relationship between the "direction" property and the expectation of a protocol assembly as "direction" is about data flow, and was not intended to reflect which end initiates the connection.

[brian-ruf]

These are still OK

• count(./prop[@name='direction'])>=1
• count(./prop[@name='direction' and @value='incoming']) <= 1
• count(./prop[@name='direction' and @value='outgoing']) <= 1

These incorrectly conflate data direction with connection direction and should not be created or should be dropped if already created:

• If direction is incoming there must be at least one local ipv4 address, ipv6 address, or URI to an API.
  count( (./prop[@Class='local' and @name=('ipv4-address', 'ipv6-address')]) or (./link[@rel='uri']) ) >=1

• If direction is incoming there must be at least one local protocol entry.
  count(./protocol[@name='local']/port-range/@start)

-If direction is outgoing there must be at least one remote ipv4 address, ipv6 address or URI to an API.
count( (./prop[@Class='remote' and @name=('ipv4-address', 'ipv6-address')]) or (./link[@rel='uri']) ) >=1

• If direction is outgoing there must be at least one remote ports entry.
  count(./protocol[@name='remote']/port-range/@start) >= 1

These incorrect items do not need to be replaced. This task can be closed when the first three count constraints are addressed.

[brian-ruf]

We need to pause this and discuss it. There are two items that put any further work on this at risk:

• the concept I proposed about bundling the data flow direction with the information type so that it is clear what information is crossing into the boundary and what is crossing out of the boundary.
• a head's up from @david-waltermire that the PMO is considering revisions to boundary guidance that is likely to impact how we model and enforce this content in OSCAL.

[brian-ruf]

Per conversations over the past two days there are actually three things happening with this issue.

Item 1: Potential changes to the FedRAMP requirements for Table 7-1 are "in the works" related to the pending boundary guidance; however, there is no clear ETA nor definition for this yet.

Decision on Item 1: We have agreed to continue working on OSCAL modeling, documentation, and constraints based on existing guidance. We will circle back to any changes once they are more clearly defined with a clearer ETA. We intend to insert OSCAL-rework into that boundary guidance release process.

Item 2: @DimitriZhurkin had started work on this and implemented the first constraint of four. I then realized that I had incorrectly used the "direction" property in the metapath. If we continue forward with this approach (vs Item #3 below) we need to rework the first constraint to use this revised metapath:

context="//component[
   (@type=('service', 'software') and not(./prop[@name='leveraged-authorization-uuid']) and  ./prop[@name='implementation-point' and @value='external'])
or
   (@type='interconnection')
or 
   (@type=('service', 'software') and ./prop[@name='implementation-point' and @value='internal'] and ./prop[@name='communicates-externally' and @value='yes' and @ns='http://fedramp.gov/ns/oscal'])
]"

Item 3: The current "direction" property in concert with the FedRAMP "information-type" prop/extension does not give a complete picture. It becomes ambiguous when the direction is both incoming and outgoing with more than one information type specified. We need clarity around which information is crossing the boundary on its way into the system vs crossing the boundary on its way out. As a result I proposed the use of @class on the "information-type" prop/extensions to indicate direction of boundary crossing. There has been no decision made on this proposal yet.

---

Regardless, the other constraints can still be worked, but with the revised target pasted in #2 above.

[aj-stein-gsa]

Item 3: The current "direction" property in concert with the FedRAMP "information-type" prop/extension does not give a complete picture. It becomes ambiguous when the direction is both incoming and outgoing with more than one information type specified. We need clarity around which information is crossing the boundary on its way into the system vs crossing the boundary on its way out. As a result I proposed the use of @class on the "information-type" prop/extensions to indicate direction of boundary crossing. There has been no decision made on this proposal yet.

Regardless, the other constraints can still be worked, but with the revised target pasted in #2 above.

Per discussion today, I support moving forward with item 2 and Item 3. Item 2 adds the prop[@name="communicates-externally"] and require the class on information types with a class of ingoing, outgoing, or doubled up for bi-directional like so.

         <prop name="information-type" value="C.3.5.1" class="incoming" ns="http://fedramp.gov/ns/oscal"/>
         <prop name="information-type" value="C.3.5.8" class="outgoing" ns="http://fedramp.gov/ns/oscal"/>

@brian-ruf and @Rene2mt agreed that's a good way forward. So the next steps:

1. (Short-term) We need to adjust the relevant acceptance criteria for the open issues not ready to ship.
2. (Medium to long-term) We need to notify the community even though it is develop, we are signaling the change is coming down the pike. We will send an email to the mailing list (and consider a website update if we need to call it out) and quickly brief in the next Implementers Meeting. (At a subsequent meeting we will do a deep dive.)

@brian-ruf or @Rene2mt, do I need to update the issues for 1? Did I understand correctly that it is just #930?

[brian-ruf]

@DimitriZhurkin consistent with @aj-stein-gsa decision above, please drop/remove any constraints related to the "direction" prop. The other constraints remain viable based on the redefined metapath in my above comment that replaced the "direction" prop with the "communicates-externally" prop/extension.

[DimitriZhurkin]

@brian-ruf, as regards "other constraints remain viable," they all include direction.

Please redefine constraints that need to be worked on. In the meantime, I'll remove the direction constraints and will pause working on this issue.

[brian-ruf]

@DimitriZhurkin as promised hours ago, here is the final update, with the whole issue re-summarized.

Drop these:

• count(./prop[@name='direction'])>=1
• count(./prop[@name='direction' and @value='incoming']) <= 1
• count(./prop[@name='direction' and @value='outgoing']) <= 1

Create/Revise These As Follows

context="//component[@type='interconnection']"

• "interconnection" components must have at least one remote IPv4 Address, IPv6 Address or URI

  • target="."
  • count( (./prop[@class='remote' and @name=('ipv4-address', 'ipv6-address')]) or (./link[@rel='uri']) ) >=1

• "interconnection" components must have at least one local IPv4 Address, IPv6 Address or URI

  • target="."
  • count( (./prop[@class='local' and @name=('ipv4-address', 'ipv6-address')]) or (./link[@rel='uri']) ) >=1

• For an "interconnection" component, at least one of the "used-by" linked components must have at least one protocol assembly.

  • target="."
  • count( //component[@uuid=//component[@type='interconnection']/link[@rel='used-by']/substring-after(@href, "#")]/protocol ) >=1

NOTE that the protocol construct had to move to one of the "used-by" components as there was no way within the protocol construct to indicate which end was "listening" on those ports if that construct remained within the "interconnection" component. (Core OSCAL states the @name attribute is supposed to contain the protocol name, and the title field is markup-line, which is not intended for machine readable values.