18846320559

Committed 27 Oct 2025 03:23PM UTC coverage: 53.917% (-0.08%) from 53.999%

Build # 18846320559

Build Type

push

github

Committed by

web-flow

Commit Message

controlplane: add debug server (#5891)

## Summary
Add a new setting `debug_address` that allows a user to expose the debug
listener similar to the `metrics_address`. Add an index page and a
`config_dump` endpoint.

The current behavior is to start the debug server on a random port only
accessible to the local host. This is still the default behavior.
Exposing the debug server is dangerous because there are sensitive
values in the config.

## Related issues
-
[ENG-3047](https://linear.app/pomerium/issue/ENG-3047/core-admin-panel)

## Checklist

- [x] reference any related issues
- [x] updated unit tests
- [x] add appropriate label (`enhancement`, `bug`, `breaking`,
`dependencies`, `ci`)
- [x] ready for review

Run Details

34 of 132 new or added lines in 7 files covered. (25.76%)

20 existing lines in 5 files now uncovered.

27484 of 50975 relevant lines covered (53.92%)

83.75 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

30.36

/internal/controlplane/server_debug.go

package controlplane

import (
        "io"
        "net/http"
        "net/http/pprof"
        "sync/atomic"

        "google.golang.org/protobuf/encoding/protojson"

        "github.com/pomerium/pomerium/config"
)

type debugServer struct {
        mux atomic.Pointer[http.ServeMux]
}

func newDebugServer(cfg *config.Config) *debugServer {
        srv := &debugServer{}
        srv.Update(cfg)
        return srv
}

func (srv *debugServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
        srv.mux.Load().ServeHTTP(w, r)
}

func (srv *debugServer) Update(cfg *config.Config) {
        mux := http.NewServeMux()

        // only enable admin endpoints if the runtime flag is set
        if cfg.Options.IsRuntimeFlagSet(config.RuntimeFlagDebugAdminEndpoints) {
                // index
                mux.HandleFunc("GET /", srv.indexHandler())
                // config
                mux.HandleFunc("GET /config_dump", srv.configDumpHandler(cfg))
        }

        // pprof
        mux.HandleFunc("GET /debug/pprof/", pprof.Index)
        mux.HandleFunc("GET /debug/pprof/cmdline", pprof.Cmdline)
        mux.HandleFunc("GET /debug/pprof/profile", pprof.Profile)
        mux.HandleFunc("GET /debug/pprof/symbol", pprof.Symbol)
        mux.HandleFunc("GET /debug/pprof/trace", pprof.Trace)

        srv.mux.Store(mux)
}

func (srv *debugServer) configDumpHandler(cfg *config.Config) http.HandlerFunc {
        return func(w http.ResponseWriter, _ *http.Request) {
                o := protojson.MarshalOptions{
                        Multiline:     true,
                        Indent:        "  ",
                        AllowPartial:  true,
                        UseProtoNames: true,
                }
                bs, err := o.Marshal(cfg.Options.ToProto())
                if err != nil {
                        http.Error(w, err.Error(), http.StatusInternalServerError)
                        return
                }
                w.Header().Set("Content-Type", "application/json; charset=utf-8")
                _, _ = w.Write(bs)
        }
}

func (srv *debugServer) indexHandler() http.HandlerFunc {
        return func(w http.ResponseWriter, _ *http.Request) {
                w.Header().Set("X-Content-Type-Options", "nosniff")
                w.Header().Set("Content-Type", "text/html; charset=utf-8")
                _, _ = io.WriteString(w, `<html>
<head>
<title>Pomerium Debug</title>
</head>
<body>
                <ul>
                        <li><a href="/config_dump">Config Dump</a></li>
                        <li><a href="/debug/pprof/">Go PProf</a></li>
                </ul>
</body>
`)
        }
}

1	package controlplane
2
3	import (
4	"io"
5	"net/http"
6	"net/http/pprof"
7	"sync/atomic"
8
9	"google.golang.org/protobuf/encoding/protojson"
10
11	"github.com/pomerium/pomerium/config"
12	)
13
14	type debugServer struct {
15	mux atomic.Pointer[http.ServeMux]
16	}
17
18	func newDebugServer(cfg config.Config) debugServer {	1✔
19	srv := &debugServer{}	1✔
20	srv.Update(cfg)	1✔
21	return srv	1✔
22	}	1✔
23
NEW 24	func (srv debugServer) ServeHTTP(w http.ResponseWriter, r http.Request) {	×
NEW 25	srv.mux.Load().ServeHTTP(w, r)	×
NEW 26	}	×
27
28	func (srv debugServer) Update(cfg config.Config) {	1✔
29	mux := http.NewServeMux()	1✔
30		1✔
31	// only enable admin endpoints if the runtime flag is set	1✔
32	if cfg.Options.IsRuntimeFlagSet(config.RuntimeFlagDebugAdminEndpoints) {	1✔
NEW 33	// index	×
NEW 34	mux.HandleFunc("GET /", srv.indexHandler())	×
NEW 35	// config	×
NEW 36	mux.HandleFunc("GET /config_dump", srv.configDumpHandler(cfg))	×
NEW 37	}	×
38
39	// pprof
40	mux.HandleFunc("GET /debug/pprof/", pprof.Index)	1✔
41	mux.HandleFunc("GET /debug/pprof/cmdline", pprof.Cmdline)	1✔
42	mux.HandleFunc("GET /debug/pprof/profile", pprof.Profile)	1✔
43	mux.HandleFunc("GET /debug/pprof/symbol", pprof.Symbol)	1✔
44	mux.HandleFunc("GET /debug/pprof/trace", pprof.Trace)	1✔
45		1✔
46	srv.mux.Store(mux)	1✔
47	}
48
NEW 49	func (srv debugServer) configDumpHandler(cfg config.Config) http.HandlerFunc {	×
NEW 50	return func(w http.ResponseWriter, _ *http.Request) {	×
NEW 51	o := protojson.MarshalOptions{	×
NEW 52	Multiline: true,	×
NEW 53	Indent: " ",	×
NEW 54	AllowPartial: true,	×
NEW 55	UseProtoNames: true,	×
NEW 56	}	×
NEW 57	bs, err := o.Marshal(cfg.Options.ToProto())	×
NEW 58	if err != nil {	×
NEW 59	http.Error(w, err.Error(), http.StatusInternalServerError)	×
NEW 60	return	×
NEW 61	}	×
NEW 62	w.Header().Set("Content-Type", "application/json; charset=utf-8")	×
NEW 63	_, _ = w.Write(bs)	×
64	}
65	}
66
NEW 67	func (srv *debugServer) indexHandler() http.HandlerFunc {	×
NEW 68	return func(w http.ResponseWriter, _ *http.Request) {	×
NEW 69	w.Header().Set("X-Content-Type-Options", "nosniff")	×
NEW 70	w.Header().Set("Content-Type", "text/html; charset=utf-8")	×
NEW 71	_, _ = io.WriteString(w, `<html>	×
NEW 72	<head>	×
NEW 73	<title>Pomerium Debug</title>	×
NEW 74	</head>	×
NEW 75	<body>	×
NEW 76	<ul>	×
NEW 77	<li><a href="/config_dump">Config Dump</a></li>	×
NEW 78	<li><a href="/debug/pprof/">Go PProf</a></li>	×
NEW 79	</ul>	×
NEW 80	</body>	×
NEW 81	`)	×
NEW 82	}	×
83	}

pomerium / pomerium / 18846320559

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous