air_sys_syscall/

security.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Wrappers de la famille `security` — seccomp-BPF primitif et Landlock.
//!
//! Cf. `docs/specs/layer-0/family-security.md`.
//!
//! **API primitive couche 0 :** cette crate charge un programme BPF
//! précompilé tel quel dans le kernel (pas de compilation BPF ici).
//! La couche 1 fournira l'API déclarative (règles → BPF).

#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
compile_error!("air-sys-syscall::security supporte uniquement x86_64 et aarch64 (ADR-014).");

use air_sys_types::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
use core::mem::size_of;
use core::num::NonZeroI32;

use air_sys_types::Errno;
use air_sys_types::security::{
    LandlockAccessFs, LandlockAccessNet, LandlockRestrictFlags, LandlockScope, SeccompFilterFlags,
    SockFprog,
};

// ─────────────────────────────────────────────────────────────────────────
// Numéros de syscalls
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
const SYS_SECCOMP: i64 = 317;
#[cfg(target_arch = "aarch64")]
const SYS_SECCOMP: i64 = 277;

#[cfg(target_arch = "x86_64")]
const SYS_LANDLOCK_CREATE_RULESET: i64 = 444;
#[cfg(target_arch = "aarch64")]
const SYS_LANDLOCK_CREATE_RULESET: i64 = 444;

#[cfg(target_arch = "x86_64")]
const SYS_LANDLOCK_ADD_RULE: i64 = 445;
#[cfg(target_arch = "aarch64")]
const SYS_LANDLOCK_ADD_RULE: i64 = 445;

#[cfg(target_arch = "x86_64")]
const SYS_LANDLOCK_RESTRICT_SELF: i64 = 446;
#[cfg(target_arch = "aarch64")]
const SYS_LANDLOCK_RESTRICT_SELF: i64 = 446;

// ─────────────────────────────────────────────────────────────────────────
// Constantes kernel
// ─────────────────────────────────────────────────────────────────────────

/// `seccomp(2)` — mode strict (seuls read/write/_exit/sigreturn autorisés).
const SECCOMP_SET_MODE_STRICT: u32 = 0;
/// `seccomp(2)` — charge un filtre BPF précompilé.
const SECCOMP_SET_MODE_FILTER: u32 = 1;

/// `landlock_create_ruleset(2)` — drapeaux : requête de version ABI.
const LANDLOCK_CREATE_RULESET_VERSION: u32 = 1;

/// `landlock_add_rule(2)` — type de règle : chemin filesystem.
const LANDLOCK_RULE_PATH_BENEATH: i32 = 1;

/// `landlock_add_rule(2)` — type de règle : **port TCP** (ABI v4+, Linux 6.7).
const LANDLOCK_RULE_NET_PORT: i32 = 2;

// ─────────────────────────────────────────────────────────────────────────
// Structures kernel internes (repr C, non exposées)
// ─────────────────────────────────────────────────────────────────────────

/// Attributs d'un ruleset Landlock (cf. `linux/landlock.h`).
#[repr(C)]
struct KernelLandlockRulesetAttr {
    handled_access_fs: u64,
}

/// Attributs d'un ruleset Landlock **ABI v4+** — deux champs (cf. `linux/landlock.h`).
///
/// **Une structure distincte, et non un champ ajouté à la précédente.** Le noyau lit
/// exactement `size` octets : passer seize octets à un noyau qui n'en connaît que huit
/// échoue `E2BIG`. Garder les deux formes permet de n'employer la seconde que lorsque
/// l'ABI la supporte, plutôt que de dégrader silencieusement.
#[repr(C)]
struct KernelLandlockRulesetAttrV4 {
    handled_access_fs: u64,
    handled_access_net: u64,
}

/// Attributs d'un ruleset Landlock **ABI v6+** — trois champs (cf. `linux/landlock.h`).
///
/// Le troisième champ, `scoped`, ne porte **pas** des droits sur des ressources : il borne
/// ce qu'un domaine peut atteindre **hors** de lui-même — sockets UNIX abstraits et signaux,
/// deux voies qu'aucune règle par chemin ne pouvait voir.
///
/// **Une troisième structure**, pour la même raison qui en imposait une deuxième : le noyau
/// lit exactement `size` octets, et présenter vingt-quatre octets à un noyau qui n'en connaît
/// que seize échoue `E2BIG`. La pose de cage étant *fail-closed*, cet échec tuerait le
/// processus sur un noyau parfaitement valide.
#[repr(C)]
struct KernelLandlockRulesetAttrV6 {
    handled_access_fs: u64,
    handled_access_net: u64,
    scoped: u64,
}

/// Attributs d'une règle Landlock de type `NET_PORT` (cf. `linux/landlock.h`, ABI v4+).
#[repr(C)]
struct KernelLandlockNetPortAttr {
    allowed_access: u64,
    /// Port en **ordre hôte**, sur 64 bits — le noyau l'exige ainsi, malgré la
    /// tentation de croire qu'un port de réseau voyage en ordre réseau.
    port: u64,
}

/// Attributs d'une règle Landlock de type `PATH_BENEATH` (cf. `linux/landlock.h`).
#[repr(C)]
struct KernelLandlockPathBeneathAttr {
    allowed_access: u64,
    parent_fd: i32,
}

