Skip to content

Engine runner

A program that uses BomLens as its scan engine can run the engine’s containers itself, following the engine contract, or call the engine runner. The runner is a Python package (bomlens-runner, standard library only, Python 3.10 or later) that does the part every such program would otherwise write:

  • it runs MODE=PLAN, reads the execution plan and checks it against what it allows;
  • it runs stage 1 and stage 2 as Kubernetes Jobs or Docker containers, passes stage 1’s exit code, out-of-memory state and log to stage 2, and runs the source restore after a killed stage 1;
  • it checks the result manifest and the output files it lists;
  • it removes every Job and Pod before it returns.

The runner of a release knows that release’s plan and manifest, so a program that moves to a new runner version gets the engine changes of that release without changing its own code.

From the first release that ships the runner, each final release (MAJOR.MINOR.PATCH, not a pre-release tag) puts the package on PyPI with the release’s version:

pip install bomlens-runner==<version>

Each release’s notes list the SHA-256 of the published files and the image digests the package names, so a program can pin both. Before that release, install it from a commit on main:

pip install "git+https://github.com/sktelecom/bomlens@<commit>#subdirectory=runner"

A package installed from a commit has no release images: give images to the command, or Images.parse(...) to RunnerPolicy.

The command bomlens-runner runs one scan from a JSON policy file. A program calls the package instead.

from pathlib import Path
from bomlens_runner import Images, RunnerPolicy, Volume, run_source_scan
from bomlens_runner.kubernetes import KubeApi, KubernetesBackend, KubernetesOptions
policy = RunnerPolicy(
images=Images.parse("ghcr.io/sktelecom/bomlens:1.15.0@sha256:563fb0be1b188bbd550f504fcd77b3f2f062637d25104c3f9ac99bcfd61f2a51"),
workspace=Volume("pvc-workspace", Path("/workspace")), # the claim, and where this process sees it
trivy_db=Volume("pvc-trivy", Path("/trivy")),
uid=1000, gid=1000,
labels={"example.com/app": "scanner"},
)
backend = KubernetesBackend(KubeApi.in_cluster(),
KubernetesOptions(namespace="scan", workspace_claim="pvc-workspace",
trivy_db_claim="pvc-trivy"))
result = run_source_scan(policy, backend, scan_id="a1b2c3", project="app", version="1.0",
scan_dir=Path("/workspace/a1b2c3"), source=Path("/workspace/a1b2c3/src"),
on_log=lambda stage, line: print(stage, line))
print(result.manifest.run_status, result.output_dir)

run_image_scan scans an image from its registry in one container (MODE=IMAGE); it needs a non-root uid. Both return a RunResult: the output folder, the checked manifest (EngineResult), the plan’s status and reason, the detected ecosystem, and each container’s exit code, time-out and out-of-memory state (as_metadata() gives them as a dictionary). Read the outputs with read_output, which checks each file’s size and sha256 against the manifest and reads it once.

Argument Meaning
scan_id 1 to 32 lower-case letters, digits or -. Names the Jobs and labels them, so a later call with the same id removes what an interrupted one left
scan_dir a folder under the workspace root for this scan. The runner keeps its files in scan_dir/bomlens/ and replaces that folder
source the source tree, under the workspace root
on_stage called with prep, cdxgen and postprocess before each step. Raising ScanCancelled from it stops the scan
on_log called with (stage, line) for every line a container prints (lines over 64 KiB are cut, at most 16 MiB per container). This is the only place container output goes: no exception message holds a line of it, or a path
cancel a function the runner polls; when it returns true, the running container is stopped and removed and ScanCancelled is raised

The runner never reads its own environment for a container. Each value a container gets is fixed by the runner, fixed by the checked plan, or set in the policy and allowed for that container.

Field Meaning
images the engine image and, when used, the deep_license and deep_cve images, each as repository:tag@sha256:.... latest and an image without a digest are refused
workspace, trivy_db the claim name and where this process sees it. Every path the runner mounts must be under workspace.local_root with no symbolic link in it
stage1_repositories, stage1_image_prefix where the stage 1 image may come from (ghcr.io/cdxgen/ by default). A mirror prefix replaces the default and is passed to MODE=PLAN as CDXGEN_IMAGE_PREFIX
limits, timeouts memory, CPU and /tmp size per container; the time limit of each container and of an image pull
uid, gid the user the plan, stage 2 and image containers run as, and HOST_UID/HOST_GID for the files stage 1 writes. Give the runner’s own user: the files it writes for the containers are readable by their owner only
stage1_env, stage2_env, image_env values for each container, by name. A name the runner sets itself, or one the container does not take, is refused. A value can be a SecretRef to a Kubernetes Secret key, so it is never written into a Job; NVD_API_KEY, TRIVY_USERNAME, TRIVY_PASSWORD, TRIVY_REGISTRY_TOKEN and a proxy address with a user name or password are taken only that way
caller_mounts folders or files for the plan’s caller roles (cache-maven, cache-gradle, maven-settings and the other settings roles)
labels added to every Job and Pod
stage2_network gives stage 2 the egress label, for lookups that need the network (stage 2 has none by default)
deep_license, deep_cve run stage 2 in the deep-license or deep-cve image (not both)

