Skip to content

Commit 0cde482

Browse files
q1sh101q1sh101
committed
docs: add README and LICENSE
1 parent c7bbff6 commit 0cde482

2 files changed

Lines changed: 218 additions & 0 deletions

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Giorgi Kishmareia "q1sh101"
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# bythos
2+
3+
![Linux](https://img.shields.io/badge/Linux-FFA500?logo=linux&logoColor=black&labelColor=FFA500) ![C11](https://img.shields.io/badge/C11-A8B9CC?logo=c&logoColor=black&labelColor=A8B9CC) ![Zero--deps](https://img.shields.io/badge/Zero--deps-brightgreen.svg) ![UEFI](https://img.shields.io/badge/UEFI-firmware%20trust-7B68EE?labelColor=7B68EE)
4+
5+
Read-only firmware trust posture auditor for Linux. Single C11 binary, no
6+
daemon, zero third-party deps.
7+
8+
bythos does not harden. It reads, classifies, prints, exits.
9+
10+
## At a glance
11+
12+
```text
13+
+-----------------------------------------------------------------------------------------+
14+
| BYTHOS 0.1 ~75 checks · 10 subgroups |
15+
+----------------+-----------------+-----------------+-----------------+------------------+
16+
| Trust layer | hardware | firmware | Secure Boot | boot chain |
17+
+================+=================+=================+=================+==================+
18+
| | TPM | BIOS_CNTL | db, dbx | shim |
19+
| sample | IOMMU | Intel ME | MOK, PK | SBAT |
20+
| checks | Thunderbolt | Intel DCI | SbatLevel | BootOrder |
21+
| | DMA | AMD PSP | CA breadth | BootNext |
22+
| | ... | ... | ... | ... |
23+
+----------------+-----------------+-----------------+-----------------+------------------+
24+
25+
+-------------------+---------------------------------------------------------------------+
26+
| Subgroup | Sample checks |
27+
+===================+=====================================================================+
28+
| EFI | EFI boot mode, ESRT entries |
29+
| Secure Boot | state, setup mode, db/dbx, SBAT, MOK, trust breadth, efivarfs |
30+
| Boot chain | shim signature, SBAT revocations, BootOrder, EFI one-shot boot, ... |
31+
| ESP | ownership, filesystem type, fallback boot binary, capsules |
32+
| TPM | TPM 2.0, DA lockout, PCR 0/7, event-log CRTM signal |
33+
| LUKS | encrypted volumes, systemd TPM2 token, PCR mask strength |
34+
| Platform firmware | BIOS_CNTL, Intel ME, Intel DCI, AMD PSP, chipsec availability |
35+
| Platform DMA | IOMMU groups, IOMMU DMA posture, Thunderbolt DMA protection |
36+
| CPU | microcode, memory encryption, CPU vulnerability scan |
37+
| fwupd | service state, LVFS, inventory, updates, history, HSI signals |
38+
+-------------------+---------------------------------------------------------------------+
39+
40+
+-----------------------------------------------------------------------------------------+
41+
| Reads: sysfs . efivarfs . /proc . PCI config . MSRs . trusted CLI helpers |
42+
| Outputs: plain colored text | --json (CI / dashboards / posture diffs) |
43+
| Exit: 0 = no FAIL | 1 = FAIL | 2 = usage error |
44+
+-----------------------------------------------------------------------------------------+
45+
```
46+
47+
## Mini example
48+
49+
Plain output is colored in a terminal; `--json` emits the same tree for CI and posture diffs.
50+
51+
```text
52+
$ sudo bythos
53+
[bythos] firmware trust posture
54+
warn: 55 ok 8 warn 0 fail 12 skip
55+
56+
secure boot:
57+
ok state Secure Boot enabled
58+
ok SBAT policy level SbatLevel: sbat,1,2024010100
59+
warn trust breadth Microsoft 3rd Party UEFI CA in db
60+
61+
tpm:
62+
ok PCR 0 non-zero; firmware measured at boot
63+
ok PCR 7 non-zero; Secure Boot state measured
64+
65+
platform firmware:
66+
ok Intel BIOS write protection BLE and SMM_BWP set; BIOS region protected
67+
ok Intel DCI DCI disabled and locked
68+
69+
fwupd:
70+
ok HSI: Boot Guard enabled and verified
71+
ok HSI: pre-boot DMA protection active
72+
```
73+
74+
## Quick Start
75+
76+
```bash
77+
git clone https://github.com/q1sh101/bythos
78+
cd bythos && make && sudo make install
79+
80+
sudo bythos # requires root for full coverage
81+
bythos --json # machine-readable output
82+
bythos --help
83+
bythos --version
84+
```
85+
86+
Install paths can be overridden with `prefix`, `bindir`, `mandir`, `DESTDIR`.
87+
Remove with `sudo make uninstall`.
88+
89+
## How It Works
90+
91+
**bythos opens no sockets, writes no files, runs no shell, and ignores `$PATH`.**
92+
Helpers are spawned via `fork` + `execvp` against a compile-time PATH; their
93+
output is captured through a bounded pipe with a 10-second timeout and parsed
94+
by hand-written C parsers.
95+
96+
PE/COFF parsing extracts `.sbat` from installed shim/grub binaries. JSON
97+
output escapes control characters and invalid UTF-8. Each subgroup has a fixed
98+
result capacity; overflow is flagged as truncated in both outputs.
99+
100+
## Optional Helpers
101+
102+
bythos reads kernel-exposed state without extra packages. Helpers expand
103+
coverage:
104+
105+
| Helper | Adds coverage for |
106+
|--------------|----------------------------------------------------|
107+
| `fwupdmgr` | HSI signals, firmware inventory, update status |
108+
| `mokutil` | Secure Boot state, MOK enrollments, db/dbx, SBAT |
109+
| `sbctl` | Secure Boot owner GUID and vendor-key state |
110+
| `tpm2-tools` | TPM PCR reads and dictionary-attack lockout policy |
111+
| `dmidecode` | SMBIOS firmware password status |
112+
113+
Narrower probes also use `cryptsetup`, `lsblk`, `pesign`, `sha256sum`, and
114+
`systemctl`. `chipsec` and `spectre-meltdown-checker` are detected for
115+
availability only. Missing helpers degrade their checks to `skip`, never `fail`.
116+
117+
## Output States
118+
119+
| State | Meaning |
120+
|--------|----------------------------------------------|
121+
| `ok` | Expected posture was observed |
122+
| `warn` | Weaker posture, stale state, or softer risk |
123+
| `fail` | Direct posture regression |
124+
| `skip` | Not applicable or not observable on this run |
125+
126+
`skip` is not a hidden pass. It means bythos could not make that observation:
127+
hardware absent, helper missing, field absent, root required, vendor mismatch,
128+
or output unparseable, among other typed reasons (full list in `man bythos`).
129+
130+
Plain output uses lowercase labels. `--json` capitalizes them (`OK`, `WARN`,
131+
`FAIL`, `SKIP`) and adds a `skip_reason` field per row. Exit codes are
132+
listed in the overview at the top.
133+
134+
## Comparison
135+
136+
| Tool | Layer | Best at | Footprint |
137+
|------------|-----------------------------|---------------------------------|-----------------------|
138+
| **bythos** | UEFI / TPM / DMA / EFI vars | Firmware trust posture report | read-only, userland |
139+
| lynis | OS configuration | Compliance hardening sweep | read-only, user/root |
140+
| aide | Filesystem hashes | Post-deploy integrity tripwire | writes hash DB, root |
141+
| chkrootkit | Known-bad signatures | Userland rootkit detection | read-only, root |
142+
| fwupdmgr | LVFS + HSI subset | Firmware updates and HSI report | writes firmware, root |
143+
| fwts | ACPI / SMBIOS / UEFI tests | Firmware compliance test suite | read-only, root |
144+
| chipsec | SMI / SMM / SPI flash | Deep firmware research audit | kernel module, root |
145+
146+
chipsec goes deeper and needs lower-level access. bythos stays in userland and
147+
reads what Linux already exposes.
148+
149+
## Requirements
150+
151+
**Runtime**:
152+
- Linux 5.x or newer
153+
- UEFI host recommended
154+
- x86_64 primary; ARM64 coverage is narrower
155+
156+
**Build**:
157+
- glibc or musl
158+
- GNU Make and a C11 compiler
159+
160+
On legacy BIOS hosts and inside containers, most firmware paths are
161+
unavailable; bythos still completes, marking missing checks as `skip` and
162+
flagging absent EFI runtime as `warn`.
163+
164+
## Limitations
165+
166+
- Pre-OS firmware internals (SMI / SMM / SPI flash) are not exposed by Linux and are invisible to bythos.
167+
- Versions and posture only - not a CVE scanner.
168+
- Hash comparisons confirm file identity, not Authenticode chain validity.
169+
- BMC / IPMI / iLO / iDRAC management plane is out of scope.
170+
- PCR reads are local observations; remote attestation is out of scope.
171+
- ACPI / SMBIOS structural validation is out of scope (see `fwts`).
172+
- Userland security (processes, memory, network) is out of scope.
173+
174+
## Build and Test
175+
176+
```bash
177+
make # build bythos
178+
make ci-test # unit suite
179+
make smoke # end-to-end smoke test
180+
make asan # ASan + UBSan unit suite
181+
```
182+
183+
The default build uses `-Wall -Wextra -Wpedantic -Werror`,
184+
`-fstack-protector-strong`, `_FORTIFY_SOURCE=2`, PIE, RELRO, now binding, and
185+
non-executable stack linker flags. ASan and UBSan are clean on the unit suite
186+
and live binary.
187+
188+
## Contributing
189+
190+
Found a bug or have a feature request? Open an issue at
191+
[github.com/q1sh101/bythos](https://github.com/q1sh101/bythos/issues).
192+
193+
Human-written PRs only; LLM-generated submissions are not accepted.
194+
195+
Built for engineers who care about firmware trust.
196+
197+
**Built by** Giorgi Kishmareia · [q1sh101](https://github.com/q1sh101)

0 commit comments

Comments
 (0)