Do we need a deprecated status for Decision Points?

[ahouseholder]

The discussion in #370 reminded me that ADR-006 contains the following line:

• Multiple versions of decision points will be "live and available for use" by folks modeling decisions unless explicitly deprecated.
• We think that Decision Points SHOULD have a way to indicate a deprecated status as a means to stave off future regrets. This implies the need for a way to denote the status of a decision point in addition to its version. Decision Point status will need to be addressed in a separate decision (or decisions) regarding decision point lifecycles.

However, we currently have no mechanism to express this beyond noting in the documentation that a decision point has been deprecated, or superseded as in the case with Virulence evolving into Automatable.

So this issue is intended to lead to a decision of whether a documentation-level indication of deprecation is sufficient, or whether we need to reflect it in the data schema and corresponding object models.

[j---]

What would it look like for the code to issue a warning if a decision tree is using a deprecated or superseded version?
I'm thinking that deprecation warnings are fairly common in code, and that seems like if we were going to do this, it would be the right level of notification (rather than an error that stops the program).
I suppose a principle of usability would be that, ideally, we wouldn't make a human user do something that the software could do (like check version numbers). But this may not be a priority. Most people will likely just use the documentation, which is where the information currently is.

[ahouseholder]

I hadn't been thinking of UI, just of representing status in the data object. So for example:

SSVC/src/ssvc/decision_points/automatable.py

Lines 36 to 45 in e5567ee

	VIRULENCE_1 = SsvcDecisionPoint(
	name="Virulence",
	description="The speed at which the vulnerability can be exploited.",
	key="V",
	version="1.0.0",
	values=(
	SLOW,
	RAPID,
	),
	)

might get an extra line:

     deprecated = False,

which would then flow downstream into the JSON object and the documentation.

If we wanted to support more than just a binary deprecated status, we might consider something like a status field with an enumerated set of values to choose from. I'm inclined to say that would violate the YAGNI principle unless we have specific other statuses we need to reflect. Although I can think of of none at present, I'm open to discussion if there is any to be had.

Getting back to the UI question: We don't really have any sort of UI for SSVC aside from the policy generator tool etc. And we could decide separately whether they need to have any indication that one of the decision points they're using is deprecated. We can do that in this issue and address it in a single PR if appropriate, of course. I'm just noting that the questions:

• How to represent a deprecated decision point in the code
• How to inform a tool user that a decision point is deprecated

are distinct questions that could be answered independently.

I've also not thought about whether we need to do something similar with outcomes as well -- presumably whatever logic argues in favor of it with decision points might also apply to outcome sets. But outcomes seem to be more "shelf-stable", so maybe that's also ok to wait and see because YAGNI.

[j---]

OK, thanks. Good point we don't need to handle UI questions here. Agree.

Is deprecated = True useful without a reference to what it is deprecated by? Just putting pressure on whether a T/F flag is adequate. For version numbers, I think it is useful without further info, as a higher version number would do it. Superseded is more complex, as that's possibly non-obvious.

In that sense, I might actually argue for no flag for deprecated in a software engineering sense of a higher version number is available. Checking version numbers is easy enough. I might suggest instead a superseded flag would be a useful one, but then we might need a supersededBy variable if superseded = True?

[ahouseholder]

I'll probably need to extend this comment later, but the more I think about it we might want to institute a small decision point lifecycle.

---
title: Decision Point Lifecycle (3-state)
---
stateDiagram-v2
  direction LR
  [*] --> Proposed
  Proposed --> Supported
  Supported --> Deprecated

Loading

---
title: Decision Point Lifecycle (4-state)
---
stateDiagram-v2
  direction LR
  [*] --> Proposed
  Proposed --> Supported
  Supported --> Deprecated
  Supported --> Superseded
  Superseded --> Deprecated

Loading

I'm not committed to the state names, consider them placeholders for now. We might settle on other names later.

My rationale for this is

• We currently have a bunch of decision points that we have created but aren't actually in use by any model yet. (E.g., all the CVSS vector elements as decision points), and those seem like they are more "proposed" than "supported".
• We've talked previously about wanting to have some way to indicate a "long-term support" concept for some decision points.
• This thread appears to be converging on the need for at least 2 states ("supported" or its equivalent, and "deprecated")

3 states or 4?

I thought about whether Superseded is distinct from deprecated or not. I'm not sure at this point, but I think it might be more useful to think of it as a way to link decision point versions rather than a distinct lifecycle state.

On the one hand: We could potentially track the state using the 3-state model above, and have a separate optional field like supersededBy: that would serve to point to the replacement. If supersededBy: was absent or null, it would mean that the item has no suggested replacement. In the 3-state model, the supersededBy: could be non-null for any decision point in Proposed, Supported, or Deprecated. So we could have multiple versions in the Supported state simultaneously. That seems like it might be a good thing.

