Security Controls Action Documentation

.gitignore

@@ -1,4 +1,5 @@
 .idea/
 node_modules/
 *.iml
+internal/tools/bin/
 

CHANGELOG.md

@@ -8,6 +8,17 @@
 
 ### Fixes
 
+## v0.4.0 (2024-12-17)
+
+### Breaking
+
+### Features
+
+- add definitions for custom security control actions.
+  ([#8](https://github.com/Contrast-Security-OSS/secobs-semantic-conventions/pull/8))
+
+### Fixes
+
 ## v0.3.0 (2024-03-06)
 
 ### Breaking

docs/actions/security-control.md

@@ -0,0 +1,20 @@
+# Semantic Conventions for `security-control` Actions
+
+Used when span name is `security-control`.
+
+<!-- semconv contrast.action.span.security-control(full) -->
+| Attribute                 | Type | Description                                                  | Examples                              | Requirement Level |
+|---------------------------|---|--------------------------------------------------------------|---------------------------------------|-------------------|
+| `security.control.method` | string | The method of the custom security control.                   | `com.Acme.OldSecurity.DoLegacySecurity` | Required          |
+| `security.control.name`   | string | The name of the custom security control.                     | "My Custom Security Control"           | Recommended       |
+| `security.control.rules`  | string | The rules applicable to the custom security control.         | `reflected-xss`; `path-traversal` | Recommended       |
+| `security.control.type`   | string | The custom security control type.                            | `sanitizer`; `validator`              | Recommended       |
+
+`security.control.type` MUST be one of the following:
+
+| Value               | Description     |
+|---------------------|-----------------|
+| `sanitizer`         | Sanitizer       |
+| `input-validator`   | Input Validator |
+| `regex-validator`   | Regex Validator |
+<!-- endsemconv -->

model/metrics/contrast-actions.yaml

@@ -49,6 +49,9 @@ groups:
             - id: ognl-execution
               value: "ognl-execution"
               brief: "Object-Graph Navigation Language expression execution."
+            - id: security-control
+              value: "security-control"
+              brief: "Custom security controls defined by the user."
 
   - id: attributes.contrast.action.metric
     extends: attributes.contrast.actions

model/trace/contrast-actions.yml

@@ -191,16 +191,59 @@ groups:
           "#{20 - 1}",
           "'Just a string value'.substring(5)"
         ]
+
   - id: contrast.action.span.el-execution
     type: span
     extends: attributes.contrast.code-exec
     brief: >
       Describes attributes for Contrast Action span of type el-execution. The Spring Expression Language (SpEL for short) is a
       powerful expression language that supports querying and manipulating an object graph at runtime.
+
   - id: contrast.action.span.ognl-execution
     extends: attributes.contrast.code-exec
     type: span
     brief: >
       Describes attributes for Contrast Action span of type ognl-execution. OGNL stands for Object-Graph Navigation Language.
       It is an expression language for getting and setting properties of Java objects, plus other extras such as list projection
       and selection and lambda expressions. You use the same expression for both getting and setting the value of a property.
+
+  - id: contrast.action.span.security-control
+    type: span
+    brief: >
+      Describes attributes for Contrast Action span of type security-control.
+    attributes:
+      - id: method
+        brief: >
+          The method of the custom security control.
+        requirement_level: required
+        examples: [ com.Acme.OldSecurity.DoLegacySecurity ]
+        type: string
+      - id: name
+        brief: >
+          The name of the custom security control.
+        requirement_level: recommended
+        examples: [ "My Custom Security Control" ]
+        type: string
+      - id: rules
+        brief: >
+          The rules applicable to the custom security control.
+        requirement_level: recommended
+        examples: [ reflected-xss; path-traversal ]
+        type: string
+      - id: type
+        brief: >
+          The custom security control type.
+        requirement_level: recommended
+        examples: [ sanitizer; input-validator ]
+        type:
+          allow_custom_values: false
+          members:
+            - id: sanitizer
+              value: sanitizer
+              brief: Sanitizer
+            - id: input-validator
+              value: input-validator
+              brief: Input Validator
+            - id: regex-validator
+              value: regex-validator
+              brief: Regex Validator

schema-next.yaml

@@ -2,6 +2,7 @@ file_format: 1.1.0
 schema_url: https://github.com/Contrast-Security-OSS/secobs-semantic-conventions/releases/download/next/next
 versions:
   next:
+  0.4.0:
   0.3.0:
   0.2.0:
   0.1.0:

schemas/0.4.0

@@ -0,0 +1,7 @@
+file_format: 1.1.0
+schema_url: https://github.com/Contrast-Security-OSS/secobs-semantic-conventions/releases/download/v0.4.0/0.4.0
+versions:
+  0.4.0:
+  0.3.0:
+  0.2.0:
+  0.1.0: