Skip to content

Commit 2b8c5af

Browse files
ahouseholderahouseholder
committed
add namespaces docs
1 parent 494dbbd commit 2b8c5af

File tree

1 file changed

+300
-0
lines changed

1 file changed

+300
-0
lines changed

‎docs/reference/code/namespaces.md‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,303 @@
11
# SSVC Namespaces
22

3+
We use namespaces in SSVC to organize the various components of the framework.
4+
The bulk of our work is done in the `ssvc` namespace, which contains the core
5+
decision points for SSVC.
6+
7+
!!! question "Why does SSVC need namespaces?"
8+
9+
We want to provide a clear way to differentiate between decision points we
10+
developed as part of the SSVC project, and those that are derived from work
11+
done by other projects. This helps us maintain clarity in our codebase and
12+
to avoid confusion when integrating with other systems or libraries.
13+
14+
!!! tip "Namespace syntax"
15+
16+
The syntax for namespaces is `<base>/<extensions>`, where
17+
18+
- `base` is the name of the namespace
19+
- `extensions` is an optional set of extensions that can be used to further
20+
specify the decision point. Extensions are delimited by a `/`
21+
22+
See below for additional details on SSVC namespace extensions.
23+
24+
!!! note "Namespace Requirements"
25+
26+
A full namepace string must be between 3 and 1000 characters long. (We recommend
27+
keeping them short ease of use.)
28+
29+
Further requirements are noted in each section below.
30+
31+
32+
## Registered Namespaces
33+
34+
Registered namespaces appear in the `Namespaces` enum, and are intended to be used as follows:
35+
36+
- Objects in the `ssvc` namespace are managed by the SSVC
37+
project team. We have complete control over these ones.
38+
- Objects in other explicitly registered namespaces are provided for convenience,
39+
but the SSVC team is not responsible for modifying the content or semantics of
40+
those decision points.
41+
42+
!!! note "Base Namespace Requirements"
43+
44+
Base namespaces must start with a letter and contain only lowercase
45+
alphanumeric characters, dots (`.`), and dashes (`-`).
46+
The sole exception is the the `x_` prefix for private namespaces described below.
47+
48+
Consecutive dots or dashes or combinations thereof are not allowed.
49+
Base namespaces cannot end with a dot or dash.
50+
51+
For base namespaces only, we chose to use lowercase alphanumeric
52+
characters to ensure consistency and avoid confusion when using namespaces
53+
in code. (Extensions may contain mixed case alphanumeric characters, dots, and dashes.)
54+
55+
The SSVC project may create, at our discretion, new namespaces to reflect
56+
administrative scope for decision points we choose to include for user convenience.
57+
58+
!!! example "Potential Standards-based namespaces"
59+
60+
We may in the future add namespaces when needed to reflect different standards
61+
bodies like `nist`, `iso-iec`, `ietf`, `oasis`, etc.
62+
63+
!!! question "How do I request a new registered namespace?"
64+
65+
If you have a suggestion for a new registered namespace, please open an
66+
issue in the [SSVC GitHub repository](https://github.com/CERTCC/SSVC/issues)
67+
and provide a brief description of the namespace and its intended use.
68+
69+
### Current Registered Namespaces
70+
71+
```python exec="true" idprefix=""
72+
from ssvc.namespaces import NameSpace
73+
74+
for ns in NameSpace:
75+
print(f"- {ns.value}")
76+
```
77+
78+
### Non-`ssvc` Namespaces
79+
80+
We use namespaces other than `ssvc` to indicate decision points that are based
81+
externally defined standards, specifications, or relevant projects.
82+
We expect for decision points in these namespaces to be technically compatible
83+
with SSVC, but we do not claim any ownership or responsibility for the
84+
underlying specifications or their semantic content.
85+
Objects in these namespaces are provided for the convenience
86+
of SSVC users to allow them to use these decision points in their SSVC
87+
decision models without needing to implement them from scratch.
88+
89+
While we are happy to resolve technical issues with these decision points as
90+
technically implemented in the SSVC project, all suggestions for changes to the
91+
underlying specifications or semantic content should be directed to the
92+
maintainers of the respective projects or standards.
93+
94+
!!! example "The `cvss` namespace"
95+
96+
We wanted to allow SSVC users to include Common Vulnerability Scoring System
97+
(CVSS) vector elements as [decision points](../decision_points/cvss/index.md)
98+
in their SSVC decision models.
99+
So we created the `cvss` namespace to contain
100+
[decision points](../decision_points/cvss/index.md) that are
101+
based on various versions of the CVSS. These
102+
[decision points](../decision_points/cvss/index.md) are provided
103+
as part of the SSVC project for convenience, but we do not maintain the
104+
underlying CVSS specifications, their semantic content or their implementations.
105+
Suggestions for changes to the CVSS specifications should be directed to the
106+
[FIRST CVSS Special Interest Group](https://www.first.org/cvss/) (SIG).
107+
108+
109+
## Private / Experimental Namespaces
110+
111+
Private and experimental namespaces may prepend a prefix `x_` to a namespace
112+
to an otherwise valid namespace string to create private decision points that
113+
are not intended to be shared outside of a specific scope, e.g., for internal
114+
use only.
115+
116+
The SSVC project does not manage namespaces with the `x_` prefix, so
117+
collisions may occur across organizations who develop their own private SSVC
118+
namespaces.
119+
120+
!!! example "OT Monitoring Service (OTMS) Private Namespace"
121+
122+
Organization A creates a set of decision points for testing purposes and
123+
uses the `x_test` namespace. They do not intend to share these decision
124+
points with anyone outside of their organization, so they use the `x_`
125+
prefix to indicate that this namespace is private to them.
126+
127+
Organization B also creates a set of decision points for testing purposes
128+
and uses the same `x_test` namespace. They also do not intend to share
129+
these decision points with anyone outside of their organization.
130+
131+
!!! warning "Namespace Conflicts"
132+
133+
Conflicts are possible in the x_ prefix space.
134+
In the previous example, Organizations A and B could both choose to use
135+
`x_test`, and there are no guarantees of global uniqueness for the
136+
decision points in the `x_test` namespace.
137+
138+
!!! tip "Private vs Extension Namespaces"
139+
140+
Private namespaces are intended for internal use only and are not registered
141+
with the SSVC project. They are not intended to be shared or used outside of
142+
the organization that created them. In contrast, extension namespaces are
143+
intended to extend the existing SSVC namespaces and may be shared with other
144+
users of the SSVC framework.
145+
146+
## Namespace Extensions
147+
148+
We allow users to extend the SSVC namespaces to clarify existing decision
149+
points or to add new decision points that are compatible with the SSVC framework.
150+
The intent of an extension is to allow clarification of the application of
151+
decision points and their values to specific constituencies.
152+
153+
- Extensions must not alter the decision point key, version number, or value keys
154+
for any decision point they are derived from.
155+
- Extensions must not alter the meaning of existing values, or add values to
156+
existing decision points in the parent namespace.
157+
- Extensions may reduce the set of values for a decision point in the parent
158+
namespace, but must not add new values.
159+
160+
161+
!!! info "Namespace Extension Syntax and Structure"
162+
163+
Extension strings may contain alphanumeric characters (upper or lower case),
164+
dots (`.`), and dashes (`-`).
165+
Multiple extension segments are separated by a `/` character.
166+
167+
The structure of the namespace string is intended to show inheritance for
168+
variations on SSVC objects.
169+
170+
Extension order matters. `ssvc/de-DE/ref-arch-1` would describe an extension
171+
for `ref-arch-1` derived from the German (Germany) translation of SSVC.
172+
`ssvc/ref-arch-1/de-DE` would denote an extension of SSVC for `ref-arch-1`
173+
(in English) that had subsequently been translated in to German (Germany).
174+
175+
176+
!!! note "First Extension Segment Reserved for Language Tag"
177+
178+
The first extension segment is reserved for a language tag, which is
179+
optional but recommended.
180+
This allows users to specify the language of extension, making it easier to
181+
understand and use in different linguistic contexts.
182+
183+
If *any* extensions are present, the first extension segment must be an
184+
(optionally empty)
185+
[BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag.
186+
E.g., `ssvc/jp-JP/extension`
187+
188+
The language may be left empty in which case the default language (`en-US`) is
189+
implied. An unspecified language tag will result in a `<base>//<extension>` format.
190+
191+
The use of a language tag in the first segment is intended to be used to
192+
indicate translations of entire sets of decision points.
193+
194+
!!! example "Translation and Localization"
195+
196+
`ssvc/de-DE` might denote a German translation of the corresponding `ssvc` object.
197+
198+
!!! example "Refinement of Concepts for a Specific Constituency"
199+
200+
A sector-specific information sharing and analysis organization (ISAO)
201+
might create an extension for their specific constituency.
202+
For example, say that namespace foo has a decision point for
203+
Regulated System=(Y,N). A medical-focused ISAO might create an extension
204+
`foo//example.med-isao` where they refine the values to refer to specific
205+
regulations. If multiple regulatory regimes exist, they might even have
206+
`foo//example.med-isao/regulation-1` and `foo//example.med-isao/regulation-2`
207+
to cover assessment of the appropriate regulations.
208+
209+
210+
### Usage Suggestions
211+
212+
Although we reserved the first segment of the extension for language tags,
213+
there are scenarios where it may be appropriate to use a language tag in a later
214+
segment of the extension.
215+
216+
!!! tip "Use BCP-47 Language Tags"
217+
218+
Regardless where they appear in the extension strings, we recommend using
219+
BCP-47 strings for any language-based extension. Note, however that we do not
220+
strictly enforce this recommendation in the SSVC codebase outside of the
221+
first segment.
222+
223+
!!! example "Translation of a custom extension"
224+
225+
If you have a custom extension that is not a translation of an existing
226+
decision point, you might use a language tag in a later segment to indicate
227+
a translation of the extension.
228+
For example, `ssvc//com.example/extension/pl-PL` would indicate that the
229+
an extension in the default `en-US` language has been translated to Polish (Poland).
230+
231+
!!! tip "Use Reverse Domain Name Notation for Extensions"
232+
233+
To avoid conflicts with other users' extensions, we recommend using reverse
234+
domain name notation for your extensions. This helps to ensure that your
235+
extensions are unique and easily identifiable.
236+
237+
!!! example "Reverse Domain Name Notation"
238+
239+
If your organization has a domain name, you can use it as the base for your
240+
extension. This helps to ensure that your extensions are unique and easily
241+
identifiable.
242+
243+
For example, if your organization is `example.com`, you might use an extension
244+
like `ssvc//com.example/extension`.
245+
246+
247+
## Technical requirements
248+
249+
The following technical requirements are enforced for SSVC namespaces,
250+
based on the implementation in `src/ssvc/namespaces.py` and the NS_PATTERN regular expression:
251+
252+
```python exec="true" idprefix=""
253+
from ssvc.namespaces import NS_PATTERN
254+
255+
print(f"`{NS_PATTERN.pattern}`")
256+
```
257+
258+
- **Length**: Namespaces must be between 3 and 1000 characters long.
259+
- **Base Namespace**:
260+
- Must start with a lowercase letter.
261+
- Must contain at least 3 total characters in the base part (after the optional experimental/private prefix).
262+
- Only lowercase letters, numbers, dots (`.`), and hyphens (`-`) are allowed.
263+
- Must not contain consecutive dots or hyphens (no `..`, `--`, `.-`, `-.`, `---`, etc.).
264+
- Cannot end with a dot or hyphen.
265+
- May optionally start with the experimental/private prefix `x_`.
266+
- **Experimental/Private Namespaces**:
267+
- Must start with `x_` followed by a valid base namespace.
268+
- **Extensions (Optional)**:
269+
- Extensions are optional and must be delineated by slashes (`/`).
270+
- If present, the first extension segment must be a valid BCP-47 language tag or empty (`//`).
271+
- Subsequent extension segments:
272+
- Must start with a letter (upper or lowercase).
273+
- May contain letters, numbers, dots (`.`), and hyphens (`-`).
274+
- Must not start or end with a dot or hyphen.
275+
- Must not contain consecutive dots or hyphens.
276+
- Are separated by single forward slashes (`/`).
277+
- Multiple extension segments are allowed.
278+
- **Examples of valid namespaces**:
279+
- `ssvc`
280+
- `cisa`
281+
- `x_private-test`
282+
- `ssvc/de-DE/reference-arch-1`
283+
- `x_custom//extension` (empty language tag)
284+
- **Examples of invalid namespaces**:
285+
- `custom` (not in enum, no `x_` prefix)
286+
- `x_custom/extension` (first segment must be a language tag)
287+
- `x_custom.extension.` (ends with punctuation)
288+
- `x_custom..extension` (double dot)
289+
- `x_custom/` (ends with slash)
290+
- `x_custom/extension//` (double slash at end)
291+
- `ab` (too short)
292+
- `x_` (too short after prefix)
293+
294+
These requirements are strictly enforced by the `NS_PATTERN` regular expression
295+
in the codebase. For full details, see the documentation below and
296+
implementation in `src/ssvc/namespaces.py`.
297+
298+
## The `ssvc.namespaces` module
299+
300+
The `ssvc.namespaces` module provides a way to access and use these namespaces.
301+
3302
::: ssvc.namespaces
303+

0 commit comments

Comments
 (0)