Skip to content

Commit 32ccc8e

Browse files
RiSKeDRiSKeD
committed
feat: add base & chipsec image targets & modules
Signed-off-by: Fabian Wienand <fabian.wienand@9elements.com>
1 parent c14bb89 commit 32ccc8e

17 files changed

Lines changed: 897 additions & 4 deletions

File tree

‎.commitlintrc.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Configuration for commitlint
2+
---
3+
# Basic set of roules taken from https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional
4+
extends:
5+
- "@commitlint/config-conventional"
6+
# Override type-enum to just use types, which are relevant to this project
7+
rules:
8+
type-enum:
9+
- 2
10+
- always
11+
- - build
12+
- chore
13+
- ci
14+
- docs
15+
- feat
16+
- fix
17+
- refactor
18+
- revert
19+
- test

‎.envrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
use flake

‎.github/workflows/commitlint.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: Commits
2+
on: [pull_request]
3+
4+
jobs:
5+
commitlint:
6+
runs-on: ubuntu-latest
7+
steps:
8+
- uses: actions/checkout@v4
9+
with:
10+
fetch-depth: 0
11+
- uses: wagoid/commitlint-github-action@v6

‎.github/workflows/nix.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Nix Flake CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
nix:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout repository
13+
uses: actions/checkout@v4
14+
15+
- name: Install Nix
16+
uses: cachix/install-nix-action@v31
17+
with:
18+
extra_nix_config: |
19+
experimental-features = nix-command flakes
20+
21+
- name: Lint Nix code with statix
22+
run: nix run .#statix -- check .
23+
24+
- name: Format check with nixpkgs-fmt
25+
run: nix run .#nixpkgs-fmt -- --check .
26+
27+
- name: Flake check
28+
run: nix flake check --show-trace
29+
30+
- name: Build base image
31+
run: nix build .#base
32+
33+
- name: Build chipsec image
34+
run: nix build .#chipsec

‎.gitignore‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# Ignore build outputs from performing a nix-build or `nix build` command
2-
result
3-
result-*
2+
result*
3+
base
4+
chipsec
45

56
# Ignore automatically generated direnv output
67
.direnv
8+
9+
# Ignore hooks
10+
.pre-commit-config.yaml

‎Makefile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
TARGETS = base chipsec
2+
3+
all: $(TARGETS)
4+
5+
$(TARGETS):
6+
nix build .#$@ --out-link $@
7+
8+
clean:
9+
rm -f $(TARGETS)
10+
11+
.NOTPARALLEL: all $(TARGETS)
12+
.PHONY: all clean $(TARGETS)

‎README.md‎

