Capabilities (LCBS)

Lyx bindet jedes Programm an ein Capability-Modell: Der Compiler erzeugt aus den deklarierten Berechtigungen einen seccomp-Filter, der zur Laufzeit jeden nicht angeforderten Systemaufruf hart abbricht. Das Modell ist Zero-Privilege mit Default-Deny — was nicht ausdrücklich gewährt wurde, ist verboten.

Ohne Deklaration läuft ein Programm ungehärtet: der Compiler meldet Capability-Modell: NONE und erzeugt keinen seccomp-Filter.

→ Module und Importe · FFI · DO-178C

@capabilities steht vor allen anderen Deklarationen der Datei:

@capabilities([system.exit, system.memory.heap])
import std.io;

fn main(): int64 {
    PrintLn("Hallo");
    return 0;
}

Mehrere Berechtigungen werden mit Komma getrennt. Alternativ erlaubt @capabilities(dynamic) die Auflösung zur Laufzeit.

Ein unbekannter Name ist ein Compile-Fehler:

@capabilities([zzz.erfunden])
→ sema error: unbekannte Capability

Das sind alle 36 gültigen Namen der Registry (src/security/capabilities.lyx), nachgemessen mit lyxc 1.1.14A. Jeder andere wird mit unbekannte Capability abgewiesen.

Der seccomp-Filter ist fail-closed: was keine Capability nennt, wird beim Aufruf mit SIGSYS beendet (Exit 159). Hier zählen zwei verschiedene Dinge, das ist die häufigste Verwechslung:

Die Lücke ist also nicht 154 − 82, sondern die Differenz der Mengen: 101 Syscalls, für die es keine Schreibweise gibt. Ein Name deckt dabei viele Nummern ab — fs.read allein steht für open, read, lseek, stat und Verwandte. Zum Schließen braucht es deshalb keine 101 neuen Namen, sondern etwa zehn (io.wait, io.fd, system.tty, process.privileges, system.namespace, ipc.sysv, ipc.mqueue, fs.xattr, fs.watch, debug.trace, kernel.bpf) plus ein paar Erweiterungen bestehender Namen (system.time um nanosleep, memory.mmap um mremap/madvise, process.sched um sched_yield …). Der vollständige Zuordnungsvorschlag steht als Kommentar an #1865.

Erhoben mit 1.1.14A:

Auf –target=lyxos schreibt der Compiler die Berechtigungen als Bitmaske in die CAPS-TLV des LBF-Manifests. Der Kernel liest sie beim Laden und leitet daraus seine PLEDGE-Klassen ab. Auf allen anderen Zielen entsteht stattdessen ein seccomp-Filter — die Namen sind dieselben, der Mechanismus nicht.

Die Bitwerte stammen aus den Umsetzungsberichten zu #1755, #1759 und #1797 (die maßgebliche Belegung steht in src/std/lyxos/lbf_layout.lyx); die Zuordnung Name → Bit gibt der Compiler selbst aus, siehe unten. Zwei Dinge sind daran bemerkenswert:

• Die vier Gerätezugriffe teilen sich ein Bit. Der Kernel kennt genau eine Geräteklasse; eine feinere Trennung wäre eine Zusage, die sich nicht durchsetzen ließe. Aufteilen geht später, ohne bestehende Bedeutungen zu verschieben.
• hardware.block ist bewusst getrennt — PLEDGE_BLOCK ist im Kernel eine andere Klasse als der Gerätezugriff.

Ein Name, der kein Bit setzt, wird beim Übersetzen genannt statt stillschweigend verworfen:

warning: --target=lyxos: @capabilities(quatsch.blah) setzt kein Bit in der CAPS-TLV.
  Das LBF kommt beim Ladeprogramm an wie eines ohne Manifest (nur Standardausgabe).
  Abgebildet sind: fs.read, fs.write, network.*, process.*, ki.embed, ki.graph,
  audio.*, system.config, hardware.block, hardware.i2c/usb/gpio/spi.

