Understanding AIB build policies

Understanding AIB build policies¶

Automotive Image Builder supports a policy system that enforces build restrictions through external .aibp.yml policy files. Policies constrain what manifests can contain, which RPM packages and kernel modules are permitted, and which SELinux booleans and sysctl parameters the policy enforces.

Use policies to maintain consistent security and compliance standards across multiple builds and teams.

Using a policy¶

Apply a policy with the --policy flag on aib build or aib-dev build:

$ aib build --policy hardened \
    --target qemu \
    manifest.aib.yml \
    localhost/my-image

Policy validation runs before the build starts. If the manifest conflicts with any restriction in the policy, the build fails with a clear error message describing the violation.

Policy resolution order¶

When you pass a policy name to --policy, Automotive Image Builder searches for the policy file in the following order:

Full path -- If the value contains a path separator (/), AIB treats it as a direct file path.
Name with extension -- If the value ends with .aibp.yml but contains no path separator, AIB searches in this order: current working directory, system-wide directory, package-provided directory.
Bare name (no extension) -- If the value has no .aibp.yml extension, AIB appends the extension and searches only the system-wide and package-provided directories (skipping the current directory).

The installed policy directories are:

System-wide -- /etc/automotive-image-builder/policies/<name>.aibp.yml
Package-provided -- /usr/lib/automotive-image-builder/files/policies/ (the default installation path for AIB is /usr/lib/automotive-image-builder).

AIB uses the first match it finds and stops searching. If a policy file with the same name exists in multiple locations, the earlier location in the search order takes precedence. Policy files from different locations are not merged.

For example, --policy hardened resolves to the built-in files/policies/hardened.aibp.yml file shipped with AIB. Specifying --policy ./my-policy.aibp.yml loads the file from the current directory.

Policy file format¶

A policy file is a YAML document with the .aibp.yml extension. The two required fields are name and description. Put all restrictions under the restrictions key.

name: my-policy
description: Example policy for production builds

restrictions:
  require_simple_manifest: true

  modes:
    allow:
      - bootc

  rpms:
    disallow:
      - debug-package

  selinux_booleans:
    force:
      deny_ptrace: true

  variables:
    force:
      disable_ipv6: true

Restriction types¶

You can set the following restriction categories in a policy file.

Build mode restrictions¶

In the modes section, you can specify which build modes are permitted. Use allow to permit only specific modes, or disallow to block specific modes. You can allow or disallow the following modes: image, package, and bootc.

restrictions:
  modes:
    allow:
      - image
      - bootc

Target restrictions¶

In the targets section, you can limit which hardware targets a build can use.

restrictions:
  targets:
    disallow:
      - rpi4

Distribution and architecture restrictions¶

In the distributions and architectures sections, you can limit which distributions and CPU architectures are permitted.

restrictions:
  distributions:
    allow:
      - autosd10
  architectures:
    allow:
      - x86_64
      - aarch64

Repository restrictions¶

In the repositories section, you can specify which RPM repositories are permitted.

restrictions:
  repositories:
    disallow:
      - untrusted-repo

Manifest property restrictions¶

In the manifest_restrictions section, you can specify which manifest properties and values are allowed or disallowed. Use disallow.properties to block specific manifest keys. Use disallow.values to block specific values for a given property path.

restrictions:
  manifest_restrictions:
    disallow:
      properties:
        - experimental
        - image.partitions.root.grow
      values:
        "content.container_images[].containers-transport":
          - containers-storage

RPM and kernel module restrictions¶

In the rpms and kernel_modules sections, you can block specific packages or kernel modules from being included in the image. Only disallow lists are supported for these sections.

restrictions:
  rpms:
    disallow:
      - dosfstools
      - e2fsprogs
  kernel_modules:
    disallow:
      - fat
      - nfs

Variable enforcement¶

In the variables section, you can force specific build variable values. Forced variables override any values set in the manifest.

restrictions:
  variables:
    force:
      disable_ipv6: true
      enable_oom_protection: true

SELinux boolean enforcement¶

In the selinux_booleans section, you can force specific SELinux boolean values across all builds that use the policy.

restrictions:
  selinux_booleans:
    force:
      deny_ptrace: true

For background on SELinux in AutoSD images, see Understanding SELinux policies in AutoSD images.

Sysctl parameter enforcement¶

In the sysctl section, you can force specific kernel parameters.

restrictions:
  sysctl:
    force:
      "net.core.busy_poll": "0"

Simple manifest requirement¶

You can set require_simple_manifest to true to block builds from using low-level .mpp.yml manifests. When enabled, only simplified manifest files in .aib.yml format are accepted.

restrictions:
  require_simple_manifest: true

Target-specific overrides¶

In many restriction sections, you can set target-specific overrides using the @target suffix. A target-specific rule applies only when building for that hardware target, as the following example shows:

restrictions:
  kernel_modules:
    disallow:
      - fat
      - nfs
    disallow@rcar_s4:
      - ufs-renesas
      - at24

You can specify target-specific overrides for the following sections: modes, targets, distributions, architectures, repositories, rpms, kernel_modules, manifest_restrictions, variables, selinux_booleans, and sysctl.

The built-in hardened policy¶

AIB ships with a hardened policy (formerly named fusa) designed for safety-critical and security-sensitive deployments. You can apply the hardened policy by using the following command:

$ aib build --policy hardened manifest.aib.yml localhost/my-image

The hardened policy enforces the restrictions described in the following table:

Restriction	Detail
Build modes	Only `image` and `bootc` modes are allowed.
Manifest format	Only simple manifests (`.aib.yml`) are accepted.
Disallowed manifest properties	`experimental` and `image.partitions.root.grow` are blocked.
Disallowed container transport	`containers-storage` is blocked for embedded container images.
Disallowed RPMs	Filesystem tools (`dosfstools`, `e2fsprogs`, `erofs-utils`, `xfsprogs`) and `libbpf` are blocked.
Disallowed kernel modules	`fat`, `nfs`, and `nfs_acl` are blocked globally. Additional modules (`ufs-renesas`, `at24`, `pcie-rcar-gen4`) are blocked for the `rcar_s4` target.
Forced variables	IPv6 is disabled, OOM protection is enabled, QM containers require digest verification and a separate partition, and EFI features are disabled.
Forced SELinux booleans	`deny_ptrace` is set to `true`.
Forced sysctl parameters	`net.core.busy_poll` is set to `0`, and multicast forwarding is disabled.

Creating a custom policy¶

To create a custom policy, write a .aibp.yml file with the required name and description fields, then add the restrictions appropriate for your environment. Place the file in one of the following locations:

The current working directory (reference with the full filename including the .aibp.yml extension).
/etc/automotive-image-builder/policies/ for system-wide policies (reference by name without extension).
A custom path (reference with the full file path).

Validate a custom policy by running a build with --policy and reviewing the output for any schema validation errors.