On the other hand: Using a separate Superseded state seems to imply that something that has been superseded is just deprecated with replacement. I'm not sure that this is as useful as the separate pointer idea in the previous paragraph.

Additional thoughts

A future process might emerge in which we periodically review the status of each extant decision point to decide whether it needs to move between these states. I think this could turn into a decent mechanism for managing the decision point vocabulary over time.

[j---]

Thanks!

(E.g., all the CVSS vector elements as decision points), and those seem like they are more "proposed" than "supported"

I might propose these are "informational". I'm trying to distinguish between "things you can get changed by creating an issue in this repository" (which I'd call proposed early on and then supported later) and "things we have copied from other documentation and we are not at liberty to change, go talk to the relevant documentation owner". CVSS would be this latter. The SIG makes changes to CVSS, we can just represent their outputs for convenience in this repository.

On the one hand: We could potentially track the state using the 3-state model above, and have a separate optional field like supersededBy: that would serve to point to the replacement.

This seems like the more intuitive option to me.

[ahouseholder]

I might propose these are "informational". I'm trying to distinguish between "things you can get changed by creating an issue in this repository" (which I'd call proposed early on and then supported later) and "things we have copied from other documentation and we are not at liberty to change, go talk to the relevant documentation owner". CVSS would be this latter. The SIG makes changes to CVSS, we can just represent their outputs for convenience in this repository.

I get your point that we are not the arbiters of CVSS vector elements, and we are in agreement on that.

I'm not clear on whether you're

• proposing informational as a distinct state from proposed, supported, and deprecated, or
• it's sort of just a particular type of decision point (that we'd still manage through a three-state lifecycle), but for which we'd redirect most semantic content related change requests to the appropriate authoritative source

An example of the latter would be: We have a decision point for CVSS Confidentiality Impact in https://github.com/CERTCC/SSVC/blob/main/src/ssvc/decision_points/cvss/confidentiality_impact.py

If someone suggests we change the wording of

SSVC/src/ssvc/decision_points/cvss/confidentiality_impact.py

Lines 110 to 117 in ad427b3

	_LOW_1 = SsvcDecisionPointValue(
	name="Low",
	key="L",
	description="There is some loss of confidentiality. Access to some restricted information is obtained, "
	"but the attacker does not have control over what information is obtained, or the amount or kind of "
	"loss is constrained. The information disclosure does not cause a direct, serious loss to the "
	"impacted component.",
	)

we would have to redirect them to the FIRST CVSS SIG because the description text came from the CVSS v4 spec.

However, if they were noting that our text in those lines was out-of-sync with a more recent version of CVSS, we'd still respond according to the status of the decision point. If it was deprecated, we could decline the change. If it were supported or proposed, we would likely need to make an adjustment.

I don't think informational rises to the level of being a lifecycle state. I think it's just a sort of annotation on a decision point that "We modeled this from somewhere else, and our intent in supporting it is to maintain synchronization with the source semantics. If you want to change the semantics, go to the authoritative source. If you want to help us keep our modeled implementation in sync with that source, and it's not deprecated, we'll be happy to consider your request."

[j---]

proposing informational as a distinct state from proposed, supported, and deprecated, or

I was thinking this first one.
Of course we will accept bug fixes and typos to things in our repo to make them match the informational source from which they're pulled. And we may, as a best effort thing, redirect comments to the appropriate information source. But I don't think we should take on anything that would imply we can be a trusted pass through for information to any other triage standards.

Part of this is we should only implement stuff in SSVC as informational that is finalized. If the CVSS SIG comes out with 4.1 and it changes some text, people can make a PR or an issue that creates any new informational points to add them to our library.

I get there is a distinction here in that we had to do some metric value version numbering for the CVSS metrics that is distinct from the CVSS versioning, as an exercise related to #322. But I wouldn't expect that to mean we are "supporting" those example metric version numbers. Is that a concern? Should we be doing that? it seems like a distraction to me.

[ahouseholder]

It seems to me that having different states implies having different service level expectations. What is the SLE distinction between "informational" and "supported" in this case?

I guess I'm not clear on what "supported" means for that matter.

Is it

• "currently in favor for use by SSVC implementers"? if so, should we call it "preferred" instead? Is "informational" disfavored/dispreferred? Or can something be both "informational" and "preferred"?
• "available for use by SSVC implementers"? if so, how is this different from "informational"?
• "we think it's pretty good at expressing a salient dimensional feature for one or more decisions we care about?" If so, then some of the CVSS decision points might also fall into this category.

Otherwise, it seems like for both "supported" and "informational":

• we take requests to make changes
• we can use them in example decision models
• they're available for SSVC implementers to use
• for "informational" we only make changes to maintain sync with some external enumeration

What if we went with four states as follows:

flowchart LR
subgraph supported
  available
  preferred
end

proposed --> available
proposed --> preferred
available --> preferred
preferred --> available
preferred --> deprecated
available --> deprecated

