DOCSEARCHbyAlgolia
Submit Docs

SELinux Notebook

repository·main·Indexed 20 days ago

https://github.com/selinuxproject/selinux-notebook

An open-source resource covering Linux Kernel components, userspace libraries, tools, policy toolchain, and SELinux policy. It includes a tiny CIL policy for experimentation, Android policy inspection tools, networking demos for CIPSO, CALIPSO, and IPSEC, and guides for building monolithic reference policies and SE-PostgreSQL integration.

Tokens
116.5K
Snippets
301
Records
494
Agent score
71%

What's inside selinux-notebook

  1. Introduction to the SELinux Notebook

    main

    The SELinux Notebook is an educational resource designed to explain the architecture, implementation, and management of SELinux within GNU/Linux and Android. It covers several key domains:

    • Architecture: The LSM (Linux Security Module) architecture and supporting services.
    • Capabilities: SELinux integration with Networking, Virtual Machines, X-Windows, PostgreSQL, and Apache.
    • Policy Language: The core kernel policy language, basic policy module construction, and the Common Intermediate Language (CIL).
    • Management Tools: Core SELinux policy management tools and their usage.
    • Reference Policy: The architecture and implementation of the Reference Policy and its supporting macros.
    • Android: How SELinux services support the Android platform.
    • Object Classes and Permissions: Detailed descriptions of SELinux object classes and permissions.

  2. Overview of SELinux Notebook Examples

    main

    The src/notebook-examples directory provides several specialized examples for testing and learning SELinux configurations. The available examples are categorized by their functional area:

    • cil-policy: Instructions for building and installing simple CIL (Common Intermediate Language) policies.
    • network: Examples involving CIPSO, CALIPSO, and IPSEC.
    • selinux-policy: Instructions for building simple kernel and CIL policies.
    • sepgsql: An example demonstrating SE-PostgreSQL database integration.

  3. Overview of the tiny CIL policy

    main

    The tiny CIL policy is a minimal SELinux policy written in Common Intermediate Language (CIL). It is designed for experimentation and as a base for custom security policies.

    Key Characteristics:

    • Mutable at Runtime: Uses CIL and semodule for easy runtime access and modification.
    • Minimalism: Declares only eight security classes and two access vector permissions. Unknown access vectors are allowed by default to facilitate experimentation.
    • Security Models: Supports Type-Enforcement (TE), Identity-Based Access Control (IBAC), and Role-Based Access Control (RBAC). Multi-Level Security (MLS) can be added manually.
    • Tooling: It is recommended to use the setools policy analysis suite to inspect the policy state.

  4. Overview of Sample Policy Builds

    main

    The src/notebook-examples/selinux-policy directory provides tools and source files for building SELinux kernel and CIL (Common Intermediate Language) policies. The directory structure includes:

    • tools/: Contains the build-sepolicy script and its man page for building kernel and CIL policy files.
    • cil/: Contains the CIL_Reference_Guide and a Makefile to build CIL policies (supporting both MLS and non-MLS).
    • kernel/: Contains a Makefile to build kernel language policies (supporting both MLS and non-MLS).
    • policy-files/: Contains configuration files for both kernel and CIL policies.
    • flask-files/: Contains Fedora 31 policy source files, specifically initial_sids, security_classes, and access_vectors flask files.

  5. Inspect Android SELinux policies

    main

    Android policies in this repository are defined via Makefile files. This allows you to build and inspect policies without requiring the full AOSP (Android Open Source Project) source tree or build environment.

    Building the policy produces two primary artifacts:

    1. policy.conf: A text file that can be examined with any standard text editor.
    2. sepolicy: A binary file that should be viewed using specialized tools like apol(1).

    Note that while these Makefiles build the policy, the core policy is typically built as-is, whereas in a real Android environment, each device adds its own specific policy modules.

  6. Index of SELinux Kernel Policy Language components

    main

    The SELinux Kernel Policy Language is composed of various statement and rule sections used to define security policies. The following components are available in the policy language:

    • Configuration & Defaults: Policy Configuration Statements, Default Rules.
    • Identity & Roles: User Statements, Role Statements, Type Statements.
    • Access Control: Bounds Rules, Access Vector Rules (AVC), Extended Access Vector Rules (xperm), Object Class and Permission Statements, Constraint Statements.
    • Specialized Security: Conditional Policy Statements, MLS (Multi-Level Security) Statements, Security ID (SID) Statements.
    • Labeling: File System Labeling Statements, Network Labeling Statements, InfiniBand Labeling Statements, XEN Statements.

    Note on Reference Policy Build Process: The Reference Policy uses makefiles and m4 macros to build the policy. The final output of the build process (controlled by the MONOLITHIC=Y/N option) consists of source files containing these statements and rules, which are then compiled into a binary policy. This process does not include the file_contexts file, as that file contains security contexts (labels) rather than policy statements.

  7. Use the libselinux Library for SELinux-aware applications

    main

    The libselinux library provides the necessary functions to build userspace SELinux-aware applications and object managers. It supports 'C', Python, Ruby, and PHP. It abstracts low-level interactions with the SELinux kernel security server, the /proc filesystem, extended attribute services, and SELinux policy configuration files.

    Key functional categories include:

    • Access Vector Cache Services: Caching and auditing access decisions.
    • Boolean Services: Managing SELinux booleans.
    • Class and Permission Management: Converting and mapping class/permission strings.
    • Compute Access Decisions: Determining if access is allowed or denied.
    • Labeling Services: Computing, getting, and setting labels for files, file descriptors, sockets, processes, kernel keys, and user sessions.
    • Context Management: Validating contexts and translating between raw and readable formats.
    • Management Services: Loading policies, setting enforcement modes, and obtaining configuration info.
    • Netlink Services: Detecting policy reloads and enforcement changes.

    For a complete list of functions, refer to the Appendix B - libselinux API Summary in libselinux_functions.md.

  9. Use the libsepol Library to manipulate kernel binary policies

    main

    The libsepol library is used to build and manipulate the contents of SELinux kernel binary policy files.

    Note that certain functions required by tools like audit2allow(8) and checkpolicy(8)—specifically sepol_compute_av(), sepol_compute_av_reason(), and sepol_context_to_sid()—are only available in the static version of the library and are not available in the dynamic library.

  10. What is the Linux Security Module (LSM)?

    main

    The LSM is a Linux kernel framework that allows third-party access control mechanisms (Mandatory Access Control or MAC) to be linked into the kernel. It does not provide security services itself; instead, it provides security function hooks and data structures that allow modules like SELinux, AppArmor, or SMACK to apply access control over and above standard Discretionary Access Control (DAC).

    Key capabilities of LSM include:

    • Security Hooks: Inserting hooks into kernel services (e.g., program execution, filesystem operations, socket operations) to allow modules to intercept and authorize actions.
    • Module Registration: Providing services for third-party security modules to initialize and register.
    • Process Attribute Exposure: Extending the /proc filesystem to allow userspace to view and manage process security attributes.
    • Filesystem Support: Supporting filesystems that use extended attributes (e.g., SELinux using security.selinux).
    • Module Stacking: Allowing multiple LSM modules to be called in a predefined order (e.g., lockdown,yama,selinux,...).

  11. Overview of sepgsql extension

    main

    The sepgsql extension adds SELinux Mandatory Access Control (MAC) to PostgreSQL database objects, including schemas, tables, columns, views, functions, and sequences.

    When a client executes SQL commands, the PostgreSQL Object Manager (OM) checks each operation against the SELinux security policy. The extension interfaces with the libselinux library and logs AVC audits to the standard PostgreSQL logfile.

    Key Requirements:

    • PostgreSQL version 11.x or higher.
    • Each Linux user must have a valid PostgreSQL database role.
    • For remote clients requiring labeled networking, IPSec or NetLabel can be used.

  12. How extended permissions are evaluated

    main

    Extended permission rules add a secondary layer of validation to standard SELinux checks:

    1. No extended rules defined: Standard SELinux AVC rules and constraints apply.
    2. Extended rules defined: Both standard AVC checks and extended permission checks must pass.
      • An allowxperm rule only grants access if the base allow rule for that class/operation is also present.
      • An auditallowxperm rule only triggers extended auditing if auditallow is permitted for the resource.
    3. Deny-by-default: If any extended permission rule is defined for a resource/operation, all permissions within the available xperm_set that are not explicitly allowed are automatically denied.