A container may declare the capabilities it is granted (hq ADR 0169)

Exactly the names declared reach the runtime, named in the spec so a change
recreates the container; a name that is not a capability's is refused and a
privileged container stays undeclarable. For a seat holder whose runtime
changes the machine's packet filter.

internal/declaration/declaration.go

@@ -940,6 +940,12 @@ type Container struct {
 	// its siblings can name before any of them can resolve anything.
 	Dns []string `json:"dns,omitempty"`
 
+	// Capabilities are the Linux capabilities this container is granted beyond the runtime's
+	// default set, by name (novox/hq ADR 0169): a holder's runtime that changes the machine's packet
+	// filter asks for NET_ADMIN. Exactly these, named in the spec so a change recreates the
+	// container; a privileged container stays undeclarable.
+	Capabilities []string `json:"capabilities,omitempty"`
+
 	// Networks are networks this container also joins once created, by name — a found network a
 	// per-machine setting keeps for a taken container (novox/hq ADR 0163, rule 4), so a
 	// neighbour that resolves it there keeps resolving it until the neighbour is taken too.
@@ -1039,6 +1045,12 @@ func (c *Container) validate(where string, _ bool) []string {
 				"static address anywhere but a user-defined one")
 		}
 	}
+	for _, cap := range c.Capabilities {
+		if !capabilityName.MatchString(cap) {
+			problems = append(problems, where+": capabilities names "+strconv.Quote(cap)+", which is not a "+
+				"capability's name (CAP_NET_ADMIN or NET_ADMIN)")
+		}
+	}
 	for _, n := range c.Networks {
 		problems = append(problems, (&Network{Name: n}).validate(where+": networks", false)...)
 		if n == c.Network {
@@ -1209,6 +1221,10 @@ type Adoption struct {
 	Untaken map[string][]string `json:"untaken,omitempty"`
 }
 
+// capabilityName is what a Linux capability is called: upper case, underscores, an optional CAP_
+// prefix. The runtime accepts either spelling.
+var capabilityName = regexp.MustCompile(`^(CAP_)?[A-Z][A-Z0-9_]*$`)
+
 // AdoptionPrefix is the id prefix of what the mesh itself declares because a node is adopted —
 // its openings and its guard. Nothing under it belongs to a module, so none of it is ever held.
 const AdoptionPrefix = "adoption."

internal/declaration/declaration_test.go

@@ -504,3 +504,23 @@ func TestKeptNetworksAndLeftOutModulesAreReadStrictly(t *testing.T) {
 		t.Fatalf("a carried bundle leaving modules out was accepted: %v", err)
 	}
 }
+
+// A container may ask for a capability by name, and nothing else (novox/hq ADR 0169).
+func TestACapabilityIsNamedOrRefused(t *testing.T) {
+	image := "postgres@sha256:" + strings.Repeat("a", 64)
+	d, err := Parse([]byte(`{"declaration":1,"resources":[
+	  {"id":"fw","type":"container","name":"fw","image":"` + image + `","network":"host","capabilities":["NET_ADMIN","CAP_NET_RAW"]}
+	]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := d.Resources[0].(*Container).Capabilities; len(got) != 2 || got[0] != "NET_ADMIN" {
+		t.Fatalf("capabilities read as %v", got)
+	}
+	for _, bad := range []string{`"net_admin"`, `"ALL;rm -rf /"`, `"privileged"`} {
+		if _, err := Parse([]byte(`{"declaration":1,"resources":[
+		  {"id":"fw","type":"container","name":"fw","image":"` + image + `","capabilities":[` + bad + `]}]}`)); err == nil {
+			t.Errorf("%s was accepted as a capability", bad)
+		}
+	}
+}