/// `struct sock_fprog` tel que vu par le kernel sur LP64 (x86_64/aarch64).
///
/// Sur LP64 : `{ u16 length, 6 octets de padding, u64 filter_ptr }` = 16 octets.
/// Le padding est nécessaire pour aligner le pointeur sur 8 octets.
#[repr(C)]
struct KernelSockFprog {
    len: u16,
    _pad: [u8; 6],
    filter: u64,
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscalls bruts (privés, spécifiques à l'architecture)
// ─────────────────────────────────────────────────────────────────────────

/// Effectue `seccomp(op, flags, uargs)` et retourne la valeur brute i64.
///
/// # Safety
///
/// L'appelant est responsable de la validité de `uargs` pour l'opération
/// demandée. Pour `SECCOMP_SET_MODE_FILTER`, `uargs` doit pointer sur un
/// `KernelSockFprog` valide dont les instructions restent en mémoire
/// pendant la durée de l'appel.
#[cfg(target_arch = "x86_64")]
unsafe fn raw_syscall_seccomp(op: u32, flags: u32, uargs: u64) -> i64 {
    let ret: i64;
    // SAFETY: (délégué à l'appelant) voir doc de la fonction.
    // ABI syscall x86_64 : numéro dans RAX, args dans RDI, RSI, RDX.
    // Clobbe : RCX, R11 (préservés par l'ABI x86_64 de toute façon).
    unsafe {
        core::arch::asm!(
            "syscall",
            inlateout("rax") SYS_SECCOMP => ret,
            in("rdi") u64::from(op),
            in("rsi") u64::from(flags),
            in("rdx") uargs,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
unsafe fn raw_syscall_seccomp(op: u32, flags: u32, uargs: u64) -> i64 {
    let ret: i64;
    // SAFETY: (délégué à l'appelant) voir doc de la fonction.
    // ABI syscall aarch64 : numéro dans x8, args dans x0..x5.
    unsafe {
        core::arch::asm!(
            "svc #0",
            inlateout("x0") u64::from(op) => ret,
            in("x1") u64::from(flags),
            in("x2") uargs,
            in("x8") SYS_SECCOMP as u64,
            options(nostack),
        );
    }
    ret
}

/// Effectue `landlock_create_ruleset(attr, size, flags)` et retourne le
/// résultat brut i64.
///
/// # Safety
///
/// `attr` doit être soit nul (requête de version ABI) soit un pointeur
/// valide sur un `KernelLandlockRulesetAttr` pour la durée de l'appel.
#[cfg(target_arch = "x86_64")]
unsafe fn raw_syscall_landlock_create_ruleset(attr: u64, size: u64, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: `attr` est nul (requête de version ABI) ou pointe un `KernelLandlockRulesetAttr`
    // valide pendant l'appel (contrat de la fonction) ; le noyau ne lit rien d'autre. ABI x86_64
    // — numéro dans RAX, arguments dans RDI, RSI, RDX ; RCX et R11, que `syscall` écrase, sont
    // déclarés ; `nostack` : la pile n'est pas touchée.
    unsafe {
        core::arch::asm!(
            "syscall",
            inlateout("rax") SYS_LANDLOCK_CREATE_RULESET => ret,
            in("rdi") attr,
            in("rsi") size,
            in("rdx") u64::from(flags),
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack),
        );
    }
    ret
}

/// Variante aarch64 de `raw_syscall_landlock_create_ruleset`.
///
/// # Safety
///
/// `attr` doit être soit nul (requête de version ABI) soit un pointeur
/// valide sur un `KernelLandlockRulesetAttr` pour la durée de l'appel.
#[cfg(target_arch = "aarch64")]
unsafe fn raw_syscall_landlock_create_ruleset(attr: u64, size: u64, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: `attr` est nul (requête de version ABI) ou pointe un `KernelLandlockRulesetAttr`
    // valide pendant l'appel (contrat de la fonction) ; le noyau ne lit rien d'autre. ABI aarch64
    // — numéro dans X8, arguments dans X0 à X2, retour dans X0, aucun autre registre écrasé par
    // `svc` ; `nostack` : la pile n'est pas touchée.
    unsafe {
        core::arch::asm!(
            "svc #0",
            inlateout("x0") attr => ret,
            in("x1") size,
            in("x2") u64::from(flags),
            in("x8") SYS_LANDLOCK_CREATE_RULESET as u64,
            options(nostack),
        );
    }
    ret
}

/// Effectue `landlock_add_rule(ruleset_fd, rule_type, rule_attr, flags)`.
///
/// # Safety
///
/// `rule_attr` doit pointer sur un `KernelLandlockPathBeneathAttr` valide
/// pour la durée de l'appel.
#[cfg(target_arch = "x86_64")]
unsafe fn raw_syscall_landlock_add_rule(
    ruleset_fd: i32,
    rule_type: i32,
    rule_attr: u64,
    flags: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: `rule_attr` pointe un `KernelLandlockPathBeneathAttr` valide pendant l'appel
    // (contrat de la fonction) ; le noyau ne lit que cette structure. ABI x86_64 — numéro dans
    // RAX, arguments dans RDI, RSI, RDX, R10 ; RCX et R11, que `syscall` écrase, sont déclarés ;
    // `nostack` : la pile n'est pas touchée.
    unsafe {
        core::arch::asm!(
            "syscall",
            inlateout("rax") SYS_LANDLOCK_ADD_RULE => ret,
            in("rdi") i64::from(ruleset_fd),
            in("rsi") i64::from(rule_type),
            in("rdx") rule_attr,
            in("r10") u64::from(flags),
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack),
        );
    }
    ret
}

/// Variante aarch64 de `raw_syscall_landlock_add_rule`.
///
/// # Safety
///
/// `rule_attr` doit pointer sur un `KernelLandlockPathBeneathAttr` valide
/// pour la durée de l'appel.
#[cfg(target_arch = "aarch64")]
unsafe fn raw_syscall_landlock_add_rule(
    ruleset_fd: i32,
    rule_type: i32,
    rule_attr: u64,
    flags: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: `rule_attr` pointe un `KernelLandlockPathBeneathAttr` valide pendant l'appel
    // (contrat de la fonction) ; le noyau ne lit que cette structure. ABI aarch64 — numéro dans
    // X8, arguments dans X0 à X3, retour dans X0, aucun autre registre écrasé par `svc` ;
    // `nostack` : la pile n'est pas touchée.
    unsafe {
        core::arch::asm!(
            "svc #0",
            inlateout("x0") i64::from(ruleset_fd) => ret,
            in("x1") i64::from(rule_type),
            in("x2") rule_attr,
            in("x3") u64::from(flags),
            in("x8") SYS_LANDLOCK_ADD_RULE as u64,
            options(nostack),
        );
    }
    ret
}

/// Effectue `landlock_restrict_self(ruleset_fd, flags)`.
#[cfg(target_arch = "x86_64")]
fn raw_syscall_landlock_restrict_self(ruleset_fd: i32, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_LANDLOCK_RESTRICT_SELF ne touche à aucune mémoire utilisateur.
    // - ABI x86_64 : numéro dans RAX, args dans RDI, RSI.
    unsafe {
        core::arch::asm!(
            "syscall",
            inlateout("rax") SYS_LANDLOCK_RESTRICT_SELF => ret,
            in("rdi") i64::from(ruleset_fd),
            in("rsi") u64::from(flags),
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
fn raw_syscall_landlock_restrict_self(ruleset_fd: i32, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_LANDLOCK_RESTRICT_SELF ne touche à aucune mémoire utilisateur.
    // - ABI aarch64 : numéro dans x8, args dans x0, x1.
    unsafe {
        core::arch::asm!(
            "svc #0",
            inlateout("x0") i64::from(ruleset_fd) => ret,
            in("x1") u64::from(flags),
            in("x8") SYS_LANDLOCK_RESTRICT_SELF as u64,
            options(nostack),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helper commun : interprétation du retour i64 d'un syscall.
// ─────────────────────────────────────────────────────────────────────────

/// Convertit un retour brut de syscall en `Result<i64, Errno>`.
///
/// Linux indique une erreur avec un retour dans `[-4095, -1]`.
fn syscall_result(raw: i64) -> Result<i64, Errno> {
    if (-4095..0_i64).contains(&raw) {
        // raw est dans [-4095, -1] : c'est un code errno négatif.
        // On calcule l'inverse via wrapping_neg : pas de risque d'overflow
        // car raw != i64::MIN (borné à -4095). Le résultat est dans [1, 4095],
        // valide pour un i32 et non nul.
        let errno_raw_i64 = raw.wrapping_neg();
        // errno_raw_i64 est dans [1, 4095] : la troncature i64 → i32 est
        // sans perte (4095 < i32::MAX) et le signe ne change pas.
        #[allow(clippy::cast_possible_truncation)]
        let errno_raw = errno_raw_i64 as i32;
        let nz =
            NonZeroI32::new(errno_raw).expect("errno dans [-4095,-1] est nécessairement non nul");
        Err(Errno::from_nonzero(nz))
    } else {
        Ok(raw)
    }
}

// ─────────────────────────────────────────────────────────────────────────
// LandlockRuleset — type RAII autour du FD ruleset Landlock.
// ─────────────────────────────────────────────────────────────────────────

/// Ruleset Landlock (cf. `landlock_create_ruleset(2)`).
///
/// Encapsule un FD ruleset Landlock qui accumule des règles d'accès
/// filesystem avant d'être appliqué au thread courant via
/// [`LandlockRuleset::restrict_self`].
///
/// Les restrictions sont **irréversibles pour le fil qui les pose** : une fois
/// `restrict_self` appelé, ce fil ne peut plus voir ses permissions augmenter.
///
/// # Ce que la monotonie ne couvre PAS : `TSYNC`
///
/// Cette page affirmait « Landlock est monotone », sans réserve. **C'est faux en présence
/// de [`LandlockRestrictFlags::TSYNC`]**, et la correction est datée du 2026-08-13 après
/// mesure sur un noyau réel : un fil qui pose un domaine **avec** `TSYNC` **écrase** celui
/// de ses fils frères, y compris quand le leur était **plus strict**. Le noyau le dit —
/// *« irrespective of previously established Landlock domains »* — et l'expérience le
/// confirme : un fil frère qui ne pouvait rien ouvrir a retrouvé l'accès.
///
/// Ce n'est pas une élévation de privilège au sens usuel : les fils d'un processus
/// partagent leur espace d'adressage et n'ont jamais été une frontière de sécurité entre
/// eux. Mais l'intuition « une restriction Landlock ne se retire pas » est **fausse à
/// l'échelle du processus**, et la croire conduirait à poser `TSYNC` d'office.
#[derive(Debug)]
pub struct LandlockRuleset(OwnedFd);

impl LandlockRuleset {
    /// Vue empruntée du FD ruleset.
    #[must_use]
    pub fn as_fd(&self) -> BorrowedFd<'_> {
        use air_sys_types::fd::AsFd;
        self.0.as_fd()
    }

    /// Ajoute une règle d'accès pour un chemin filesystem et ses descendants.
    ///
    /// Wrappeur de `landlock_add_rule(2)` avec `LANDLOCK_RULE_PATH_BENEATH`.
    /// La règle s'applique au chemin référencé par `path` et à tous ses
    /// descendants. `path` doit être ouvert avec `O_PATH | O_DIRECTORY`
    /// (ou `O_PATH` seul pour un fichier).
    ///
    /// **Sémantique additive :** les règles ne peuvent qu'étendre les accès
    /// autorisés au sein de ce ruleset. `restrict_self` appliquera
    /// l'intersection de tous les rulesets cumulés.
    ///
    /// # Parameters
    ///
    /// - `path` : FD du chemin cible (typiquement ouvert avec `O_PATH`).
    /// - `allowed_access` : permissions autorisées sur ce chemin et ses
    ///   descendants.
    ///
    /// # Errors
    ///
    /// - `EINVAL` : `allowed_access` contient un bit non géré par ce ruleset,
    ///   ou `path` n'est pas un FD valide.
    /// - `ENOMEM` : mémoire kernel insuffisante.
    /// - `EBADFD` : `path` n'est pas un FD de fichier ou répertoire.
    /// - `EINTR` : interruption par signal (ADR-021 convention 2 — remonté
    ///   tel quel, sans retry automatique).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use air_sys_syscall::security::landlock_create_ruleset;
    /// use air_sys_types::security::LandlockAccessFs;
    /// use air_sys_types::fd::BorrowedFd;
    ///
    /// # fn example(path_fd: BorrowedFd<'_>) {
    /// let mut ruleset = landlock_create_ruleset(
    ///     LandlockAccessFs::READ_FILE | LandlockAccessFs::EXECUTE,
    /// ).expect("create_ruleset");
    /// ruleset.add_rule_path_beneath(path_fd, LandlockAccessFs::READ_FILE)
    ///     .expect("add_rule");
    /// # }
    /// ```
    pub fn add_rule_path_beneath(
        &mut self,
        path: BorrowedFd<'_>,
        allowed_access: LandlockAccessFs,
    ) -> Result<(), Errno> {
        let attr = KernelLandlockPathBeneathAttr {
            allowed_access: allowed_access.bits(),
            parent_fd: path.as_raw_fd(),
        };
        let ruleset_fd = self.0.as_raw_fd();
        // SAFETY:
        // - `attr` est une variable locale valide pour toute la durée de l'appel.
        // - `LANDLOCK_RULE_PATH_BENEATH` est la seule valeur de type règle
        //   actuellement définie et acceptée par le kernel pour `attr` de
        //   type `KernelLandlockPathBeneathAttr`.
        // - `flags` = 0 : aucun drapeau défini pour cette opération à ce jour.
        let ret = unsafe {
            raw_syscall_landlock_add_rule(
                ruleset_fd,
                LANDLOCK_RULE_PATH_BENEATH,
                &raw const attr as u64,
                0,
            )
        };
        syscall_result(ret).map(|_| ())
    }

    /// Autorise un **port TCP** — `landlock_add_rule(2)` avec
    /// `LANDLOCK_RULE_NET_PORT` (ABI **v4+**, Linux 6.7).
    ///
    /// # Parameters
    ///
    /// - `port` : le port en **ordre hôte** (`443`, pas son écriture réseau) ;
    /// - `allowed_access` : [`LandlockAccessNet::BIND_TCP`] et/ou
    ///   [`LandlockAccessNet::CONNECT_TCP`].
    ///
    /// # Ce que cette règle borne, et ce qu'elle ne borne pas
    ///
    /// Elle borne le **port**, jamais l'**adresse**. Un processus autorisé à se
    /// connecter au port 443 peut joindre n'importe quelle machine sur ce port.
    /// Landlock n'est pas un pare-feu, et le prendre pour tel donnerait un faux
    /// sentiment de confinement réseau.
    ///
    /// # Errors
    ///
    /// - `EINVAL` : le ruleset ne **gère** pas les accès réseau (il faut l'avoir créé
    ///   avec [`landlock_create_ruleset_with_net`]), ou `allowed_access` porte un bit
    ///   inconnu du noyau ;
    /// - `EAFNOSUPPORT` / `ENOSYS` : ABI Landlock antérieure à v4.
    pub fn add_rule_net_port(
        &mut self,
        port: u16,
        allowed_access: LandlockAccessNet,
    ) -> Result<(), Errno> {
        let attr = KernelLandlockNetPortAttr {
            allowed_access: allowed_access.bits(),
            port: u64::from(port),
        };
        let ruleset_fd = self.0.as_raw_fd();
        // SAFETY:
        // - `attr` est une variable locale valide pour toute la durée de l'appel.
        // - `LANDLOCK_RULE_NET_PORT` est le type de règle défini par le kernel pour
        //   un `attr` de type `KernelLandlockNetPortAttr` (ABI v4).
        // - `flags` = 0 : aucun drapeau défini pour cette opération à ce jour.
        let ret = unsafe {
            raw_syscall_landlock_add_rule(
                ruleset_fd,
                LANDLOCK_RULE_NET_PORT,
                &raw const attr as u64,
                0,
            )
        };
        syscall_result(ret).map(|_| ())
    }

    /// Applique le ruleset au thread courant.
    ///
    /// Wrappeur de `landlock_restrict_self(2)`. **Irréversible.** Après
    /// cet appel, le thread ne peut plus accéder aux chemins filesystem
    /// non couverts par les règles du ruleset (pour les accès dans
    /// `handled_access` du ruleset).
    ///
    /// Prérequis : avoir appelé [`crate::process::set_no_new_privs`] ou
    /// posséder `CAP_SYS_ADMIN`.
    ///
    /// # Errors
    ///
    /// - `EPERM` : `no_new_privs` non positionné et `CAP_SYS_ADMIN` absent.
    /// - `EINVAL` : flags invalides.
    /// - `EINTR` : interruption par signal (ADR-021 convention 2 — remonté
    ///   tel quel, sans retry automatique).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use air_sys_syscall::security::landlock_create_ruleset;
    /// use air_sys_syscall::process::set_no_new_privs;
    /// use air_sys_types::security::LandlockAccessFs;
    ///
    /// let ruleset = landlock_create_ruleset(LandlockAccessFs::READ_FILE)
    ///     .expect("create_ruleset");
    /// set_no_new_privs().expect("no_new_privs");
    /// ruleset.restrict_self().expect("restrict_self");
    /// ```
    pub fn restrict_self(&self) -> Result<(), Errno> {
        self.restrict_self_with(LandlockRestrictFlags::empty())
    }

    /// Applique le ruleset **avec des drapeaux** (cf. [`LandlockRestrictFlags`]).
    ///
    /// # Ce que `TSYNC` change, et pourquoi une fonction séparée n'aurait rien réglé
    ///
    /// Sans [`TSYNC`](LandlockRestrictFlags::TSYNC), le domaine ne borne que le **fil
    /// appelant** : dans un processus multifil qui se met lui-même en cage, les fils frères
    /// restent dehors, et la cage se contourne en changeant de fil. Avec lui, la
    /// configuration s'applique **atomiquement à tous les fils**.
    ///
    /// Les drapeaux ne sont pas des opérations multiplexées (ADR-021 convention 3) : ils se
    /// combinent, et un wrapper par combinaison serait une explosion combinatoire sans
    /// gain de typage.
    ///
    /// # Le noyau refuse ce qu'il ne connaît pas
    ///
    /// Un drapeau inconnu de l'ABI courante fait échouer l'appel (`EINVAL`) — il n'est
    /// **pas** ignoré. La pose de cage étant *fail-closed*, demander un drapeau trop
    /// récent **tue** le processus : interroger [`landlock_supported_abi`] d'abord.
    ///
    /// # Errors
    ///
    /// - `EPERM` : `no_new_privs` non positionné et `CAP_SYS_ADMIN` absent.
    /// - `EINVAL` : un drapeau inconnu de l'ABI courante.
    /// - `EINTR` : interruption par signal (ADR-021 convention 2 — remonté tel quel).
    pub fn restrict_self_with(&self, flags: LandlockRestrictFlags) -> Result<(), Errno> {
        let ruleset_fd = self.0.as_raw_fd();
        let ret = raw_syscall_landlock_restrict_self(ruleset_fd, flags.bits());
        syscall_result(ret).map(|_| ())
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Fonctions publiques
// ─────────────────────────────────────────────────────────────────────────

/// Retourne la version ABI Landlock supportée par le kernel courant.
///
/// Utilise `landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION)`.
/// Retourne `ENOSYS` si le kernel ne supporte pas Landlock (< 5.13).
///
/// | Valeur retournée | Version Landlock | Kernel minimum |
/// |---|---|---|
/// | 1 | v1 | Linux 5.13 |
/// | 2 | v2 (REFER) | Linux 5.19 |
/// | 3 | v3 (TRUNCATE) | Linux 6.2 |
/// | 5 | v5 (IOCTL_DEV) | Linux 6.10 |
///
/// # Errors
///
/// - `ENOSYS` : Landlock non supporté ou non compilé dans le kernel.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::security::landlock_supported_abi;
///
/// match landlock_supported_abi() {
///     Ok(v) => println!("Landlock ABI v{v}"),
///     Err(_) => println!("Landlock non disponible"),
/// }
/// ```
pub fn landlock_supported_abi() -> Result<u32, Errno> {
    // SAFETY:
    // - attr = 0 (NULL) et size = 0 sont les valeurs attendues pour la
    //   requête de version ABI (drapeaux LANDLOCK_CREATE_RULESET_VERSION).
    // - Le kernel ne déréférence pas le pointeur quand flags = VERSION.
    let ret = unsafe { raw_syscall_landlock_create_ruleset(0, 0, LANDLOCK_CREATE_RULESET_VERSION) };
    let version = syscall_result(ret)?;
    // La version ABI est un entier positif <= quelques dizaines ; la
    // troncature i64 → u32 est sans perte sur les valeurs réalistes.
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(version as u32)
}

/// Crée un ruleset Landlock pour les accès filesystem spécifiés.
///
/// Wrappeur de `landlock_create_ruleset(2)` (Linux 5.13+). Le ruleset
/// gérera les permissions listées dans `handled_access` — toute
/// permission dans `handled_access` qui n'est pas couverte par une règle
/// sera **refusée** par défaut après `restrict_self`.
///
/// # Parameters
///
/// - `handled_access` : ensemble des permissions filesystem que ce
///   ruleset va gérer. Doit être un sous-ensemble des bits supportés
///   par la version ABI du kernel (voir [`landlock_supported_abi`]).
///
/// # Errors
///
/// - `EINVAL` : `handled_access` contient un bit non supporté par la
///   version ABI courante.
/// - `ENOMEM` : mémoire kernel insuffisante.
/// - `ENOSYS` : Landlock non disponible sur ce kernel.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::security::landlock_create_ruleset;
/// use air_sys_types::security::LandlockAccessFs;
///
/// let ruleset = landlock_create_ruleset(
///     LandlockAccessFs::READ_FILE | LandlockAccessFs::READ_DIR | LandlockAccessFs::EXECUTE,
/// ).expect("create_ruleset");
/// ```
pub fn landlock_create_ruleset(handled_access: LandlockAccessFs) -> Result<LandlockRuleset, Errno> {
    let attr = KernelLandlockRulesetAttr {
        handled_access_fs: handled_access.bits(),
    };
    // SAFETY:
    // - `attr` est une variable locale valide pour toute la durée de l'appel.
    // - `size_of::<KernelLandlockRulesetAttr>()` est la taille exacte de la
    //   structure attendue par le kernel pour les versions ABI connues.
    // - `flags` = 0 : création normale (pas requête de version ABI).
    let ret = unsafe {
        raw_syscall_landlock_create_ruleset(
            &raw const attr as u64,
            size_of::<KernelLandlockRulesetAttr>() as u64,
            0,
        )
    };
    let fd_raw = syscall_result(ret)?;
    // SAFETY: le syscall a réussi (ret >= 0) ; le kernel garantit qu'un
    // fd retourné est valide et appartient maintenant au processus.
    // La troncature i64 → i32 est sans perte : les numéros de fd Linux
    // tiennent dans un i32.
    #[allow(clippy::cast_possible_truncation)]
    let owned_fd = unsafe { OwnedFd::from_raw_fd(fd_raw as i32) };
    Ok(LandlockRuleset(owned_fd))
}

/// Crée un ruleset Landlock gérant **les fichiers ET le réseau** (ABI **v4+**).
///
/// # Pourquoi une fonction distincte de [`landlock_create_ruleset`]
///
/// Le noyau lit exactement `size` octets d'attributs. Passer la structure à deux champs
/// à un noyau qui n'en connaît qu'un échoue `E2BIG` — et la pose de cage étant
/// *fail-closed*, cet échec **tuerait** le processus sur un noyau parfaitement valide.
///
/// Garder les deux formes permet à l'appelant de choisir en connaissance de cause, après
/// avoir interrogé [`landlock_supported_abi`], plutôt que de dégrader en silence. C'est le
/// même raisonnement qui a fait borner `air-sandbox` à l'ABI v1 : demander au noyau ce
/// qu'il ne connaît pas n'est pas une dégradation, c'est une mort.
///
/// # Errors
///
/// - `EINVAL` : un bit de `handled_fs` ou `handled_net` est inconnu de l'ABI courante ;
/// - `E2BIG` : le noyau ne connaît pas la forme à deux champs (ABI < v4) ;
/// - `ENOMEM`, `ENOSYS` : comme [`landlock_create_ruleset`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::security::{landlock_create_ruleset_with_net, landlock_supported_abi};
/// use air_sys_types::security::{LandlockAccessFs, LandlockAccessNet};
///
/// // Le réseau n'existe qu'à partir de l'ABI v4 : on demande avant de composer.
/// if landlock_supported_abi().unwrap_or(0) >= 4 {
///     let ruleset = landlock_create_ruleset_with_net(
///         LandlockAccessFs::READ_FILE,
///         LandlockAccessNet::CONNECT_TCP,
///     )
///     .expect("create_ruleset avec réseau");
///     let _ = ruleset;
/// }
/// ```
pub fn landlock_create_ruleset_with_net(
    handled_fs: LandlockAccessFs,
    handled_net: LandlockAccessNet,
) -> Result<LandlockRuleset, Errno> {
    let attr = KernelLandlockRulesetAttrV4 {
        handled_access_fs: handled_fs.bits(),
        handled_access_net: handled_net.bits(),
    };
    // SAFETY:
    // - `attr` est une variable locale valide pour toute la durée de l'appel.
    // - `size_of::<KernelLandlockRulesetAttrV4>()` est la taille exacte de la forme
    //   à deux champs attendue par un kernel d'ABI v4 ou supérieure.
    // - `flags` = 0 : création normale (pas requête de version ABI).
    let ret = unsafe {
        raw_syscall_landlock_create_ruleset(
            &raw const attr as u64,
            size_of::<KernelLandlockRulesetAttrV4>() as u64,
            0,
        )
    };
    let fd_raw = syscall_result(ret)?;
    // SAFETY: le syscall a réussi (ret >= 0) ; le kernel garantit qu'un fd retourné est
    // valide et appartient maintenant au processus. La troncature i64 → i32 est sans
    // perte : les numéros de fd Linux tiennent dans un i32.
    #[allow(clippy::cast_possible_truncation)]
    let owned_fd = unsafe { OwnedFd::from_raw_fd(fd_raw as i32) };
    Ok(LandlockRuleset(owned_fd))
}

/// Crée un ruleset Landlock gérant **fichiers, réseau ET portées** (ABI **v6+**).
///
/// # Ce que la portée ajoute, et que les deux autres ne pouvaient pas dire
///
/// `handled_fs` et `handled_net` bornent ce qu'on a le droit de faire **sur** une ressource
/// nommée. `scoped` borne autre chose : jusqu'où le domaine peut **atteindre en dehors de
/// lui-même**. Un socket UNIX abstrait n'a pas de chemin et un signal ne traverse aucun
/// descripteur — ni l'un ni l'autre ne pouvait donc être borné par une règle.
///
/// # Pourquoi une fonction de plus
///
/// Même raison qu'entre [`landlock_create_ruleset`] et [`landlock_create_ruleset_with_net`] :
/// le noyau lit exactement `size` octets. Sonder [`landlock_supported_abi`] avant de choisir
/// la forme est le seul moyen de ne pas mourir sur un noyau plus ancien.
///
/// # Errors
///
/// - `EINVAL` : un bit de `handled_fs`, `handled_net` ou `scope` est inconnu de l'ABI
///   courante ;
/// - `E2BIG` : le noyau ne connaît pas la forme à trois champs (ABI < v6) ;
/// - `ENOMEM`, `ENOSYS` : comme [`landlock_create_ruleset`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::security::{landlock_create_ruleset_with_scope, landlock_supported_abi};
/// use air_sys_types::security::{LandlockAccessFs, LandlockAccessNet, LandlockScope};
///
/// // Les portées n'existent qu'à partir de l'ABI v6 : on demande avant de composer.
/// if landlock_supported_abi().unwrap_or(0) >= 6 {
///     let ruleset = landlock_create_ruleset_with_scope(
///         LandlockAccessFs::READ_FILE,
///         LandlockAccessNet::CONNECT_TCP,
///         LandlockScope::ABSTRACT_UNIX_SOCKET | LandlockScope::SIGNAL,
///     )
///     .expect("create_ruleset avec portées");
///     let _ = ruleset;
/// }
/// ```
pub fn landlock_create_ruleset_with_scope(
    handled_fs: LandlockAccessFs,
    handled_net: LandlockAccessNet,
    scope: LandlockScope,
) -> Result<LandlockRuleset, Errno> {
    let attr = KernelLandlockRulesetAttrV6 {
        handled_access_fs: handled_fs.bits(),
        handled_access_net: handled_net.bits(),
        scoped: scope.bits(),
    };
    // SAFETY:
    // - `attr` est une variable locale valide pour toute la durée de l'appel.
    // - `size_of::<KernelLandlockRulesetAttrV6>()` est la taille exacte de la forme à trois
    //   champs attendue par un kernel d'ABI v6 ou supérieure.
    // - `flags` = 0 : création normale (pas requête de version ABI).
    let ret = unsafe {
        raw_syscall_landlock_create_ruleset(
            &raw const attr as u64,
            size_of::<KernelLandlockRulesetAttrV6>() as u64,
            0,
        )
    };
    let fd_raw = syscall_result(ret)?;
    // SAFETY: le syscall a réussi (ret >= 0) ; le kernel garantit qu'un fd retourné est
    // valide et appartient maintenant au processus. La troncature i64 → i32 est sans
    // perte : les numéros de fd Linux tiennent dans un i32.
    #[allow(clippy::cast_possible_truncation)]
    let owned_fd = unsafe { OwnedFd::from_raw_fd(fd_raw as i32) };
    Ok(LandlockRuleset(owned_fd))
}

/// Applique un filtre seccomp-BPF précompilé au thread courant.
///
/// Wrappeur de `seccomp(SECCOMP_SET_MODE_FILTER, flags, prog)`.
/// Charge le programme BPF tel quel dans le kernel — aucune compilation
/// BPF n'est effectuée ici (API primitive couche 0).
///
/// **L'opération est irréversible.** Une fois chargé, le filtre ne peut
/// pas être retiré. Des filtres successifs peuvent être ajoutés mais
/// seulement pour restreindre davantage (jamais pour assouplir).
///
/// # Piège : avec `TSYNC`, un retour POSITIF est un ÉCHEC
///
/// `seccomp(2)` avec [`SeccompFilterFlags::TSYNC`] rend, en cas d'échec, le **`tid` du fil
/// fautif** — un entier **positif** — au lieu d'un code d'erreur négatif. Ce wrapper traite
/// tout retour ≥ 0 comme un succès : posé nu, `TSYNC` rapporterait donc une cage posée
/// alors qu'elle ne l'est pas.
///
/// **Toujours l'accompagner de [`SeccompFilterFlags::TSYNC_ESRCH`]**, qui existe
/// précisément pour cela : le noyau rend alors `-ESRCH`, et l'échec redevient un échec.
///
/// # Safety
///
/// - L'appelant doit avoir appelé `set_no_new_privs()` OU posséder
///   `CAP_SYS_ADMIN`.
/// - Le programme BPF doit autoriser tous les syscalls nécessaires au
///   runtime Rust (au minimum : `read`, `write`, `mmap`, `munmap`,
///   `futex`, `exit_group`, `rt_sigreturn`).
/// - Un programme BPF incorrect peut bloquer le processus ou le tuer.
/// - Irréversible.
///
/// # Errors
///
/// - `EPERM` : `no_new_privs` non positionné et `CAP_SYS_ADMIN` absent.
/// - `EINVAL` : programme BPF invalide ou flags non reconnus.
/// - `ENOMEM` : mémoire insuffisante.
/// - `ENOSYS` : seccomp non compilé dans ce kernel.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::security::seccomp_set_mode_filter;
/// use air_sys_types::security::{SeccompFilterFlags, SockFilter, SockFprog};
///
/// // Instruction BPF RET ALLOW (0x7fff0000 = SECCOMP_RET_ALLOW).
/// let allow_all = [SockFilter { code: 0x0006, jt: 0, jf: 0, k: 0x7fff_0000 }];
/// let prog = SockFprog::new(&allow_all).expect("programme valide");
///
/// // unsafe : charge un filtre irréversible dans le kernel.
/// unsafe {
///     seccomp_set_mode_filter(&prog, SeccompFilterFlags::empty())
///         .expect("seccomp_set_mode_filter");
/// }
/// ```
pub unsafe fn seccomp_set_mode_filter(
    prog: &SockFprog<'_>,
    flags: SeccompFilterFlags,
) -> Result<(), Errno> {
    // Construction du struct sock_fprog attendu par le kernel sur LP64.
    // Sur x86_64 et aarch64 (les deux archs supportées, ADR-014), la ABI
    // LP64 impose : u16 length, 6 octets de padding, puis le pointeur aligné
    // sur 8 octets — total 16 octets.
    let kfprog = KernelSockFprog {
        len: prog.len(),
        _pad: [0u8; 6],
        filter: prog.as_ptr() as u64,
    };
    // SAFETY: (préconditions héritées de l'appelant)
    // - Le programme BPF pointé par `prog` reste valide pendant l'appel.
    // - `kfprog` est une variable locale valide pour toute la durée
    //   de l'appel syscall.
    // - `SECCOMP_SET_MODE_FILTER` avec un `sock_fprog` valide ne cause
    //   pas d'UB intrinsèquement — c'est un appel kernel ordinaire.
    let ret = unsafe {
        raw_syscall_seccomp(
            SECCOMP_SET_MODE_FILTER,
            flags.bits(),
            &raw const kfprog as u64,
        )
    };
    syscall_result(ret).map(|_| ())
}

/// Active le mode seccomp strict.
///
/// En mode strict, seuls `read(2)`, `write(2)`, `_exit(2)` et
/// `sigreturn(2)` sont autorisés pour le thread courant. Tout autre
/// syscall entraîne un `SIGKILL`.
///
/// **L'opération est irréversible.**
///
/// # Errors
///
/// - `EPERM` : les threads du processus utilisent déjà des filtres
///   incompatibles (cas rare).
/// - `ENOSYS` : seccomp non compilé dans ce kernel.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::security::seccomp_set_mode_strict;
///
/// // N'appeler que dans un sous-processus dédié ; irréversible.
/// seccomp_set_mode_strict().expect("seccomp_set_mode_strict");
/// ```
pub fn seccomp_set_mode_strict() -> Result<(), Errno> {
    // SAFETY:
    // - `SECCOMP_SET_MODE_STRICT` avec flags=0 et uargs=0 est l'appel
    //   canonique documenté dans seccomp(2). Aucune mémoire utilisateur
    //   n'est déréférencée par le kernel pour cette opération.
    let ret = unsafe { raw_syscall_seccomp(SECCOMP_SET_MODE_STRICT, 0, 0) };
    syscall_result(ret).map(|_| ())
}

// ─────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests;