crocochrome

README

Crocochrome

Crocochrome is a chromium supervisor, which runs and reaps chromium processes on demand.

Crocochrome needs to be granted certain linux capabilities to funciton, see docs/capabilities.md for details.

Crocochrome runs chromium with --no-sandbox. The reason for this is that to run with sandboxing enabled, chromium needs user namespaces to work, which are not available everywhere.

Moreover, chromium's sandbox focuses on isolating the processes running untrusted code from other processes, the network, and the filesystem. Regarding process isolation, we only run one chromium process concurrently, and that's the only process in the container running as the (unprivileged) container. Therefore we do not see much value in this isolation. Regarding filesystem access, the whole container is run with a read-only filesystem. The Crocochrome binary is not readable or runnable by the user chromium is running on, and there should be no sensitive files to be accessed whatsoever. Regarding the network, we can use NetworkPolicy objects to forbid the Crocochrome container from accessing private IP ranges.

Manual testing

The manualtest folder includes some simple scripts that use browser and can be used to test Crocochrome. Additionally, a script called croco6.sh also in that folder acts as a k6 wrapper that connects to a running instance of Crocochrome and configures k6 to use it. It can be used as follows:

# Build and run container
docker build . -t localhost:5000/crocochrome && \
docker run -ti --rm -p 8080:8080 --memory=512M --read-only -v /tmp:/chromium-tmp localhost:5000/crocochrome

# Run a script
./manualtest/croco6.sh run manualtest/testk6io.js

All arguments passed to croco6.sh are passed to k6 unmodified. croco6.sh takes care of creating a browser session in Crocochrome, retrieving the websocket URL, passing it down to k6, and finally destroying the session when k6 exits.

Documentation

Index

• type Options
• type SessionInfo
• type Supervisor
  • func New(logger *slog.Logger, opts Options) *Supervisor
  • func (s *Supervisor) ComputeUserAgent(ctx context.Context) error
  • func (s *Supervisor) Create() (SessionInfo, error)
  • func (s *Supervisor) Delete(sessionID string) bool
  • func (s *Supervisor) Session(id string) *SessionInfo
  • func (s *Supervisor) Sessions() []string

Types

type Options

type Options struct {
	// ChromiumPath is the path to the chromium executable.
	// Must be specified.
	ChromiumPath string
	// ChromiumPort is the port where chromium will be instructed to listen.
	// Defaults to 5222.
	ChromiumPort string
	// Maximum time a browser is allowed to be running, after which it will be killed unconditionally.
	// Defaults to 5m.
	SessionTimeout time.Duration
	// UserGroup allows running chromium as a different user and group. The same value will be used for both.
	// If UserGroup is 0, chromium will be run as the current user.
	UserGroup int
	// TempDir is the path to a writable directory where folders for chromium processes will be stored.
	TempDir string
	// Registry is a prometheus registerer for telemetry.
	Registry prometheus.Registerer
	// ExtraUATerms is appended, after a space, to the chromium user agent. It can be used to add vendor-specific
	// information to it, such as the name of the product using chromium to perform requests.
	ExtraUATerms string
}

type SessionInfo

type SessionInfo struct {
	ID              string               `json:"id"`
	ChromiumVersion chromium.VersionInfo `json:"chromiumVersion"`
}

SessionInfo contains the ID and chromium info for a session.

type Supervisor

type Supervisor struct {
	// contains filtered or unexported fields
}

func New

func New(logger *slog.Logger, opts Options) *Supervisor

func (*Supervisor) ComputeUserAgent

func (s *Supervisor) ComputeUserAgent(ctx context.Context) error

ComputeUserAgent runs chromium once, retrieves its default user agent, and stores a patched version so it can be used in all subsequent calls.

func (*Supervisor) Create

func (s *Supervisor) Create() (SessionInfo, error)

Create creates a new browser session, and returns its information. Currently, creating a new session will terminate other existing ones, if present. Clients should not rely on this behavior and should delete their sessions when they finish. If a session has to be terminated when a new one is created, an error is logged.

func (*Supervisor) Delete

func (s *Supervisor) Delete(sessionID string) bool

Delete cancels a session's context and removes it from the map.

func (*Supervisor) Session

func (s *Supervisor) Session(id string) *SessionInfo

Session returns an existing session with the given ID. If the session does not exist, either because it has expired or because it has not been created, Session returns nil.

func (*Supervisor) Sessions

func (s *Supervisor) Sessions() []string

Sessions returns a list of active session IDs. Crocochrome is currently wired to allow only one session at a time, by means of terminating all others when a new one is created, but the design of its API try to be agnostic to this decision.