SBOB specification — v0.0.3

Document

Software Bill of Behavior

Version

0.0.3

Stage

Proposed

Status

First implementation is being tested, Feedback welcome

Where to report comments

Typos: https://github.com/billofbehavior/fusioncore-web

Abstract

A Software Bill of Behavior (SBOB) is a signed, declarative document that states what a piece of software is intended to do at runtime — specifically, which Linux capabilities it requires, which files it expects to open, which child processes it spawns, which network destinations it accepts/establishes.

This document specifies version 0.0.3 of the SBOB document format. It does not specify in how many seperate files such a spec would be supplied, only the definitions of the fields.

1. Introduction

1.1 What an SBOB is for

The SBOB expresses, in machine-readable and human-readable form, the prescriptive intent of the software author: the set of behaviors the software is designed to exhibit.

The quality of an SBOB can be judged by:

• its ability to distinguish malicious from intentional behavior
• its transferability (portability) across linux-based systems
• its compatibility with standard gitOps tooling
• its usability by humans (time to first detection)

1.1.1 Kernel vs User-Space: Universal Applicability

The SBOB is designed to make runtime security more achievable, not to replace existing approaches such as the Linux Security Modules.

To serve all application languages, an SBOB is based on the lowest common denominator: the Linux Kernel and for high-compatibility, we will rely on the ABI or other long-term-stable elements.

1.2 Relationship to existing standards

1.3 Conformance language

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

Reference implementation

This specification is in continuous feedback interaction with its reference implementation in CNCF Kubescape . We use two markers:

2. Conformance

A conformant SBOB document is a (set of) YAML document(s) that:

1. Has the envelope described in §4.1, with apiVersion, kind, metadata, and spec populated.
2. Contains at least one entry under spec.containers[].
3. Populates each entry with at least name and imageID, plus any of the structural sections (§4.3 through §4.8) that apply.
4. If any field uses a wildcard or pattern, that pattern conforms to §5.
5. is of kind spdx.softwarecomposition.kubescape.io/v1beta1
6. Distinguishes absent fields (NULL) from explicit-empty fields (NONE) per §5.4 in its YAML form, even when the underlying language binding collapses the two.

A conformant verifier:

1. Matches the SBOB name using a label kubescape.io/user-defined-profile or user-defined-network
2. Implements every match step in §6 against every section of §4 that the document populates.
3. Treats absent fields (NULL — non-deterministic, implementation-defined posture) and explicit empty-collection fields (NONE — declared zero-activity, hard violation on first observation) differently (§5.4).
4. Reports its NULL-handling posture (deny / log-only / learn-mode) at startup so operators know what their absent-field workloads will encounter.
5. Emits drift events keyed by the canonical action verbs in Appendix B, carrying the engine-specific rule ID alongside the verb.

3. Document structure

An SBOB document is a single YAML stream containing one Kubernetes-style resource.

apiVersion: spdx.softwarecomposition.kubescape.io/v1beta1
metadata:
  name: <name-unique-to-environment> #mandatory
spec:
  architectures: [...]
  containers:
  - type: init| null
  - name: <container-name> #mandatory
    imageID: <oci-image-with-digest>
    capabilities:   [...]
    endpoints:      [...]
    execs:          [...]
    opens:          [...]
    egress:         [...]
    policyBinding:  { ... }

4. Schema reference

4.1 Envelope

4.2 Container entry

The container lifecycle phase (regular / init / ephemeral) is currently not implemented as a field on the entry. Only, Kubernetes PodSpec convention — is supported:

• spec.containers[] — regular workload containers
• spec.initContainers[] — init containers (run to completion before the regular containers start)
• spec.ephemeralContainers[] — debug / sidecar ephemeral containers (added post-creation)

4.3 capabilities

A list of Linux capabilities that the workload is permitted to hold. Each entry MUST be a token from the kernel’s capabilities(7) manual page, in upper-case (e.g. CAP_NET_BIND_SERVICE).

