jnitecki/fexec repository overview

⁠FExec — Secure Execution Gateway

FExec is an HTTP API service that executes pre-defined system commands or Docker container tasks on demand. It acts as a security boundary between untrusted callers and the host execution environment: only explicitly configured command aliases can be triggered, and every parameter is validated before use.

Clients call FExec over HTTP, authenticating with a JWT or API key. FExec looks up the requested alias, validates all parameters against the alias's regex rules, executes the command (on the host or in a Docker container), and returns the result. No arbitrary commands can be run — only aliases defined by the operator.

⁠Objectives

Containers that are only needed occasionally still consume memory and CPU while sitting idle. A cron job can start one on a regular schedule, and a person can start one by hand for interactive use — but neither fits functionality that needs to start on demand, triggered by an event such as a step in an automated workflow. Giving the triggering process direct access to the Docker socket solves the "on demand" problem, but grants unrestricted, unauthenticated control of the Docker daemon. FExec replaces that with a narrow, authenticated HTTP API: only pre-defined, parameter-validated aliases can be triggered.

⁠Execution Modes and Types

Every action FExec's API can perform is defined as an alias — a named configuration that bundles what to run, how input/output are mapped, logging, and other execution details. Each alias runs as one of two types:

• Container — start a Docker container, run it to completion, and return the result.
• Process — start a normal host process and return the result once it exits.

Both exchange input/output via environment variables, command-line arguments, streams, and files.

Every alias also declares a mode, mandatory and currently fixed to inline — the API call blocks until execution completes. See README.md⁠ on GitHub for details.

⁠Configurability

FExec is configured through simple files, not code. Configurable areas include:

• Directories — where auth, alias, shared, and log data live
• Network — listen address/port and optional SSL/TLS
• Logging — app log and audit log destinations, levels, and format
• Configuration reload — picking up auth/alias changes via polling, filesystem events, or SIGHUP, without a restart
• Execution — container vs. host auto-detection, timeouts, and image refresh/prefetch policy
• Authentication — JWT public keys and API-key users
• Aliases — the commands/containers themselves: parameters, volumes, streams, exit-code mapping, and output shape

See CONFIGURATION.md⁠ on GitHub for the full reference.

⁠Quick Start

docker run -d \
  -p 8080:80 \
  -v $(pwd)/alias.d:/etc/fexec/alias.d:ro \
  -v $(pwd)/auth.d:/etc/fexec/auth.d:ro \
  jnitecki/fexec:latest

FExec reads its configuration from /etc/fexec/fexec.conf (optional — sane defaults apply if absent), authentication files from /etc/fexec/auth.d/, and alias definitions from /etc/fexec/alias.d/. At least one auth file and one alias are required before FExec will accept requests. Listens on port 80 by default (443 when SSL is enabled).

See the GitHub repository⁠ for full configuration reference, alias syntax, and API documentation.

⁠Tags

Alpine is the default OS variant — latest and X.Y.Z are Alpine-based, identical to their -alpine-suffixed equivalents:

All tags are published as multi-arch manifests (linux/amd64 + linux/arm64).

⁠Verifying Image Signatures

Every published image is signed with cosign⁠:

cosign verify --key cosign.pub docker.io/jnitecki/fexec:<tag>

cosign.pub is published in the GitHub repository⁠'s root. See SECURITY.md⁠ for full details and vulnerability reporting.

⁠License

FExec is free for personal, non-commercial use (research, learning, testing, hobby projects). Commercial use requires a separate written agreement — see LICENSE⁠ or contact TBSS Ltd.