Runtime Modification and Security

Relevant source files

• intra/core/runtime/overreach.go
• intra/core/undelegated.go
• tools/runtime_write_err_android.patch

Purpose and Scope

This page documents the runtime modification system in Firestack that directly manipulates Go runtime internals to improve crash diagnostics and logging capabilities, particularly on Android. The system uses Go's go:linkname directive to access and modify unexported runtime symbols, override security restrictions, and provide direct output to Android's logcat.

For information about general logging and panic recovery mechanisms, see 6.1 Logging System and Panic Recovery For build system configuration that enables these modifications, see 1.1 Build System and Deployment

Overview

Firestack modifies Go runtime behavior in several key areas:

1. Secure Mode Override: Disables runtime.secureMode on Android to enable full stack traces in crash logs intra/core/runtime/overreach.go36-49
2. Traceback Ratchet Reset: Provides a mechanism to reset runtime.traceback_env to allow lowering the traceback level after it has been raised intra/core/runtime/overreach.go125-141
3. Environment Variable Manipulation: Provides programmatic access to the runtime's cached environment variables for dynamic reconfiguration of GOTRACEBACK intra/core/runtime/overreach.go76-117
4. Direct Logcat Output: Exposes runtime.writeErr for direct Android logcat emission, specifically targeting the crash log buffer intra/core/runtime/overreach.go119-123

All runtime modifications are implemented in intra/core/runtime/overreach.go intra/core/runtime/overreach.go1-156

Sources: intra/core/runtime/overreach.go1-156

Runtime Linkage Architecture

The following diagram shows how Firestack uses go:linkname to bridge the gap between application code and runtime internals.

Linkname Entity Mapping

Title: Runtime Symbol Linkage Map

Sources: intra/core/runtime/overreach.go30-156

Linkname Mechanism

The go:linkname directive allows Firestack to access unexported runtime symbols intra/core/runtime/overreach.go12-17 This requires the linker flag -ldflags="-checklinkname=0" intra/core/runtime/overreach.go19-20

Link Type	Local Symbol	Runtime Symbol	Purpose
Variable	secureMode	runtime.secureMode	Direct memory access to the secure mode flag intra/core/runtime/overreach.go30-31
Variable	traceback_env	runtime.traceback_env	Access the traceback level "ratchet" intra/core/runtime/overreach.go33-34
Function	runtime_environ	runtime.environ	Access cached environment variables intra/core/runtime/overreach.go143-144
Function	runtime_finishDebugVarsSetup	runtime.finishDebugVarsSetup	Re-initialize debug vars from env intra/core/runtime/overreach.go146-147
Function	runtime_isSecureMode	runtime.isSecureMode	Check runtime's secure mode state intra/core/runtime/overreach.go149-150
Function	runtime_gotraceback	runtime.gotraceback	Query GOTRACEBACK settings intra/core/runtime/overreach.go152-153
Function	runtime_wtf	runtime.writeErr	Direct logcat output on Android intra/core/runtime/overreach.go155-156

Sources: intra/core/runtime/overreach.go12-156

Secure Mode Override System

Android AT_SECURE Problem

Android apps have AT_SECURE set (detectable in /proc/self/auxv on non-rooted devices) intra/core/runtime/overreach.go38-39 This causes the Go runtime to enter secureMode, which limits GOTRACEBACK output to a single line on fatal errors or panics, making diagnostics difficult intra/core/runtime/overreach.go40-41

Implementation Details

The override is implemented in the init() function of the runtime package intra/core/runtime/overreach.go36-49

• Variable Linkage: //go:linkname secureMode runtime.secureMode creates a direct alias to the internal boolean intra/core/runtime/overreach.go30-31
• Initialization Override: secureMode = false is set during init() to ensure full stack traces are available even on non-rooted Android devices intra/core/runtime/overreach.go48

The current status of both the Firestack-internal and Go-runtime secureMode can be checked via RuntimeSecureMode() intra/core/runtime/overreach.go59-61

Sources: intra/core/runtime/overreach.go30-61

Environment Variable Manipulation

The Go runtime maintains a cached copy of environment variables separate from the standard os package. Firestack provides direct access to this cache to ensure that runtime-specific settings (like GODEBUG) are correctly synchronized.

Environment Flow

Title: Runtime Environment Variable Propagation

Sources: intra/core/runtime/overreach.go72-117 intra/core/runtime/overreach.go143-147

Key Functions

• RuntimeEnviron(): Returns the runtime's cached environment variables intra/core/runtime/overreach.go78-80
• GetRuntimeEnviron(key): Searches the runtime cache for a specific key intra/core/runtime/overreach.go108-117
• SetRuntimeEnviron(key, val): Modifies a value in the runtime's cache and also updates the OS environment via os.Setenv to maintain consistency intra/core/runtime/overreach.go84-104
• RuntimeFinishDebugVarsSetup(): Forces the runtime to re-read GODEBUG and GOTRACEBACK from the environment intra/core/runtime/overreach.go72-74
• RuntimeResetTracebackEnv(): Zeros the traceback_env variable to break the "ratchet" mechanism that normally prevents lowering the traceback level intra/core/runtime/overreach.go137-141

Sources: intra/core/runtime/overreach.go72-141

Direct Logcat Output and Patching

On Android, Firestack can write directly to logcat by accessing runtime.writeErr. This is particularly useful for post-mortem diagnostics where standard logging might have failed.

• RuntimeWtf(s string): Passes a string to the linked runtime_wtf (internal runtime.writeErr) function intra/core/runtime/overreach.go121-123
• Linkname: //go:linkname runtime_wtf runtime.writeErr intra/core/runtime/overreach.go155-156

Runtime Patching

Firestack includes a patch for the Go runtime itself to elevate the severity and destination of these logs tools/runtime_write_err_android.patch1-23

Aspect	Original Go Runtime	Firestack Patched Runtime
Log Priority	ANDROID_LOG_ERROR (6)	ANDROID_LOG_FATAL (7) tools/runtime_write_err_android.patch9-10
Log Tag	Go	GoWtf tools/runtime_write_err_android.patch10
Log ID	LOG_ID_MAIN (0)	LOG_ID_CRASH (4) tools/runtime_write_err_android.patch18-19

Sources: intra/core/runtime/overreach.go119-123 tools/runtime_write_err_android.patch1-23