Drei Capabilities sind implizit gesetzt, weil ohne sie kein Programm startet:

Jeder import kann angeben, welche Berechtigungen die eingebundene Unit erhalten soll. grant zählt auf, was weitergegeben wird, restrict nimmt zurück:

@capabilities([system.exit, system.memory.heap, fs.read])
import std.io grant [system.exit];
import std.fs grant [fs.read];

Beides lässt sich am selben Import kombinieren, und mehrere Imports stehen wahlweise in einer Deklaration:

import std.io grant [system.exit], std.string grant [system.exit];

Eine Unit kann nur bekommen, was das aufrufende Modul selbst besitzt. Diese Prüfung greift zur Übersetzungszeit:

sema error: grant enthält Capability die nicht in Parent-Capabilities ist

Jede std-Unit trägt inzwischen ein eigenes @capabilities. Damit ist grant keine bloße Absichtserklärung mehr, sondern wird gegen die Deklaration des Moduls geprüft. Drei Fälle, mit 1.1.14A gemessen:

Ein Bau gelingt also erst, wenn grant genau das aufzählt, was die Unit deklariert, und das Programm dieselben Rechte in seinem eigenen @capabilities führt:

@capabilities([system.exit, system.memory.heap,
               fs.create, fs.delete, fs.meta, fs.perm, fs.read, fs.write, system.time])
import std.fs grant [fs.create, fs.delete, fs.meta, fs.perm, fs.read, fs.write, system.time];

Das ist unbequem und soll es sein: wer std.fs einbindet, führt danach sichtbar sieben Rechte — statt sie unbemerkt mitzunehmen. Wer weniger will, bindet eine kleinere Unit ein.

Eine Funktion, die eine Berechtigung des Aufrufers benötigt, deklariert das ausdrücklich. Geprüft wird gegen die aufrufende Funktion — diese muss die Berechtigung selbst per @capabilities tragen. Die Angabe am Dateikopf genügt dafür nicht:

@capabilities([system.exit, system.memory.heap, fs.read])
import std.io;

@uses_caller_cap([fs.read])
fn LiesKonfiguration(): int64 {
    return 0;
}

@capabilities([fs.read])
fn main(): int64 {
    PrintLn(IntToStr(LiesKonfiguration()));
    return 0;
}

Fehlt das @capabilities an main, wird der Aufruf abgelehnt:

sema error: Caller hat nicht: fs.read (benötigt von @uses_caller_cap)

Das gilt auch für implizite Capabilities: @uses_caller_cap([system.exit]) verlangt ebenfalls ein ausdrückliches @capabilities([system.exit]) an der aufrufenden Funktion.

extern fn ohne passende Capability wird abgewiesen — nicht gewarnt, sondern abgelehnt:

sema error: extern fn: unbekanntes FFI-Symbol erfordert @capabilities([...])
            (FFI-Sandbox Fail-Closed)

Ein FFI-Aufruf ist damit immer eine bewusste, sichtbare Entscheidung.

Jeder Build gibt eine Bewertung aus. Sie zeigt unmittelbar, was die Deklaration bewirkt:

# ohne @capabilities
Capability-Modell: NONE (kein @capabilities -- keine LCBS-Haertung)
Sicherheits-Score: 33/45
  + 0: seccomp fehlt
  +8: Grant-Modell -- 1 Import(e) ohne grant (-2 pro fehlendem grant)

# mit @capabilities und vollständigen grants
+ seccomp (SECCOMP_RET_KILL_PROCESS, 53 Regeln)
Sicherheits-Score: 45/45
  +10: Grant-Modell -- alle Imports haben explizites grant
  + 5: seccomp aktiv

Weitere Posten: W^X (getrennte PT_LOAD-Segmente), RELRO, und der Nachweis, dass keine Klasse-3-Extern-Funktion ohne system.unsafe.format_string verwendet wird. PIE ist derzeit nicht implementiert (+0).