Lines changed: 203 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,203 @@
1-
# fwci-base-image
2-
This repository provides a minimal, NixOS-based image designed to serve as a base environment for FirmwareCI tests. It equips the host machine with all necessary capabilities required for running the tests.
1+
# FirmwareCI Base Image
2+
3+
This repository provides **modular, reproducible NixOS base images** for FirmwareCI and custom hardware testing. It is intended as a robust foundation for building your own NixOS-based CI images, offering flexible configuration of kernel, firmware, packages, and services. Each image includes essential default tooling, enabling your host machine to execute any FirmwareCI test step reliably.
4+
5+
**Note:** Chipsec requires an older kernel version for compatibility. To run the chipsec test step, use the provided chipsec configuration or image, which is preconfigured with the appropriate kernel.
6+
7+
For a comprehensive overview of available FirmwareCI commands and usage, refer to the [FirmwareCI Commands Reference](https://docs.firmware-ci.com/references/2_commands/index.html).
8+
9+
## Features
10+
11+
- **Nix Flake-based**: Modern, reproducible, and composable.
12+
- **Easy to extend**: Use as a base for your own hardware.
13+
14+
---
15+
16+
## Quick Start
17+
18+
### Prerequisites
19+
20+
- [Nix](https://nixos.org/download.html) with flakes enabled (`experimental-features = nix-command flakes` in your `nix.conf`).
21+
22+
### Build All Images
23+
24+
```sh
25+
make all
26+
```
27+
28+
### Build a Specific Image
29+
30+
```sh
31+
make base
32+
make chipsec
33+
```
34+
35+
### Clean build outputs
36+
37+
```sh
38+
make clean
39+
```
40+
41+
The resulting images will be symlinked as `./base` and `./chipsec`.
42+
43+
---
44+
45+
## Flake Structure
46+
47+
- `flake.nix` – Flake entrypoint, exposes base and chipsec images as outputs.
48+
- `modules/base.nix` – Base system options and configuration.
49+
- `modules/kernel.nix` – Kernel options and configuration.
50+
- `pkgs/default-tools/default.nix` – Default fwci testing tools package.
51+
- `Makefile` – Simple build automation for images.
52+
53+
---
54+
55+
## Using as a Base for Your Own Image
56+
57+
You can use this flake as a base for your own NixOS image or configuration.
58+
59+
### Example: Extend in Your Own Flake
60+
61+
```nix
62+
{
63+
description = "My Custom FirmwareCI Image";
64+
65+
inputs.firmwareci-base-image.url = "github:BlindspotSoftware/firmwareci-base-image";
66+
67+
outputs = { self, nixpkgs, firmwareci-base-image, ... }:
68+
let
69+
myHardwareConfig = { ... }: {
70+
firmwareci.base = {
71+
sshAccess = {
72+
user = "root";
73+
key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKcSD9iHnCrJXkSt7aGSnfL0tVHUm+x6/EDr/FchmBfu";
74+
};
75+
};
76+
77+
firmwareci.kernel = {
78+
version = "6.6.7";
79+
sha256 = "...";
80+
extraKernelModules = [ "dummy" "loop" ];
81+
};
82+
};
83+
in {
84+
nixosConfigurations.my-custom-image = nixpkgs.lib.nixosSystem {
85+
system = "x86_64-linux";
86+
modules = [
87+
firmwareci-base-image.baseConfig
88+
myHardwareConfig
89+
];
90+
};
91+
};
92+
}
93+
```
94+
95+
---
96+
97+
## Configuration Options
98+
99+
You can override these options in your own configuration or flake:
100+
101+
### **firmwareci.base options**
102+
103+
| Option | Type | Default | Description |
104+
|-------------------|-----------|--------------------------------|-----------------------------------------------------|
105+
| `sshAccess` | submodule | `{ user = ""; key = ""; }` | Add an SSH public key for a user (see below). |
106+
| `enableFwupd` | bool | `true` | Enable the fwupd firmware update service. |
107+
| `enableAllFirmware` | bool | `true` | Enable all available firmware blobs. |
108+
| `allowBroken` | bool | `true` | Allow installation of broken packages. |
109+
| `allowUnfree` | bool | `true` | Allow installation of unfree packages. |
110+
| `includeChipSec` | bool | `false` | Include chipsec with kernel module (<= 6.12 only). |
111+
| `includeDefaultTools` | bool | `true` | Include the default tools package in the image. |
112+
113+
#### `sshAccess` submodule
114+
115+
| Option | Type | Default | Description |
116+
|--------|------|---------|-------------|
117+
| `user` | str | `""` | SSH user for access (e.g. `"root"`). |
118+
| `key` | str | `""` | SSH public key to add to the user's authorized_keys. |
119+
120+
### **firmwareci.kernel options**
121+
122+
| Option | Type | Default | Description |
123+
|---------------------------|---------------------|-----------|---------------------------------------------------------------------------------------------|
124+
| `version` | `str` | `"6.15.8"`| Linux kernel version to use. |
125+
| `sha256` | `str` | SRI hash | sha256 hash for the kernel tarball (must be in SRI format, e.g. `sha256-...`). |
126+
| `extraKernelModules` | `list of str` | `[]` | Extra kernel modules to load at boot (e.g. `["dummy"]`). |
127+
128+
---
129+
130+
## SSH Access and Security
131+
132+
**Note:**
133+
The default FirmwareCI images are configured to allow SSH access to the root user:
134+
135+
```nix
136+
users.users.root.openssh.authorizedKeys.keys = [
137+
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKcSD9iHnCrJXkSt7aGSnfL0tVHUm+x6/EDr/FchmBfu"
138+
];
139+
```
140+
141+
This configuration allows FirmwareCI to securely connect to your device via SSH using a preconfigured key at `/root/.ssh/fwci` inside the test environment. You may also customize the SSH access settings to suit your specific requirements.
142+
143+
Example SSH transport configuration for FirmwareCI to connect to the machine:
144+
145+
```yaml
146+
transport: &transport
147+
proto: ssh
148+
options:
149+
host: "my.network"
150+
user: root
151+
identity_file: /root/.ssh/fwci #pre-configured SSH-key
152+
```
153+
154+
**Caution:**
155+
Do not enable this configuration on devices connected to publicly accessible networks, as it may expose your system to unauthorized access.
156+
157+
---
158+
159+
## Structure
160+
161+
- `flake.nix` – Flake entrypoint, exposes base and chipsec images.
162+
- `modules/base.nix` – Base system options and configuration.
163+
- `modules/kernel.nix` – Kernel options and configuration.
164+
- `pkgs/default-tools/default.nix` – Default fwci testing tools package.
165+
- `Makefile` – Simple build automation for images.
166+
167+
---
168+
169+
## Development
170+
171+
We welcome contributions from everyone!
172+
Format and lint Nix code with:
173+
174+
```sh
175+
nix fmt
176+
nix run .#statix
177+
```
178+
179+
Pre-commit hooks are available via `pre-commit-hooks.nix` and will run `nixpkgs-fmt` and `statix` on all `.nix` files before commit.
180+
181+
---
182+
183+
## License
184+
185+
[BSD 2-Clause License](LICENSE)
186+
187+
---
188+
189+
## Maintainers
190+
191+
- [@BlindspotSoftware](https://github.com/orgs/BlindspotSoftware)
192+
193+
---
194+
195+
## Contributing
196+
197+
Contributions and issues are welcome! Please open a PR or issue on GitHub.
198+
199+
---
200+
201+
## References
202+
203+
- [NixOS](https://nixos.org/)

0 commit comments

Comments
 (0)