mirror of
https://github.com/subhobhai943/SUB-OS.git
synced 2026-10-25 16:52:29 +00:00
docs: add Contributing, Security, and Roadmap docs; link them from the README
Create docs/CONTRIBUTING.md (build/verify workflow, coding style, kernel gotchas, commit & PR conventions), docs/SECURITY.md (supported versions, private vulnerability reporting, documented caveats), and docs/ROADMAP.md (shipped in v1.0.0 plus near/mid/long-term plans). Add a Documentation and Contributing section to the README pointing at all four docs. Note: used the conventional CONTRIBUTING.md / SECURITY.md filenames (in docs/) so GitHub auto-detects them as community-health files. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01Fh5z6V7nGPbHvqVG5p4CXX
This commit is contained in:
subhobhai943andClaude Opus 4.8 committed
1 parent
bc4e19bb37
commit
a0cd95cdc9
4 files changed
+385
No files matched your search
@@ -273,6 +273,26 @@ Download precompiled kernel binaries and bootable disk images from GitHub:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 📚 Documentation
|
||||||
|
|
||||||
|
| Document | What's inside |
|
||||||
|
|---|---|
|
||||||
|
| 📝 **[Contributing Guide](docs/CONTRIBUTING.md)** | How to build, code style, kernel gotchas, commit & PR conventions |
|
||||||
|
| 🔒 **[Security Policy](docs/SECURITY.md)** | Supported versions, how to report a vulnerability, known caveats |
|
||||||
|
| 🗺️ **[Roadmap](docs/ROADMAP.md)** | What shipped in v1.0.0 and what's planned next |
|
||||||
|
| 🤖 **[Autonomous Dev Roadmap](docs/AUTODEV_ROADMAP.md)** | Fine-grained per-session engineering backlog |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Contributing
|
||||||
|
|
||||||
|
Contributions are welcome! Please read the **[Contributing Guide](docs/CONTRIBUTING.md)**
|
||||||
|
before opening a pull request, and see the **[Roadmap](docs/ROADMAP.md)** for
|
||||||
|
where help is most valuable. Found a security issue? Follow the
|
||||||
|
**[Security Policy](docs/SECURITY.md)** — do not open a public issue.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 📄 License
|
## 📄 License
|
||||||
|
|
||||||
SUB-OS is distributed under the open-source **MIT License**. See [`LICENSE`](LICENSE) for details.
|
SUB-OS is distributed under the open-source **MIT License**. See [`LICENSE`](LICENSE) for details.
|
||||||
@@ -0,0 +1,183 @@
|
|||||||
|
<div align="center">
|
||||||
|
|
||||||
|
<img src="../assets/logo_SUB_OS.png" alt="SUB-OS logo" width="140" height="140" />
|
||||||
|
|
||||||
|
# Contributing to SUB-OS
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
Thanks for your interest in **SUB-OS** — a multi-architecture, modular monolithic,
|
||||||
|
Linux-compatible operating system written from scratch in C, C++17, Assembly,
|
||||||
|
freestanding Rust (`no_std`), and the native SUB Language. This guide covers how
|
||||||
|
to build, the conventions we follow, and how to get a change merged.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Ground rules](#ground-rules)
|
||||||
|
- [Development environment](#development-environment)
|
||||||
|
- [Building](#building)
|
||||||
|
- [Running & verifying](#running--verifying)
|
||||||
|
- [Coding style](#coding-style)
|
||||||
|
- [Kernel gotchas](#kernel-gotchas)
|
||||||
|
- [Commit & PR conventions](#commit--pr-conventions)
|
||||||
|
- [Reporting bugs](#reporting-bugs)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ground rules
|
||||||
|
|
||||||
|
- **Verify before you claim.** Nothing is "done" until it builds *and* boots.
|
||||||
|
Every crypto primitive and codec is tested against a reference vector (RFC or
|
||||||
|
a PIL-generated fixture) **before** it enters the kernel. Hold new code to the
|
||||||
|
same bar.
|
||||||
|
- **No libc, no POSIX host.** The kernel is freestanding. No floating point in
|
||||||
|
kernel space (`-mno-sse`); all math is integer.
|
||||||
|
- **Small, reviewable changes.** One feature or fix per pull request, with a
|
||||||
|
clear description of what you verified and how.
|
||||||
|
- **Be kind.** Assume good faith, keep discussion technical, and respect
|
||||||
|
reviewers' time.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development environment
|
||||||
|
|
||||||
|
The project targets `x86_64`, `aarch64`, and `armv8i` (AArch32). On a Debian/
|
||||||
|
Ubuntu host, install the toolchains and emulators:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install build-essential g++ nasm qemu-system-x86 qemu-system-arm \
|
||||||
|
gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu \
|
||||||
|
gcc-arm-linux-gnueabihf binutils-arm-linux-gnueabihf \
|
||||||
|
rustc cargo dialog python3
|
||||||
|
```
|
||||||
|
|
||||||
|
For the freestanding Rust layer:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rustup target add x86_64-unknown-none
|
||||||
|
```
|
||||||
|
|
||||||
|
> The x86_64 kernel is normally built with an `x86_64-elf-` cross toolchain. A
|
||||||
|
> stock `x86_64-linux-gnu-` GCC also works — pass it via `CROSS_COMPILE=`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
SUB-OS uses a Linux-style Kconfig + Kbuild flow. The version/codename lives at
|
||||||
|
the top of the `Makefile` (`VERSION`/`PATCHLEVEL`/`SUBLEVEL`/`EXTRAVERSION`/
|
||||||
|
`NAME`) and in [`include/init/version.h`](../include/init/version.h) — keep the
|
||||||
|
two in sync when you bump a release.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Configure (interactive) or pick an architecture preset:
|
||||||
|
make configure # or: make menuconfig
|
||||||
|
make x86_64_defconfig # x86_64 (Intel / AMD)
|
||||||
|
make aarch64_defconfig # 64-bit ARM (Cortex-A57)
|
||||||
|
make armv8i_defconfig # 32-bit ARM (Cortex-A15)
|
||||||
|
|
||||||
|
# Build:
|
||||||
|
make # builds the configured/default ARCH
|
||||||
|
make ARCH=aarch64 # or target one explicitly
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Always `make clean` when switching `ARCH`.** Object files from another
|
||||||
|
> architecture link into a *"file in wrong format"* error otherwise.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Running & verifying
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make run # x86_64 disk image in QEMU
|
||||||
|
make run-gui # windowed graphical desktop
|
||||||
|
make run-fullscreen # fullscreen desktop
|
||||||
|
make run-vnc # headless: VNC on localhost:5900
|
||||||
|
make ARCH=aarch64 run # ARM targets
|
||||||
|
```
|
||||||
|
|
||||||
|
Default login is **`SUB` / `SUB`**. Pass `nogui`, `text`, `emergency`, or
|
||||||
|
`single` on the kernel command line to boot to the TTY instead of the desktop.
|
||||||
|
|
||||||
|
**Headless verification** (what CI and reviewers use): boot with
|
||||||
|
`-serial file:serial.log -monitor unix:mon.sock,server,nowait -display none`,
|
||||||
|
drive the login over the monitor `sendkey` interface, and capture the screen
|
||||||
|
with `screendump`. For a code path with no UI, add a temporary CLI applet under
|
||||||
|
`userland/lazybox/` that exercises it over serial, verify, then revert the
|
||||||
|
temporary hook.
|
||||||
|
|
||||||
|
When you submit a change, state plainly **what you ran and what you saw** — build
|
||||||
|
output, boot log excerpt, screenshot, or reference-vector comparison.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Coding style
|
||||||
|
|
||||||
|
- **C:** freestanding C11. Match the surrounding file — 4-space indent, K&R
|
||||||
|
braces, `snake_case` for functions and variables, `SCREAMING_SNAKE` for
|
||||||
|
macros/constants. Keep comment density and idiom consistent with the module
|
||||||
|
you're editing.
|
||||||
|
- **Assembly:** per-arch under `arch/<arch>/`. `.S` files run through `cpp`, so
|
||||||
|
**no nested `/* ... */` comments**.
|
||||||
|
- **Rust:** `no_std`, no allocator assumptions beyond what the kernel provides.
|
||||||
|
- **C++:** freestanding C++17, no exceptions/RTTI, no host STL.
|
||||||
|
- **Headers:** public interfaces in `include/`, with an include guard.
|
||||||
|
- **No new external dependencies** in kernel space.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Kernel gotchas
|
||||||
|
|
||||||
|
These bite newcomers — internalize them before touching the relevant subsystem:
|
||||||
|
|
||||||
|
- **`printk`/`vsprintf` are minimal.** Supported conversions are
|
||||||
|
`c s d i u o x X p %` only — **no** length modifiers (`l`, `ll`) and **no**
|
||||||
|
field width. Cast to `int` / `unsigned` / `void*` at the call site.
|
||||||
|
- **`list_del()` NULLs both links**, so `list_empty()` is not a reliable "is
|
||||||
|
this node still queued?" test after a delete — inspect the links directly.
|
||||||
|
- **Preemption is armed after boot.** A context switch must never run while a
|
||||||
|
plain spinlock is held: wrap such sections with
|
||||||
|
`sched_preempt_disable/enable` (as `printk` does). `weave_lock` sections use
|
||||||
|
`arch_irq_save/restore` so the timer tick cannot fire inside them.
|
||||||
|
- **Dead tasks/stacks are not reclaimed yet.** Prefer one long-lived worker
|
||||||
|
thread over spawning a task per request.
|
||||||
|
- **Network checksums are byte-wise on purpose** — word-at-a-time reads get
|
||||||
|
reordered around the caller's `hdr->checksum = 0` store under `-O2`.
|
||||||
|
- **Ethernet frames are padded to 60 bytes** — trim payloads to the IP
|
||||||
|
`total_length`, never the frame length.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Commit & PR conventions
|
||||||
|
|
||||||
|
- **Commit messages** follow Conventional-Commits-style prefixes:
|
||||||
|
`feat(scope): …`, `fix(scope): …`, `build: …`, `docs: …`, `release(vX.Y.Z): …`.
|
||||||
|
Write the subject in the imperative and add a body explaining *what changed
|
||||||
|
and what you verified*.
|
||||||
|
- **Branch** off `main` for your work; open a pull request against `main`.
|
||||||
|
- **One logical change per PR.** Rebase/squash noisy WIP commits before review.
|
||||||
|
- **CI must pass** (build + kernel verification) before merge.
|
||||||
|
- In the PR description, include: what the change does, which architectures you
|
||||||
|
built, and how you verified boot behaviour.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reporting bugs
|
||||||
|
|
||||||
|
Open a GitHub issue with:
|
||||||
|
|
||||||
|
1. **Architecture** and how you built (`defconfig`, `ARCH`, toolchain).
|
||||||
|
2. **Exact command** that reproduces it.
|
||||||
|
3. **What you expected** vs. **what happened** — paste the serial log and, for
|
||||||
|
the desktop, attach a `screendump`.
|
||||||
|
4. The commit SHA (`git rev-parse --short HEAD`).
|
||||||
|
|
||||||
|
For **security-sensitive** reports, do **not** open a public issue — follow the
|
||||||
|
[Security Policy](SECURITY.md) instead.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Happy hacking. 🐉
|
||||||
@@ -0,0 +1,87 @@
|
|||||||
|
<div align="center">
|
||||||
|
|
||||||
|
<img src="../assets/logo_SUB_OS.png" alt="SUB-OS logo" width="140" height="140" />
|
||||||
|
|
||||||
|
# SUB-OS Roadmap
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
Where SUB-OS is, and where it's going. This is a living document — priorities
|
||||||
|
shift as the kernel grows. For the fine-grained, per-session engineering backlog
|
||||||
|
see [`AUTODEV_ROADMAP.md`](AUTODEV_ROADMAP.md).
|
||||||
|
|
||||||
|
**Current release:** [`v1.0.0` — Titan](https://github.com/subhobhai943/SUB-OS/releases/tag/v1.0.0) (stable)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Shipped in v1.0.0 (Titan)
|
||||||
|
|
||||||
|
- **Weave scheduler** — genuine per-architecture context switching with
|
||||||
|
behavioural priority lanes; cooperative **and** preemptive (timer-driven).
|
||||||
|
- **Concurrency core** — wait queues, completions, futexes, tiny RCU.
|
||||||
|
- **Memory management** — buddy PMM, slab allocator, per-process page tables,
|
||||||
|
page cache.
|
||||||
|
- **VFS** — ext2, FAT32, ramfs, procfs, sysfs, devfs.
|
||||||
|
- **Networking** — Ethernet/ARP/IPv4/UDP, full TCP (active + passive open),
|
||||||
|
DHCP, DNS, NetFilter; `sshd` and `httpd`.
|
||||||
|
- **TLS 1.3 client** — X25519, ChaCha20-Poly1305, HKDF key schedule (browses
|
||||||
|
HTTPS; see the [Security Policy](SECURITY.md) for the cert-verification caveat).
|
||||||
|
- **Image & compression codecs** — DEFLATE/zlib, PNG, BMP, baseline JPEG.
|
||||||
|
- **Graphical desktop (SUB-WT)** — 60 FPS compositor, window manager, Terminal,
|
||||||
|
Files, System & Network Monitor, a real web browser with inline images, and
|
||||||
|
more.
|
||||||
|
- **Multi-arch** — `x86_64`, `aarch64`, `armv8i`.
|
||||||
|
- **Linux-style build** — Kconfig TUI, Kbuild, per-arch defconfigs.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔜 Near term (1.1.x)
|
||||||
|
|
||||||
|
- **Thread reaping / zombie cleanup.** Exited kernel threads currently leak their
|
||||||
|
16 KB stack + `task_t`. Add a reaper (a dead list drained by the idle thread).
|
||||||
|
- **Boot-test the ARM context switch.** Wire `weave_selftest()` into the
|
||||||
|
aarch64/armv8i boot paths and verify the AArch64/AArch32 `sub_ctx_switch`
|
||||||
|
frames under `qemu-system-aarch64` / `-arm`.
|
||||||
|
- **`fork`/`exec`/`wait` for ring-3 userland.** Build on the ELF64 loader and
|
||||||
|
per-process page tables so `sh` can spawn and reap real children.
|
||||||
|
- **TLS certificate verification.** Close the biggest documented security gap by
|
||||||
|
validating the server chain against a bundled trust store.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🌗 Mid term (1.x)
|
||||||
|
|
||||||
|
- **Capability-based IPC ("sub-ports").** Typed, capability-addressed message
|
||||||
|
endpoints distinct from the SysV msg/pipe/shm set already in `ipc/`.
|
||||||
|
- **SMP bring-up (x86_64).** AP boot trampoline, per-CPU run lanes, and per-CPU
|
||||||
|
Weave lanes with work-stealing.
|
||||||
|
- **Desktop maturity.** Compositor damage tracking, a richer file manager, a
|
||||||
|
text editor, and a settings panel over the toolkit widgets.
|
||||||
|
- **Storage & FS.** Write-back caching improvements, journaling groundwork, and
|
||||||
|
broader ext2 write coverage.
|
||||||
|
- **Exploit mitigations.** Enforce W^X on all mappings, add kernel stack
|
||||||
|
canaries, and begin ASLR groundwork.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🌒 Long term (exploratory)
|
||||||
|
|
||||||
|
- **Self-hosting toolchain path** — grow the userland toward building parts of
|
||||||
|
SUB-OS on SUB-OS.
|
||||||
|
- **A native SUB-Language userland** — first-class apps written in `.sb`.
|
||||||
|
- **Real hardware bring-up** — beyond QEMU, on at least one aarch64 board.
|
||||||
|
- **Networking depth** — IPv6, a TLS *server*, and a hardened, fuzzed stack.
|
||||||
|
- **Audio/graphics acceleration** — virtio-gpu 3D paths and a mixer.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How priorities are chosen
|
||||||
|
|
||||||
|
Each development pass picks the single highest-value item achievable and
|
||||||
|
verifiable in one session, implements it, verifies it under QEMU, and refines
|
||||||
|
the backlog. Correctness and boot-tested verification always gate a feature
|
||||||
|
before it's called done. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the
|
||||||
|
verification discipline.
|
||||||
|
|
||||||
|
> Have an idea or want to pick something up? Open an issue or a discussion —
|
||||||
|
> contributions against any of the items above are very welcome.
|
||||||
@@ -0,0 +1,95 @@
|
|||||||
|
<div align="center">
|
||||||
|
|
||||||
|
<img src="../assets/logo_SUB_OS.png" alt="SUB-OS logo" width="140" height="140" />
|
||||||
|
|
||||||
|
# Security Policy
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
SUB-OS is an from-scratch, research/hobby operating system. It is built to be
|
||||||
|
correct and educational, **not** to be deployed as a hardened production system.
|
||||||
|
This document explains what is supported, how to report a vulnerability, and the
|
||||||
|
security caveats you should know before running it anywhere that matters.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Supported versions
|
||||||
|
|
||||||
|
| Version | Codename | Status | Security fixes |
|
||||||
|
|---------|----------|--------|----------------|
|
||||||
|
| `1.0.0` (`1.0.x`) | Titan | ✅ Current stable | Yes |
|
||||||
|
| `0.2.x` / `0.0.x` (alpha/beta) | — | ⚠️ Superseded | No |
|
||||||
|
|
||||||
|
Only the current stable line receives security fixes. Please upgrade to the
|
||||||
|
latest [release](https://github.com/subhobhai943/SUB-OS/releases/latest) before
|
||||||
|
reporting an issue.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reporting a vulnerability
|
||||||
|
|
||||||
|
**Please do not open a public GitHub issue for a security vulnerability.**
|
||||||
|
|
||||||
|
Instead, report it privately through GitHub's coordinated-disclosure channel:
|
||||||
|
|
||||||
|
1. Go to the repository's **Security** tab →
|
||||||
|
**[Report a vulnerability](https://github.com/subhobhai943/SUB-OS/security/advisories/new)**.
|
||||||
|
2. This opens a **private security advisory** visible only to you and the
|
||||||
|
maintainers.
|
||||||
|
3. Include:
|
||||||
|
- Affected version / commit SHA and architecture.
|
||||||
|
- A description of the class of problem and its impact.
|
||||||
|
- Minimal steps or a proof-of-concept that reproduces it.
|
||||||
|
- Any suggested remediation, if you have one.
|
||||||
|
|
||||||
|
> Please describe the **class** of problem and its impact rather than publishing
|
||||||
|
> a weaponized, step-by-step exploit.
|
||||||
|
|
||||||
|
### What to expect
|
||||||
|
|
||||||
|
- **Acknowledgement:** we aim to confirm receipt within **7 days**.
|
||||||
|
- **Assessment:** an initial severity assessment and triage within **14 days**.
|
||||||
|
- **Fix & disclosure:** we coordinate a fix and a disclosure timeline with you,
|
||||||
|
and credit you in the advisory and release notes (unless you prefer to remain
|
||||||
|
anonymous).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known security caveats
|
||||||
|
|
||||||
|
SUB-OS deliberately trades several hardening properties for simplicity and
|
||||||
|
readability at this stage. These are **known and documented**, not bugs:
|
||||||
|
|
||||||
|
- **TLS has no certificate verification.** The TLS 1.3 client performs the key
|
||||||
|
exchange and AEAD correctly but **does not validate the server certificate
|
||||||
|
chain**. Connections are encrypted but **not authenticated** — they are
|
||||||
|
trivially MITM-able. Do not use it to protect real secrets.
|
||||||
|
- **Default credentials are `SUB` / `SUB`.** Every image ships with the same
|
||||||
|
well-known login. Treat any running instance as unauthenticated.
|
||||||
|
- **No exploit mitigations yet.** There is no ASLR, no stack canaries in kernel
|
||||||
|
space, and W^X is not enforced on every mapping. Some segments load RWX.
|
||||||
|
- **Single-user, cooperative trust model.** Isolation between the ring-3 shell
|
||||||
|
and the kernel is minimal; the userland is trusted.
|
||||||
|
- **Networking is best-effort.** The stack is a from-scratch implementation and
|
||||||
|
has not been fuzzed or audited against hostile packets.
|
||||||
|
|
||||||
|
Run SUB-OS in a **VM or emulator (QEMU)**, on isolated networks, and never with
|
||||||
|
real credentials or sensitive data.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
In scope for a security report:
|
||||||
|
|
||||||
|
- Memory-safety faults reachable from the network stack, filesystem parsers, or
|
||||||
|
the image/crypto codecs.
|
||||||
|
- Authentication or privilege-boundary bypasses beyond the documented caveats.
|
||||||
|
- Cryptographic implementation errors (e.g. a broken AEAD or key schedule).
|
||||||
|
|
||||||
|
Out of scope (already documented above): the default credentials, the absence
|
||||||
|
of TLS certificate verification, and the lack of exploit mitigations.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Thank you for helping keep SUB-OS and its users safe. 🐉
|
||||||
Reference in new issue
Block a user