Der erzeugte seccomp-Filter arbeitet mit SECCOMP_RET_KILL_PROCESS. Ein nicht gewährter Systemaufruf beendet den Prozess sofort:

@capabilities([system.exit, system.memory.heap])
import std.fs;

fn main(): int64 {
    if (FileExists("/etc/hostname"c)) { return 1; }
    return 0;
}

$ ./programm
Ungültiger Betriebssystemaufruf (Speicherabzug geschrieben)
$ echo $?
159

Mit fs.read in der Liste läuft dasselbe Programm durch.

Eine Capability kann Argumente tragen, die ihren Geltungsbereich einschränken:

@capabilities([system.exit, system.memory.heap, fs.read(path: "/tmp")])

Der Argumentname wird geprüft — ein Tippfehler wie pfad: wird mit unbekanntes Capability-Argument abgewiesen.

path: an einer fs-Capability wird seit lyxc 1.0.15E durchgesetzt. Der Compiler legt je genanntem Pfad eine eigene Landlock-Regel an, mit genau den Zugriffsarten der Capability, zu der das Argument gehört. Ein Lesen außerhalb schlägt zur Laufzeit fehl:

@capabilities([system.exit, system.memory.heap, fs.read(path: "/tmp")])
// ReadFile("/etc/hostname"c, …) -> -1;  mit fs.read(path: "/etc") -> gelesene Bytes

Zwei Regeln dazu:

• Die pauschale “/„-Regel entfällt genau dann, wenn alle fs-Capabilities einen Pfad tragen. Trägt auch nur eine keinen, bleibt sie stehen — ein einzelnes fs.write ohne path: hebt die Beschränkung der übrigen also faktisch auf.
• Existiert ein genannter Pfad nicht, wird keine Regel angelegt und der Zugriff bleibt verboten (fail-closed).

Weiterführende Seiten:

• Module und Importe — grant/restrict im Kontext
• FFI — externe Funktionen einbinden
• Attribute und Pragmas

Letzte Aktualisierung: 2026-09-05 (#1826, nachgemessen mit lyxc 1.2.2B) — ki.embed/ki.graph sind inzwischen deklarierbar, werden im Audit aber nicht geführt; audio.play erscheint dort als unknown. Tabelle und Kasten entsprechend gezogen.

Vorherige letzte Aktualisierung: 2026-08-27 — CAPS-TLV am Erzeugnis nachgemessen (0x41 für fs.read, hardware.block); Kernel-Abbildung von 0x100 auf PLEDGE_DEVICE bestätigt. Namensliste gegen lyxc 1.1.11B neu erhoben (31 statt 25 Namen: system.config aus #1797, hardware.* aus #1755/#1759); Abschnitt 2b zur CAPS-TLV des LBF-Manifests ergänzt.

Letzte Aktualisierung: 2026-08-30 — Registry gegen src/security/capabilities.lyx abgeglichen (36 Namen statt 31, ki.embed/ki.graph/audio.mic ergänzt) und Abschnitt „Was sich damit NICHT anfordern lässt“ aufgenommen (#1865–#1873, aus dieser Prüfung gemeldet).

Zuvor 2026-08-30 — grant wird seit 1.1.12E gegen die @capabilities der importierten std-Unit geprüft (#1340); die drei Fälle gegen 1.1.14A gemessen.

Vorherige Aktualisierung: 2026-08-13 — process.signal ist seit lyxc 1.0.17K deklarierbar (#1198).

Codebeispiele geprüft: gegen lyxc 1.2.5C übersetzt (Prüflauf 2026-09-08 über die gesamte Doku: 574 Vollprogramme, 0 echte Fehler; zusätzlich 5159 Aufrufe gegen die pub fn-Signaturen in aurum/std gehalten, 0 Abweichungen).