In the plan, the runner refuses: another contract name or major version; stages other than generate then postprocess; a stage 1 image that is not pinned or not from an allowed repository; a stage 2 image other than the configured one; an unknown mount role, or one in the wrong stage; a mount target that is a system folder, /, under /tmp or /trivy-db (with the documented exceptions) or holds ..; a plan file outside bomlens-plan/; a required caller role; a non-numeric user; an entrypoint other than a shell; a stage 2 env without its required values. Env names off its list are dropped and reported in RunResult.dropped_plan_env.

In the result manifest, it refuses: a file that is a symbolic link or over 4 MiB; another contract name or major version; an unknown run or step status; a successful run with a non-zero exit code. An output is refused when its path is not a plain file name, it is over 256 MiB, or its size or sha256 differs from the manifest. Unknown step ids, reasons and roles are kept.

The runner creates Jobs only. What the cluster provides:

  • A namespace whose Pod Security level allows stage 1: it runs as root (0:0) with CHOWN, DAC_OVERRIDE, FOWNER, SETGID and SETUID, because the dependency resolvers install packages and write lock files. baseline allows it; restricted does not. The other containers run as the policy’s non-root user with every capability dropped.
  • A Role for the runner’s service account: jobs (create, get, list, delete), pods (get, list, delete) and pods/log (get).
  • The workspace claim, ReadWriteMany when the runner and the Jobs can be on different nodes, and a claim for the Trivy database.
  • NetworkPolicies selected by the labels below. The runner does not create them, so it needs no permission on them.
Label Values
app.kubernetes.io/part-of bomlens-engine
app.kubernetes.io/component engine-plan, engine-stage1, engine-restore, engine-stage2, engine-image, engine-chown
bomlens.engine/network none for every container but stage 1 and the image scan, which are egress (and stage 2 with stage2_network)
bomlens.engine/scan the scan id

A policy that denies all traffic to bomlens.engine/network: none, and one that allows DNS and the internet, without the cluster’s private ranges, to egress, give the containers the same network the CLI does. A CNI that enforces NetworkPolicy is needed. Every Pod has a seccomp profile of RuntimeDefault, no service account token, no service links, a read-only root file system and an emptyDir at /tmp. Kubernetes has no per-Pod process limit, so limits.pids applies only where the node’s podPidsLimit is set.

CI runs the runner against a kind cluster with the image built from the commit (tests/test-engine-runner-kind.sh): a source scan, a cancelled scan, an image scan, and the network labels under the two policies above.

DockerBackend runs the same containers through the docker CLI, on the daemon DOCKER_HOST names. A socket proxy that allows only the container and image endpoints is enough: the runner uses version, image inspect, pull, create, inspect, start, logs, kill, rm and ps.

from bomlens_runner.docker import DockerBackend, DockerOptions
backend = DockerBackend(DockerOptions(
workspace="scan-workspace", # a named volume, mounted by subpath
trivy_db="scan-trivy",
egress_network="scan-egress", # the network stage 1 and image scans join
refuse_networks=("app-internal",), # never joined, whatever the options say
instance_labels={"example.com/instance": "prod"},
secrets=lambda ref: read_secret(ref.name, ref.key),
))
Option Meaning
volume_strategy named (default): the workspace and Trivy volumes are Docker volumes mounted by subpath, which needs Docker API 1.45 or later. bind: they are host folders (API 1.41 or later)
workspace, trivy_db the volume names, or the absolute host folders with bind. The policy’s workspace.local_root is where the runner sees the same files
egress_network the network a container with the egress label joins, by name (an id is refused). host, none, bridge, refuse_networks and the networks of the worker’s own container are refused
worker_container the worker’s container, to read its networks. By default the runner inspects its HOSTNAME when it runs in a container
instance_labels labels every container gets, and that scope the removal of an earlier attempt’s containers to this installation
secrets turns a SecretRef into its value when a container is created

A container’s values never reach a command line or the docker CLI’s environment: they are written to an env file readable by its owner only, which is removed once the container is created. After a container is created, the mounts and settings the daemon recorded are compared with the ones asked for, and a container that differs is removed without being started. Every container has --security-opt no-new-privileges, --cap-drop ALL (and the root capabilities for the root containers), memory with no extra swap, a CPU and process limit, a read-only root (stage 1 unless stage1_read_only_root is off), --network none unless it has the egress label, and a bomlens.engine/deadline label with the time after which it may be removed. Named volumes are mounted with volume-nocopy. /tmp is a fresh workspace folder. When run returns, the container has been removed, or ContainerStillRunning is raised.

The bomlens-runner command uses Docker when the policy file has a docker object with these options (secrets aside). It reads a SecretRef {"secret": {"name": "proxy", "key": "url"}} from the runner’s environment variable BOMLENS_SECRET_PROXY_URL (the name and key in upper case, other characters as _); those variables are not passed to the docker commands.

CI runs the Docker backend on the runner’s daemon (tests/test-engine-runner-docker.sh): a source scan with a host folder and with a named volume, a cancelled scan and an image scan.

The package has the version of the BomLens release it comes with, and the images of that release. When images is not given to the command, it uses them; release_images() gives them to a program. A runner reads the contract major version it was made for (1) and refuses another.