capabilities: [CAP_SETGID, CAP_SETPCAP, CAP_SETUID]

A verifier MUST emit a violation if the live process holds any capability not listed. The absence of the field carries a different meaning from explicit empty (capabilities: []) — see §5.4.

4.4 endpoints

A list of HTTP-level endpoints the workload is expected to expose (direction: inbound) or call (direction: outbound).

endpoints:
- endpoint: ":0/api/data"   # any port, exact path
  methods: [GET, POST]      
  headers: null             # explicit, no extra headers expected
  direction: outbound

The desired degree of specificity in methods and headers is under debate

4.5 execs

A list of processes that the workload is permitted to spawn (via execve).

execs:
- path: /usr/sbin/apache2          # exact installation path
  args: [/usr/sbin/apache2, '⋯⋯']  # anchored argv[0] then any tail
- path: /⋯/apache2                 # relative installation path
  args: [/⋯/apache2, '⋯⋯']         

4.6 opens

A list of file paths the workload is permitted to open, with the open-flag combinations under which it is permitted to open them.

opens:
- flags: [O_RDONLY, O_WRONLY, O_CREAT]
  path: /var/log/apache2/*       # any descendant (1+ segments under, never the bare dir)
- flags: [O_RDONLY]
  path: /etc/resolv.conf         # exact
- flags: [O_RDONLY, O_WRONLY]
  path: /opt/*/vendor/app/node/*  # mid-path * is 0+ segments (§5.1), trailing * is 1+ segments
- flags: [O_RDONLY, O_WRONLY]
  path: /opt/⋯/vendor/app/node/*  # mid-path ⋯ is 1 segments (§5.1), trailing * is 1+ segments

4.7 egress and ingress

Two parallel lists the workload is permitted to exchange traffic with:

• egress[] — destinations the workload is permitted to dial (it initiates the connection)
• ingress[] — peers the workload is permitted to accept connections from (the peer initiates)

Both lists carry entries of the same shape (table below) and are evaluated by symmetric verifier paths.

spec:
  containers:
  - name: payment-app
    egress:
    - identifier: stripe-api
      type: external
      ipAddresses: ["162.0.217.171/32"]     
      dnsNames: [*.api.stripe.com.]
      ports:
      - {name: TCP-443, protocol: TCP, port: 443}
    - identifier: cluster-dns
      type: internal
      namespaceSelector:
        matchLabels: {kubernetes.io/metadata.name: kube-system}
      podSelector:
        matchLabels: {k8s-app: kube-dns}
      ports:
      - {name: UDP-53, protocol: UDP, port: 53}
    ingress:
    - identifier: load-balancer-health
      type: internal
      ipAddresses: ["10.244.0.0/16"]      # TBD: should there be a K8S-SVC-CIDR etc placeholder
      ports:
      - {name: TCP-8080, protocol: TCP, port: 8080}
    - identifier: prometheus-scrape
      type: internal
      namespaceSelector:
        matchLabels: {kubernetes.io/metadata.name: monitoring}
      podSelector:
        matchLabels: {app.kubernetes.io/name: prometheus}
      ports:
      - {name: TCP-9090, protocol: TCP, port: 9090}

4.8 policyBinding

A map keyed by a vendor-neutral action verb whose value is a fine-grained allow / deny clause for that action.

Key: engine-specific rule ID, currently a numerical value referencing the CEL rule in kubescape (e.g. R0001).

Value :

policyBinding:
  syscall.unshare:           # vendor-neutral verb (in kubescape `Rule1006`)
    allowProcess: [runc]     # only runc may unshare

Future: The action verb namespace shall use lower-snake-case strings, prefixed by category:
exec.* (process spawning),
file.* (filesystem activity),
net.* (network),
syscall.* (raw syscalls) WIP

5. Pattern and wildcard semantics

Relevant to abstract exact kernel events into a semantic and portable description of intent.

5.1 Path wildcards * and ⋯

Two wildcard tokens are defined for path components.

⋯ (U+22EF) — exactly one segment. A single Unicode codepoint, NOT three ASCII periods. Matches one full path segment (zero-or-more characters that do not contain /). Spelt distinctly to avoid colliding with accidential use of globs.

* (PathWildcard) — variable arity, position-dependent.

• When * appears mid-path (i.e. there are more segments after it), it matches zero or more consecutive segments.
• When * appears trailing (last segment of the pattern), it matches one or more remaining segments — never zero.

5.3 Exec-argument wildcards

The * and ⋯ tokens of §5.1 are path wildcards. An exec entry’s args vector uses

• ⋯⋯ (WildcardExecs) — zero or more arguments. Absorbs a run of consecutive argv entries, including none: [/bin/foo, '⋯⋯'] matches /bin/foo with any tail (or none), whereas [/bin/foo] matches only the bare invocation with no arguments.

* is not an argument wildcard — inside args it is a literal asterisk.

5.4 Absent (NULL) vs explicit-empty (NONE)

TBD

5.6 Port wildcards

Ports appear in two contexts curretly

• endpoints[].endpoint string — for http, use the integer 0 to express the intent of ANY PORT. :0/api/data

• NetworkNeighbor.ports[].port — TODO

5.7 IP address matching

Matches an observed IP against an ipAddresses[] list using these forms in order. Each entry is one of:

5.8 DNS name matching

Matches an observed DNS name (from the workload’s own getaddrinfo / res_query event see §8.2) against the dnsNames[]

Rationale for the token choices

• Leading * = exactly one label is RFC 4592
• Mid-label * is non-standard — bind/coredns reject it, cilium uses regex, Calico has its own glob form. v0.0.2 deliberately uses the project’s existing ⋯ token for the mid position, so the wire format never claims RFC 4592 compliance for a non-standard shape and producers’ intent is unambiguous.
• Trailing * = one-or-more matches the path semantic in §5.1 — a trailing * MUST consume at least one label, never zero, so mycorp.com.* does not silently allow access to the bare apex.

Apex matching

*.example.com. does NOT match the bare apex example.com. — same defensive rule as path-side trailing-*. Producers that intend the apex MUST list example.com. as a separate dnsNames entry. Same rule for <prefix>.* trailing form.

Empty / ** rejection

A dnsNames[i] containing ** (recursive wildcard) MUST be rejected

List semantics

The verifier matches each observed name against EVERY entry in dnsNames; an observation that matches ANY entry passes. Entries are unordered. A NONE list (dnsNames: []) per §5.4 means “no DNS traffic intended” — any DNS observation is a hard violation.

6. Verifier algorithm

WIP

7. Examples

7.1 Minimal example

The smallest legal SBoB:

apiVersion: spdx.softwarecomposition.kubescape.io/v1beta1
kind: ApplicationProfile
metadata:
  name: payment-app
spec:
  containers:
  - name: payment-app
    imageID: ghcr.io/billofbehavior/payment-app@sha256:f6c18b0...

7.2 Full example with wildcards

apiVersion: spdx.softwarecomposition.kubescape.io/v1beta1
kind: ApplicationProfile
metadata:
  name: payment-app
  annotations:
    sbob.io/spec-version: "0.0.3"
spec:
  architectures: [amd64]
  containers:
  - name: payment-app
    imageID: ghcr.io/billofbehavior/payment-app@sha256:f6c18b0...
    capabilities: [CAP_SETGID, CAP_SETPCAP, CAP_SETUID]
    endpoints:
    - endpoint: ":0/api/data"     # any port, exact path
      methods: [GET, POST]
      headers: null               # explicit: no extra headers
      direction: outbound
    execs:
      path: /usr/sbin/apache2                  # intended exact path
    - args: [/usr/sbin/apache2, '⋯⋯']          # zero-or-more trailing args
    - path: /usr/lib/postgresql/⋯/bin/postgres # version number does NOT matter 
      args: ["postgres"]
    - path: /usr/lib/postgresql/16/bin/initdb  # version number DOES matter
      args: ["initdb"]
    opens:
    - flags: [O_RDONLY, O_WRONLY, O_CREAT]
      path: /var/log/apache2/*       # any descendant (1+ segments under, never the bare dir)
    - flags: [O_RDONLY]
      path: /etc/resolv.conf         # exact
    - flags: [O_RDONLY, O_WRONLY]
      path: /opt/*/vendor/app/node/*  # mid * is 0+ segments, trailing * is 1+ segments
    egress:
    - identifier: stripe-api
      type: external
      ipAddresses:                       # v0.0.2 plural form, supersedes singular ipAddress
        - "162.0.217.171"                # IPv4 literal
        - "2001:db8::/32"                # IPv6 CIDR (§5.7)
      dnsNames:                          # supersedes the deprecated single dns field
        - api.stripe.com.                # literal FQDN
        - "*.api.stripe.com."            # RFC 4592 leading-* — exactly one label (§5.8)
      ports:
      - {name: TCP-443, protocol: TCP, port: 443}
    - identifier: cluster-dns
      type: internal
      namespaceSelector:
        matchLabels: {kubernetes.io/metadata.name: kube-system}
      podSelector:
        matchLabels: {k8s-app: kube-dns}
      ports:
      - {name: UDP-53, protocol: UDP, port: 53}
    - identifier: kube-svc-resolver       # demonstrates the mid-label ⋯ form
      type: internal
      dnsNames:
        - "svc.⋯.cluster.local."         # leaves NAMESPACE label open to user
      ports:
      - {name: UDP-53, protocol: UDP, port: 53}
    policyBinding:
      syscall.unshare:         # canonical verb (kubescape R1006, see Appendix B)
        allowProcess: [runc]   # only runc may unshare
      kernel.module_load:      # kubescape R1002 / Falco "Linux Kernel Module Loaded"
        allowProcess: []       

7.3 Companion stack-profile example

WIP: extend the document above with CPU stack profile + abstraction handles, see spec-stackprofile-v0.0.1

8. Security considerations

Spec maturity

This is v0.0.3, a pre-1.0 specification. Field names and semantics are stabilising but MAY still change between minor versions; every change is recorded in Appendix A, and conformance claims MUST cite a pinned version.

9. Open issues

• Generalisation of rules: names and verbs
• Notations for common network-masks such as {pod_cidr} to be discoverable/replaceable by bobctl
• Implementation and example of bundling and signing of bundles
• Support for pod-lifecycle
• Guidance on useful syscalls

10. References

• RFC 2119, Key words for use in RFCs to Indicate Requirement Levels. https://www.rfc-editor.org/rfc/rfc2119
• RFC 8174, Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. https://www.rfc-editor.org/rfc/rfc8174
• capabilities(7), Linux manual page. https://man7.org/linux/man-pages/man7/capabilities.7.html
• open(2), Linux manual page. https://man7.org/linux/man-pages/man2/open.2.html
• RFC 6335, Internet Assigned Numbers Authority (IANA) Procedures for the Management of the Service Name and Transport Protocol Port Number Registry — note on port 0. https://www.rfc-editor.org/rfc/rfc6335
• kubescape ApplicationProfile CRD, schema source. https://github.com/kubescape/storage
• SBoB stack-profile extension, draft v0.0.3. spec-stackprofile-v0.0.1

Appendix B. Vendor rule-name mapping

B.1 Process / exec verbs

B.2 File-access verbs

B.3 Syscall verbs

B.4 Capability verbs

B.5 Network verbs

B.6 Credential / kernel verbs

B.7 Cryptominer heuristics

B.8 Profile-integrity verbs

B.9 Producer guidance

Appendix A. Change log