diff --git a/README.md b/README.md index f25618d..729fb24 100644 --- a/README.md +++ b/README.md @@ -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 SUB-OS is distributed under the open-source **MIT License**. See [`LICENSE`](LICENSE) for details. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..d1a7c80 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,183 @@ +
+ +SUB-OS logo + +# Contributing to SUB-OS + +
+ +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//`. `.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. πŸ‰ diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..6a1f7fb --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,87 @@ +
+ +SUB-OS logo + +# SUB-OS Roadmap + +
+ +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. diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100644 index 0000000..c225192 --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,95 @@ +
+ +SUB-OS logo + +# Security Policy + +
+ +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. πŸ‰