Loading

so most of the CVSS decision points land in available instead of preferred to start, but maybe some move up to preferred instead of reinventing or duplicating the vector elements.

I expect CVSS v1 and v2 elements to be largely static for the forseeable future, but I also don't see us ever starting to use them either, so technically they're available which costs us approximately zero in carrying costs.

We could even consider moving CVSSv4 Automatable and Value Density to preferred and our own versions to available with a supersededBy: pointing to the CVSSv4 ones. If CVSS vx (for x>4) removes either of them, we could still keep the CVSSv4 definitions as our preferred versions.

There is a practical consideration over the long term insofar as if we have an externally-sourced element that is basically dormant in the world (thinking of CVSSv1 vector elements for example) for which there are no known active data sources,
maybe we move those to deprecated? Is there a stop off before that? A state that says "continue using it if you're already dependent on it, but don't build new things with it"? (This would have been declining way back in the days of 1990s Corporate IT Architecture.)

---
title: Don't quote me on this
---
flowchart LR
experimental --> emerging
experimental --> exited
emerging --> core
emerging -->specialized
emerging --> declining
core --> specialized
specialized --> core
specialized --> declining
declining --> exited
core --> declining

Loading

I've kind of been thinking of a rough equivalence between:

SSVC states	90s IT Architecture states
???	experimental (we didn't really track these then either, this state was notional)
proposed	emerging - you can try it out but no commitments for long term support
preferred	core - ok for any use, long-term supported
available	specialized - ok to use in certain prescribed contexts
???	declining - ok for existing use, don't build new things with them
deprecated	exited - don't use it

[j---]

Thanks for expanding this out. Here's my thoughts on the difference (using these labels for now, point taken we may rename them once we decide what the SLEs actually mean)

Otherwise, it seems like for both "supported" and "informational":
we take requests to make changes
we can use them in example decision models
they're available for SSVC implementers to use
for "informational" we only make changes to maintain sync with some external enumeration

My thinking would be
For both:

• we can use them in example decision models
• they're available for SSVC implementers to use

For supported:

• we take, consider, and can make substantive changes

For informational:

• we make changes to maintain sync with some external enumeration

I think it's worth distinguishing between these kinds of change making.

I need to think more about these other ideas. Sorry, just wanted to do one idea at a time.

[ahouseholder]

For both:

• we can use them in example decision models
• they're available for SSVC implementers to use

For supported:

• we take, consider, and can make substantive changes

For informational:

• we make changes to maintain sync with some external enumeration

I think it's worth distinguishing between these kinds of change making.

That clarification helps.

I need to think more about these other ideas. Sorry, just wanted to do one idea at a time.

Understood.

I suppose while we're thinking about this kind of state machine, we should probably be working towards one that works for any of the formally-versioned things (Decision Points, Decision Point Groups, possibly future Outcomes, etc.)

[j---]

I suppose while we're thinking about this kind of state machine, we should probably be working towards one that works for any of the formally-versioned things (Decision Points, Decision Point Groups, possibly future Outcomes, etc.)

I'll actually recommend we do specific before we try to generalize. I guess there is no reason why we can't have informational outcome sets or groups. But the problem we have at hand is with decision points, not these other things. So I'm tempted to stick to solving the problem we actually have in front of us.

Can you say a little more about how you expect "available" to be used in practice?
I'm sensing that there might be significant overlap between "available" and "informational" as far as level of support we would provide here?

[ahouseholder]

Can you say a little more about how you expect "available" to be used in practice? I'm sensing that there might be significant overlap between "available" and "informational" as far as level of support we would provide here?

I think they're largely synonymous in terms of support. The difference is that "available" could include things we created for ourselves (i.e., that maybe were "preferred" at some point) whereas given the above thread, "informational" would only be applicable to stuff that originated outside of SSVC to begin with.

I don't know that "available" and "informational" are distinct states though. It's almost like the "informational" axis is kind of orthogonal to the "do we recommend using it" axis. Have to think about this some more maybe.

[j---]

Maybe we could simplify with a "supported --> available --> deprecated" workflow. And things that I've been thinking about as "informational" just enter directly into available status. Creation / proposal / ideation / experimentation by the SSVC community can make things that are started as "supported" when they are v1. I think we can already use the existing versioning regime to say some new idea is a v0.1 decision point with whatever name, and it doesn't become supported until the community decides it's stable enough to call it a v1.0. So that experimental phase definitely exists, but I don't know that it's a problem we need to solve with this status flag about deprecated / supported.

I guess what you called 3-state in #388 (comment) I'm suggesting adding something between supported and depreciated but otherwise keeping it linear, and I guess adding a new entry point where things can come in directly as available if they are from another source.
Implicit, I suppose, is a suggestion things don't go from supported to deprecated without spending some time in "available". Presumably, to test out their replacement that is now supported.