So 164 authzn attributes

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,7 @@ Fixes #
 
 Please provide a brief description of the changes here.
 
-Note: if the PR is touching an area that is not listed in the 
+Note: if the PR is touching an area that is not listed in the
 [existing areas](https://github.com/Contrast-Security-OSS/secobs-semantic-conventions/blob/main/docs/README.md),
 or the area does not have sufficient
 [domain experts coverage](https://github.com/Contrast-Security-OSS/secobs-semantic-conventions/blob/main/.github/CODEOWNERS),

.prettierignore

@@ -0,0 +1,5 @@
+/.github
+/docs/**
+/model
+/schemas
+

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- add definitions for authentication and authorization actions.
+  ([#1](https://github.com/Contrast-Security-OSS/secobs-semantic-conventions/pull/2))
+
 ## Breaking
 
 ## Features

Makefile

@@ -20,7 +20,7 @@ SEMCONVGEN_VERSION=0.22.0
 OTEL_SEMCONV_VERSION=1.22.0
 
 .PHONY: all
-all: install-tools markdownlint markdown-link-check yamllint misspell table-check \
+all: install-tools markdown-toc table-generation fix-format check yamllint \
 		 check-file-and-folder-names-in-docs
 
 .PHONY: check-file-and-folder-names-in-docs

docs/README.md

@@ -16,7 +16,7 @@ for a foundational understanding of what we build on top of.
 
 Security Observability Semantic Conventions are defined for the following areas:
 
-- [Actions](actions/README.md): Semantic Conventions for cloud providers libraries.
+- [Actions](actions/README.md): Semantic Conventions for actions.
 
 Semantic Conventions by signals:
 

docs/actions/README.md

@@ -9,19 +9,20 @@ as part of a sampling activity.
 
 <!-- toc -->
 
-- [Http Actions](#http-actions)
+- [Actions](#actions)
   * [Metric: `http.server.action.total`](#metric-httpserveractiontotal)
+  * [Spans](#spans)
 
 <!-- tocstop -->
 
-## Http Actions
+## Actions
 
 ### Metric: `http.server.action.total`
 
 <!-- semconv metric.http.server.action.total(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `action` | string | The type of action that was observed. | `file-open-create`; `authn-request` | Required |
+| [`action`](action-spans.md) | string | The type of action that was observed. | `file-open-create`; `authn-request` | Required |
 | `http.method` | string | http method used when the action was encountered. | `GET`; `POST` | Required |
 | `http.route` | string | http route used when the action was encountered. | `/foo/bar` | Required |
 
@@ -38,7 +39,11 @@ as part of a sampling activity.
 | `smtp-exec` | Functions that result in an SMTP command execution |
 | `outbound-service-call` | Functions that result in external calls to other services |
 | `authn-request` | Functions that perform authentication actions |
-| `authz-request` | Functions that perform authorization  actions |
+| `authz-request` | Functions that perform authorization actions |
 | `el-execution` | Spring expression language execution |
 | `ognl-execution` | Object-Graph Navigation Language expression execution. |
 <!-- endsemconv -->
+
+### Spans
+
+- [Action Spans](action-spans.md): Semantic Conventions for Action _spans_.

docs/actions/action-spans.md

@@ -0,0 +1,106 @@
+# Contrast Action Spans
+
+<!-- toc -->
+
+- [Definitions](#definitions)
+- [Action Span Attributes](#action-span-attributes)
+  * [Authentication Span](#authentication-span)
+  * [Authorization Span](#authorization-span)
+
+<!-- tocstop -->
+
+## Definitions
+
+The span name MUST be set to the action name:
+
+```
+<action name>
+```
+
+Valid action names are are listed in the action attribute for metrics:
+
+<!-- semconv attributes.contrast.actions(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `action` | string | The type of action that was observed. | `file-open-create`; `authn-request` | Required |
+
+`action` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `storage-query` | Functions that execute queries |
+| `file-open-create` | file open or create action |
+| `url-forward` | Any function designed to forward a request to another URL |
+| `url-redirect` | Function that result in an http 302 redirect code sent to the client |
+| `host-cmd-exec` | system shell command execution |
+| `ldap-query` | Functions that result in and ldap query operation |
+| `smtp-exec` | Functions that result in an SMTP command execution |
+| `outbound-service-call` | Functions that result in external calls to other services |
+| `authn-request` | Functions that perform authentication actions |
+| `authz-request` | Functions that perform authorization actions |
+| `el-execution` | Spring expression language execution |
+| `ognl-execution` | Object-Graph Navigation Language expression execution. |
+<!-- endsemconv -->
+
+## Action Span Attributes
+
+Each Action Span has attributes that describe the action observed. For instance, an `authn-request` span
+will list the authentication mechanism along with other authentication-related attributes
+An action span for the `storage-query` action will have a different set of attributes
+targeted toward describing that action.
+
+### Authentication Span
+
+Used when span name is `authn-request`
+
+<!-- semconv contrast.action.span.authn(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `contrast.authentication.mechanism` | string | An authentication mechanism is a specific method or approach used to verify the identity of a user, system, or entity attempting to access a resource. | `password`; `token`; `biometric` | Recommended |
+| `contrast.authentication.protocol` | string | An authentication protocol is a set of rules and procedures that dictate how authentication mechanisms should operate to establish trust and verify identities securely. | `oauth`; `saml`; `ldap`; `custom` | Recommended |
+
+`contrast.authentication.mechanism` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `password` | Users provide a username and password. |
+| `certificate` | x509 certificate authentication or similar |
+| `token` | Involves using a physical or virtual token to authenticate a user |
+| `biometric` | file open or create action |
+| `mfa` | Two or more of the above mechanisms are used |
+
+`contrast.authentication.protocol` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `saml` | Security Assertion Markup Language |
+| `oauth` | Open Authentication and OIDC |
+| `ldap` | Lightweight Directory Access Protocol |
+| `kerberos` |  |
+<!-- endsemconv -->
+
+### Authorization Span
+
+Used when span name is `authz-request`
+
+<!-- semconv contrast.action.span.authz(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `contrast.authorization.dac.permission` | string | Permission requested for access to the resource. The values here are very domain specific, but will always be normalized to a lowercase value in the data here. | `read`; `write`; `append`; `delete` | Recommended: If mechanism is 'dac' |
+| `contrast.authorization.mac.labels` | string | Labels on the requested resource. The values here are very domain specific, but will always be normalized to a lowercase value in the data here. | `top_secret`; `confidential`; `internal`; `public` | Recommended: If mechanism is 'mac' |
+| `contrast.authorization.mechanism` | string | How are authz decisions made for the resource. | `rbac`; `dac`; `pbac` | Recommended |
+| `contrast.authorization.rbac.role` | string | Role Requested for authz check. The values here are very domain specific, but will always be normalized to a lowercase value in the data here. | `user`; `editor`; `manager` | Recommended: If mechanism is 'rbac' |
+
+`contrast.authorization.mechanism` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `rbac` | Role Based Access Control |
+| `abac` | Attribute Based Access Control |
+| `mac` | Mandatory Access Control (MAC) is a security model where access to resources is determined by the security labels assigned to subjects (users or processes) and objects (resources). |
+| `dac` | Discretionary Access Control (DAC) is a model where owners of resources have the discretion to control access to their resources. |
+| `pbac` | Policy Based Access Control |
+| `hbac` | History Based Access Control |
+| `tbac` | Time Based Access Control |
+| `pbac` | Policy Based Access Control |
+<!-- endsemconv -->

model/contrast-actions.yml

@@ -1,22 +1,8 @@
 groups:
-  - id: attributes.contrast.action
+  - id: attributes.contrast.actions
     type: attribute_group
-    brief: "Describes attributes for Contrast Action metrics"
+    brief: "Actions that we track in Contrast"
     attributes:
-      - id: http.method
-        type: string
-        requirement_level: required
-        brief: >
-          http method used when the action was encountered.
-        examples:
-          - GET
-          - POST
-      - id: http.route
-        type: string
-        requirement_level: required
-        brief: >
-          http route used when the action was encountered.
-        examples: "/foo/bar"
       - id: action
         brief: >
           The type of action that was observed.
@@ -56,14 +42,33 @@ groups:
               brief: "Functions that perform authentication actions"
             - id: authz-request
               value: "authz-request"
-              brief: "Functions that perform authorization  actions"
+              brief: "Functions that perform authorization actions"
             - id: el-execution
               value: "el-execution"
               brief: "Spring expression language execution"
             - id: ognl-execution
               value: "ognl-execution"
               brief: "Object-Graph Navigation Language expression execution."
 
+  - id: attributes.contrast.action.metric
+    type: attribute_group
+    brief: "Describes attributes for Contrast Action metrics"
+    attributes:
+      - id: http.method
+        type: string
+        requirement_level: required
+        brief: >
+          http method used when the action was encountered.
+        examples:
+          - GET
+          - POST
+      - id: http.route
+        type: string
+        requirement_level: required
+        brief: >
+          http route used when the action was encountered.
+        examples: "/foo/bar"
+
   - id: metric.http.server.action.total
     type: metric
     metric_name: http.server.action.total
@@ -74,3 +79,136 @@ groups:
       - ref: action
       - ref: http.method
       - ref: http.route
+
+  - id: attributes.contrast.action.span.authn
+    prefix: contrast.authentication
+    type: span
+    brief: "Describes attributes for Contrast Action span of type authn-request"
+    attributes:
+      - id: mechanism
+        brief: >
+          An authentication mechanism is a specific method or approach used to
+          verify the identity of a user, system, or entity attempting to access a resource.
+        examples: [password, token, biometric]
+        type:
+          allow_custom_values: false
+          members:
+            - id: password
+              value: "password"
+              brief: "Users provide a username and password."
+            - id: certificate
+              value: "certificate"
+              brief: "x509 certificate authentication or similar"
+            - id: token
+              value: "token"
+              brief: "Involves using a physical or virtual token to authenticate a user"
+            - id: biometric
+              value: "biometric"
+              brief: "file open or create action"
+            - id: mfa
+              value: "mfa"
+              brief: "Two or more of the above mechanisms are used"
+
+      - id: protocol
+        brief: >
+          An authentication protocol is a set of rules and procedures that
+          dictate how authentication mechanisms should operate to establish
+          trust and verify identities securely.
+        examples: [oauth, saml, ldap, custom]
+        type:
+          allow_custom_values: false
+          members:
+            - id: saml
+              value: "saml"
+              brief: "Security Assertion Markup Language"
+            - id: oauth
+              value: "oauth"
+              brief: "Open Authentication and OIDC"
+            - id: ldap
+              value: "ldap"
+              brief: "Lightweight Directory Access Protocol"
+            - id: kerberos
+              value: "kerberos"
+              brief: ""
+
+  - id: attributes.contrast.action.span.authz
+    prefix: contrast.authorization
+    type: span
+    brief: >
+      Describes attributes for Contrast Action span of type authz-request
+    attributes:
+      - id: mechanism
+        brief: >
+          How are authz decisions made for the resource.
+        examples: [rbac, dac, pbac]
+        type:
+          allow_custom_values: false
+          members:
+            - id: rbac
+              value: "rbac"
+              brief: Role Based Access Control
+            - id: abac
+              value: "abac"
+              brief: Attribute Based Access Control
+            - id: mac
+              value: "mac"
+              brief: >
+                Mandatory Access Control (MAC) is a security model where access to resources is determined by
+                the security labels assigned to subjects (users or processes) and objects (resources).
+            - id: dac
+              value: "dac"
+              brief: Discretionary Access Control (DAC) is a model where owners of resources have the discretion to control access to their resources.
+            - id: pbac
+              value: "pbac"
+              brief: Policy Based Access Control
+            - id: hbac
+              value: "hbac"
+              brief: History Based Access Control
+            - id: tbac
+              value: "tbac"
+              brief: Time Based Access Control
+            - id: pbac
+              value: "pbac"
+              brief: Policy Based Access Control
+
+      - id: rbac.role
+        brief: >
+          Role Requested for authz check. The values here are very domain specific, but
+          will always be normalized to a lowercase value in the data here.
+        examples: [user, editor, manager]
+        type: string
+      - id: dac.permission
+        brief: >
+          Permission requested for access to the resource. The values here are very domain specific, but
+          will always be normalized to a lowercase value in the data here.
+        examples: [read, write, append, delete]
+        type: string
+      - id: mac.labels
+        brief: >
+          Labels on the requested resource. The values here are very domain specific, but
+          will always be normalized to a lowercase value in the data here.
+        examples: [top_secret, confidential, internal, public]
+        type: string
+
+  - id: contrast.action.span.authn
+    type: span
+    brief: "Describes attributes for Contrast Authentication Action spans"
+    attributes:
+      - ref: contrast.authentication.mechanism
+      - ref: contrast.authentication.protocol
+
+  - id: contrast.action.span.authz
+    type: span
+    brief: "Describes attributes for Contrast Authorization Action spans"
+    attributes:
+      - ref: contrast.authorization.mechanism
+        requirement_level: recommended
+      - ref: contrast.authorization.rbac.role
+        requirement_level:
+          recommended: If mechanism is 'rbac'
+      - ref: contrast.authorization.dac.permission
+        requirement_level:
+          recommended: If mechanism is 'dac'
+      - ref: contrast.authorization.mac.labels
+        requirement_level:
+          recommended: If mechanism is 'mac'