SBOB specification — v0.0.4

Document

Software Bill of Behavior

Version

0.0.4

Stage

Proposed

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.

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.

1.4 Generalized rules: the portable set

Cell legend: Tool 1 cells abbreviate the rule’s CEL predicate, prefixed by its event type; the verbatim expressions are in the shipped rule set (default-rules.yaml, chart tag kubescape-operator-1.41.0-duckling16). native = shipped; generated = emitted from the SBOB by tooling; deny-list = expressible only as an explicit deny of the observed value; N/A = no equivalent found in the indexed sources.

1.4.1 Rules that read the SBOB

1.4.2 Signature rules; the SBOB allowlists who may perform them

These rules fire without an SBOB. The SBOB section for them is rulePolicies: per rule, the processes (processAllowed, by comm) or the whole container (containerAllowed) that are intended to perform the action. The engine implements the detection; the SBOB supplies the exemption.

1.4.3 rulePolicies in the SBOB

spec:
  rulePolicies:
    file-access:
      processAllowed: [logrotate]
    service-account-token-access:
      containerAllowed: true
    module-load:
      processAllowed: [modprobe]

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. Describes exactly one Pod with all ContainerTypes.
3. Populates at least spec.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. 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 on the pod
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 generalized rule names of §1.4, carrying the engine-specific rule ID alongside the name.

3. Document structure

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

kind: ContainerProfile
metadata:
  name: <name-unique-to-environment>   # mandatory; the pod label binds to this value
  namespace: <namespace>
spec:
  architectures: [...]
  imageID: <oci-image-with-digest>
  capabilities:   [...]
  endpoints:      [...]
  execs:          [...]
  opens:          [...]
  ingress:        [...]
  egress:         [...]
  rulePolicies:   { ... }

One document describes one container. A pod with several containers carries one ContainerProfile per container, each bound by its own label value.

4. Schema reference

4.1 Envelope

4.2 Sections

All sections sit directly under spec. There is no per-container list; init and ephemeral containers get their own ContainerProfile documents.

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.

The two stanzas mirror the Kubernetes NetworkPolicy model as closely as the runtime view allows: the same two directions, the same podSelector / namespaceSelector / ipBlock peer vocabulary, and the same ports[] shape. An SBOB SHOULD be expressible as a NetworkPolicy and a NetworkPolicy SHOULD be expressible as the observed-intent half of an SBOB, so that a declared profile and an enforced policy can be diffed against one another. Where the two diverge, the divergence is stated: an SBOB additionally carries dnsNames (a query name the workload resolved, which NetworkPolicy cannot express) and records observed addresses rather than admission-time selectors.

spec:
  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 rulePolicies

A map keyed by a generalized rule name (§1.4, kebab case) whose value says who is intended to perform that action. It is the SBOB’s allowlist for the signature rules of §1.4.2; the rules of §1.4.1 read their own sections and ignore it.

Key: the generalized rule name (namespace-change, module-load, …). The verifier maps it to its engine rule ID and carries both in the drift event.

Value:

rulePolicies:
  namespace-change:
    processAllowed: [runc]         # only runc may unshare
  file-access:
    processAllowed: [logrotate]

An entry for a rule the engine does not honour (§1.4.3) has no effect and MUST NOT be treated as a deny.

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

• egress[].ports[].port / ingress[].ports[].port — an absent port (null) means ANY PORT; an omitted ports stanza means any port on that peer. A populated ports[] matches only its literal (protocol, port) entries. The RFC 6335 numeric-0 sentinel does NOT apply at this field.

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:

kind: ContainerProfile
metadata:
  name: payment-app
  namespace: shop
  annotations: {kubescape.io/managed-by: User}
spec:
  imageID: ghcr.io/billofbehavior/payment-app@sha256:f6c18b0...

7.2 Full example with wildcards

kind: ContainerProfile
metadata:
  name: payment-app
  namespace: shop
  annotations:
  kubescape.io/managed-by: User
  sbob.io/spec-version: "0.0.4"
spec:
  architectures: [amd64]
  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}
  rulePolicies:
    namespace-change:            # §1.4.2 (kubescape R1006, Falco "Change namespace privileges via unshare")
      processAllowed: [runc]     # only runc may unshare
    module-load:                 # §1.4.2 (kubescape R1002, Falco "Linux Kernel Module Injection Detected", Tracee TRC-1017)
      containerAllowed: false    # same as omitting the entry; shown for clarity

8. Signatures

WIP

9. Security considerations

10. 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

11. 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 ContainerProfile CRD, schema source. https://github.com/kubescape/storage
• SBoB stack-profile extension, draft v0.0.3. spec-stackprofile-v0.0.1

Appendix A. Change log