How grapheneos/vanadium works
Project Type & Purpose
• Vanadium is a native, privacy-hardened variant of Chromium for Android, supplying both a WebView component and a full-featured browser APK.
• It layers a series of downstream patches on top of upstream Chromium, leverages GrapheneOS’s hardened OS primitives (malloc, seccomp-bpf, MTE, CFI, etc.), and produces final Android APK artifacts.
File-Structure Analysis
• Top-level artifacts:
• README.md, LICENSEs, .gitignore
• args.gn (GN build args), generate-release script
• patches/ (0001…0212-named .patch files)
• No “src/” folder because the upstream Chromium source tree is implied; this repo holds only patches, build scripts, and config glue.
• The presence of protobuf generator/parser patches, config-apk targets, content-filtering modules indicates custom config and content-filter components.
README Insights
• Describes that Vanadium depends on GrapheneOS for low-level hardening.
• Points to official build docs for obtaining the upstream Chromium source and assembling the final binaries.
a. Main Components
1. Upstream Chromium Source (cloned from the official repo)
2. Vanadium Patch Layer (patches/ directory, patch-application pipeline)
3. GN & Ninja Build System (args.gn, generate-release, build targets)
4. Config Components:
– Config APK generator (protoc, protobuf definitions, custom parser)
– Content-filtering and feature-flag modules
5. Android Packaging & UI Layers:
– Vanadium Browser APK
– Vanadium WebView APK
6. GrapheneOS Hardening & Runtime:
– Hardened malloc
– Seccomp-bpf policies, MTE (Memory Tagging), CFI, JIT-disable
– OS services (network, storage, package manager)
7. End User & Host App (apps using WebView)
b. Relationships & Data Flows
• Build System pulls in GrapheneOS OS headers/libraries at link time
• Build outputs: Browser APK, WebView APK, Config APK
• At runtime:
• Browser APK ↔ OS services
• WebView APK ↔ Host App via Android WebView API
• Both APKs reference Config APK (via content-provider or AIDL) for feature flags & filtering rules
c. Architectural Patterns & Principles
• Layered architecture: clean separation of upstream source, patch management, build, and runtime components
• Multi-process sandboxing (Chromium’s browser, renderer, GPU, utility processes)
• Plug-in/extension points: Config APK and content-filter modules loaded at runtime
• Defense-in-depth: OS-level hardening complementing code-level patches
d. Key Technologies & Frameworks
• Build: GN, Ninja, Clang/LLVM toolchain
• Packaging: Android SDK/NDK, Gradle wrappers or custom scripts
• IPC & config: Protocol Buffers, Java/Android IPC (ContentProvider or AIDL)
• Runtime: GrapheneOS hardened C library, seccomp-bpf, Memory Tagging Extension, CFI, Shadow Call Stack